Codesurface

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.