内容
# 代码洞察 MCP
<p align="center">
<br>
<b>为 AI 助手提供安全加固、令牌高效的代码智能。</b>
<br><br>
<a href="LICENSE">
<img src="https://img.shields.io/github/license/cmillstead/codesight-mcp?style=flat-square" alt="许可证">
</a>
<img src="https://img.shields.io/badge/MCP-Compatible-green?style=flat-square" alt="MCP 兼容">
<img src="https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square&logo=python" alt="Python 3.10+">
<img src="https://img.shields.io/badge/tests-2495-brightgreen?style=flat-square" alt="测试">
</p>
MCP 服务器通过 tree-sitter AST 解析索引本地和 GitHub 代码库，然后提供 34 种工具用于符号检索、代码图遍历和影响分析 — 所有这些都具有字节偏移精度，以将令牌成本降低约 99% 与发送完整文件相比。支持 66 种语言。
基于 [jcodemunch-mcp](https://github.com/jgravelle/jcodemunch-mcp) 由 J. Gravelle 开发，结合 [CodeGraphContext](https://github.com/CodeGraphContext/CodeGraphContext) 的代码图技术和 [basalt-mcp](https://github.com/cmillstead/basalt-mcp) 的安全模式。
---
## 快速导航
- [功能](#功能)
- [支持的语言](#支持的语言)
- [快速入门](#快速入门)
- [工具参考](#工具)
- [代码图和关系分析](#代码图和关系分析)
- [安全模型](#安全模型)
- [Git Hooks](#git-hooks-自动在提交和推送时重新索引)
- [语义搜索](#语义搜索)
- [环境变量](#环境变量)
---
## 功能
### 代码索引和检索
- **Tree-sitter AST 解析**，支持 66 种语言，具有字节偏移 O(1) 符号检索
- **增量索引**，通过内容哈希 — 跳过未更改的文件重新索引
- **本地 + GitHub 仓库索引** — 索引磁盘上的文件夹或从 GitHub 获取
- **AI 生成的摘要** — 可选的 Anthropic API 集成，用于符号描述
- **全文搜索**，跨索引文件内容，具有防篡改匹配
- **语义搜索** — 通过设备上的嵌入（可选 `[semantic]` 额外）进行混合关键字 + 向量评分
### 代码图和关系分析
- **调用者和被调用者** — 调用某个函数的函数，它调用什么？
- **调用链** — 跟踪任意两个符号之间的完整路径
- **类型层次结构** — 继承树和接口实现
- **导入图** — 哪些文件导入什么，从哪里？
- **影响分析** — 更改一个函数，查看下游受影响的所有内容
### 安全
- **6 步路径验证链** — 空字节、遍历、限制、解析、包含、符号链接
- **内容边界标记** — 间接提示注入防御（Microsoft spotlighting 研究）
- **错误净化** — 原始异常永远不会到达 AI；系统路径始终被剥离
- **MCP ToolAnnotations** — 所有 34 种工具的 readOnlyHint、destructiveHint、idempotentHint、openWorldHint，用于客户端权限决策
- **2,495 个测试** — 对抗性、安全、集成、基准、模糊和压力测试，覆盖真实临时目录
---
## 支持的语言
codesight-mcp 通过 tree-sitter 支持 **66 种编程语言**，包括 Python、JavaScript、TypeScript、Go、Rust、Java、C/C++、C#、Ruby、Swift、Kotlin、PHP、Dart、Perl、Haskell、Scala、Erlang 和 49 种其他语言。有关详细信息，请参见 [完整的语言列表](docs/development-guide.md)。
每个语言解析器都提取函数、类、方法、参数、调用关系、导入和继承，以构建一个全面的代码图。
---
## 快速入门
### 步骤 1：安装
```bash
# 从源码（推荐 — 尚未发布到 PyPI）
git clone https://github.com/cmillstead/codesight-mcp.git
cd codesight-mcp
uv sync # 推荐 — 使用带有固定版本的锁文件
# 或：pip install -e . （使用版本范围，不使用锁文件）
```
### 步骤 2：注册 MCP 服务器
使用 `claude mcp add` 注册。这是 Anthropic 的 [代码执行与 MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) 模式的推荐方法 — 服务器通过 MCP 协议自我描述其工具，您的客户端通过 `tools/list` 自动发现它们。不需要手动工具列表或每个工具的权限配置。
```bash
claude mcp add codesight-mcp \
-e CODESIGHT_ALLOWED_ROOTS=/Users/you/src \
-e GITHUB_TOKEN=ghp_... \
-- /path/to/codesight-mcp/.venv/bin/codesight-mcp
```
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `CODESIGHT_ALLOWED_ROOTS` | 是（本地） | 以冒号分隔的目录列表，`index_folder` 可以访问。默认情况下，如果未设置，则拒绝。 |
| `GITHUB_TOKEN` | 是（GitHub） | 私有仓库必填；建议使用公共仓库以避免速率限制。 |
| `ANTHROPIC_API_KEY` | 否 | 使能 AI 生成的符号摘要。如果未设置，则回退到文档字符串。 |
所有 34 种工具都包含 [MCP ToolAnnotations](https://modelcontextprotocol.io/docs/concepts/tools#annotations) — 每种工具都声明它是只读的、破坏性的、幂等的还是访问外部服务的。您的 MCP 客户端使用这些注释自动做出权限决策，因此您不需要为每个工具配置权限。
### 步骤 3：索引仓库
在其他工具工作之前，您必须至少索引一个仓库。询问您的 AI：
- **本地文件夹：** *"索引 ~/src/myproject 处的仓库"*
- **GitHub 仓库：** *"索引 GitHub 仓库 owner/myproject"*
AI 调用 `index_folder` 或 `index_repo`，它获取文件，解析 AST，并将符号提取到 `~/.code-index/` 中。后续调用自动跳过未更改的文件。
### 步骤 4：探索
一旦索引完成，AI 使用 `get_repo_outline`、`search_symbols` 和 `get_symbol` 来导航代码库 — 只检索它需要的符号，而不是整个文件。
### 步骤 5（可选）：将 CLAUDE.md 添加到索引仓库
在每个索引仓库中添加一个 `CLAUDE.md`，以便 Claude Code 更喜欢 codesight-mcp 而不是读取完整文件：
```markdown
## 代码导航
该仓库在 codesight-mcp 中索引。使用 codesight-mcp MCP 工具进行代码
探索，而不是读取完整文件：
- `search_symbols` — 按名称或描述查找函数/类/类型
- `get_file_outline` — 文件中所有带有签名的符号
- `get_symbol` — 特定符号的完整源代码
- `get_repo_outline` — 目录结构和语言分解
- `get_callers` / `get_callees` — 调用图导航
- `get_call_chain` — 跟踪两个符号之间的执行路径
- `get_impact` — 查看更改符号时受影响的内容
仅在内容不是命名符号时使用 `Read`（例如配置文件等）。
```
---
## 工具
codesight-mcp 公开 **34 种 MCP 工具**，分为八类：
### 索引
| 工具 | 描述 |
|------|-------------|
| `index_repo` | 索引 GitHub 仓库（获取，解析 AST，提取符号） |
| `index_folder` | 索引本地文件夹（遍历，解析 AST，提取符号） |
| `list_repos` | 列出所有索引的仓库 |
| `invalidate_cache` | 删除索引以强制完全重新索引 |
### 导航
| 工具 | 描述 |
|------|-------------|
| `get_repo_outline` | 高级概述：目录，文件数量，语言分解 |
| `get_file_tree` | 索引仓库的文件树，可选按路径前缀过滤 |
| `get_file_outline` | 文件中所有带有签名和摘要的符号 |
| `get_symbol` | 特定符号的完整源代码（字节偏移检索） |
| `get_symbols` | 一次调用批量检索多个符号 |
| `get_symbol_context` | 符号 + 邻近符号 + 父类信息在一个调用中 |
### 搜索
| 工具 | 描述 |
|------|-------------|
| `search_symbols` | 按名称、签名、摘要或文档字符串搜索符号 |
| `search_text` | 跨索引文件内容的全文搜索（与编辑内容匹配） |
| `search_references` | 文本搜索丰富了每个命中的封闭符号上下文 |
### 代码图
| 工具 | 描述 |
|------|-------------|
| `get_callers` | 查找调用给定符号的所有函数 |
| `get_callees` | 查找给定符号调用的所有函数 |
| `get_call_chain` | 跟踪两个符号之间的执行路径（BFS 带有环检测） |
| `get_type_hierarchy` | 显示继承树 — 类的父类和子类 |
| `get_imports` | 显示文件或符号的导入关系 |
| `get_impact` | 影响分析 — 更改符号时受影响的所有内容 |
### 分析和可视化
| 工具 | 描述 |
| :--- | :--- |
| `analyze_complexity` | 查找最复杂/最危险的符号 — 环复杂度、认知复杂度、嵌套深度、扇入/扇出、复合风险评分。支持路径过滤和排序模式。 |
| `get_key_symbols` | 使用调用图上的 PageRank 排名符号结构重要性。标识最连接和依赖的符号。 |
| `get_diagram` | 从代码图中生成 Mermaid 图 — 调用图、类型层次结构、导入树和影响图。 |
| `get_dead_code` | 查找未引用的符号 — 零调用者或导入者的函数和类。 |
| `get_status` | 服务器状态 — 存储配置、索引统计和功能标志。 |
| `get_usage_stats` | 每个工具的调用次数、错误率、平均响应时间和未调用的工具。 |
| `verify` | 验证索引完整性 — 校验和、符号一致性和文件存在。 |
| `lint_index` | 审计索引质量 — 缺失字段、孤立符号、过时数据。 |
### 安全
| 工具 | 描述 |
|------|-------------|
| `scan_security` | 扫描符号的危险 API 用法模式（19 条 OWASP/CWE 规则） |
| `generate_sbom` | 生成物料清单（CycloneDX、SPDX 或内部 JSON） |
| `check_licenses` | 从 lockfiles 分析依赖许可证并标记风险 |
| `trace_taint` | 通过代码图进行前向 BFS 源到汇聚的污点分析 |
### 依赖和差异
| 工具 | 描述 |
|------|-------------|
| `get_dependencies` | 外部 vs 内部导入分析 — 哪些包被使用以及由哪些文件使用 |
| `compare_symbols` | 使用内容哈希在两个索引版本之间进行符号级差异 |
| `get_changes` | 将 git diff 映射到受影响的符号，可选的下游影响分析 |
---
## 自然语言示例
一旦索引完成，通过 AI 助手使用普通英语交互：
### 查找代码
- *"`process_payment` 函数在哪里？"*
- *"显示所有与身份验证相关的类"*
- *"查找任何处理数据库连接的代码"*
### 理解关系
- *"哪些函数调用 `validate_input`？*
- *" `initialize_system` 调用什么？*
- *"显示从 `main` 到 `process_data` 的完整调用链"*
- *" `BaseController` 的继承层次结构是什么？*
### 影响分析
- *"如果我更改 `calculate_tax`，什么会受到影响？*
- *"哪些文件导入 `utils` 模块？*
- *"显示 `authenticate_user` 下游的所有内容"*
### 探索结构
- *"给我这个仓库的概述"*
- *" `src/server.py` 中有哪些符号？*
- *"列出所有索引的仓库"*
---
## 代码图和关系分析
codesight-mcp 从索引期间提取的关系构建内存代码图。不需要外部图数据库 — 图使用字典集的邻接列表构造，查询时从符号字典构造。
**工作原理：**
1. 索引期间，AST 解析器为每个符号提取 `calls`、`imports` 和 `inherits_from` 关系。
2. 这些关系存储在符号元数据旁边 JSON 索引中。
3. 查询时，`CodeGraph.build(symbols)` 从符号字典构造图。
4. 图工具（调用者、被调用者、调用链、影响）使用 BFS 遍历此结构并检测环。
**与 [CodeGraphContext](https://github.com/CodeGraphContext/CodeGraphContext) 的比较：** codesight-mcp 不使用外部数据库（FalkorDB/Neo4j）。权衡是简单性和零配置 vs. 处理巨大图的 ability。对于大多数项目（数千个文件），内存方法是快速且足够的。
---
## Git Hooks：自动在提交和推送时重新索引
codesight-mcp 包括 git hooks 以自动保持索引更新：
| Hook | 触发 | 更新 |
|------|---------|---------|
| `post-commit` | 每次提交 | 本地文件夹索引 |
| `post-push` | 每次推送 | GitHub 仓库索引（自动检测远程） |
**安装在任何仓库：
```bash
cp /path/to/codesight-mcp/hooks/post-commit .git/hooks/post-commit
cp /path/to/codesight-mcp/hooks/post-push .git/hooks/post-push
chmod +x .git/hooks/post-commit .git/hooks/post-push
```
两个钩子都在后台运行，因此它们永远不会阻塞您的工作流。如果您希望自动更新 AI 生成的摘要，请从两个钩子中删除 `--no-ai`。
**一次性设置** — git hooks 不会继承您的 shell 环境，因此必须单独提供凭证和二进制路径：
```bash
mkdir -p ~/.config/codesight-mcp
cat > ~/.config/codesight-mcp/env <<'EOF'
export GITHUB_TOKEN=ghp_...
export CODESIGHT_BIN=/path/to/.venv/bin/codesight-mcp
EOF
chmod 600 ~/.config/codesight-mcp/env
```
您也可以直接从命令行索引：
```bash
codesight-mcp index ~/src/myproject # 索引本地文件夹
codesight-mcp index ~/src/myproject --no-ai # 跳过 AI 摘要（更快）
codesight-mcp index-repo owner/myproject # 索引 GitHub 仓库
```
---
## 安全模型
codesight-mcp 将连接的 AI 视为不受信任的 Principal。每个工具参数在使用前都会验证。每个索引的文件路径在检索时都会重新验证。错误消息被净化，因此系统路径永远不会泄露。
| 层 | 防御 |
|-------|---------|
| **路径验证** | 6 步链：空字节、遍历、长度限制、解析、包含、符号链接检查 |
| **内容边界标记** | Microsoft 风格的 spotlighting 标记以抵抗间接提示注入 |
| **错误净化** | 工具响应中没有原始异常或系统路径 |
| **允许根目录** | `CODESIGHT_ALLOWED_ROOTS` 限制哪些目录可以被索引 |
| **秘密红化** | 函数体中的秘密内容被从 API 输出中红化；`CODESIGHT_NO_REDACT=1` 禁用并记录警告 |
| **秘密存储** | 索引文件在 `~/.code-index/` 中包含原始代码，包括任何嵌入的秘密。存储在加密卷并限制文件系统权限。使用 `CODE_INDEX_PATH` 覆盖。 |
| **提示注入防御** | 非阻塞随机数分隔符，用于 AI 摘要；注入短语阻止列表；验证提示插值 |
| **图遍历限制** | 搜索 BFS 调用链在 5 条路径和深度 50 处被限制，以防止资源耗尽 |
请参阅 [SECURITY.md](SECURITY.md) 以获取完整威胁模型、防御矩阵和验证链细节。有关关键安全决策的架构决策记录位于 [docs/decisions/](docs/decisions/)。
---
## 数据处理
当设置 `ANTHROPIC_API_KEY` 时，codesight-mcp 在索引期间将函数和类签名发送到 Anthropic API 以获取 AI 生成的摘要。不会发送源代码 — 仅发送签名。如果未设置 `ANTHROPIC_API_KEY` 环境变量，则回退到文档字符串。
---
## 环境变量
| 变量 | 描述 |
|----------|-------------|
| `CODESIGHT_ALLOWED_ROOTS` | 以冒号分隔的目录列表，`index_folder` 允许索引。**必填** 用于本地文件夹索引 — 如果未设置，则默认为拒绝。示例：`/Users/you/src:/home/you/projects` |
| `GITHUB_TOKEN` | GitHub 个人访问令牌。私有仓库必填；强烈建议使用公共仓库以避免速率限制。 |
| `ANTHROPIC_API_KEY` | Anthropic API 密钥，用于 AI 生成的符号摘要。可选 — 如果未设置，则回退到文档字符串。 |
| `CODE_INDEX_PATH` | 索引的自定义存储目录。默认： `~/.code-index/` |
| `CODESIGHT_NO_REDACT` | 设置为 `1` 以禁用秘密编辑工具输出。记录警告；`search_text` 完全禁用。 |
| `CODESIGHT_READ_ONLY` | 设置为 `1` 以跳过文件系统权限操作（fchmod/mkdir）。自动用于非破坏性 CLI 命令在沙箱环境中。 |
| `CODESIGHT_USAGE_LOG` | 索引持久 JSONL 使用日志的路径。没有它，使用记录在内存中（重启后丢失）。 |
| `CODESIGHT_USAGE_ENABLED` | 设置为 `0` 以禁用使用日志记录。默认： `1` （启用）。 |
| `CODESIGHT_USAGE_MAX_MEMORY` | 内存中最大使用记录数，超过后清除。默认： `10000`。 |
| `CODESIGHT_LOG_LEVEL` | 日志详细程度： `DEBUG`， `INFO`， `WARNING`， `ERROR`， `CRITICAL`。所有级别均允许。默认： `WARNING`。优先于 `LOG_LEVEL`。 |
| `LOG_LEVEL` | 备用日志级别。限制在 `WARNING`/`ERROR`/`CRITICAL` 以确保安全（ADV-LOW-10）。使用 `CODESIGHT_LOG_LEVEL` 解锁 `DEBUG`/`INFO`。 |
---
## 语义搜索
按意图搜索，而不是确切的名称。需要 `semantic` 额外功能：
```bash
pip install codesight-mcp[semantic] # 添加 fastembed (~100MB ONNX 运行时 + 模型权重)
```
如果不使用此额外功能，传递语义参数会返回一个有帮助的错误，解释需要安装的内容。
### 参数
| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| `semantic` | bool | 混合关键词 + 语义评分（默认权重：0.7 语义，0.3 关键词） |
| `semantic_only` | bool | 纯语义评分，完全跳过关键词匹配 |
| `semantic_weight` | float | 混合比率，从 0.0（仅关键词）到 1.0（仅语义） |
### 示例
```python
# 按意图查找，而不是确切名称
search_symbols(query="验证凭证的函数", semantic=True)
# 纯语义搜索
search_symbols(query="密码哈希实用程序", semantic_only=True)
```
### 环境变量
| 变量 | 描述 |
|----------|-------------|
| `CODESIGHT_EMBED_PROVIDER` | 显式提供者选择（默认自动检测） |
| `CODESIGHT_EMBED_MODEL` | 模型覆盖（默认：`BAAI/bge-base-en-v1.5`） |
| `CODESIGHT_NO_SEMANTIC` | 设置为 `1` 以完全禁用语义功能 |
### 工作原理
嵌入式在第一次语义查询时惰性生成，并在索引的 gzip-JSON 边车文件中缓存。缓存会在重新索引时自动失效。默认提供程序在设备上运行，无需 API 调用。当 `semantic=false`（默认）时，**没有开销** — 永远不会加载或计算嵌入式。
关键词评分包括复合标识符拆分 (`hash_password` → `{hash, password}`，`AuthManager` → `{auth, manager}`）和后缀词干提取 (`hashing` → `hash`，`validates` → `validate`），因此基于意图的查询即使在禁用语义搜索时也能匹配。
---
## 致谢
基于 J. Gravelle 的 [jcodemunch-mcp](https://github.com/jgravelle/jcodemunch-mcp)。代码图技术改编自 [CodeGraphContext](https://github.com/CodeGraphContext/CodeGraphContext)。安全强化灵感来自 [basalt-mcp](https://github.com/cmillstead/basalt-mcp)。
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器