codesurface

codesurface

一个 MCP 服务，可在启动时为代码库的公共 API 建立索引，并通过精简的工具响应提供服务，相比读取源文件可节省 Token。

解析源文件，提取公共类、方法、属性、字段和事件，并通过 5 个 MCP 工具提供服务。适用于 Claude Code、Cursor、Windsurf 或任何兼容 MCP 的 AI 工具。

支持的语言： C#（.cs）、C++ 头文件（.h、.hpp、.hxx、.h++）、Go（.go）、Java（.java）、Python（.py）、TypeScript/JavaScript（.ts、.tsx、.js、.jsx）

快速开始

将其添加到你的 .mcp.json：

{
  "mcpServers": {
    "codesurface": {
      "command": "uvx",
      "args": ["codesurface", "--project", "/path/to/your/src"]
    }
  }
}

将 --project 指向包含受支持源文件的任意目录（例如 Unity 的 Assets/Scripts 文件夹、Spring Boot 项目、.NET 的 src/ 目录树、Node.js/React 项目、Python 包等）。系统会自动检测语言。

重启你的 AI 工具并询问：“MyService 有哪些方法？”

CLAUDE.md 片段

将以下内容添加到项目的 CLAUDE.md（或同类说明文件）中。**这一步很重要。**如果没有这一步，AI 虽然可以使用这些工具，却不知道何时该调用它们。

## 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、get_signature 和 get_class 支持两个可选筛选条件：

• file_path：将结果限定为某个目录前缀或确切文件（例如 "src/services/" 或 "src/services/MergeService.ts"）
• include_tests：在结果中包含测试文件（默认值为 false）。可检测 __tests__/、tests/、test/、*.test.*、*.spec.*、*_test.*、test_*

测试项目

针对性读取的行号

每条记录都包含 line_start 和 line_end（从 1 开始计数）。多行声明会覆盖完整签名：

[METHOD] com.google.common.base.Converter.from
  Signature: static Converter<A, B> 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 Agent 就能进行针对性读取，而不必读取整个文件：

# 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 + 针对性 Read 方法使用的 Token 仍比熟练的 Grep+Read Agent 少 44%，比简单 Agent 少 87%：

按问题细分

请参阅 workflow-benchmark.md，了解所有语言的完整逐步分析。

筛选索引内容

默认情况下，codesurface 会跳过常见的第三方依赖、构建和版本控制目录：node_modules、vendor、bin、obj、dist、build、target、.git、.venv、__pycache__ 以及其他几十个目录。Git 工作树和子模块也会被跳过。

如需排除其他路径：

项目级（提交到仓库）： 在项目根目录下创建 .codesurfaceignore 文件，每行填写一个 glob 模式。

generated/**
docs/**
**/*.pb.go

实例级（CLI）： 使用逗号分隔的 glob 模式传入 --exclude。

{
  "command": "uvx",
  "args": ["codesurface", "--project", "src", "--exclude", "generated/**,vendor/**"]
}

其他索引选项：

• --include-submodules：为 Git 子模块建立索引（默认跳过）
• --language <name>：指定单个解析器（例如 --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 Agent 可以同时看到这些实例，并跨项目查询。

设置详情

pip install codesurface

{
  "mcpServers": {
    "codesurface": {
      "command": "codesurface",
      "args": ["--project", "/path/to/your/src"]
    }
  }
}

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

联系方式

[email protected]

许可证

MIT