engineering-board MCP server

A zero-dependency Model Context Protocol server that exposes the engineering-board plugin's markdown board as MCP tools. It lets any MCP client (Claude Code, Claude Desktop, …) scaffold boards, create/list/update entries, preview and promote scratch findings, manage stable pattern identities, rank provenance-linked clusters, preserve durable root-cause hypotheses and rejected-claim memory, and claim/release entry locks — all against the exact on-disk format the plugin's hooks and skills expect.

Design constraints

• Pure python3, zero third-party dependencies. No mcp pip SDK, no pydantic. The MCP stdio/JSON-RPC protocol is implemented directly, so the server runs under the same bash + python3 + coreutils toolchain as the rest of the plugin (CI has no install step).
• Transport: stdio, JSON-RPC 2.0, newline-delimited messages, protocolVersion 2025-06-18. Only JSON-RPC messages go to stdout; diagnostics go to stderr.
• Locking is not reimplemented — board_claim / board_release shell out to the plugin's existing hooks/scripts/board-claim-acquire.sh / board-claim-release.sh.
• Timestamps are real UTC ISO-8601 (second precision) via datetime.now(timezone.utc).

The board location for a project is resolved via engineering-board/BOARD-ROUTER.md (then the pre-1.1.0 docs/boards/BOARD-ROUTER.md compat path), falling back to engineering-board/<project>/. The repo root defaults to $CLAUDE_PROJECT_DIR, then the current working directory, and can be overridden per-call with a root argument.

Tools

All 17 tools use the same canonical Markdown format. Pattern, promotion, graph, ranking, and hypothesis behavior delegates to the same zero-dependency core used by the plugin.

Configuration

The server is published to PyPI as engineering-board-mcp (available with the v1.7.0 release), so the primary install is one uvx line — no clone, no absolute path. The clone path still works everywhere and is the fallback.

Note (PyPI installs): board_claim / board_release shell out to the plugin's hooks/scripts/board-claim-*.sh, which the PyPI package does not ship; on a PyPI install those two tools return a clean error unless the plugin (or a repo clone) is present. All other tools are self-contained.

Claude Code (CLI)

# primary — uvx (available with the v1.7.0 release)
claude mcp add engineering-board -- uvx engineering-board-mcp

Fallback — run from a clone:

git clone https://github.com/GhostlyGawd/engineering-board
claude mcp add engineering-board -- python3 "$(pwd)/engineering-board/mcp-server/engineering_board_mcp.py"

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.engineering-board]
command = "uvx"
args = ["engineering-board-mcp"]

Or one line: codex mcp add engineering-board -- uvx engineering-board-mcp.

Gemini CLI

Add to ~/.gemini/settings.json (or per-project .gemini/settings.json):

{
  "mcpServers": {
    "engineering-board": {
      "command": "uvx",
      "args": ["engineering-board-mcp"]
    }
  }
}

Or one line: gemini mcp add engineering-board uvx engineering-board-mcp.

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json in the project:

{
  "mcpServers": {
    "engineering-board": {
      "command": "uvx",
      "args": ["engineering-board-mcp"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "engineering-board": {
      "command": "uvx",
      "args": ["engineering-board-mcp"]
    }
  }
}

(Clone fallback: "command": "python3", "args": ["/abs/path/to/engineering-board/mcp-server/engineering_board_mcp.py"].)

Bundled with the plugin (automatic)

Installing the engineering-board plugin auto-registers this server via the repo-root .mcp.json, which resolves the script through ${CLAUDE_PLUGIN_ROOT}:

{
  "mcpServers": {
    "engineering-board": {
      "command": "python3",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp-server/engineering_board_mcp.py"]
    }
  }
}

No separate install step is needed when the plugin is installed.

Distribution channels

The server ships from this repo tree (it shells out to sibling hooks/scripts/board-claim-*.sh for locking; every other tool is self-contained). Beyond cloning the repo, the packaged channels:

• PyPI (engineering-board-mcp) — the uvx one-liner above. Published from v1.7.0 by the release workflow via PyPI trusted publishing (OIDC, no stored secret); pyproject.toml is the package manifest.
• MCP bundle (.mcpb) — bash mcp-server/build-mcpb.sh produces dist/engineering-board-mcp.mcpb, a self-contained bundle (server + the hook scripts it calls + manifest.json) for one-click install in MCP-bundle-aware clients. The bundle is a release asset, not committed source.
• MCP Registry — live — published as io.github.GhostlyGawd/engineering-board; server.json is the registry manifest, pointing at the .mcpb release asset. Listings auto-syndicate to PulseMCP / Glama / mcp.so.
• Smithery — smithery.yaml describes the stdio launch for smithery mcp publish.

server.json, manifest.json, and smithery.yaml are version-locked to plugin.json and validated by the MCP test suite so they cannot silently drift.

Multi-client: two clients, one board

Driving the same board from two MCP clients simultaneously (e.g. Claude Code and Claude Desktop) is supported and CI-proven (eb-self Q001): the test suite spawns two independent server processes on one board and races them for the same entry's claim — exactly one acquires (exit_code 0), the other sees clean contention (exit_code 1), and after the winner releases, the loser can acquire. Canonical reads hit the same committed Markdown. The graph accelerator is disposable, source-fingerprinted, and ignored by Git; stale or corrupt cache state falls back to a full rebuild. Locking is the plugin's atomic mkdir claim protocol. Use distinct session_ids per client (each client's claims are owned by its session id).

Tests

bash mcp-server/run-tests.sh

test_mcp_server.py (pure python3, no deps) runs two suites:

1. A real end-to-end stdio session — spawns the server as a subprocess and drives initialize → notifications/initialized → tools/list → several tools/call, asserting on the JSON-RPC responses (including -32601/-32602 error paths).
2. A full board lifecycle in a temp repo — board_init → board_create_entry (bug + question + feature + learning) → board_list_entries → board_update_entry → board_rebuild → board_status → board_capture_finding → board_claim / board_release, asserting every created file passes the real hooks/scripts/board-validate-entry.sh.

Exit 0 on all-pass; non-zero with detail on the first failure.

Notes

• The server never writes to stdout except JSON-RPC responses (a hard MCP requirement).
• Entry filenames are <ID>-<kebab-slug>.md (e.g. B001-export-drops-final-row.md).
• board_create_entry and board_update_entry rebuild BOARD.md as their final step so a freshly written entry's id is always present in the index (which board-validate-entry.sh checks).