codesurface

codesurface is an MCP server that indexes your codebase's public API at startup and serves it through a compact set of MCP tools. It scans supported languages (C#, Go, Java, Python, TypeScript/TSX), extracts public classes, methods, properties, fields, and events, and exposes them to AI tools via five built-in MCP tools. With this setup, you can query what APIs exist, inspect exact signatures, view class members, review a high-level codebase overview, and trigger incremental re-indexing when the source changes. The tools are designed to minimize token usage by focusing on indexed metadata rather than reading full source files. To use it, point the server to the directory containing your source code with --project, restart your AI tool, and then issue queries like: “What methods does MyService have?” You can also perform targeted lookups using the dedicated tools to get exact signatures or class details. The server is designed to auto-detect languages and provide file paths and line ranges for precise context when returning results.

Prerequisites:

• Python 3.10+ installed on your system
• Access to install Python packages (pip)

Installation steps:

1. Install the codesurface MCP server from PyPI: pip install codesurface
2. Run the server via uvx (the MCP runner) by pointing it to your code project: uvx codesurface --project /path/to/your/src This starts indexing the codebase and exposes the 5 MCP tools to your AI tool.
3. If you prefer to run locally without uvx, ensure Python is available and you can invoke the package entry point as documented by the project (depending on your environment, you may also use: python -m codesurface --project /path/to/your/src).

Notes:

• The project path should contain your source files in one of the supported languages. Languages are auto-detected.
• You can run multiple codesurface instances for different projects by using separate server names in your mcp.json configuration.

Tips and caveats:

• If you add or modify source files, you may want to trigger a reindex (via the reindex tool) to keep the API index up to date.
• The codesurface tools return results with file paths and line numbers to enable targeted reads when you need more context.
• Environment variables are not strictly required for basic operation, but you can configure common MCP tool environment settings as needed for your deployment (e.g., network, logging).
• If you encounter issues with language detection, ensure your project structure is representative of supported languages and that the file extensions are standard for those languages.