# Codeboarding Mcp

> Living architecture docs as an MCP server - no-LLM drift detection + on-demand CodeBoarding maps for any repo.

- **Type:** MCP server
- **Install:** `agentstack add mcp-peopleworks-codeboarding-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [peopleworks](https://agentstack.voostack.com/s/peopleworks)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [peopleworks](https://github.com/peopleworks)
- **Source:** https://github.com/peopleworks/codeboarding-mcp

## Install

```sh
agentstack add mcp-peopleworks-codeboarding-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🗺️ 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](https://github.com/CodeBoarding/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](https://modelcontextprotocol.io) 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.

```text
   ┌─────────────┐   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)

```json
{
  "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
```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](#-roadmap).

---

## 🏗️ Architecture

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

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

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

### 3. Register with your MCP host

```bash
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:

```text
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 |

```jsonc
// 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](https://github.com/CodeBoarding/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](https://github.com/peopleworks)
- **Source:** [peopleworks/codeboarding-mcp](https://github.com/peopleworks/codeboarding-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-peopleworks-codeboarding-mcp
- Seller: https://agentstack.voostack.com/s/peopleworks
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.