# codesurface [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/Codeturion/codesurface  
**GitHub Stars:** 21  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/codesurface

## Description
Indexes your codebase's public API and serves it via compact MCP tool responses.

## Tools
Capabilities this server exposes over MCP:

- **search** — Find APIs by keyword
- **get_signature** — Exact signature by name or FQN
- **get_class** — Full class reference card with all public members
- **get_stats** — Overview of indexed codebase
- **reindex** — Incremental index update (mtime-based)

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "codesurface": {
    "command": "uvx",
    "args": ["codesurface"]
  }
}
```

## Documentation

## What the codesurface MCP server does

The codesurface MCP server creates a searchable index of a project's public API. It extracts declarations such as classes, methods, properties, fields, and events from supported source files, then returns structured reference information through MCP tools. Results include file paths and line ranges, allowing an agent to follow up with a narrow source read when it needs implementation details.

Supported inputs include C# files, C++ headers, Go, Java, Python, TypeScript, and JavaScript. The project can be a source directory such as a .NET tree, Python package, Node.js application, Spring Boot project, or Unity scripts folder. Languages are detected automatically unless a parser is selected explicitly.

## How it works

Indexing runs when the process starts and records public API information from the selected project directory. The `search` tool locates APIs by keyword, while `get_signature` returns the exact signature for a symbol name or fully qualified name. `get_class` returns a reference card containing the public members of a class. `get_stats` reports index information such as file and record counts and namespace breakdowns.

The `reindex` tool performs an incremental update based on modification times. It reparses changed or newly added files and removes entries for deleted files. Reindexing also runs automatically when a query misses. Search, signature, and class lookups can be scoped with a directory prefix or exact file path, and test files can be included with the `include_tests` option.

## Setup and configuration

Run the codesurface MCP server with the `codesurface` package through `uvx`, passing `--project` and the directory to index. A typical MCP configuration uses a server entry with `command` set to `uvx` and arguments containing `codesurface`, `--project`, and the source directory.

The server skips common generated, vendored, build, virtual-environment, and version-control directories by default. Add further exclusions in a project-root `.codesurfaceignore` file, using one glob per line, or pass comma-separated patterns with `--exclude`. Use `--include-submodules` to index Git submodules, or `--language` to select one parser instead of automatic detection. Each project requires a separate server instance and name when multiple codebases are needed.

## Tools and capabilities

The codesurface MCP server exposes five tools:

- `search` finds APIs by keyword.
- `get_signature` retrieves an exact signature by name or fully qualified name.
- `get_class` lists a class and its public members.
- `get_stats` summarizes the indexed codebase.
- `reindex` refreshes the index incrementally.

The intended workflow is API lookup first, followed by targeted reads at the returned line numbers. This keeps implementation inspection separate from public API discovery and avoids requiring an agent to read complete source files for basic signature or member questions.

## Limitations and notes

The index covers public API declarations rather than method bodies or general implementation logic. Agents still need ordinary file-reading or search tools for control flow, private implementation details, and other source content not represented in the index. C++ support is described for header extensions, including `.h`, `.hpp`, `.hxx`, and `.h++`.

Test files are excluded from filtered lookups by default and are detected using common directory and filename patterns. Git worktrees and submodules are skipped unless submodule indexing is enabled. The server is intended for local MCP clients and does not describe a hosted endpoint or external API credential requirement.

_Full upstream README: https://allmcps.com/mcp/codesurface/readme_