Skip to main content
Glama
Codeturion

codesurface

by Codeturion
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

codesurface

PyPI Version PyPI Downloads MCP Registry GitHub Stars GitHub Last Commit Languages License: MIT Python 3.10+ Blog Post

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:

{
  "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?"

Related MCP server: embecode

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.

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

TypeScript

6,611

88,293

9.3s

Paper

Java

2,909

33,973

2.3s

client-go

Go

219

2,760

0.4s

langchain

Python

1,880

12,418

1.1s

pydantic

Python

365

9,648

0.3s

guava

Java

891

8,377

2.4s

immich

TypeScript

919

7,957

0.6s

fastapi

Python

881

5,713

0.5s

ant-design

TypeScript

2,947

5,452

0.9s

dify

TypeScript

4,903

5,038

1.9s

crawlee-python

Python

386

2,473

0.3s

flask

Python

63

872

<0.1s

cobra

Go

15

249

<0.1s

gin

Go

41

574

<0.1s

Unity game (private)

C#

129

1,018

0.1s

Line Numbers for Targeted Reads

Every record includes line_start and line_end (1-indexed). Multi-line declarations span the full signature:

[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

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

# 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.

Total Tokens, Cross-Language Comparison

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

Hallucination Risk

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:

Hybrid Workflow

Per-question breakdown

Per Question

See 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.

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

Other indexing flags:

  • --include-submodules: index git submodules (skipped by default)

  • --language <name>: 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:

{
  "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

Using pip install:

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

"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

Available Tools

5 tools
get_classA

Get a complete reference card for a class — all public members.

Shows every method, property, field, and event with signatures. Replaces reading the entire source file.

Args: class_name: Class name, e.g. "BlastBoardModel", "IMergeService", "CampGridService" file_path: Optional path prefix to scope the lookup include_tests: If true, include test files in results (default false)

ParametersJSON Schema
NameRequiredDescriptionDefault
class_nameYes
file_pathNo
include_testsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It explains what the tool returns but does not disclose any side effects, permissions, or performance traits. The tool is inherently read-only, but this is not explicitly stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with a brief front-loaded statement of purpose followed by a clear Arguments block. Every sentence serves a purpose without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema, the description appropriately focuses on input parameters and overall purpose. However, it lacks details on error handling, permissions, or performance, which would be helpful given no annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description adds significant value: it provides concrete examples for class_name, explains file_path as an optional scope prefix, and clarifies include_tests defaults. This compensates for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns a complete reference card of a class's public members, including methods, properties, fields, and events. It distinguishes from siblings like get_signature (which likely targets a single member) by emphasizing the full class overview.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions it 'replaces reading the entire source file,' implying a use case for quick class overview, but does not explicitly compare to alternatives like get_signature or specify when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_signatureA

Look up the exact signature of an API member by name or FQN.

Use when you need exact parameter types, return types, or method signatures without reading the full source file.

Args: name: Member name or FQN, e.g. "TryMerge", "CampGame.Services.IMergeService.TryMerge" file_path: Optional path prefix to scope the lookup include_tests: If true, include test files in results (default false)

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes
file_pathNo
include_testsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It describes a read-only lookup but does not disclose behavioral traits like error handling (e.g., if member not found), authentication requirements, or side effects. The description is adequate but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: a one-line purpose, a usage recommendation, and a well-structured args list. It could be slightly more streamlined, but it is efficient and free of fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters and an output schema (so return values are documented elsewhere), the description covers the essential context: arguments, usage guidance, and scope (FQN examples). It lacks details on error states but is otherwise complete for a lookup tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% coverage for parameter descriptions. The description compensates by providing detailed explanations for all three parameters: 'name' (with examples), 'file_path' (optional path prefix), and 'include_tests' (default false). This adds significant meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Look up the exact signature of an API member by name or FQN.' This is a specific verb+resource, and it distinguishes itself from sibling tools like 'get_class' (likely for class definitions) and 'search' (general search).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides usage context: 'Use when you need exact parameter types, return types, or method signatures without reading the full source file.' While it does not explicitly list alternatives or when-not-to-use, the context is clear and the sibling tools list helps.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_statsA

Get a quick overview of the indexed codebase.

Shows file count, record counts by type, and namespace breakdown.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions the kind of data returned but does not disclose any behavioral traits like side effects, rate limits, or authentication requirements. For a simple read-only tool with no parameters, this is minimally adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loaded, and every sentence adds value. There is no fluff or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema (not shown but flagged), the description does not need to detail return format. It provides a complete overview of what the tool does, and the tool's simplicity (no params, no side effects) means nothing is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the input schema is fully covered (100%). Per guidelines, a baseline of 4 is appropriate since the description adds no param-specific info beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs ('Get') and resources ('quick overview'), and lists the specific metrics returned (file count, record counts by type, namespace breakdown). It clearly distinguishes from siblings like get_class and get_signature which are more specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage as a top-level summary tool, but does not explicitly state when to use or when not to use it versus alternatives. The sibling tools provide context, but no exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reindexA

Incrementally update the index by re-parsing only changed, new, or deleted files.

Uses file modification times to detect changes. Fast on large codebases — only touches files that actually changed since the last index.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses key behavioral traits: incremental, uses file modification times, only touches changed files. However, it omits details like whether the operation is idempotent, locks the index, or has any side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: three sentences, front-loaded with the purpose. Every sentence adds value without unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and an existing output schema, the description provides adequate context for a mutation tool. It explains the mechanism and efficiency, but could briefly mention the output format or return value.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, and schema coverage is 100% (trivially). The description does not need to add parameter info; it is sufficient as is.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it incrementally updates the index by re-parsing only changed, new, or deleted files. It uses a specific verb ('Incrementally update') and resource ('index'), distinguishing it from sibling read-only tools like get_class and search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context on when to use (fast incremental updates based on file modification times) but does not explicitly state when not to use or mention alternatives like a full reindex. No preconditions are listed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 5 tool updatesv0.8.0
    • First observedget_class
    • First observedget_signature
    • First observedget_stats
    • First observedreindex
    • First observedsearch
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: get_class for full class reference, get_signature for specific member signatures, get_stats for overview statistics, reindex for incremental indexing, and search for keyword-based discovery. No functional overlap exists.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case (get_class, get_signature, get_stats, reindex, search). The naming is predictable and intuitive.

Tool Count5/5

Five tools are well-scoped for a code indexing server: providing search, member details, class overview, statistics, and index maintenance. This count is neither too sparse nor too heavy.

Completeness5/5

The tool set covers all essential operations for code exploration and indexing: searching, retrieving member signatures, getting full class documentation, viewing codebase statistics, and incremental reindexing. No obvious gaps for the stated purpose.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Satori

    ham-zax
    A
    license
    Not graded
    quality
    B
    maintenance
    Agent-safe code retrieval MCP server that indexes repositories and provides semantic search, file navigation, call graph analysis, and bounded file reading tools for coding agents.
    3,448,419
    3
    AGPL 3.0

  • reposynapse

    Jul879n
    A
    license
    A
    quality
    D
    maintenance
    Universal MCP server that analyzes any codebase and provides structured context to AI assistants. Dynamic, accurate, and token-efficient.
    18
    14
    MIT

  • AgentsBestFriend

    TheRealFloatDev
    F
    license
    Not graded
    quality
    D
    maintenance
    Give your AI coding agents superpowers — a local MCP server for fast, token-efficient code navigation, search & analysis.
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Codeturion/codesurface'

If you have feedback or need assistance with the MCP directory API, please join our Discord server