Context Crafter MCP

[]

Local-first MCP server that turns source repositories into compact AI-agent context: project overviews, repo maps, dependency graphs, architecture notes, and validation reports.

What it generates

Quick start

Requires Python 3.11+ and uv.

From a repo checkout

git clone https://github.com/0langa/context-crafter-mcp.git
cd context-crafter-mcp
uv sync --extra dev
uv run context-crafter-mcp --help

From the published package

Current release is 1.0.0, published to PyPI as context-crafter-mcp.

uv tool install context-crafter-mcp
context-crafter-mcp --help

Or run it without installing:

uvx context-crafter-mcp --help

From a built wheel

If you need an unpublished revision, build and install locally:

uv build
uv tool install --from dist/context_crafter_mcp-*.whl context-crafter-mcp
context-crafter-mcp --help

For MCP clients, the published-package path uses uvx:

{
  "mcpServers": {
    "context-crafter": {
      "command": "uvx",
      "args": ["context-crafter-mcp", "serve"]
    }
  }
}

Run a self-test against the current directory (uses a temp directory by default):

uv run context-crafter-mcp self-test .

Generate context docs for any repository:

uv run context-crafter-mcp generate /path/to/repo --output docs/generated --profile standard

On Windows:

uv run context-crafter-mcp generate C:\path\to\repo --output docs\generated --profile standard

Validate the generated output:

uv run context-crafter-mcp validate docs/generated

Profiles

Use as a plugin

The repository is also a plugin-forge plugin for Claude Code, Codex, and Kimi Code. The plugin bundles the MCP server with two skills and a slash command, so the agent knows when to reach for the tools instead of only how.

Install it into every provider with plugin-forge. From a plugin-forge checkout:

uv run forge install --path /path/to/context-crafter-mcp --provider all

Add --dry-run first to see the three target directories without writing anything. Agents with the plugin-forge MCP server configured can call its install tool instead.

The plugin runs the server from the checkout (uv run --project <plugin root>), so it does not depend on the published package. forge.yaml is the source of truth; the provider manifests (.claude-plugin/plugin.json, .codex-plugin/plugin.json, kimi.plugin.json, .mcp.json, .codex-mcp.json) are compiled from it and should not be hand-edited.

Use with MCP clients

Fastest path

Claude Code and Codex both register the server for you:

claude mcp add context-crafter -- uvx context-crafter-mcp serve
codex mcp add context-crafter -- uvx context-crafter-mcp serve

Config snippets

For clients without an mcp add command, generate a client-specific snippet:

uv run context-crafter-mcp mcp-config --client kimi

Supported clients: claude-desktop, claude-code, kimi, cline, roo, vscode, codex, generic-stdio.

The snippet is emitted in the format that client actually reads. codex gets TOML; every other client gets JSON.

Published package config

Clients that read JSON use the same stdio config when installed via uvx:

{
  "mcpServers": {
    "context-crafter": {
      "command": "uvx",
      "args": ["context-crafter-mcp", "serve"]
    }
  }
}

Codex reads ~/.codex/config.toml, so it gets the same server as a TOML table:

[mcp_servers.context-crafter]
command = "uvx"
args = ["context-crafter-mcp", "serve"]

Local development config

Point to the repo checkout directly:

uv run context-crafter-mcp mcp-config --client claude-desktop --repo /path/to/this/repo

Client placement

MCP Inspector

Test the server with the MCP Inspector:

npx @modelcontextprotocol/inspector uv run context-crafter-mcp serve

For local repo inspection:

npx @modelcontextprotocol/inspector uv --directory /path/to/this/repo run context-crafter-mcp serve

MCP tools

• detect_project — detect stacks for a repo path
• generate_context — generate 9 required Markdown files plus DEPENDENCY_GRAPH.mmd, EVIDENCE_LEDGER.json, CONTEXT_MANIFEST.json, and RUN_STATE.json
• generate_project_overview
• generate_repo_map
• generate_dependency_graph
• generate_architecture_summary
• validate_generated_context
• explain_capabilities

MCP resources

After generate_context, generated files are exposed as context-crafter://latest/<filename> resources. Only files from the current session are readable; arbitrary local paths are denied. Resources are advertised with file-appropriate MIME types, including text/markdown, text/vnd.mermaid, application/json, and text/html for optional HTML output.

Generation results also report resolved_output_dir. If the requested output_dir would escape the repository root, output is confined to docs/generated.

Example output

See examples/outputs/ for real generated files from the demo repository.

Quick preview of AGENT_BRIEF.md:

• Entry points: src/context_crafter_mcp/cli.py, src/context_crafter_mcp/server.py
• Stacks: Python (MCP server, LangGraph pipeline, static analyzers)
• Key dependencies: mcp, langgraph, pydantic

What makes this different

Safety model

• Read-only analysis — never executes code in the target repository.
• Output confined to repo — output_dir is resolved and validated so it cannot escape the repository root.
• Resolved path reported — generation JSON explicitly reports the actual output directory used after confinement.
• No network — no HTTP calls, no model inference, no API keys.
• Bounded scans — depth, file count, and file size limits with safe defaults.
• No symlinks followed — prevents infinite loops and directory escaping.
• No stdout logging in MCP mode — stdio protocol is protected from corrupting output.
• Basic secret awareness — flags potential secret files (.env, credentials.json) in scan reports.

See SECURITY.md for the full threat model and reporting process.

Supported stacks

Trust bar note: Python, Node/TypeScript, Go, and Rust have the highest real-repo smoke coverage. Java and .NET are supported and tested on fixtures, but their analysis depth has not yet reached the same hardening standard.

Install deeper parser support:

uv sync --extra parsers

Architecture

• Scanner boundary — Scanner.scan(root, options) -> RepoSnapshot. Everything above the scanner consumes RepoSnapshot, making the scanner replaceable without changing analyzers.
• Python product layer — MCP server, CLI, analyzers, and renderers are Python. A lower-level scanner (Rust/Go) is only considered if benchmarks prove Python traversal is the bottleneck.
• LangGraph pipeline — validate_repo -> detect -> scan -> analyze -> render.
• Analyzer registry — AnalyzerRegistry with register, detect, analyze, merge. Language analyzers run based on detected project types.
• Parser abstraction — ParserBackend protocol with concrete implementations (Tree-sitter, javalang, stdlib AST, regex fallback).
• Enriched snapshot — SnapshotFile carries extension, language_hint, and is_text for richer analysis.

See docs/adr/0001-python-product-layer-replaceable-scanner.md.

Development

uv sync --extra dev
uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest -q
uv run context-crafter-mcp self-test .

See CONTRIBUTING.md.

Limitations

See docs/REAL_REPO_SMOKE_MATRIX.md for the current pre-1.0.0 hardening confidence set.

License

MIT. See LICENSE.