peopleworks/codeboarding-mcp
GitHub: peopleworks/codeboarding-mcp
一个 MCP 服务器，为代码库提供无需 LLM 的低成本架构偏移检测，仅在发生结构性变更时按需重新生成架构映射图。
Stars: 1 | Forks: 0
# 🗺️ codeboarding-mcp
### 为你的代码库提供活态架构文档 —— 作为一个 MCP 服务器。
*低成本检测架构何时**真正**发生了变化 —— 无需 LLM 调用 —— 并仅在变化时重新生成映射。*
[](https://dotnet.microsoft.com/)
[](https://modelcontextprotocol.io)
[](https://github.com/CodeBoarding/CodeBoarding)
[](LICENSE)
[](#-contributing)
[](https://github.com/peopleworks/codeboarding-mcp)
## 存在的问题
代码编写代理或 RAG 的效果取决于它对你代码库的心智模型。**架构文档写完的那一刻就过时了。** 有两种糟糕的选择：
- 🔥 **每次提交都重新生成映射** → 你得为成千上万次 LLM 运行买单，而绝大多数时候只是为了重新发现*什么结构性变化都没发生*。
- 🧊 **从不重新生成** → 代理只能基于一个已经不存在的代码库进行推理。
[CodeBoarding](https://github.com/CodeBoarding/CodeBoarding) 能够生成精美的架构图（markdown + mermaid），并提供了 CLI、GitHub Action 和 VS Code 插件 —— **但没有 MCP 服务器**，也**无法判断何时值得重新生成映射。**
## 解决方案
`codeboarding-mcp` 将 CodeBoarding CLI 封在一个 [Model Context Protocol](https://modelcontextprotocol.io)（模型上下文协议）服务器中，并补齐了缺失的一环：一个**低成本、无需 LLM 的偏移检测器**。它会为每个仓库的*架构表面*保留一个微小的指纹，只有当该表面的偏移度超过你设定的阈值时，才会触发昂贵的重新映射。
```
┌─────────────┐ cheap, no LLM ┌──────────────┐ expensive, only if stale ┌───────────┐
│ status │ ─────────────────▶ │ map │ ───────────────────────────▶ │ get │
│ drift score │ "is it stale?" │ regenerate │ runs CodeBoarding + LLM │ read map │
└─────────────┘ └──────────────┘ └───────────┘
```
这样做的好处是：**架构文档能够自动保持最新**，在没有任何重要变更时几乎零成本，而一旦发生变更则恰好触发完整的重新映射。将任何 MCP 宿主（Claude Code、Codex 等）指向它，分析就会在**本地**运行 —— 搭配 Ollama，你的代码永远不会离开本机。
## ✨ 核心亮点
- 🧠 **无 LLM 偏移检测** —— 基于 Roslyn 的公共 API 表面指纹。注释和方法体编辑不会影响它，但签名修改会。
- 💸 **仅在关键时付费** —— 当偏移度超过*你的*设定阈值时才重新映射，而不是每次提交都执行。
- 🔌 **提供商无关** —— 本地 **Ollama**（用于私有代码）、**Anthropic**（追求极致质量），或者是**任何兼容 OpenAI** 的端点（DeepSeek、OpenRouter、LiteLLM）。支持按仓库独立配置，配置会被持久化，且绝不存储密钥。
- 🔒 **单提供商隔离** —— 从子进程中清除所有提供商环境变量，然后只精确设置其中一个，确保 CodeBoarding 绝不会因为环境不明确而报错。
- 🧩 **可组合** —— 4 个小工具，代理可在对话过程中随时调用。标准输出极其重要（MCP 协议）；所有日志均输出到 stderr。
## 🛠️ 四大工具
| 工具 | 成本 | 功能描述 |
| --- | --- | --- |
| **`codeboarding_status`** | 🟢 低成本（无 LLM） | 偏移分数 + `stale`（过期）标志 + 建议。请在执行映射*之前*调用它。 |
| **`codeboarding_map`** | 🔴 高成本（使用 LLM） | 运行 CodeBoarding → 将 `analysis.json` 写入 `示例：对从未映射过的仓库执行 codeboarding_status（瞬间完成，零 LLM 成本）
```
{
"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": []
}
```
示例：codeboarding_get 输出（markdown + 从 analysis.json 重建的 mermaid 图表）
```
# CodeBoarding 架构图
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
```
```
(Claude Code / Codex)"] -->|stdio JSON-RPC| Program["Program.cs
MCP stdio host"] Program --> Tools["CodeboardingTools
status · map · get · configure"] Tools -->|cheap, no LLM| Drift["Fingerprint + DriftCalculator
Roslyn surface hash"] Tools -->|read map| Reader["AnalysisReader
analysis.json → md + mermaid"] Tools -->|persist config / baseline| Manifest["RepoManifest
.codeboarding/.manifest.json"] Tools -->|expensive, LLM| Runner["CodeboardingRunner
shells out to the CLI"] Runner --> Env["ProviderEnvironment
scrub-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-compatible
DeepSeek · OpenRouter · LiteLLM"] ``` ## 🚀 快速开始 ### 1. 前置条件 - **.NET 9 SDK**（或更高版本）。 - **Python 3.12 或 3.13** + **CodeBoarding CLI**： pipx install codeboarding --python python3.13 codeboarding-setup # 一次性操作：下载语言服务器 - 一个 **LLM 后端** —— 可以是本地 Ollama： ollama pull qwen2.5-coder:7b ……或者是云提供商的 API 密钥（Anthropic / DeepSeek 等）。 ### 2. 构建 ``` dotnet build src/CodeboardingMcp/CodeboardingMcp.csproj -c Release ``` ### 3. 在你的 MCP 宿主中注册 ``` claude mcp add codeboarding -- \ dotnet /path/to/codeboarding-mcp/src/CodeboardingMcp/bin/Release/net9.0/codeboarding-mcp.dll ``` ### 4. 开始使用 只需询问你的代理 —— 例如： ……或者直接调用工具： ``` configure → status → (if stale) map → get set cheap expensive read map provider check regen only for RAG / per repo when it matters agent ``` ## 🔌 选择提供商 每个仓库都可以选择自己的后端，存储在 `
专为那些渴望了解你代码库真实面貌的代理而打造。
标签：AI风险缓解, LLM辅助开发, MCP服务器, SOC Prime, 代码可视化, 开发工具, 架构文档, 逆向工具