MCP server MSCodebase Intelligence
Commit 15 de nov. de 2026Fornece inteligência de codebase local-first para assistentes de IA, incluindo busca lexical, grafos de chamada, análise de impacto e memória do projeto.
Também conhecido como ManSio/mscodebase-intelligence
- Stars
- 3
- Ferramentas
- 14
- Downloads, 30 dias
- —
- Versão mais recente
- —
- Último commit
- 15 de nov. de 2026
- Licença
- MIT
O que é o MCP MSCodebase Intelligence?
MSCodebase Intelligence é um MCP server. Fornece inteligência de codebase local-first para assistentes de IA, incluindo busca lexical, grafos de chamada, análise de impacto e memória do projeto. Ele expõe 14 ferramentas, como full, investigate, search_code.
Resumo gerado a partir do README do projeto
Sobre o MCP server de MSCodebase Intelligence
O mscodebase-intelligence permite fornecer inteligência de codebase local-first para assistentes de IA no OpenCode ou Zed. Ele funciona como um MCP server local que oferece uma visão fundamentada do seu código sem exigir GPU, conexão de rede ou banco de dados vetorial. Ao utilizar uma abordagem focada em texto com SQLite FTS5/BM25 e um Tree-sitter PropertyGraph, ele permite que desenvolvedores realizem investigações complexas por meio de um único comando.
Os usuários interagem com o servidor por meio de ferramentas como a investigate, que executa buscas paralelas, consultas de símbolos e análise de impacto para fornecer uma resposta consolidada com procedência. O servidor suporta diversas operações, incluindo busca lexical, regex grep e inteligência de símbolos para definições e chamadores. Ele também gerencia a memória do projeto, como ADRs e problemas conhecidos, e oferece capacidades de escrita segura para renomear ou mover arquivos com proteções de impacto. O sistema foi projetado para ser leve, utilizando por padrão um perfil principal de 17 ferramentas para evitar o excesso de contexto (context flooding), permanecendo extensível para usuários avançados.
O que você pode fazer com ele
- 1Realizar investigações profundas de códigoFaça uma única pergunta para acionar buscas paralelas, consultas de símbolos e análise de impacto para entender lógicas complexas.
- 2Analisar o impacto de mudançasDetermine quais partes do sistema serão afetadas se um símbolo ou função específica for modificada.
- 3Executar refatoração de código seguraAplique renomeações, movimentações ou substituições no codebase utilizando proteções de impacto para garantir a segurança.
- 4Recuperar histórico e decisões do projetoConsulte a memória do projeto para encontrar registros de decisões arquiteturais ou problemas conhecidos existentes.
Escrito a partir do README do projeto. Cada caso de uso é verificado com uma citação dele.
Ferramentas do MCP MSCodebase Intelligence 14
Detectadas a partir do READMEfullinvestigatesearch_codegrep_codeget_symbol_infoimpact_analysisgraph_querycodebaseread_live_filenotify_changeget_health_reportintel_get_project_memory
| full | — | |
| investigate | — | |
| search_code | — | |
| grep_code | — | |
| get_symbol_info | — | |
| impact_analysis | — | |
| graph_query | — | |
| codebase | — | |
| read_live_file | — | |
| notify_change | — | |
| get_health_report | — | |
| intel_get_project_memory | — |
Mostrar todas as 14 ferramentasMostrar menos ferramentas
predict_changetool_help
| predict_change | — | |
| tool_help | — |
Verificações automatizadas
Executado em 14 de nov. de 2026Relatório completo →Ainda não verificado. Um servidor precisa de uma pontuação de 80, nenhum problema grave e dados suficientes para verificarmos. Como as verificações funcionam · O que corrigir para ganhar mais pontos
- Repositório de origem vinculado e acessívelmansio/mscodebase-intelligence is public and reachablegithub.com/mansio/mscodebase-intelligence ↗Passou
- O pacote indica este repositório como sua origemNão verificado
- Proveniência da build (atestação Sigstore)Não verificado
- Licença de código aberto (OSI)MITspdx.org/licenses/MIT.html ↗Passou
- Commit ou release no último anoLast commit or release 2026-11-13github.com/mansio/mscodebase-intelligence ↗Passou
- OpenSSF ScorecardNão verificado
- Nome do pacote não é próximo a um pacote popularNão verificado
- Nenhum aviso crítico no pacote ou em suas dependênciasNão verificado
- Sem instruções ocultas para o modelo14 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPassou
- Ferramentas destrutivas estão rotuladasNo tool named like delete, drop or execPassou
- O endpoint remoto responde ao handshake do MCPNão verificado
README
Ver no GitHubMSCodebase Intelligence
Local-first code intelligence for OpenCode and Zed: one question in, parallel retrieval out — lexical search, call graph, impact analysis, project memory and safe writes, over MCP.
Last rewritten: 2026-11-08. This page describes the code as it is today; the English page is authoritative.
What this is
MSCodebase Intelligence is a local MCP server that gives an AI assistant in OpenCode (or Zed) a grounded view of a codebase. It is not a chat model and not a replacement for the editor's language server. It answers four kinds of questions:
- Where is this symbol defined, who calls it, and what breaks if it changes?
- Which files matter for this question — code, tests, or documentation?
- What did this project already decide, and which incidents are still open?
- Can a rename/move/replace be previewed and applied safely?
The default runtime is text-first: SQLite FTS5/BM25 over parsed chunks plus a Tree-sitter/PropertyGraph index. Embeddings and rerankers are optional; no GPU, network or vector database is required to answer a code question.
What works today
| Area | What it does | Entry point |
|---|---|---|
| One-call investigation | One question → search + symbols + grep in parallel, then impact + callers + tests + project memory; merged by file:line with provenance and degraded[] |
investigate |
| Code search | BM25/FTS5 over parsed chunks; identifier short-circuit through the graph; optional on-demand rerank of the top candidates | search_code |
| Docs search | Separate docs/** FTS channel, selected when the BM25 margin is strong (no LLM router) |
search_code |
| Regex search | Regex with AST-aware scope=code that skips comments and strings, judged per match |
grep_code |
| Symbol intelligence | Definition, callers, callees, references, impact, structural search | get_symbol_info, impact_analysis |
| Graph | PropertyGraph of files/symbols with call, import, assignment, decorator and override edges | graph_query, codebase |
| Project memory | ADRs, incidents, known issues, retract/supersede lifecycle | intel_* (hidden by default) |
| Safe writes | Rename, move, delete, replace, insert with impact guards and receipts | codebase(action=…) |
| Diagnostics | Health, index status, logs, runtime counters, predicted change | get_health_report, predict_change |
| Tool discovery | Active profile, visible tools, hidden tools and how to enable them | tool_help |
How a question is answered
investigate is the default entry point. It does not make the model choose
between tools; it runs the relevant channels itself and merges the answers.
investigate("how does the indexer decide to reindex a file")
│
├─ pass 1 (parallel) search ─ symbols ─ grep
│ each with its own timeout
▼
├─ pass 2 (parallel) impact ─ callers ─ tests ─ project memory
│ only for what pass 1 found
▼
merge by (file, line): one row per hit, channels unioned [search+graph]
provenance on every item, degraded[] for a slow/failed channel
Rules that matter:
- A slow channel degrades the answer (
degraded: grep:timeout); it never fails the call. - A question with no matches returns an explicit "nothing found" — never a plausible guess.
- The merged answer is capped (default 8 rows, 180 characters of text each), so it does not flood the context.
search_code,grep_code,get_symbol_infoandimpact_analysisstay available for a precise follow-up.
Search quality: measured, with its limits
Numbers only mean something with the measuring stick attached. These come from
an internal 48-query panel (33 real project questions plus 15
docstring-derived ones), on a clean index with experiments/** excluded.
Snapshot date: 2026-10-25; re-run the harnesses under experiments/
before quoting them as current.
| Path | hit@1 | hit@5 |
|---|---|---|
| Code, quality mode | 0.825 | 0.900 |
| Overall, quality mode | 0.688 | 0.750 |
| Overall, auto docs route | 0.792 | 0.875 |
| Fast mode | 0.542 | 0.729 |
| Docs, exact path | 0.000 | 0.125 |
| Docs, same basename | 0.750 | 0.750 |
What this does not mean:
- It is not 95% accuracy. Static retrieval on this panel did not reach it; a two-channel repo map topped out around 40% / 62% / 73% at 1k / 2k / 4k tokens with perfect routing.
- It does not mean every reranker helps. Several local rerankers were measured and rejected: they lowered hit@1 or added unacceptable latency.
- It does not mean the docs path is broken: it often returns the right
document in another language (
docs/ru/Xfordocs/en/X). That is a gold-labeling property, not a retrieval failure.
The panel, hypotheses and raw runs live under experiments/. Every public
number and the command that regenerates it are listed in
docs/FACTS.md.
Quick start
Requirements: Windows is the validated platform; Python 3.14+; an MCP host (OpenCode is the primary one, the Zed extension still works).
cd <repo-root>
python install.py # full install: venv, pip, optional models
python install.py --sync # code-only sync into the installed copy
Restart the host after install.py finishes (the OpenCode session, or the Zed
window). The installed copy lives in %LOCALAPPDATA%\Zed\extensions\mscodebase-intelligence
and both hosts launch that venv. Verify from the agent panel:
tool_help() # profile, visible and hidden tools
get_health_report() # index, embedder, resources
codebase(action="index", path="status")
If the text index is missing or stale, rebuild chunks and graph without embeddings (measured: 498 files, 7 375 chunks, 262–266 s on this repository):
python scripts/reindex_text_only.py --project .
If only the graph is empty while chunks exist:
python scripts/rebuild_graph.py
Then restart the MCP server so the new process opens the rebuilt stores.
Tools and the profile
The server registers 69 tools (36 core + 16 intel + 13 inline + 4 dev);
execute_script is an optional 70th behind
MSCODEBASE_EXECUTE_SCRIPT_ENABLED=true. That is too many for a model to pick
from, so the client sees a profile:
| Profile | Visible | What it contains |
|---|---|---|
core (default) |
17 | one entry per intent + 4 maintenance tools |
full |
69 | everything registered |
MSCODEBASE_MCP_TOOLS remains an explicit comma-separated allowlist and
overrides the profile when set. tool_help() reports the active profile, the
visible tools with a one-line intent, and the hidden names.
Default-visible 17:
| Tool | Purpose |
|---|---|
investigate |
one query → parallel channels, merged with provenance |
search_code |
ranked code/docs search (FTS5/BM25, docs routing) |
grep_code |
regex search; scope=code skips comments/strings |
get_symbol_info |
definition, callers, callees |
impact_analysis |
what breaks if a symbol changes |
graph_query |
related files, variable flow, cypher, impact |
codebase |
hub: index status, git, write actions |
read_live_file |
read a line range from disk |
notify_change |
tell the index a file changed |
get_health_report |
index, embedder, resources, search quality |
intel_get_project_memory |
ADRs, incidents, known issues |
predict_change |
changed files, affected tests, risk |
tool_help |
profile and discovery |
generate_docs, bump_version, auto_update_docs, install_git_hooks |
maintenance |
Indexing is asynchronous: codebase(action="index", path="project_dir", project_root=...) starts a
background job and returns immediately; poll codebase(action="index", path="progress", ...) for
state / files / elapsed. A project that is not indexed yet is refused fast with the exact
remediation instead of a 5-second wait.
Hidden by default (registered, not exposed): the six lsp_* tools,
plan_search, structural_search, the 16 intel_* mutation/lifecycle tools,
submit_background_task / get_task_status / verify_action /
get_action_receipt, ack_impact, and the frame/rank/scan helpers. Set
MSCODEBASE_MCP_PROFILE=full to expose them; nothing is removed from the
server, only filtered from the client surface.
Architecture
MCP host: OpenCode (primary) or Zed
│
├── host built-in LSP (autocomplete, diagnostics)
│
└── MCP client
│
▼
MSCodebase MCP server
├── investigate two-pass parallel fan-out, merged with provenance
├── Search SQLite FTS5/BM25, symbol/path signals, docs routing
├── Graph PropertyGraph: calls, imports, assignments, decorators, overrides
├── Index parser → chunks → FTS5 + graph; incremental freshness checks
├── Memory ADRs, incidents, known issues, retract/supersede
├── Writes rename/move/delete/replace/insert with impact guards
├── Diagnostics health, jobs, logs, telemetry, change preview
└── Optional embedding providers, reranker, LSP rename
Canonical data locations (outside the repository):
%LOCALAPPDATA%/mscodebase/projects/<hash>/— per-project graph, memory, job state, commit memory, telemetry.%LOCALAPPDATA%/mscodebase/logs/— server logs.<project>/.mscodebase/chunks.db— the text chunk store used by the default search path.
LanceDB is part of the optional vector path and is not required by the default text-first configuration.
Configuration
Settings are environment variables with defaults in src/config/settings.py.
The ones that change behaviour most:
| Variable | Default | Effect |
|---|---|---|
MSCODEBASE_DENSE_OFF |
true |
Skip dense/vector retrieval; use FTS5, symbols, graph |
MSCODEBASE_SQLITE_CHUNKS |
true |
Use the SQLite/FTS5 chunk store |
MSCODEBASE_ONDEMAND_RERANK |
false |
Rerank the top candidates with live embeddings; per call: investigate(rerank=true) |
MSCODEBASE_DOCS_MARGIN |
4.0 |
Docs routing threshold (docs score − code score) |
MSCODEBASE_AUGMENT_CHUNKS |
true |
Prepend FILE/SYMBOLS/DOC to chunk text |
MSCODEBASE_TESTS_SIGNAL |
false |
Append covering tests to symbol results |
MSCODEBASE_CODE_BM25 |
false |
Identifier-aware BM25 scoring |
MSCODEBASE_RU_SYNONYMS |
false |
Russian → English code-term expansion |
MSCODEBASE_MCP_PROFILE |
core |
Tool surface: 17 visible, or all 69 with full |
MSCODEBASE_MCP_TOOLS |
— | Explicit allowlist; overrides the profile |
experiments/** is intentionally excluded from indexing: it contains frozen
panels and run artifacts, and indexing them previously made BM25 return the
panel instead of the code. The files stay tracked in git.
Supported languages
Python is the primary, fully exercised language. Tree-sitter parsing covers JavaScript, TypeScript/TSX, Rust, Go, Java, C#, Ruby, PHP, Kotlin, Swift, C, C++, Scala and Dart; SQL, YAML, TOML, HTML, CSS and HCL/Terraform are indexed as context, without the same call-graph coverage. The current build loads 31 grammars. Graph and data-flow depth depend on the grammar.
Versions are pinned for reproducibility: tree-sitter==0.26.0 (the latest
Python binding on PyPI), tree-sitter-language-pack==1.25.0, and one pinned
release per grammar package. A grammar bump changes chunking, so it requires a
reindex and a symbol-count comparison, not a routine upgrade.
Limitations
Deliberate, documented boundaries rather than hidden behaviour:
- Docs gold vs language: the docs channel may return
docs/ru/X.mdwhen the gold isdocs/en/X.md. Normalize by basename when evaluating. - Auto docs routing is heuristic: a code query with strong documentation
words can still be routed to docs;
intent="code"is the escape hatch. - Full vector reindex is blocked while
MSCODEBASE_DENSE_OFF=true. Usescripts/rebuild_graph.pyfor the graph andscripts/reindex_text_only.pyfor chunks. - No 95% claim. Static retrieval and the tested local rerankers did not reach it. An LLM planner is a separate experiment, not the default path.
- Fast mode is not quality mode: faster, materially less accurate on mixed natural-language questions.
- Tool visibility is a profile: 69 registered, 17 visible. If a tool you
expect is missing, run
tool_help()and switch the profile. - LSP tools need a working basedpyright: they fail fast with a clear message when it is missing, and the result is cached for 30 seconds.
Development
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
# Focused search tests
pytest tests/test_search_docs.py tests/test_query_plan.py tests/test_searcher.py -q
# Full suite (integration/benchmark selected by markers)
pytest tests/ -m "not integration and not benchmark"
# Live smoke: real services, no mocks
python scripts/smoke_e2e.py --project .
The repository uses Conventional Commits, keeps experiment inputs under
experiments/**/frozen/, and records results in EXPERIMENTS_LOG.md,
AGENT_DIARY.md and KNOWN_ISSUES.md.
Reporting a bug
A useful report is a small experiment:
- The exact tool call and parameters (
query,mode,intent,limit). tool_help()/get_health_report()andcodebase(action="index", path="status").- Whether the graph was rebuilt and which flags were set
(
MSCODEBASE_DENSE_OFF,MSCODEBASE_ONDEMAND_RERANK, profile). - The expected file and the actual file(s), and whether the match is exact-path or same-basename.
- The relevant log tail from
%LOCALAPPDATA%/mscodebase/logs/.
That separates four failures that look alike: bad ranking, missing candidate, stale/empty index, and gold-label mismatch.
Documentation map
| Document | What it covers |
|---|---|
| docs/FACTS.md | Every public number and the command that regenerates it |
| docs/en/ARCHITECTURE.md | Layers, DI, module boundaries, tool profile |
| docs/en/SEARCH_PIPELINE.md | Retrieval, ranking, docs routing, investigate fan-out |
| docs/en/INSTALL.md | Installation, the sync/restart loop, troubleshooting |
| docs/en/CONFIGURATION.md | Every environment variable and its default |
| docs/en/CLIENTS.md | OpenCode, Zed, Claude Code, VS Code, CLI, Docker |
| docs/en/HOOKS_AND_GATES.md | The OpenCode plugin, the 12 pre-commit gates, CI jobs |
| docs/en/FAQ.md | Short answers to the questions that come up first |
| docs/en/SECURITY.md | Threat model of a local MCP server |
| docs/en/GRACEFUL_DEGRADATION.md | Behaviour when providers are unavailable |
| docs/en/ZED_WINDOWS_QUIRKS.md | Windows behaviour shared by both hosts |
| docs/en/CHANGELOG.md | Version history |
| AGENTS.md | Rules for AI agents working in this repository |
| KNOWN_ISSUES.md | Open debt and observations |
| EXPERIMENTS_LOG.md | Experiment hypotheses and raw results |
Russian and Chinese translations of every canonical page live in
docs/ru/ and docs/zh/ with the same file names.
Historical material (blog posts, research notes, archived diaries) is kept for provenance and carries a status banner; it is not a description of today.
License
MIT. See LICENSE.
Perguntas sobre o MCP MSCodebase Intelligence
Quais ferramentas o MCP MSCodebase Intelligence oferece?
Ele expõe 14 ferramentas, incluindo full, investigate, search_code, grep_code, get_symbol_info.
Que tipo de perguntas este servidor pode responder?
Ele responde perguntas sobre definições de símbolos, chamadores (callers), análise de impacto de mudanças, arquivos relevantes (código, testes ou documentação) e decisões ou incidentes do projeto.
É necessário uma GPU ou um banco de dados vetorial?
Não, o runtime padrão é focado em texto usando SQLite FTS5/BM25 e um índice Tree-sitter, portanto não é necessária GPU, conexão de rede ou banco de dados vetorial.
Quais editores são suportados?
O servidor foi projetado para OpenCode e Zed.
Como funciona a ferramenta 'investigate'?
Ela realiza uma busca paralela em duas etapas, incluindo busca, símbolos e grep, seguida por impacto, chamadores, testes e memória do projeto, mesclando os resultados em seguida.