Reverse Engineering Knowledge Base MCP Server

This repository hosts a production-ready Model Context Protocol (MCP) server that exposes the Reverse Engineering Knowledge Base (RE KB) workflow over both SSE and FastMCP transports. It ships with all of the infrastructure that MCP clients expect—deterministic envelopes, guarded transports, and structured logging—plus a complete toolchain for creating, validating, and exporting RE KB artifacts from anywhere that can speak MCP.

Why it matters

• Purpose-built for RE teams – Work with findings, assets, and analyst notes through a consistent schema that can be bootstrapped in any repository.
• Ready for modern MCP clients – Supports FastMCP stdio, Server-Sent Events, and the included OpenWebUI shim without any extra plumbing.
• Drop-in extensibility – Keep the RE KB core tools and register additional automation via simple backend modules.

Key capabilities

RE KB workflow tooling

• Initialize .re_kb/ directories and seed canonical JSON Schemas.
• Create, list, and update findings, research threads, and assets via MCP tools.
• Export schemas or derived indices for downstream automation.
• Concurrent-safe ID allocation with cross-platform file locking.
• Automatic schema migrations for backward-compatible data evolution.
• Automatic project discovery - stdio mode auto-discovers projects from CWD, SSE mode supports token-based auto-binding.
• Web UI for human review - Built-in read-only interface at /re_kb/ with filterable findings table, search, and detailed views.

Transport & safety features

• Deterministic {ok,data,errors} HTTP envelopes and JSON logging for audits.
• Guarded SSE endpoint with readiness gates to prevent concurrent consumers.
• Environment-driven rate limits (MCP_MAX_*) and write toggles (MCP_ENABLE_WRITES).
• Unified error handling with structured error codes and MCP integration.

Extensibility surface

• Runtime discovery of modules in bridge/backends/ through a shared FastMCP instance.
• Example backend (bridge/backends/example.py) that demonstrates registering a custom tool.

Quickstart

Choose your transport based on your MCP client:

SSE over HTTP (Claude Code, aider-desk, web clients)

# Quick start - creates venv if needed, auto-reload enabled
./bin/dev

Or manually:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
uvicorn bridge.app:create_app --factory --host 127.0.0.1 --port 8000

Verify the server:

curl -s http://127.0.0.1:8000/api/ping.json | jq
curl -s http://127.0.0.1:8000/api/version.json | jq

Connect your MCP client to:

• SSE transport: http://127.0.0.1:8000/sse
• SSE with auto-binding: http://127.0.0.1:8000/sse?token=<session_token> (token generated during rekb init)
• Messages transport: http://127.0.0.1:8000/messages

Note: Only one SSE consumer can be active at a time; additional connections are rejected with HTTP 409.

New in Phase 2: rekb init now generates .mcp.json and .mcp-stdio.json configuration files with session tokens for automatic project binding. See docs/re_kb_workflow.md for details.

stdio (Codex and stdio-based MCP clients)

# Ensure venv is set up first (./bin/dev creates it automatically)
PYTHONPATH=. python scripts/bridge_stdio.py --transport stdio

This mode communicates via stdin/stdout for process-based MCP clients.

Automatic Project Discovery (stdio): When running in stdio mode, the server automatically discovers RE KB projects by walking up the directory tree from the current working directory to find .re_kb/project.json. If not found via CWD, it falls back to the REKB_PROJECT_ROOT environment variable. This eliminates the need for manual project selection in most cases.

Custom directory names: The knowledge base lives in .re_kb/ by default, but you can change the directory name with REKB_DIRNAME (or the backward-compatible alias RE_KB_DIRNAME, plus CLI flags on rekb commands). Both the server and CLI tools will read and write under the renamed folder and still honour REKB_PROJECT_ROOT when you need to pin the project root manually.

Follow the RE KB workflow

The repository bundles a complete guide and fixtures for running the RE KB workflow end-to-end:

1. Walk through docs/re_kb_workflow.md to bootstrap .re_kb/, use the select_this_project.sh helper, export JSON Schemas, and exercise every tool.
2. Copy the reference fixture under docs/examples/minimal_re_kb/ when you need a known-good sandbox.
3. Consult docs/re_kb_ghidra.md for Ghidra-specific automation ideas.

