How I built an MCP server to enforce structured bug-fixing for AI agents

If you use AI coding agents like Claude Code or Cursor, you’ve hit this wall:

The agent runs into a framework-specific error. It reads a massive, unstructured raw stack trace. It guesses a fix blindly. Sometimes it hallucinates entirely because it lacks project context. Next week, it hits the exact same error and repeats the exact same blind guesses.

I wanted to stop this chaotic, guess-heavy behavior. I wanted my agents to fix bugs using a disciplined, structured, and evidence-backed workflow.

So I built Moth.

What is Moth?

Moth is a lightweight, open-source Node.js MCP (Model Context Protocol) server. Rather than just tossing error logs to an LLM, Moth intercepts the error and forces the agent into a strict pipeline: analyze → fix → verify → remember.

Moth operates locally in your workspace without massive Vector DB setups or cloud dependencies, exposing exactly two tools to your agent: analyze_error and remember_fix_result.

The "Evidence-Backed" Pipeline

Here is how Moth transforms a blind guess into a structured workflow:

1. Pre-computational Redaction (Safety First) 🔒

Agent logs are often full of sensitive data. Before the LLM even sees the error, Moth parses the local output and scrubs API keys, bearer tokens, DB URLs, and .env formats via strict Regex.

2. Stack Inference & Issue Fingerprinting 🧠

Instead of just parsing strings, analyze_error normalizes a failure. It detects the likely stack (Vite, Next.js, Prisma, TS), strips away variable line numbers, and generates a deterministic fingerprint of the core issue.

3. Structured Fix Briefs 📝

Moth stops the agent from immediately modifying code. It analyzes the context and returns a structured "fix brief." It forces the AI to look at the evidence of the error and formulate a confident "best first fix" strategy based on your project's specific local context.

4. Verified Memory (The Magic Loop) 💾

If the agent attempts the fix, Moth prevents blind logging. A local fix is only recorded to .moth/fix-memory.jsonl if the agent runs a verification command (like npm run build) and explicitly passes a hard passed or failed state back to the tool.

Tomorrow, when the agent hits the same fingerprint, it doesn't need to guess. It pulls the verified, successful solution from its local memory.

Running Moth Locally

Moth is environment-agnostic and relies purely on explicitly provided context. You can spin it up immediately without installation via:

npx -y @stfade/moth moth-mcp

I’ve also included plug-and-play configuration wrappers for Claude Code, Cursor, and Gemini CLI in the repo.

Feedback Wanted!
I built this purely to scratch my own itch—turning chaotic agent debugging into a reliable, evidence-backed workflow.

Are you dealing with agent hallucinations in your local workspace? Check out the repo here and let me know your thoughts on the architecture:
Github: https://github.com/stfade/moth