代码表面
](https://pypi.org/project/codesurface/) ](https://pypi.org/project/codesurface/)  ](https://github.com/Codeturion/codesurface) ](https://github.com/Codeturion/codesurface)    
MCP服务器，在启动时为代码库的公共API编制索引，并通过紧凑的工具响应为其提供服务，保存令牌而不是读取源文件。
解析源文件，提取公共类/方法/属性/字段/事件，并通过5个MCP工具为其提供服务。适用于Claude Code、Cursor、Windsurf或任何兼容MCP的AI工具。
支持的语言： C.cs)，C++头文件(.h, .hpp, .hxx, .h++)去吧(.goJava.javapython.py)，Types/JavaScript(.ts, .tsx, .js, .jsx)
快速开始
添加到您的 .mcp.json:
{
"mcpServers": {
"codesurface": {
"command": "uvx",
"args": ["codesurface", "--project", "/path/to/your/src"]
}
}
}点 --project 在包含支持的源文件的任何目录（Unity Assets/Scripts 文件夹，一个Spring Boot项目，一个。网 src/ 树、Node.js/RReact项目、Python包等）。语言是自动检测的。
重新启动AI工具并询问： *“MyService有哪些方法？”*
CLAUDE.md片段
将此添加到您的项目 CLAUDE.md （或等效的说明文件）。 这一步很重要。 没有它，人工智能有工具，但不知道什么时候可以使用它们。
## Codebase API Lookup (codesurface MCP)
Use codesurface MCP tools BEFORE Grep, Glob, Read, or Task (subagents) for any class/method/field lookup. This applies to you AND any subagents you spawn.
| Tool | Use when | Example |
|------|----------|---------|
| `search` | Find APIs by keyword | `search("MergeService")` |
| `get_signature` | Need exact signature | `get_signature("TryMerge")` |
| `get_class` | See all members on a class | `get_class("BlastBoardModel")` |
| `get_stats` | Codebase overview | `get_stats()` |
Every result includes file path + line numbers. Use them for targeted reads:
- `File: Service.cs:32` → `Read("Service.cs", offset=32, limit=15)`
- `File: Converter.java:504-506` → `Read("Converter.java", offset=504, limit=10)`
Never read a full file when you have a line number. Only fall back to Grep/Read for implementation details (method bodies, control flow).工具
| 工具 | 目的 | 示例 |
|---|---|---|
search | 按关键字查找API | “MergeService”、“BlastBoard”、“GridCoord” |
get_signature | 按名称或FQN进行精确签名 | “TryMerge”，“CampGame.Services.IMergeService.TreeMerge” |
get_class | 包含所有公共成员的完整班级参考卡 | “BlastBoardModel”→ 所有方法/字段/属性 |
get_stats | 索引代码库概述 | 文件计数、记录计数、命名空间细分 |
reindex | 增量索引更新（基于mtime） | 仅重新解析更改/新建/删除的文件。查询未命中时也会自动运行 |
search, get_signature，以及 get_class 接受两个可选筛选器：
file_path：作用域结果为目录前缀或精确文件（例如。"src/services/"或"src/services/MergeService.ts")include_tests：在结果中包含测试文件（默认值false).发现__tests__/,tests/,test/,*.test.*,*.spec.*,*_test.*,test_*
已测试
| 项目 | 语言 | 文件 | 记录 | 时间 |
|---|---|---|---|---|
| VS Code | TypeScript | 6611 | 88293 | 9.3秒 |
| 纸张 | Java | 2909 | 33973 | 2.3秒 |
| 客户去 | 前进 | 219 | 2760 | 0.4秒 |
| 语言链 | Python | 1880 | 12418 | 1.1秒 |
| 皮丹提克 | Python | 365 | 9648 | 0.3秒 |
| 番石榴 | Java | 891 | 8377 | 2.4秒 |
| 立即 | TypeScript | 919 | 7957 | 0.6秒 |
| FastAPI | Python | 881 | 5713 | 0.5秒 |
| 蚂蚁设计 | TypeScript | 2947 | 5452 | 0.9秒 |
| 迪菲 | TypeScript | 4903 | 5038 | 1.9秒 |
| 爬行python | Python | 386 | 2473 | 0.3秒 |
| 烧瓶 | Python | 63 | 872 | \ from(Function forward, Function backward) |
File: Converter.java:504-506 ← multi-line signature
[METHOD] server.AlbumController.createAlbum Signature: createAlbum(@Auth() auth: AuthDto, @Body() dto: CreateAlbumDto) File: album.controller.ts:46 ← single-line
这让AI代理可以做到 **定向阅读** 而不是读取完整文件：
Instead of reading the entire 600-line file:
Read("Converter.java") # 600 lines, ~12k tokens
Read just the method + context:
Read("Converter.java", offset=504, limit=10) # 10 lines, ~200 tokens
## 基准测试
在5种语言的5个真实世界项目中进行测量，每个项目使用10步跨领域研究工作流程。
|语言|项目|文件|记录|MCP|熟练|天真|MCP与熟练|
|----------|---------|------:|--------:|----:|--------:|------:|---------------:|
|C#|团结游戏| 129 | 1034| **1,021** |4453 | 11825 |减少77%|
|TypeScript | immich | 694 | 8344| **1,451** |4500 | 14550 |减少68%|
|爪哇|番石榴| 891 | 8377| **1,851** |4200 | 26700 |减少56%|
|围棋|杜松子酒|38|534| **1,791** |2770 | 15300 |减少35%|
|Python |代码表面|9|40| **753** |2000 | 10400 |减少62%|
即使有后续的实施细节读取，混合MCP+目标读取方法也使用 **代币减少44%** 比熟练的Grep+Read代理和 **减少87%** 比一个天真的代理人：
### 按问题细分
看 [工作流程基准.md](workflow-benchmark.md) 用于所有语言的完整分步分析。
## 过滤索引内容
默认情况下，codesurface跳过常见的供应商、构建和VCS目录： `node_modules`, `vendor`, `bin`, `obj`, `dist`, `build`, `target`, `.git`, `.venv`, `__pycache__`还有几十个人。Git工作树和子模块也被跳过。
要排除其他路径，请执行以下操作：
**项目级别（已承诺）：** 创建一个 `.codesurfaceignore` 文件位于项目根目录，每行一个glob。
generated/ docs/ **/*.pb.go
**每个实例（CLI）：** 通过 `--exclude` 用逗号分隔的球体。
{ "command": "uvx", "args": ["codesurface", "--project", "src", "--exclude", "generated/,vendor/"] }
其他索引标志：
- `--include-submodules`：索引git子模块（默认跳过）
- `--language `：固定到单个解析器（例如。 `--language cpp`)而不是自动检测
## 多个项目
每 `--project` 标志索引一个目录。要索引多个代码库，请运行具有不同服务器名称的单独实例：
{ "mcpServers": { "codesurface-backend": { "command": "uvx", "args": ["codesurface", "--project", "/path/to/backend/src"] }, "codesurface-frontend": { "command": "uvx", "args": ["codesurface", "--project", "/path/to/frontend/src"] } } }
每个实例都有自己的内存索引和工具。AI代理可以看到这两者，并可以跨项目查询。
## 安装详细信息
Alternative installation methods
**使用pip安装：**
pip install codesurface
{ "mcpServers": { "codesurface": { "command": "codesurface", "args": ["--project", "/path/to/your/src"] } } }
Project structure
codesurface/ ├── src/codesurface/ │ ├── server.py # MCP server with 5 tools │ ├── db.py # SQLite + FTS5 database layer │ ├── filters.py # PathFilter (default exclusions, .codesurfaceignore, --exclude) │ └── parsers/ │ ├── base.py # BaseParser ABC │ ├── cpp.py # C++ header parser │ ├── csharp.py # C# parser │ ├── go.py # Go parser │ ├── java.py # Java parser │ ├── python_parser.py # Python parser │ └── typescript.py # TypeScript/JavaScript parser ├── pyproject.toml └── README.md
Troubleshooting
**“没有索引代码库”**
- 确保 `--project` 指向包含受支持源文件的目录(`.cs`, `.h`, `.hpp`, `.go`, `.java`, `.py`, `.ts`, `.tsx`, `.js`, `.jsx`)
- 服务器在启动时索引。检查stderr `[codesurface] scanning N files...` 和 `[codesurface] done:` 线条
**服务器无法启动**
- 检查Python版本： `python --version` （需要3.10+）
- 检查 `mcp[cli]` 已安装： `pip install mcp[cli]`
**编辑源文件后结果过时**
- 索引在查询未命中时自动刷新。如果添加新类并查询它，服务器会自动重新索引并重试
- 您也可以致电 `reindex()` 手动强制增量更新
______________________________________________________________________
## 联系
fuatcankoseoglu@gmail.com
## 许可证
[麻省理工学院](LICENSE)