# codesurface

Extracts public APIs across your repository and serves signatures with line ranges so coding agents read fewer source tokens.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 21
- Author: Codeturion
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Codeturion/codesurface
- Updated: 2026-07-28
- HTML: https://affpapa.org/en/nevibecode/mcp/codesurface

## What it does

The server parses codebases during startup to catalogue exported classes, methods, and fields. It handles repositories in Go, Python, Java, C#, TypeScript, and C++ header files. This cuts token consumption. The assistant queries structured signatures instead of dumping entire source files.

Five tools manage the catalog: `search`, `get_signature`, `get_class`, `get_stats`, and `reindex`. The `reindex` tool checks file timestamps and runs automatically on query misses. Every result includes exact line ranges. This allows agents to read narrow line slices rather than thousands of implementation lines.

Running this server requires Python 3.10 or newer and the `uvx` CLI. Omitting the `--project` path argument leaves the server without files to index.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add codesurface -- uvx codesurface
```
uvx runs the command named after the package; if the README names another one, use uvx --from codesurface <command>

### Codex

**Platform CLI**
```bash
codex mcp add codesurface -- uvx codesurface
```
uvx runs the command named after the package; if the README names another one, use uvx --from codesurface <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "codesurface": {
            "command": "uvx",
            "args": [
                "codesurface"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from codesurface <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "codesurface": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "codesurface"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from codesurface <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add codesurface uvx codesurface
```
uvx runs the command named after the package; if the README names another one, use uvx --from codesurface <command>

## When to use it
- retrieve method signatures without sending full source files into context
- inspect public members of a class with exact line positions
- perform targeted reads using line offsets instead of reading entire files
- refresh the API index incrementally based on modified file timestamps

## Example prompts
- Search for the BlastBoardModel class using codesurface
- Get the exact signature for TryMerge
- Show codebase stats for the indexed files

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md