bntvllnt/codebase-intelligence
GitHub: bntvllnt/codebase-intelligence
TypeScript代码库分析引擎，通过MCP协议为LLM提供深度架构理解和重构决策支持。
Stars: 4 | Forks: 0
# codebase-intelligence
**TypeScript 项目的代码库分析引擎。**
解析您的代码库，构建依赖关系图，计算架构指标，并通过 MCP 查询所有内容，以实现 LLM 辅助的代码理解。
[](LICENSE)
[](https://nodejs.org)
[](https://www.typescriptlang.org)
## 快速开始
### Claude Code (单行命令)
```
claude mcp add -s user -t stdio codebase-intelligence -- npx -y codebase-intelligence@latest .
```
完成。在所有项目中可用。在 Claude Code 中使用 `/mcp` 验证。
若要仅限单个项目：
```
claude mcp add -s project -t stdio codebase-intelligence -- npx -y codebase-intelligence@latest ./src
```
## 目录
- [功能特性](#features)
- [安装](#installation)
- [使用](#usage)
- [MCP 集成](#mcp-integration)
- [指标](#metrics)
- [架构](#architecture)
- [要求](#requirements)
- [限制](#limitations)
- [贡献](#contributing)
- [许可证](#license)
## 功能特性
- **15 个 MCP 工具** — 代码库概览、文件上下文、热点、模块结构、力学分析、死代码导出、符号上下文、搜索、影响分析、重命名规划、流程追踪、社区检测等
- **2 个 MCP 提示词** — detect_impact, generate_map
- **3 个 MCP 资源** — clusters, processes, setup guide
- **11 项架构指标** — PageRank、中介中心性、耦合度、内聚性、张力、变更率、复杂度、爆炸半径、死代码导出、测试覆盖率、逃逸速度
- **符号级分析** — 带有调用方/被调用方的调用图、符号 PageRank、单符号影响分析
- **BM25 搜索** — 通过关键词查找文件和符号，提供排序结果
- **流程追踪** — 检测入口点并通过调用图追踪执行流
- **社区检测** — Louvain 算法发现超越目录结构的自然文件分组
- **图持久化** — 将解析好的图缓存到 `.code-visualizer/` 以实现即时启动
## 安装
直接使用 npx 运行（无需安装）：
```
npx codebase-intelligence ./src
```
或全局安装：
```
npm install -g codebase-intelligence
codebase-intelligence ./src
```
## 使用
```
npx codebase-intelligence ./src
# => 已解析 142 个文件、387 个函数、612 个依赖
# => MCP stdio 服务器已启动
```
### 选项
| 标志 | 描述 | 默认值 |
|------|-------------|---------|
| `
` | TypeScript 代码库的路径 | 必填 |
| `--index` | 将图索引持久化到 `.code-visualizer/` | 关闭 |
| `--force` | 即使 HEAD 未更改也重新索引 | 关闭 |
| `--status` | 打印索引状态并退出 | - |
| `--clean` | 删除 `.code-visualizer/` 索引并退出 | - |
## MCP 集成
### Claude Code (手动)
添加到项目根目录的 `.mcp.json`：
```
{
"mcpServers": {
"codebase-intelligence": {
"type": "stdio",
"command": "npx",
"args": ["-y", "codebase-intelligence@latest", "./src"],
"env": {}
}
}
}
```
### Cursor / VS Code
添加到 `.cursor/mcp.json` 或 `.vscode/mcp.json`：
```
{
"servers": {
"codebase-intelligence": {
"command": "npx",
"args": ["-y", "codebase-intelligence@latest", "./src"]
}
}
}
```
### MCP 工具
| 工具 | 功能 |
|------|--------------|
| `codebase_overview` | 高层架构：模块、入口点、关键指标 |
| `file_context` | 单个文件的所有信息：导出、导入、依赖项、指标 |
| `get_dependents` | 文件级爆炸半径：如果更改此文件会破坏什么 |
| `find_hotspots` | 按任意指标（耦合度、变更率、复杂度等）排序的文件 |
| `get_module_structure` | 模块映射，包含跨模块依赖、内聚性、循环依赖 |
| `analyze_forces` | 模块健康状况：张力文件、桥接文件、提取候选 |
| `find_dead_exports` | 可安全移除的未使用导出 |
| `get_groups` | 顶层目录组及其聚合指标 |
| `symbol_context` | 任意函数或类的调用方、被调用方、重要性指标 |
| `search` | 通过关键词查找文件和符号，提供排序结果 |
| `detect_changes` | Git diff，包含每个更改文件的风险指标 |
| `impact_analysis` | 符号级爆炸半径，带按深度分组的风险标签 |
| `rename_symbol` | 查找符号的所有引用（只读，用于重命名规划） |
| `get_processes` | 从入口点通过调用图追踪执行流 |
| `get_clusters` | 社区检测发现的相关文件簇 |
## 指标
| 指标 | 揭示内容 |
|--------|-----------------|
| **PageRank** | 被引用最多的文件（重要性） |
| **Betweenness** (中介中心性) | 断开模块之间的桥接文件 |
| **Coupling** (耦合度) | 文件的纠缠程度（出度 / 总连接数） |
| **Cohesion** (内聚性) | 模块是否属于一体？（内部依赖 / 总依赖） |
| **Tension** (张力) | 文件是否在模块间被撕裂？（跨模块拉力的熵） |
| **Escape Velocity** (逃逸速度) | 此模块是否应成为独立包？ |
| **Churn** (变更率) | Git 提交频率 |
| **Complexity** (复杂度) | 导出的平均圈复杂度 |
| **Blast Radius** (爆炸半径) | 受更改影响的传递依赖项 |
| **Dead Exports** (死代码导出) | 未使用的导出（可安全移除） |
| **Test Coverage** (测试覆盖率) | 每个源文件是否存在测试文件 |
## 架构
```
codebase-intelligence
|
v
+---------+ +---------+ +----------+ +---------+
| Parser | --> | Graph | --> | Analyzer | --> | MCP |
| TS AST | | grapho- | | metrics | | stdio |
| | | logy | | | | |
+---------+ +---------+ +----------+ +---------+
```
1. **Parser (解析器)** — 通过 TypeScript Compiler API 提取文件、函数和导入。解析路径别名，遵循 `.gitignore`，检测测试关联。
2. **Graph (图)** — 使用 [graphology](https://graphology.github.io/) 构建节点和边。通过迭代 DFS 检测循环依赖。
3. **Analyzer (分析器)** — 计算所有 11 项指标以及组级聚合。
4. **MCP** — 通过 stdio 向 LLM 代理暴露 15 个工具、2 个提示词和 3 个资源。
## 要求
- Node.js >= 18
- TypeScript 代码库（`.ts` / `.tsx` 文件）
## 限制
- 仅支持 TypeScript（不支持 JS CommonJS、Python、Go 等）
- 仅静态分析（无运行时/动态导入）
- 调用图置信度各异：类型解析的调用可靠，文本推断的调用为尽力而为
## 发布
发布是自动化的，**仅在 `v*` 标签上触发**。
### 一次性设置
1. 创建 npm 自动化令牌（npmjs.com → Access Tokens）。
2. 将其作为 `NPM_TOKEN` 添加到 GitHub 仓库密钥中。
### 常规 CI (发布前)
- `CI` 工作流在每次 PR 和推送到 `main` 时运行：
- lint → typecheck → build → test
### 创建发布
1. 更新 `package.json` 版本。
2. 提交：`chore(release): bump to vX.Y.Z`
3. 打标签：`git tag vX.Y.Z`
4. 推送：`git push origin main --tags`
`v*` 标签触发 `CI` 工作流的 **publish** 任务，该任务运行 `npm publish --access public --provenance`。
## 贡献
欢迎贡献。请先开启一个 issue 讨论您想要更改的内容。
```
git clone https://github.com/bntvllnt/codebase-intelligence.git
cd codebase-intelligence
pnpm install
pnpm dev # tsx watch mode
pnpm test # vitest
pnpm lint # eslint
pnpm typecheck # tsc --noEmit
pnpm build # production build
```
## 许可证
[MIT](LICENSE)标签：AI编程助手, BM25搜索, Claude, CVE检测, DNS解析, GNU通用公共许可证, LLM辅助编程, MCP工具, MITM代理, Model Context Protocol, Node.js, NPX, PageRank, TypeScript, 代码库智能分析, 代码度量, 代码理解, 代码重构, 依赖图, 安全插件, 开源项目, 架构分析, 死代码检测, 社区检测, 符号级影响分析, 自动化攻击, 软件架构, 过程追踪, 错误基检测, 静态代码分析