codesurface

codesurface

コードベースのパブリック API を起動時にインデックス化し、コンパクトなツール応答で提供する MCP サーバーです。ソースファイルを読む場合と比べてトークンを節約できます。

ソースファイルを解析して、パブリックなクラス／メソッド／プロパティ／フィールド／イベントを抽出し、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 は、次の 2 つのオプションフィルターを受け付けます。

• 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 エージェントはファイル全体を読むのではなく、対象を絞って読み取ることができます。

# 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 と対象を絞った読み取りを組み合わせるハイブリッド方式では、熟練した Grep+Read エージェントと比べてトークンを 44% 削減でき、素朴なエージェントと比べると87% 削減できます。

質問ごとの内訳

すべての言語について、ステップごとの詳細な分析は workflow-benchmark.md を参照してください。

インデックス対象のフィルタリング

デフォルトでは、codesurface は一般的なベンダー、ビルド、VCS のディレクトリをスキップします。対象は node_modules、vendor、bin、obj、dist、build、target、.git、.venv、__pycache__ など、数十個に及びます。Git ワークツリーとサブモジュールもスキップされます。

追加のパスを除外するには、次のようにします。

プロジェクト単位（コミット対象）： プロジェクトのルートに .codesurfaceignore ファイルを作成し、1 行につき 1 つの 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 フラグで 1 つのディレクトリをインデックスに登録します。複数のコードベースをインデックスに登録するには、サーバー名を変えて個別のインスタンスを起動します。

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

各インスタンスは、それぞれ独自のインメモリーインデックスとツールを持ちます。AI エージェントから両方が見えるため、プロジェクトを横断してクエリできます。

セットアップの詳細

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