convez.ai
MCP ServerDesenvolvimento WebAvançado
ndhkaeru

Codebase MCP

ndhkaeru/codebase-mcp

Exploração eficiente de repositórios locais para agentes de IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP de alta performance em Rust que permite agentes de IA explorar, buscar e editar bases de código localmente sem carregar arquivos inteiros na memória. Oferece 25 ferramentas precisas: leitura direcionada de código, busca com escopo, análise semântica via Tree-sitter e edições estruturadas.

Instalação

$npx convez-ai ndhkaeru/codebase-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 2 semanas
Versão
v1.1.3
Issues abertas
3
Contribuidores
3

Casos de uso

  • Agentes de codificação analisando repositórios grandes sem sobrecarga de contexto
  • Refatoração de código com edições estruturadas e seguras
  • Busca semântica de símbolos, referências e dependências em múltiplas linguagens

Veredito

Solução sólida e madura para integração com agentes Claude. O design local-first, performance em Rust e 25 ferramentas especializadas fazem dele ideal para fluxos de trabalho de desenvolvimento em larga escala, especialmente com repositórios complexos.

README

A tradução para o português deste README ainda está na fila.

codebase-mcp

Rust MCP Protocol License

Let coding agents explore, search, and safely edit large repositories without loading whole files or directory trees into context.

codebase-mcp is a high-performance, local-first Model Context Protocol server written in Rust. It runs over stdio and gives an agent 25 precise tools for targeted reads, scoped search, Tree-sitter code intelligence, and structured edits, so the model spends its context window on answers, not on raw file dumps.

Everything runs on your machine. There is no external indexing service, no network calls, and no telemetry.


Highlights

  • Targeted reads: read a line range, a few snippets, or a single symbol body instead of an entire file.
  • Scoped search: literal or regex matching with glob filters and large-repo-friendly limits.
  • Code intelligence: symbols, definitions, references, imports/exports, and call graphs via Tree-sitter (13 languages).
  • Safe edits: create, edit, and delete with structured success/error metadata for auditing.
  • Persistent index: LMDB path metadata with an optional Tantivy content sidecar, kept per workspace.
  • Local-only: no external services, runs entirely over stdio.

Quick Start

1. Get the binary

Download a prebuilt binary (Windows): Grab the latest codebase-mcp-windows-x64.exe or codebase-mcp-windows-arm64.exe from the Releases page.

Build from source (all platforms, requires the Rust stable toolchain):

cargo build --release

The binary is written to:

  • Windows: target/release/codebase-mcp.exe
  • Linux/macOS: target/release/codebase-mcp

2. Add it to your MCP client

Register the binary as a stdio server with one command. Replace the path with your binary location.

Claude Code

claude mcp add codebase-mcp -- /path/to/codebase-mcp

OpenAI Codex CLI

codex mcp add codebase-mcp -- /path/to/codebase-mcp

Gemini CLI

gemini mcp add codebase-mcp -- /path/to/codebase-mcp

On Windows, use the full .exe path, for example C:\path\to\codebase-mcp.exe.

Prefer editing a config file, or using Cursor, Windsurf, Cline, Roo, or VS Code? See Client Configuration below.


Why codebase-mcp?

Coding agents waste context (and money) when they read more than they need. codebase-mcp keeps responses small and on-target:

Without itWith codebase-mcp
Read a 2,000-line file to inspect one functionread_symbol_body returns the function body plus signature only
Dump the whole tree to find a filefuzzy_find / project_map return a scoped, bounded view
cat a file and grep it inlinetext_search with paths, includes, and max_results
Multiple round trips to gather contextbatch_tool_call bundles related calls into one request

The result: fewer tokens, faster turns, and answers grounded in the real repository.


Tools

25 tools, grouped by purpose. Each returns output in the standard MCP content array shape.

Files and Edits