Configuration

Runtime behaviour is driven by environment variables. Common settings include:

Variable	Description	Default
MCP_ENABLE_WRITES	Allow write-capable tools to run	false
MCP_MAX_WRITES_PER_REQUEST	Maximum writes allowed per MCP request	2
MCP_MAX_ITEMS_PER_BATCH	Maximum batch size enforced by enforce_batch_limit	256
MCP_AUDIT_LOG	Optional path to a JSONL audit log file	unset
REKB_DIRNAME / RE_KB_DIRNAME	Override the knowledge base directory name (single path component)	.re_kb
REKB_PROJECT_ROOT	Override project root for stdio auto-discovery	unset
REKB_ACTIVE_TTL_SECONDS	Active project cache lifetime for SSE mode. Ignored in stdio mode (no timeout).	300 (5 minutes)
RE_KB_TRANSPORT	Override transport mode detection ("stdio" or "sse")	unset

For a deeper walkthrough plus .env conventions, read docs/configuration.md.

HTTP API surface

Route	Description
GET /api/ping.json	Health check returning {"pong": true}
GET /api/version.json	Semantic version of this server
GET /api/state	Diagnostics about SSE readiness and active connections
GET /api/openapi.json	Generated OpenAPI document for the registered routes
GET /sse	MCP SSE transport (single active connection; optionally accepts ?token=... for auto-binding)
POST /messages	FastMCP message transport

MCP Tools Quick Reference

Read-Only Tools (no writes required)

Tool	Purpose	Example Args
list_findings	List all findings with optional filters	{"filters": {"status": "open", "type": "vuln"}}
get_finding	Retrieve a specific finding by ID	{"id": "finding-0001"}

Write Tools (requires MCP_ENABLE_WRITES=1)

Tool	Purpose	Example Args
create_finding	Create a new finding with auto-generated ID	{"data": {"project_id": "proj", "type": "vuln", "title": "...", "summary": "...", "raw_note": "..."}}
update_finding	Update an existing finding (partial updates supported)	{"id": "finding-0001", "patch": {"status": "verified", "raw_note": null}}
attach_evidence	Add evidence to an existing finding	{"finding_id": "finding-0001", "evidence": {"source_type": "ghidra", ...}}
rebuild_index	Regenerate index.json from all findings	{}

New: Findings now support an optional raw_note field (32KB max) for unstructured analysis alongside the structured summary (2048 chars max). See docs/re_kb_workflow.md for workflow guidance.

Extending the server

Add backend modules to bridge/backends/ and implement register(server: FastMCP). Each module receives the shared FastMCP instance and can register additional tools, resources, or prompts alongside the RE KB bundle. Refer to docs/extend.md for deeper guidance.

Development & operations

Run the development helper to spin up the server and regenerate schemas:

./bin/dev              # creates .venv if necessary and starts the server
./bin/dev workflow init --root /path/to/repo   # bootstraps .re_kb/ with sample data
./bin/dev schema --root /path/to/repo   # export RE KB JSON Schemas

Set MCP_ENABLE_WRITES=1 when running ./bin/dev to allow the workflow helper and RE KB tools to write files under the target repository.

Run the test suite with pytest once your environment is active. The project includes comprehensive tests for:

• Cross-platform file locking (concurrent ID allocation)
• Error handling (structured exceptions, MCP integration)
• Schema versioning and migrations
• Evidence normalization and transformations

To observe the SSE guard in action, connect twice:

curl -iN http://127.0.0.1:8000/sse
curl -i http://127.0.0.1:8000/sse   # returns HTTP 409 while the first stream is active

Next steps

• docs/getting-started.md – opinionated setup guide that links to compatible clients.
• docs/overview.md – architecture and component map.
• docs/re_kb_workflow.md – step-by-step RE KB workflow.
• docs/extend.md – extending the MCP server with new tooling.

License

This project is distributed under the terms of the MIT License. See LICENSE for details.