MCP Codebase Server

Русская версия

MCP server for semantic codebase navigation. Builds an AST index of symbols, imports, and exports, providing high-level tools for an AI agent.

Features

• Project overview — a cheap "repo map" from the index: counts, top directories, key exported symbols ranked by importer count

• Symbol search — finds functions, classes, interfaces, methods, etc. by name with wildcard (*, ?) and OR (|) support

• Symbol details — shows source code, signature, documentation, and file imports

• Module overview — directory structure, key symbols, subdirectories, top imports

• Usage search — finds all references to a symbol in the project (plain text)

• Semantic navigation (LSP-backed): find_references (precise "who calls this") and go_to_definition (definition jump + hover info)

• Module dependencies — imports, exports, and files that use the given module

• Reindexing — full or incremental (by mtime)

• Watch mode — automatic index updates when files change

• Semantic refactoring (LSP-backed, via real language servers): rename_symbol, get_diagnostics, move_file, organize_imports, fix_all, extract_method — all with dryRun support and automatic reindex of changed files

• Tool telemetry — get_tool_stats shows per-tool call/error counters for the running server process

16 MCP tools in total: 7 navigation, 8 LSP-backed, 1 telemetry. See docs/benchmark.md for the measured context savings vs a grep-only agent loop (~18x fewer bytes on this repo).

Related MCP server: Headless Codebase Indexer

Supported Languages

The architecture makes it easy to add new languages via the ILanguageParser interface.

Requirements

• Node.js 18+

• PostgreSQL 14+

• For C# refactoring tools: .NET SDK + the csharp-ls dotnet tool (TS/JS refactoring works out of the box via the bundled typescript-language-server)

Installation

npm install
npm run build

Configuration

Environment variables:

Integration with Kimi CLI

Add to kimi-mcp.json:

{
  "mcpServers": {
    "codebase": {
      "command": "node",
      "args": ["<path-to-mcp-codebase>/dist/index.js"],
      "env": {
        "PROJECT_ROOT": "<path-to-your-codebase>",
        "PGHOST": "localhost",
        "PGPORT": "5432",
        "PGDATABASE": "codebase_index",
        "PGUSER": "postgres",
        "PGPASSWORD": "your_password"
      }
    }
  }
}

MCP Tools

project_overview

Cheap project map — call first on an unfamiliar project.

{ "max_symbols": 20 }

search_symbols

Search symbols by name with filtering.

{
  "query": "UserService|useAuth|*Controller",
  "kind": "class|function",
  "language": "typescript",
  "file_path": "src/services",
  "limit": 20
}

get_symbol_details

Full information about a symbol.

{ "symbol_id": 123 }
// or
{ "name": "UserService", "file_path": "src/services/UserService.ts" }

explore_module

Directory overview.

{ "path": "src/services", "depth": 1 }

find_usages

Find symbol usages.

{ "name": "UserService", "file_path": "src/services/UserService.ts" }

get_module_dependencies

File dependency graph.

{ "path": "src/services/UserService.ts" }

reindex

Force reindexing.

{ "full": false }

Refactoring tools (LSP-backed)

Require a language server for the file type (TS/JS out of the box; C# needs csharp-ls). All write tools accept dryRun: true to preview edits without writing.

• find_references — { "file_path": "src/util.ts", "line": 12, "column": 17 } (semantic references)

• go_to_definition — { "file_path": "src/main.ts", "line": 5, "column": 10 } (definition + hover)

• rename_symbol — { "file_path": "src/util.ts", "line": 12, "column": 17, "new_name": "hello" }

• get_diagnostics — { "file_path": "src/util.ts", "severity": "error" } (omit file_path for all stored diagnostics)

• move_file — { "old_path": "src/a.ts", "new_path": "src/lib/a.ts" }

• organize_imports — { "file_path": "src/a.ts" }

• fix_all — { "file_path": "src/a.ts" }

• extract_method — { "file_path": "src/a.ts", "start_line": 10, "end_line": 20, "new_name": "helper" }

• get_tool_stats — {} (per-tool call/error counters)

LSP env vars: LSP_ENABLED, TSSERVER_CMD, CSHARPLS_CMD, LSP_STARTUP_TIMEOUT_MS, LSP_REQUEST_TIMEOUT_MS, MCP_ERROR_LOG — see docs/configuration.md.

Architecture

src/
├── index.ts                 # MCP server
├── config.ts                # Configuration
├── db/
│   ├── connection.ts        # PostgreSQL pool
│   ├── schema.ts            # DDL and migrations
│   └── repositories.ts      # Database queries
├── indexer/
│   ├── file-crawler.ts      # File traversal
│   ├── indexer.ts           # Indexing orchestration
│   └── watcher.ts           # Watch mode (chokidar)
├── parsers/
│   ├── interface.ts         # ILanguageParser
│   ├── typescript.ts        # TS/JS parser
│   └── csharp.ts            # C# parser
├── lsp/
│   ├── client.ts            # LSP client over stdio
│   ├── backend.ts           # ILspBackend contract
│   ├── tsserver-backend.ts  # typescript-language-server
│   ├── csharp-backend.ts    # csharp-ls (needs .NET SDK)
│   ├── registry.ts          # backend lifecycle
│   ├── edits.ts             # WorkspaceEdit application
│   └── positions.ts         # path↔URI, positions
├── tools/
│   ├── search-symbols.ts
│   ├── symbol-details.ts
│   ├── explore-module.ts
│   ├── find-usages.ts
│   ├── module-deps.ts
│   ├── reindex.ts
│   ├── project-overview.ts
│   ├── tool-stats.ts
│   └── refactor/            # find-references, go-to-definition, rename-symbol,
│                            # get-diagnostics, move-file, organize-imports,
│                            # fix-all, extract-method
└── utils/
    ├── gitignore.ts
    ├── paths.ts
    └── stats.ts             # tool telemetry
benchmarks/                  # micro-benchmark suite (see docs/benchmark.md)

Performance

On the lowcodeplatform project (~71K files, ~730 source files excluding node_modules/dist):

• Full indexing: ~1.3 sec

• Symbols in the index: ~5000

• Symbol search: < 50 ms

Extending to Other Languages

1. Create a class implementing ILanguageParser

2. Register it in src/indexer/indexer.ts

3. Add the extension to config.languageMap

Example:

export class PythonParser implements ILanguageParser {
  readonly supportedExtensions = ['.py'];
  readonly languageId = 'python';
  parse(filePath: string, content: string): ParseResult | null { ... }
}