Error-Book MCP Server

Error-Book MCP delivers the goal_need.md rulebook and an error playbook over the Model Context Protocol. It is designed to feel like popular "install and it just works" servers: run it once, plug it into Claude Desktop/Code (or any MCP client), and immediately query or extend your rules.

Quick Start

# 1) Run directly with npx (no global install)
npx -y error-book-mcp

# 2) Or install globally
npm i -g error-book-mcp
error-book-mcp

By default the server uses the packaged rules and starts in stdio mode. Register it in Claude Desktop by adding:

{
  "mcpServers": {
    "error-book": {
      "command": "error-book-mcp"
    }
  }
}

To use the NPX invocation instead, set command: "npx" and args: ["-y", "error-book-mcp"].

CLI Flags

| Flag | Description | | ---- | ----------- | | --rules <path> | Override the rules directory. Defaults to the first existing path among CLI flag, RULES_DIR, ~/.error-book-mcp/rules, or packaged rules. | | --data-dir <path> | Override the writable data directory (defaults to ~/.error-book-mcp). Error history and --init output land here. | | --enable-write | Allow playbook appends and error-history writes. Without this flag the server is read-only. | | --init | Copy the packaged rules into the data directory for editing. Existing files are preserved. | | --port <number> | Port for HTTP mode (defaults to 8787). | | --http-path <path> | Serve HTTP transport at an alternate path (default /mcp). | | --http-host <host> | Hostname/interface to bind when using HTTP (default 127.0.0.1). |

Environment variables mirror the key options:

• RULES_DIR
• ERROR_BOOK_DATA_DIR
• MCP_TRANSPORT (stdio or http)
• MCP_HTTP_PATH, MCP_HTTP_HOST, PORT

MCP Tools

| Tool | Purpose | | ---- | ------- | | list_sections | Enumerate section metadata extracted from rules/initial.md (H2/H3 mapped to IDs). | | read_rule | Return the full text for a given section ID. | | search_rule | Lightweight keyword search across titles and bodies. | | read_playbook | Read an entry inside rules/error_playbook.yaml by ID. | | append_playbook_entry | Validate and append YAML entries (requires --enable-write and non-packaged rules). | | record_error / get_error_history / clear_error_history | Manage a persistent error log stored in the data directory. | | build_prompt | Emit the compact prompt derived from goal_need.md, optionally augmented with recent error summaries. | | reload_rules | Manually refresh the Markdown index from disk. |

Error History

Errors are written to error-history.json inside the data directory. The history is append-only, truncated to the latest 200 entries, and only persisted when --enable-write is set. Use build_prompt with variant = "with_error_history" to produce a prompt that includes a compact summary of the most recent issues?helpful for token reduction when fixing repeated mistakes.

HTTP Transport

Set MCP_TRANSPORT=http (or add --transport http via CLI) to expose a Streamable HTTP endpoint. The server listens on http://127.0.0.1:8787/mcp by default.

MCP_TRANSPORT=http error-book-mcp --port 9000 --enable-write
# ? register the URL with Claude: claude mcp add --transport http error-book http://127.0.0.1:9000/mcp

Requests from other hosts are rejected unless you override --http-host. Write operations remain gated behind --enable-write in HTTP mode.

Project Layout

src/
  indexer.ts         # Markdown section parser + index builder
  errorLog.ts        # Persistent error history store
  prompts.ts         # Prompt generation (base + error appendix)
  server.ts          # CLI entry point and MCP server wiring
rules/
  initial.md         # Bundled rulebook derived from goal_need.md
  error_playbook.yaml# Sample playbook entries
goal_prompt/
  base.md            # Compact prompt mirroring goal_need.md priorities
  error_appendix.md  # Template inserted when including error history
goal_need.md         # Canonical long-form goal/plan document

Development

npm install
npm run dev   # uses tsx for hot reloading
npm run build # tsc -> dist/server.js

npm run dev respects CLI flags, so you can test variations like npm run dev -- --enable-write. Run npm run build before publishing to ensure the TypeScript output is up to date.

Packaging Notes

• Package name: error-book-mcp (see package.json).
• files whitelist ensures only compiled output, default rules, and prompt templates are included.
• Writing to packaged rules is blocked; run --init once to produce an editable copy beneath the data directory.
• The repository ships with a sample playbook and rulebook?extend or replace them as needed.

Related Docs

• goal_need.md ? authoritative goals, success criteria, and roadmap.
• goal_prompt/base.md ? token-friendly prompt to feed MCP clients or agents.
• goal_prompt/error_appendix.md ? template used by build_prompt when including error history.

Feel free to open issues or tweak the rulebook to match your workflow?the server is built to stay out of your way once installed.