code-failures-mcp

MCP server that indexes your code_failures/ knowledge base and makes it searchable from Claude Code (or any MCP client). Uses BM25 via MiniSearch for fast, relevant keyword search with fuzzy matching.

Why

Every bug you debug for hours becomes institutional knowledge. This MCP server makes that knowledge automatically available to Claude Code so it searches your past fixes before attempting a new solution.

Tools

Tool	Purpose
search_past_bugs	Search bugs by symptom, error message, or library name
search_references	Search canonical working patterns and version guides
search_all_knowledge	Search everything with relevance scores
get_document	Retrieve full content of a specific document
list_documents	List all indexed documents

Setup

cd /Users/tk/Desktop/code-failures-mcp
npm install
npm run build

Configure Claude Code

CLI + Manual Config (recommended)

The claude mcp add CLI doesn't support environment variables via flags, so you need to add the server first, then manually edit the config:

# Step 1: Add the server (global)
claude mcp add code-failures -- node /Users/tk/Desktop/code-failures-mcp/dist/index.js

# Step 2: Edit ~/.claude.json and add the env object to the code-failures server config:
# "env": {
#   "BRAIN_PATH": "/Users/tk/Desktop/brain/code_failures"
# }

# For project-scoped:
claude mcp add -s project code-failures -- node /Users/tk/Desktop/code-failures-mcp/dist/index.js
# Then edit the project's section in ~/.claude.json

Verify with:

claude mcp list

JSON config (alternative)

Manually add to ~/.claude.json (find your project section):

{
  "projects": {
    "/your/project/path": {
      "mcpServers": {
        "code-failures": {
          "type": "stdio",
          "command": "node",
          "args": ["/Users/tk/Desktop/code-failures-mcp/dist/index.js"],
          "env": {
            "BRAIN_PATH": "/Users/tk/Desktop/brain/code_failures"
          }
        }
      }
    }
  }
}

Or for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "code-failures": {
      "command": "node",
      "args": ["/Users/tk/Desktop/code-failures-mcp/dist/index.js"],
      "env": {
        "BRAIN_PATH": "/Users/tk/Desktop/brain/code_failures"
      }
    }
  }
}

CLAUDE.md Integration

Add this to your project's CLAUDE.md to make Claude Code automatically use the knowledge base:

# Global Preferences

- Implement only what's explicitly requested. Prefer minimal changes. No unnecessary features, files, or abstractions.
- Check all related functionality before modifying code — update or verify dependents.
- Before writing a script, check what tools are available via MCP or plugins. Prefer existing tools over bash scripts.
- Always use Context7 MCP (resolve-library-id → get-library-docs) before writing code involving external libraries or frameworks.
- ALWAYS call `search_past_bugs` before debugging any error. Call `search_references` before writing integration code. These check your verified fixes first — prioritize over Context7 and web search.
- After solving a bug that took >15 min: draft Symptom/Root Cause/Fix/Prevention, show me for review, then call `file_bug` to save it.

## Git Workflow

- Commit after each logical unit of work with conventional commit messages (feat:, fix:, refactor:, chore:).
- Do not push unless explicitly asked.
- Work on feature branches, never commit directly to main.

## Self-Improving Project CLAUDE.md

When I correct you on something that represents a recurring pattern or architectural decision (not a one-off typo), propose an update to the project's CLAUDE.md. Follow these rules:

**Before writing, check the existing file.** If a similar rule exists, replace or refine it — never duplicate. If the file exceeds 80 lines, identify a lower-value rule to remove before adding.

**How to write rules:**
1. Use absolute directives — start with NEVER or ALWAYS when appropriate
2. Lead with why (1 sentence max), then the concrete rule
3. Include actual commands or file:line references, not abstract descriptions
4. One code example max per rule. No example if the rule is obvious
5. Bullets over paragraphs. No "Warning Signs" sections for trivial rules

**When to update:** Only for corrections that would apply to future sessions — patterns, conventions, architectural decisions, recurring tool preferences. Not for one-off fixes, typos, or task-specific context.

**Two-tier structure:** If the project CLAUDE.md has a summary section at the top, add a one-line summary there and the detailed rule in the appropriate section below.

If the correction is about a library bug or integration pattern (not project-specific), use `file_bug` or `file_reference` instead of updating CLAUDE.md.

After proposing the update, wait for my approval before writing to the file.

Test with MCP Inspector

npm run inspect

This opens the MCP Inspector UI where you can test each tool interactively.

How Indexing Works

On startup, the server:

1. Recursively finds all .md files under BRAIN_PATH
2. Parses YAML frontmatter for metadata (type, library, tags, severity, status)
3. Extracts structured sections (Symptom, Root Cause, Fix, Prevention) from bug files
4. Builds a BM25 index with field boosting:
   • symptom × 3.0 (highest — you search by what you see)
   • title × 2.5
   • library × 2.0
   • rootCause × 1.5
   • tags × 1.5
   • fix × 1.0
   • fullText × 1.0 (fallback for anything else)
5. Enables fuzzy matching (0.2 edit distance) and prefix search
6. Watches the directory for changes and auto-rebuilds

Adding New Bugs

Follow the format in your existing knowledge base:

# Create a new bug file
touch /Users/tk/Desktop/brain/code_failures/bugs/<library>-<short-description>.md

Template:

---
type: bug
library: <library name>
versions_affected: "<version range>"
status: confirmed
severity: critical|high|medium|low
tags:
  - tag1
  - tag2
---

# BUG: Short Description

## Symptom
What you see (error messages, behavior)

## Root Cause
Why it happens

## Fix
Working code

## Prevention
How to avoid it

The index auto-rebuilds when files change.