🗺️ 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.

---

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 <repo>/.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)

# 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
```mermaid
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.

---

🏗️ Architecture

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

graph TD
    Host["MCP Host<br/>(Claude Code / Codex)"] -->|stdio JSON-RPC| Program["Program.cs<br/>MCP stdio host"]
    Program --> Tools["CodeboardingTools<br/>status · map · get · configure"]

    Tools -->|cheap, no LLM| Drift["Fingerprint + DriftCalculator<br/>Roslyn surface hash"]
    Tools -->|read map| Reader["AnalysisReader<br/>analysis.json → md + mermaid"]
    Tools -->|persist config / baseline| Manifest["RepoManifest<br/>.codeboarding/.manifest.json"]
    Tools -->|expensive, LLM| Runner["CodeboardingRunner<br/>shells out to the CLI"]

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

    Env -.-> Ollama["Ollama (local)"]
    Env -.-> Anthropic["Anthropic"]
    Env -.-> OpenAI["OpenAI-compatible<br/>DeepSeek · OpenRouter · LiteLLM"]

Loading

---

🚀 Quick start

1. Prerequisites

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

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

• An LLM backend — either local Ollama:

  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 <repo>/.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 <repo>/.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

• 4 MCP tools, Roslyn drift, generic provider, single-provider env scrubbing
• 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. Built on CodeBoarding (MIT) — please ⭐ them too.

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