ToolDescription
resolve_pathNormalize a path and return preflight accessibility metadata.
read_file_rangeRead a file or line range with encoding detection and truncation metadata.
count_file_linesCount lines in a text file with basic encoding and binary detection.
read_snippetsRead multiple file ranges in one request.
convert_file_formatRewrite a file with normalized encoding and line endings.
create_fileCreate or overwrite a file with optional parent creation, encoding, and line endings.
create_directoryCreate a directory with optional parent creation and structured results.
delete_fileDelete a file with structured success and error metadata.
edit_fileEdit a file using replace, append, prepend, or find-replace modes.
file_summaryReturn quick file metadata, binary detection, and a short preview.

Search and Workspace

ToolDescription
text_searchSearch files or directories using literal or regex matching.
fuzzy_findFuzzy path and file-name search across one or more roots.
project_mapBuild a tree view of a project with optional size metadata.
workspace_statsSummarize file, line, and language counts for a workspace path.

Code Intelligence

ToolDescription
get_symbolsExtract Tree-sitter AST symbols from source files.
read_symbol_bodyRead a symbol body with AST-first resolution and heuristic fallback.
find_definitionFind likely symbol definitions across the project.
find_referencesFind symbol references across the project.
list_importsList imports (Rust, JS/TS, Swift, Objective-C).
list_exportsList exports (Rust, JS/TS, Swift, Objective-C).
get_call_graphList outbound calls made from a function or symbol.
compare_symbolsCompare two resolved symbols and return metadata plus a unified diff.

Data and Diagnostics

ToolDescription
peek_archiveList archive entries or read a file inside an archive.
server_healthCheck server uptime and indexing health.
batch_tool_callRun multiple tools sequentially in one request and flatten combined results.

Supported Languages

The AST-backed code-intelligence tools (get_symbols, read_symbol_body, find_definition, find_references, get_call_graph, compare_symbols) use Tree-sitter and support these languages:

LanguageExtensions
Rust.rs
C.c
C++.cc, .cpp, .cxx, .h, .hh, .hpp, .hxx, .inc, .inl
Go.go
Java.java
C#.cs
PHP.php
Ruby.rb
JavaScript.js, .jsx, .mjs, .cjs
TypeScript.ts, .tsx
Python.py
Swift.swift
Objective-C.m, .mm

list_imports and list_exports currently support a subset: Rust, JavaScript/TypeScript, Swift, and Objective-C. The file, search, and workspace tools (text_search, fuzzy_find, read_file_range, and others) work on any text file regardless of language. Files larger than 2 MB are skipped by the AST parser.


Example Tool Calls

Search Rust files with regex:

{
  "name": "text_search",
  "arguments": {
    "query": "TODO|FIXME",
    "paths": ["/workspace"],
    "mode": "regex",
    "includes": ["*.rs"],
    "max_results": 50
  }
}

Read multiple focused snippets in one call:

{
  "name": "read_snippets",
  "arguments": {
    "max_total_bytes": 24000,
    "requests": [
      { "path": "/workspace/src/main.rs", "start_line": 1, "end_line": 80 },
      { "path": "/workspace/src/lib.rs", "start_line": 1, "end_line": 60 }
    ]
  }
}

Read a symbol body with its signature:

{
  "name": "read_symbol_body",
  "arguments": {
    "symbol": "processPayment",
    "paths": ["/workspace/src"],
    "include_signature": true
  }
}

Batch related calls in one MCP round trip:

{
  "name": "batch_tool_call",
  "arguments": {
    "calls": [
      { "tool": "file_summary", "args": { "path": "/workspace/README.md" } },
      { "tool": "project_map", "args": { "path": "/workspace", "max_depth": 2 } }
    ]
  }
}

Client Configuration

Use the release binary as a stdio MCP server. On Windows, point command to the .exe file.

