Codeboarding Mcp

🗺️ codeboarding-mcp

Living architecture docs for your codebase — as an MCP server.

Detect when your architecture actually changed — cheaply, with no LLM call — and regenerate the map only then.

[](https://dotnet.microsoft.com/) [](https://modelcontextprotocol.io) [](https://github.com/CodeBoarding/CodeBoarding) [](LICENSE) [](#-contributing) [](https://github.com/peopleworks/codeboarding-mcp)

---

The problem

A coding agent or RAG is only as good as its mental model of your codebase. Architecture docs go stale the moment they're written. Two bad options:

• 🔥 Regenerate the map on every commit → you pay for an LLM run thousands of times, mostly to re-discover that nothing structural changed.
• 🧊 Never regenerate → the agent reasons about a codebase that no longer exists.

CodeBoarding generates beautiful architecture maps (markdown + mermaid) and ships a CLI, a GitHub Action, and a VS Code extension — but no MCP server, and no way to know when a remap is even worth it.

The solution

codeboarding-mcp wraps the CodeBoarding CLI in a Model Context Protocol server and adds the missing piece: a cheap, no-LLM drift detector. It keeps a tiny fingerprint of each repo's architectural surface and only triggers an expensive remap when that surface shifts past a threshold you control.

   ┌─────────────┐   cheap, no LLM    ┌──────────────┐   expensive, only if stale   ┌───────────┐
   │   status    │ ─────────────────▶ │     map      │ ───────────────────────────▶ │    get    │
   │ drift score │   "is it stale?"   │  regenerate  │   runs CodeBoarding + LLM     │  read map │
   └─────────────┘                    └──────────────┘                               └───────────┘

The payoff: architecture documentation that stays fresh on its own, at near-zero cost when nothing important changed — and a full remap exactly when it does. Point any MCP host (Claude Code, Codex, …) at it and the analysis runs locally — with Ollama, your code never leaves the machine.

---

✨ Highlights

• 🧠 No-LLM drift detection — a Roslyn-based fingerprint of your public API surface. Comment and method-body edits don't move it; signature changes do.
• 💸 Pay only when it matters — remap when drift crosses your threshold, not on every commit.
• 🔌 Provider-agnostic — local Ollama (private code), Anthropic (top quality), or any OpenAI-compatible endpoint (DeepSeek, OpenRouter, LiteLLM). Per-repo, persisted, keys never stored.
• 🔒 Single-provider isolation — scrubs every provider env var from the child process, then sets exactly one, so CodeBoarding never errors on an ambiguous environment.
• 🧩 Composable — 4 small tools any agent can call mid-conversation. Stdout is sacred (MCP protocol); all logs go to stderr.

---

🛠️ The four tools

| Tool | Cost | What it does | | --- | --- | --- | | codeboarding_status | 🟢 cheap (no LLM) | Drift score + stale flag + a recommendation. Call this before mapping. | | codeboarding_map | 🔴 expensive (LLM) | Runs CodeBoarding → writes analysis.json to /.codeboarding/; updates the drift baseline on success. | | codeboarding_get | 🟢 cheap | Reads the map back — parses analysis.json into a markdown overview + a rebuilt mermaid graph, or drills into one component. | | codeboarding_configure | 🟢 cheap | Sets a repo's LLM provider, model, and drift threshold (persisted in the manifest). |

Example: codeboarding_status on a never-mapped repo (instant, zero LLM cost)

{
  "repoPath": "/path/to/repo",
  "stale": true,
  "neverMapped": true,
  "driftScore": 1,
  "threshold": 0.15,
  "reason": "No prior map — a full analysis is needed.",
  "recommendation": "Run codeboarding_map with mode=\"full\".",
  "provider": "Ollama · qwen2.5-coder:7b",
  "totalComponents": 13,
  "added": ["src/.../Fingerprint.cs", "src/.../CodeboardingTools.cs", "..."],
  "removed": [],
  "changed": []
}

Example: codeboarding_get output (markdown + a mermaid graph rebuilt from analysis.json)

````markdown

CodeBoarding architecture map

A sample service that ingests records, validates them, and persists results.

Components (3)

Ingestor

Reads incoming records from the source and hands them to the Validator.

Validator

Checks record shape and business rules; rejects bad input.

Record Store

Persists validated records and exposes them for query.

Relations

graph LR
    C0["Ingestor"]
    C1["Validator"]
    C2["Record Store"]
    C0 -->|"sends records to"| C1
    C1 -->|"writes to"| C2

````

---

🧬 How drift detection works

codeboarding-mcp builds a per-file architectural surface hash — cheaply, without an LLM — and compares it against the last-mapped baseline. The drift score is simply changed components / union, and a repo is stale once that score reaches your threshold (default 0.15).

| File type | What counts as a change | | --- | --- | | C# (.cs) | public / protected / internal type & member signatures (via Roslyn). Comments and method bodies are ignored — only the API surface moves the hash. | | Dependency manifests (*.csproj, package.json, requirements.txt, go.mod, Cargo.toml, pom.xml, …) | full content hash — dependency changes are architectural. | | Other source files | path-only hash — add / remove / rename counts; content edits don't (yet). |

> v1 note: true API-surface drift is C#-only today. Other languages use a structural (path) signal — a stronger exported-symbol extractor is on the [roadmap](#-roadmap).

---

🏗️ Architecture

A self-referential taste of what CodeBoarding maps — here's codeboarding-mcp itself:

graph TD
    Host["MCP Host(Claude Code / Codex)"] -->|stdio JSON-RPC| Program["Program.csMCP stdio host"]
    Program --> Tools["CodeboardingToolsstatus · map · get · configure"]

    Tools -->|cheap, no LLM| Drift["Fingerprint + DriftCalculatorRoslyn surface hash"]
    Tools -->|read map| Reader["AnalysisReaderanalysis.json → md + mermaid"]
    Tools -->|persist config / baseline| Manifest["RepoManifest.codeboarding/.manifest.json"]
    Tools -->|expensive, LLM| Runner["CodeboardingRunnershells out to the CLI"]

    Runner --> Env["ProviderEnvironmentscrub-all → set one provider"]
    Runner -->|child process| CLI["codeboarding CLI(Python)"]
    CLI -->|writes| Analysis["analysis.json"]
    Reader -->|reads| Analysis

    Env -.-> Ollama["Ollama (local)"]
    Env -.-> Anthropic["Anthropic"]
    Env -.-> OpenAI["OpenAI-compatibleDeepSeek · OpenRouter · LiteLLM"]

---

🚀 Quick start

1. Prerequisites

• .NET 9 SDK (or newer).
• Python 3.12 or 3.13 + the CodeBoarding CLI:

``bash pipx install codeboarding --python python3.13 codeboarding-setup # one-time: downloads language servers ``

• An LLM backend — either local Ollama:

``bash ollama pull qwen2.5-coder:7b `` …or an API key for a cloud provider (Anthropic / DeepSeek / …).

2. Build

dotnet build src/CodeboardingMcp/CodeboardingMcp.csproj -c Release

3. Register with your MCP host

claude mcp add codeboarding -- \
  dotnet /path/to/codeboarding-mcp/src/CodeboardingMcp/bin/Release/net9.0/codeboarding-mcp.dll

> If the CodeBoarding CLI isn't on PATH, point to it with the CODEBOARDING_CLI environment variable.

4. Use it

Just ask your agent — for example:

> "Configure codeboarding for this repo with Ollama, check if the map is stale, and update it if so."

…or call the tools directly:

configure  →  status  →  (if stale) map  →  get
   set         cheap        expensive       read map
 provider      check        regen only      for RAG /
 per repo                  when it matters    agent

---

🔌 Choosing a provider

Each repo picks its own backend, stored in /.codeboarding/.manifest.json. API keys are read from a named environment variable and never written to the manifest.

| Kind | Selects | Best for | | --- | --- | --- | | ollama | local Ollama (OLLAMA_BASE_URL) | 🔒 private / client code — nothing leaves the machine | | anthropic | ANTHROPIC_API_KEY | 🏆 public repos, highest-quality maps | | openai-compatible | OPENAI_BASE_URL + key env | 🧩 DeepSeek, OpenRouter, LiteLLM, any proxy |

// codeboarding_configure arguments
{
  "repoPath": "/path/to/repo",
  "kind": "anthropic",            // or "ollama" / "openai-compatible"
  "model": "claude-sonnet-4-6",
  "apiKeyEnv": "ANTHROPIC_API_KEY",
  "driftThreshold": 0.15
}

Adding a new OpenAI-compatible provider (e.g. DeepSeek) is just configuration — no code change.

> Quality caveat (honest): a local 7B model is fast and private but often too weak for clean component extraction (it can fail CodeBoarding's internal validation). For production-grade maps, use a cloud provider on a public repo, or a larger local model. Keep private code on local Ollama and accept the quality trade-off.

---

📂 What gets written

Everything lives under /.codeboarding/:

| Path | Written by | Purpose | | --- | --- | --- | | analysis.json | CodeBoarding CLI | the architecture map (description, components, components_relations) | | .manifest.json | this server | per-repo provider, threshold, and drift baseline | | cache/, logs/, health/, static_analysis.pkl | CodeBoarding CLI | run artifacts |

Add .codeboarding/ to your .gitignore (or commit analysis.json if you want the map in version control).

---

🗺️ Roadmap

• [x] 4 MCP tools, Roslyn drift, generic provider, single-provider env scrubbing
• [x] Parse analysis.json → markdown + rebuilt mermaid in codeboarding_get
• [ ] Stronger non-C# drift (exported-symbol extraction beyond path-only)
• [ ] Auto-triggers (git hook / scheduled sweep) — v1 is in-session / agent-driven
• [ ] CI + published binaries

---

🤝 Contributing

Issues and PRs are very welcome — new language fingerprinters, provider presets, and quality reports are especially appreciated. Please keep stdout clean (MCP protocol) and route all logging to stderr.

📄 License

[MIT](LICENSE). Built on CodeBoarding (MIT) — please ⭐ them too.

Made for agents that deserve to know what your codebase actually looks like.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: peopleworks
• Source: peopleworks/codeboarding-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.