# Codesurface

> Give your AI agent instant API lookups instead of expensive source file reads. MCP server for C#, Go, Java, Python, and TypeScript.

- **Type:** MCP server
- **Install:** `agentstack add mcp-codeturion-codesurface`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Codeturion](https://agentstack.voostack.com/s/codeturion)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.4.1
- **License:** MIT
- **Upstream author:** [Codeturion](https://github.com/Codeturion)
- **Source:** https://github.com/Codeturion/codesurface
- **Website:** https://www.codeturion.me

## Install

```sh
agentstack add mcp-codeturion-codesurface
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# codesurface

[](https://pypi.org/project/codesurface/)
[](https://pypi.org/project/codesurface/)
[](https://registry.modelcontextprotocol.io/?q=codesurface)
[](https://github.com/Codeturion/codesurface)
[](https://github.com/Codeturion/codesurface)
[](https://github.com/Codeturion/codesurface)
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://www.codeturion.me/blog/reducing-llm-agent-hallucinations-through-constrained-api-retrieval)

**MCP server that indexes your codebase's public API at startup and serves it via compact tool responses, saving tokens vs reading source files.**

Parses source files, extracts public classes/methods/properties/fields/events, and serves them through 5 MCP tools. Works with Claude Code, Cursor, Windsurf, or any MCP-compatible AI tool.

**Supported languages:** C# (`.cs`), C++ headers (`.h`, `.hpp`, `.hxx`, `.h++`), Go (`.go`), Java (`.java`), Python (`.py`), TypeScript/JavaScript (`.ts`, `.tsx`, `.js`, `.jsx`)

## Quick Start

Add to your `.mcp.json`:

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

Point `--project` at any directory containing supported source files (a Unity `Assets/Scripts` folder, a Spring Boot project, a .NET `src/` tree, a Node.js/React project, a Python package, etc.). Languages are auto-detected.

Restart your AI tool and ask: *"What methods does MyService have?"*

## CLAUDE.md Snippet

Add this to your project's `CLAUDE.md` (or equivalent instructions file). **This step is important.** Without it, the AI has the tools but won't know when to reach for them.

````markdown
## 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).
````

## Tools

| Tool | Purpose | Example |
|------|---------|---------|
| `search` | Find APIs by keyword | "MergeService", "BlastBoard", "GridCoord" |
| `get_signature` | Exact signature by name or FQN | "TryMerge", "CampGame.Services.IMergeService.TryMerge" |
| `get_class` | Full class reference card with all public members | "BlastBoardModel" → all methods/fields/properties |
| `get_stats` | Overview of indexed codebase | File count, record counts, namespace breakdown |
| `reindex` | Incremental index update (mtime-based) | Only re-parses changed/new/deleted files. Also runs automatically on query misses |

`search`, `get_signature`, and `get_class` accept two optional filters:

- `file_path`: scope results to a directory prefix or exact file (e.g. `"src/services/"` or `"src/services/MergeService.ts"`)
- `include_tests`: include test files in results (default `false`). Detects `__tests__/`, `tests/`, `test/`, `*.test.*`, `*.spec.*`, `*_test.*`, `test_*`

## Tested On

| Project | Language | Files | Records | Time |
|---------|----------|-------|---------|------|
| [vscode](https://github.com/microsoft/vscode) | TypeScript | 6,611 | 88,293 | 9.3s |
| [Paper](https://github.com/PaperMC/Paper) | Java | 2,909 | 33,973 | 2.3s |
| [client-go](https://github.com/kubernetes/client-go) | Go | 219 | 2,760 | 0.4s |
| [langchain](https://github.com/langchain-ai/langchain) | Python | 1,880 | 12,418 | 1.1s |
| [pydantic](https://github.com/pydantic/pydantic) | Python | 365 | 9,648 | 0.3s |
| [guava](https://github.com/google/guava) | Java | 891 | 8,377 | 2.4s |
| [immich](https://github.com/immich-app/immich) | TypeScript | 919 | 7,957 | 0.6s |
| [fastapi](https://github.com/tiangolo/fastapi) | Python | 881 | 5,713 | 0.5s |
| [ant-design](https://github.com/ant-design/ant-design) | TypeScript | 2,947 | 5,452 | 0.9s |
| [dify](https://github.com/langgenius/dify) | TypeScript | 4,903 | 5,038 | 1.9s |
| [crawlee-python](https://github.com/apify/crawlee-python) | Python | 386 | 2,473 | 0.3s |
| [flask](https://github.com/pallets/flask) | 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
```

This lets AI agents do **targeted reads** instead of reading full files:

```python
# 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
```

## Benchmarks

Measured across 5 real-world projects in 5 languages, each using a 10-step cross-cutting research workflow.

| Language | Project | Files | Records | MCP | Skilled | Naive | MCP vs Skilled |
|----------|---------|------:|--------:|----:|--------:|------:|---------------:|
| C# | Unity game | 129 | 1,034 | **1,021** | 4,453 | 11,825 | 77% fewer |
| TypeScript | immich | 694 | 8,344 | **1,451** | 4,500 | 14,550 | 68% fewer |
| Java | guava | 891 | 8,377 | **1,851** | 4,200 | 26,700 | 56% fewer |
| Go | gin | 38 | 534 | **1,791** | 2,770 | 15,300 | 35% fewer |
| Python | codesurface | 9 | 40 | **753** | 2,000 | 10,400 | 62% fewer |

Even with follow-up reads for implementation detail, the hybrid MCP + targeted Read approach uses **44% fewer tokens** than a skilled Grep+Read agent and **87% fewer** than a naive agent:

### Per-question breakdown

See [workflow-benchmark.md](workflow-benchmark.md) for the full step-by-step analysis across all languages.

## Filtering What Gets Indexed

By default, codesurface skips common vendored, build, and VCS directories: `node_modules`, `vendor`, `bin`, `obj`, `dist`, `build`, `target`, `.git`, `.venv`, `__pycache__`, and a few dozen others. Git worktrees and submodules are also skipped.

To exclude additional paths:

**Project-level (committed):** create a `.codesurfaceignore` file at your project root with one glob per line.

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

**Per-instance (CLI):** pass `--exclude` with comma-separated globs.

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

Other indexing flags:

- `--include-submodules`: index git submodules (skipped by default)
- `--language `: pin to a single parser (e.g. `--language cpp`) instead of auto-detecting

## Multiple Projects

Each `--project` flag indexes one directory. To index multiple codebases, run separate instances with different server names:

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

Each instance gets its own in-memory index and tools. The AI agent sees both and can query across projects.

## Setup Details

Alternative installation methods

**Using pip install:**
```bash
pip install codesurface
```
```json
{
  "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

**"No codebase indexed"**
- Ensure `--project` points to a directory containing supported source files (`.cs`, `.h`, `.hpp`, `.go`, `.java`, `.py`, `.ts`, `.tsx`, `.js`, `.jsx`)
- The server indexes at startup. Check stderr for `[codesurface] scanning N files...` and `[codesurface] done:` lines

**Server won't start**
- Check Python version: `python --version` (needs 3.10+)
- Check `mcp[cli]` is installed: `pip install mcp[cli]`

**Stale results after editing source files**
- The index auto-refreshes on query misses. If you add a new class and query it, the server reindexes and retries automatically
- You can also call `reindex()` manually to force an incremental update

---

## Contact

fuatcankoseoglu@gmail.com

## License

[MIT](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Codeturion](https://github.com/Codeturion)
- **Source:** [Codeturion/codesurface](https://github.com/Codeturion/codesurface)
- **License:** MIT
- **Homepage:** https://www.codeturion.me

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.4.1 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.4.1** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-codeturion-codesurface
- Seller: https://agentstack.voostack.com/s/codeturion
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.