{
  "mcpServers": {
    "codebase-mcp": {
      "command": "C:\\path\\to\\codebase-mcp\\target\\release\\codebase-mcp.exe",
      "args": []
    }
  }
}
{
  "mcpServers": {
    "codebase-mcp": {
      "command": "/absolute/path/to/codebase-mcp/target/release/codebase-mcp",
      "args": []
    }
  }
}
{
  "servers": {
    "codebase-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/codebase-mcp/target/release/codebase-mcp",
      "args": []
    }
  }
}

Runtime Configuration

VariablePurpose
CODEBASE_MCP_INDEX_DIROverrides the persistent index cache directory.
CODEBASE_MCP_TANTIVY_ENABLEDEnables the Tantivy content sidecar. Defaults to true.

Chromium-sized defaults are built in: path index map size is 8 GB, stale path metadata refreshes after 1 hour, Tantivy reads up to 2 MB per file, warms up to 4 GB per content zone, and caps each workspace content sidecar at 16 GB.

Workspace roots are dynamic: the server indexes client-provided workspaceFolders, roots, rootUri, or clientInfo.workspaceRoot; if none are provided, it falls back only to the process current directory when that directory looks like a workspace root. Relative tool paths resolve against the active indexed workspace, so clients should send the workspace for each chat session.

The server keeps one index per canonical workspace root.

  • Windows default: %LOCALAPPDATA%\codebase-mcp\index-v2\<workspace_hash>\
  • Linux/macOS default: $XDG_CACHE_HOME/codebase-mcp/index-v2/<workspace_hash>/ or ~/.cache/codebase-mcp/index-v2/<workspace_hash>/
  • Custom root: <CODEBASE_MCP_INDEX_DIR>\index-v2\<workspace_hash>\
  • Tantivy sidecar: <workspace_index_dir>\tantivy-content\

LMDB stores path metadata. Tantivy is used as an optional sidecar for warmed content zones. When a query or scope cannot be served from the content index, tools fall back to filesystem scanning where appropriate.


Behavior and Safety

  • The server exposes tools only: no MCP resources, prompts, or templates.
  • Tool responses are returned in the standard MCP content array shape.
  • batch_tool_call executes calls sequentially and rejects recursive batch calls.
  • Mutating tools return structured write metadata for auditing; write tools return structured success or error payloads instead of free-form text.
  • read_file_range and search-oriented tools keep output bounded for agent context.
  • Tool calls default to a 60-second timeout. Clients may request longer calls with timeout_seconds, capped at 600 seconds.
  • A global rate limiter protects the server from excessive request volume.
  • server_health reports uptime and indexing status for readiness checks.

Large Repository Tips

  • Scope paths to the smallest relevant subtree.
  • Prefer concrete path tokens and basenames for fuzzy_find.
  • Keep project_map shallow, for example max_depth <= 2.
  • Use recursive glob excludes such as third_party/**, node_modules/**, target/**, dist/**, and out/**.
  • Use read_snippets after search results instead of reading full files.
  • Treat Tree-sitter results as local syntactic intelligence, not as a replacement for full semantic language servers.

Development

Format, lint, and test:

cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo test --release

Repository layout

src/
  main.rs              MCP stdio server, JSON-RPC handling, logging, timeouts
  mcp.rs               JSON-RPC request/response types
  common.rs            shared path and environment helpers
  version.rs           package version export
  indexer/             LMDB/Tantivy workspace indexing
  history/             write-change metadata support
  security/            path guarding and rate limiting
  tools/               MCP tool implementations and schemas
tests/                 integration and behavior tests

Project Status

  • Package: codebase-mcp
  • Version: 1.3.1
  • Runtime: Rust + Tokio
  • Transport: MCP stdio
  • MCP protocol version: 2024-11-05
  • Tool count: 25
  • License: Apache-2.0

Acknowledgements

Built on Tree-sitter, Tantivy, LMDB (via heed), Tokio, and the Model Context Protocol.

License

Apache-2.0. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados