# semfora-error-reporter

An MCP (Model Context Protocol) server for tracking issues with [semfora-engine](https://github.com/Semfora-AI/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:

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

## Setup

### Prerequisites

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

### Install

```bash
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`:

```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:

```bash
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`):

```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`):

```markdown
### 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`):

```markdown
### 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:

```bash
# 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](https://github.com/modelcontextprotocol/servers/tree/main/src/github) 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:

```bash
#!/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