semfora-error-reporter

An MCP (Model Context Protocol) server for tracking issues with semfora-engine. Designed for semfora developers to log, confirm, and triage engine bugs discovered during AI-assisted workflows.

If you're a semfora user and want an easy way to report issues you encounter, you can pull this down and use it with your own MCP-compatible toolchain.

What It Does

Provides four MCP tools:

Tool	Description
reportSemforaIssue	File a new issue (wrong results, crashes, broken commands)
confirmSemforaIssue	Confirm an issue reported by another agent/user
invalidateSemforaIssue	Mark an issue as invalid (duplicate, user error, already fixed)
listSemforaIssues	List issues filtered by status (unconfirmed/confirmed/invalid/all)

Issues are stored locally in ~/.openclaw/semfora-errors.json with file-level locking for concurrent access.

Usage Log

All tool calls are logged to ~/.openclaw/logs/semfora-error-reporter.log with auto-truncation at 512KB. Tail it to watch activity in real time:

tail -f ~/.openclaw/logs/semfora-error-reporter.log

Setup

Prerequisites

• Node.js 18+
• An MCP-compatible client (Claude Code, OpenClaw, etc.)

Install

git clone https://github.com/Semfora-AI/semfora-error-reporter.git
cd semfora-error-reporter
npm install
npm run build

Configure with Claude Code

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "semfora-error-reporter": {
      "command": "node",
      "args": ["/path/to/semfora-error-reporter/dist/index.js"]
    }
  }
}

Configure with OpenClaw

Use mcporter to register the server:

mcporter config add semfora-error-reporter \
  --command node \
  --args /path/to/semfora-error-reporter/dist/index.js

Or add it manually to your mcporter config (~/.mcporter/mcporter.json):

{
  "mcpServers": {
    "semfora-error-reporter": {
      "command": "node",
      "args": ["/path/to/semfora-error-reporter/dist/index.js"]
    }
  }
}

Configure with DevClaw (Auto Ticket Ingestion)

To have DevClaw workers automatically report semfora issues they encounter, add the following to your DevClaw agent prompts (developer and reviewer):

For developer workers — add to your developer prompt (e.g. devclaw/prompts/developer.md):

### Semfora Error Reporting (semfora-engine project only)

When working on `semfora-engine`, use the `semfora-error-reporter` MCP tools to report issues with the engine:

- **Report** (`reportSemforaIssue`) when semfora returns wrong/missing results, crashes on valid input,
  produces output that doesn't match reality, or has broken commands. Do NOT report your own misuse.
- **Severity:** `critical` (crashes/data loss), `high` (blocks task), `medium` (workaround exists), `low` (minor/cosmetic).
- **After reporting:** Continue with fallbacks (manual file reading, ripgrep). Do not fix semfora unless
  that's your task. Do not `confirmSemforaIssue` on your own reports.
- **Required fields:** `projectRootAbsolutePath`, `filePathAbsolute`, `workflowSeverity`, `reportingModel`,
  `semforaVersion`, `projectDetails` (languages, estimatedSize, additionalContext), `semforaToolUsed`,
  `toolPurpose`, `details`.

For reviewer workers — add to your reviewer prompt (e.g. devclaw/prompts/reviewer.md):

### Semfora Error Reporting (semfora-engine project only)

When reviewing PRs for `semfora-engine`, use the `semfora-error-reporter` MCP tools:

- **Report** (`reportSemforaIssue`) if you encounter semfora returning wrong/missing results, crashes,
  or broken commands during review. Do NOT report your own misuse.
- **Confirm/Invalidate** issues filed by other agents. Only verify reports you did NOT file yourself.
  To confirm, reproduce the exact scenario. To invalidate, explain why (duplicate, user error, already fixed).
- **Severity:** `critical` (crashes/data loss), `high` (blocks task), `medium` (workaround exists), `low` (minor/cosmetic).

Creating GitHub Issues from Reports

If you want to escalate confirmed reports to GitHub issues on the semfora-engine repo, you can use the gh CLI:

# List confirmed issues from the local DB
node dist/index.js  # (via MCP: listSemforaIssues with status "confirmed")

# Create a GitHub issue from a confirmed report
gh issue create \
  --repo Semfora-AI/semfora-engine \
  --title "Bug: <description from report>" \
  --body "Reported by: <reportingModel>
Severity: <workflowSeverity>
Semfora version: <semforaVersion>
Tool used: <semforaToolUsed>

## Details
<details field from report>

## Confirmation
Confirmed by: <confirmedByModel>
<confirmationDetails>"

Or if you have the GitHub MCP server configured, your AI agent can create issues directly using mcp__github__create_issue or similar tools with the report data.

Automating with a Script

For bulk escalation of confirmed issues to GitHub:

#!/usr/bin/env bash
# escalate-confirmed.sh — create GH issues from confirmed semfora error reports

DB="$HOME/.openclaw/semfora-errors.json"
REPO="Semfora-AI/semfora-engine"

jq -c '.confirmedSemforaErrors[]' "$DB" | while read -r entry; do
  title="Bug: $(echo "$entry" | jq -r '.semforaToolUsed') — $(echo "$entry" | jq -r '.toolPurpose' | head -c 60)"
  body=$(cat <<EOF
**Reported by:** $(echo "$entry" | jq -r '.reportingModel')
**Severity:** $(echo "$entry" | jq -r '.workflowSeverity')
**Semfora version:** $(echo "$entry" | jq -r '.semforaVersion')
**Tool used:** $(echo "$entry" | jq -r '.semforaToolUsed')
**Discovered:** $(echo "$entry" | jq -r '.discoveredAt')

## Details
$(echo "$entry" | jq -r '.details')

## Confirmation
**Confirmed by:** $(echo "$entry" | jq -r '.confirmedByModel')
$(echo "$entry" | jq -r '.confirmationDetails')

---
*Auto-created from semfora-error-reporter ID: $(echo "$entry" | jq -r '.id')*
EOF
  )
  gh issue create --repo "$REPO" --title "$title" --body "$body" --label "bug"
done

Required Fields Reference

When calling reportSemforaIssue, all fields are required:

projectRootAbsolutePath  — absolute path to the repo root
filePathAbsolute          — file involved (null if not file-specific)
workflowSeverity          — low | medium | high | critical
reportingModel            — your model name (e.g. "claude-sonnet-4-5")
semforaVersion            — output of `semfora-engine --version`
projectDetails.languages  — ["Rust", "Python", etc.]
projectDetails.estimatedSize — "small" / "medium" / "large" / "10K files"
projectDetails.additionalContext — anything relevant
semforaToolUsed           — the command/tool name (e.g. "search", "query overview")
toolPurpose               — what you were trying to do
details                   — exact command, expected vs actual output

License

MIT