Code-Index-MCP

Um indexador de código local-first que aprimora LLMs com compreensão profunda de código. Ele se integra a assistentes de IA via Model Context Protocol (MCP) e oferece suporte à busca semântica baseada em IA.

GitHub

Experimente este MCPPatrocinado

Documentação

Code-Index-MCP

Dê ao seu assistente de codificação com IA busca instantânea e precisa em todo o seu código — para que ele encontre o código exato de que precisa em milissegundos, em vez de gastar tempo e tokens lendo arquivos inteiros.

Code-Index-MCP é um índice de busca rápido e local-first para o seu código. Ele se conecta ao Claude Code e a outros assistentes de IA (por meio do Model Context Protocol, "MCP") e permite que eles consultem qualquer símbolo ou pesquisem qualquer texto no seu repositório quase instantaneamente — sem que o seu código saia da sua máquina.

Novo no Code-Index-MCP? Comece com o Guia de Introdução.

Status: superfície estável v1.4.0 preparada — ferramentas MCP (search_code, symbol_lookup) são a interface principal; um gateway administrativo FastAPI está disponível para diagnósticos.

Status da preparação da superfície estável: este guia tem como alvo o release candidate de endurecimento 1.4.0 de propriedade do repositório. O MCP STDIO permanece como a principal superfície LLM e o FastAPI permanece como uma superfície administrativa secundária. Uma verificação de colisão em 10 de julho de 2026 não encontrou index-it-mcp==1.4.0 ativo, portanto este guia usa prova de fonte e wheel local em vez de afirmar que a superfície 1.4.0 preparada está publicada.

Status do Projeto

Versão: 1.4.0 (superfície preparada de propriedade do repositório; não publicada em 10 de julho de 2026) Distribuição Python: index-it-mcp Imagem de contêiner: ghcr.io/consiliency/code-index-mcp Superfície primária: ferramentas MCP (search_code, symbol_lookup) via runner STDIO quando a prontidão do repositório é ready Superfície secundária: gateway REST administrativo FastAPI para diagnósticos e scripts — consulte "Interface REST Administrativa (secundária)" abaixo Recursos principais: indexação local, busca de símbolos/texto, cobertura de linguagens baseada em registro; consulte docs/SUPPORT_MATRIX.md Recursos opcionais: busca semântica (requer Voyage AI ou um endpoint vLLM local), sincronização de índice de GitHub Artifacts Desempenho: consulta de símbolos abaixo de 100ms e busca abaixo de 500ms em repositórios indexados (benchmark neste código; resultados variam conforme o tamanho do repositório e a mistura de linguagens) Decisão de GA: consulte docs/validation/ga-final-decision.md; a decisão atual do produto é ship GA, enquanto as alegações de superfície de instalação permanecem limitadas por docs/status/public-package-identity.md. Contrato de prontidão para GA: consulte docs/validation/ga-readiness-checklist.md para o limite de release congelado, rótulos de nível de suporte, propriedade de evidências e expectativas de rollback que se aplicam antes do despacho. Despacho de release: o registro histórico de governança nomeia esse limite como GADISP; o fluxo de trabalho atual o implementa como um modo separado publish restrito a main protegidos. Modelo de repositório: um servidor pode atender a muitos repositórios não relacionados, com um worktree registrado por diretório comum do git. Apenas o branch rastreado/padrão é indexado automaticamente. Os resultados MCP indexados são autoritativos somente quando a prontidão é ready; índices indisponíveis retornam index_unavailable com safe_fallback: "native_search".

MCP_CLIENT_SECRET é uma proteção local de handshake STDIO para mcp-index stdio. O gateway FastAPI usa autenticação separada de token bearer administrativo/debug, e nenhuma autorização MCP remota é implementada enquanto o transporte MCP remoto permanecer adiado.

Por que existe

Quando um assistente de IA trabalha em um código grande, ele frequentemente lê grandes blocos de arquivos apenas para encontrar o que precisa. Isso é lento, e cada arquivo lido custa tokens (dinheiro). O Code-Index-MCP constrói um índice local para que o assistente possa ir direto para a função, classe ou linha certa — reduzindo o custo de tokens e tornando as respostas mais rápidas e precisas.

Para quem é

Desenvolvedores e equipes que usam assistentes de codificação com IA em bases de código reais e consideráveis que desejam resultados mais rápidos, mais baratos e mais precisos — e que desejam que seu código permaneça privado, na própria máquina.

O que você obtém

⚡ Consultas instantâneas — consulta de símbolos abaixo de 100ms, busca abaixo de 500ms em repositórios indexados.
🔒 Local-first e privado — a indexação roda na sua máquina; seu código não é enviado para a nuvem.
💸 Menor custo de tokens — o assistente pesquisa em vez de ler arquivos inteiros (veja os gráficos abaixo).
🧠 Busca semântica (opcional) — busca de código em linguagem natural via embeddings.
🌐 Muitas linguagens, muitos repositórios — um servidor pode indexar vários repositórios com linguagens mistas.
🔌 Baseado em plugins e extensível — adicione suporte a linguagens sem tocar no núcleo.

Veja em ação

Benchmarks neste repositório mostram grandes reduções de tokens/custos quando um assistente pesquisa com Code-Index-MCP em vez de ler arquivos diretamente:

Token and cost savings — summary

Cost savings

Token reduction by language

(Gráficos gerados a partir dos benchmarks em reports/; números variam conforme o tamanho do repositório e a mistura de linguagens.)

🎯 Recursos Principais

🚀 Arquitetura Local-First: Toda a indexação acontece localmente para velocidade e privacidade
📂 Armazenamento de Índice Local: Todos os índices armazenados em .indexes/ (relativo ao servidor MCP)
🔌 Design Baseado em Plugins: Facilmente extensível com plugins específicos de linguagem
🔍 Suporte a linguagens: Suporte em camadas de linguagens/runtimes documentado em docs/SUPPORT_MATRIX.md
⚡ Atualizações em Tempo Real: Monitoramento do sistema de arquivos para atualizações instantâneas de índice
🧠 Busca Semântica: Busca de código com IA usando embeddings Voyage AI
📊 Inteligência de Código Rica: Resolução de símbolos, inferência de tipos, rastreamento de dependências
🚀 Desempenho Aprimorado: Consultas abaixo de 100ms com proteção de timeout e bypass BM25
🔄 Sincronização Git: Atualizações automáticas de índice rastreando mudanças no repositório
📦 Gerenciamento de Índice Portátil: Compartilhamento de índice com custo zero via GitHub Artifacts
🔄 Sincronização Automática de Índice: Puxa índices no clone, envia em mudanças
🎯 Reordenação Inteligente de Resultados: Reordenação multi-estratégia para relevância aprimorada
🎯 Roteamento de Intenção de Consulta: Consultas de padrão de símbolo (class Foo, def bar, CamelCase) ignoram BM25 e acessam diretamente a tabela de símbolos para consultas abaixo de 5ms
🔒 Exportação Consciente de Segurança: Filtragem automática de arquivos sensíveis de índices compartilhados
🔍 Busca Híbrida: BM25 + busca semântica com fusão configurável
🔐 Indexe Tudo Localmente: Pesquise arquivos .env e segredos na sua máquina
🚫 Filtragem Inteligente ao Compartilhar: Padrões .gitignore e .mcp-index-ignore aplicados apenas durante a exportação
🌐 Indexação Multi-Linguagem: Indexe repositórios inteiros com linguagens mistas

🏗️ Arquitetura

O Code-Index-MCP segue uma arquitetura modular baseada em plugins projetada para extensibilidade e desempenho:

Camadas do Sistema

🌐 Contexto do Sistema (Nível 1)
- Desenvolvedor interage com Claude Code ou outros LLMs
- Protocolo MCP fornece interface padronizada de ferramentas
- Processamento local-first com recursos opcionais de nuvem
- SLAs de desempenho: <100ms para consulta de símbolos, <500ms para busca

📦 Arquitetura de Contêiner (Nível 2)

┌─────────────────┐     ┌──────────────┐     ┌─────────────┐
│   API Gateway   │────▶│  Dispatcher  │────▶│   Plugins   │
│   (FastAPI)     │     │              │     │ (Language)  │
└─────────────────┘     └──────────────┘     └─────────────┘
       │                        │                     │
       ▼                        ▼                     ▼
┌─────────────────┐     ┌──────────────┐     ┌─────────────┐
│  Local Index    │     │ File Watcher │     │  Embedding  │
│  (SQLite+FTS5)  │     │  (Watchdog)  │     │   Service   │
└─────────────────┘     └──────────────┘     └─────────────┘

🔧 Detalhes dos Componentes (Nível 3)
- Gateway Controller: Endpoints de API RESTful
- Dispatcher Core: Roteamento de plugins e ciclo de vida
- Plugin Base: Interface padrão para todos os plugins
- Language Plugins: Parsers e analisadores especializados
- Index Manager: SQLite com FTS5 para buscas rápidas
- Watcher Service: Monitoramento de arquivos em tempo real

🔐 Segurança

O Code-Index-MCP implementa endurecimento de segurança em profundidade (Fase 15):

Sandbox de Plugins: Plugins executam em processos de trabalho isolados com restrições baseadas em capacidades. Consulte docs/security/sandbox.md.
Atestação de Artefatos: Índices publicados são assinados com atestações SLSA do GitHub e verificados no download. Consulte docs/security/attestation.md.
Proteção contra Path Traversal: Resultados de busca são validados para impedir fuga das raízes configuradas do repositório. Consulte docs/security/path-guard.md.
Validação de Tokens: Tokens do GitHub são validados para escopos necessários na inicialização (contents:read, metadata:read, actions:read, actions:write, attestations:write). Consulte docs/security/token-scopes.md.
Autenticação de Métricas: O endpoint /metrics requer autenticação com token bearer.

MCP_CLIENT_SECRET é apenas uma proteção local de handshake STDIO. Não é a autenticação de token bearer administrativo/debug do gateway, e nenhuma autorização MCP remota é implementada enquanto o repositório continuar adiando o transporte MCP remoto.

Para um runbook abrangente de operador, consulte docs/operations/user-action-runbook.md.

📁 Estrutura do Projeto

O projeto segue uma estrutura limpa e organizada. Consulte docs/PROJECT_STRUCTURE.md para o layout detalhado.

Diretórios principais:

mcp_server/ - Implementação principal do servidor MCP
scripts/ - Scripts de desenvolvimento e utilitários
tests/ - Suíte de testes abrangente com fixtures
docs/ - Documentação e guias
architecture/ - Design do sistema e diagramas
docker/ - Configurações Docker e arquivos compose
mcp-index-kit/ - Toolkit de indexação MCP compartilhado e exemplos
docs/status/ - Notas de evidência duráveis mantidas sob controle de versão

🛠️ Suporte a Linguagens

O contrato de suporte atual da superfície estável está centralizado em docs/SUPPORT_MATRIX.md. Ele distingue plugins especializados, cobertura genérica do registro Tree-sitter, suporte padrão de sandbox, extras opcionais, configuração semântica/reordenação e limitações alfa conhecidas. Não assuma que toda linguagem do registro tem a mesma qualidade de símbolos ou comportamento padrão de sandbox.

🚀 Início Rápido

Caminhos de instalação suportados são a imagem de contêiner publicada ghcr.io/consiliency/code-index-mcp:v1.4.0 (ou :latest), Python/STDIO nativo com uv sync --locked, e um wheel index-it-mcp construído localmente. A imagem ghcr.io/consiliency/code-index-mcp:local-smoke permanece um caminho de desenvolvimento opcional construído a partir deste checkout com make release-smoke-container. A cobertura de linguagens é limitada por docs/SUPPORT_MATRIX.md, a propriedade de evidências de endurecimento GA está congelada em docs/validation/ga-readiness-checklist.md, e os procedimentos de rollback estão em docs/operations/deployment-runbook.md. Não trate esta superfície estável publicada como uma alegação universal de suporte a linguagens; os níveis de suporte por linha ainda vivem na matriz de suporte.

🎯 Configuração Automática para Claude Code/Desktop (Recomendado)

# Auto-configures MCP for your environment
./scripts/setup-mcp-json.sh

# Or interactive mode
./scripts/setup-mcp-json.sh --interactive

Isso detecta automaticamente seu ambiente e cria a configuração .mcp.json apropriada.

🐳 Configuração Docker

Puxe a imagem v1.4.0 publicada do GHCR. O instalador usa por padrão essa imagem publicada; a tag local-smoke permanece uma imagem de desenvolvimento opcional que você pode construir a partir deste checkout com make release-smoke-container.

Opção 1: Busca Básica (Sem Chaves de API) - 2 Minutos

# Index your current directory with the published image
docker run -it -v $(pwd):/workspace ghcr.io/consiliency/code-index-mcp:v1.4.0

Opção 2: Busca com IA

# Set your API key (get one at https://www.voyageai.com — free tier available)
export VOYAGE_API_KEY=your-key

# Run with semantic search enabled explicitly
docker run -it -v $(pwd):/workspace -e SEMANTIC_SEARCH_ENABLED=true -e VOYAGE_API_KEY ghcr.io/consiliency/code-index-mcp:v1.4.0

💻 Configuração Específica por Ambiente

🪟 Windows (Nativo)

# PowerShell
.\scripts\setup-mcp-json.ps1

# Or manually with Docker Desktop
docker run -it -v ${PWD}:/workspace ghcr.io/consiliency/code-index-mcp:v1.4.0

🍎 macOS

# Install Docker Desktop or use Homebrew
brew install --cask docker

# Run setup
./scripts/setup-mcp-json.sh

🐧 Linux

# Install Docker (no Desktop needed)
curl -fsSL https://get.docker.com | sh

# Run setup
./scripts/setup-mcp-json.sh

🔄 WSL2 (Subsistema Windows para Linux)

# With Docker Desktop integration
./scripts/setup-mcp-json.sh  # Auto-detects WSL+Docker

# Without Docker Desktop
cp .mcp.json.templates/native.json .mcp.json
uv sync --locked

📦 Contêineres Aninhados (Dev Containers)

# For VS Code/Cursor dev containers
# Option 1: Use native Python (already in container)
cp .mcp.json.templates/native.json .mcp.json

# Option 2: Use Docker sidecar (avoids dependency conflicts)
docker-compose -f docker/compose/development/docker-compose.mcp-sidecar.yml up -d
cp .mcp.json.templates/docker-sidecar.json .mcp.json

Fallback de Limite de Caminho no Windows

Caminhos de repositórios rastreados são mantidos no limite de 160 caracteres de caminho rastreado, e a auditoria REPOCLEAN também verifica a profundidade de caminho do conteúdo do wheel para membros site-packages instalados. Se um checkout no Windows ainda atingir um limite de comprimento de caminho devido a um local de clone profundamente aninhado ou ferramentas de terceiros, use git config --global core.longpaths true como fallback em vez de como mitigação primária.

📋 Exemplos de Configuração MCP.json

O script de configuração cria o .mcp.json apropriado para seu ambiente. Exemplos manuais:

Python Nativo (Dev Container/Local)

{
  "mcpServers": {
    "code-index-native": {
      "command": "python",
      "args": ["-m", "mcp_server.cli.stdio_runner"],
      "cwd": "${workspace}"
    }
  }
}

Docker (Windows/Mac/Linux)

{
  "mcpServers": {
    "code-index-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "${workspace}:/workspace",
        "ghcr.io/consiliency/code-index-mcp:v1.4.0"
      ]
    }
  }
}

Smoke de Release

make release-smoke
make release-smoke-container

Usando com Muitos Repositórios

Indexe muitos repositórios não relacionados a partir de uma única instância de servidor em execução. Pré-requisitos: defina MCP_ALLOWED_ROOTS como uma lista separada por separador de caminho do SO de caminhos absolutos de diretórios (: no Unix, ; no Windows) que o servidor está autorizado a indexar antes de iniciar o servidor:

export MCP_ALLOWED_ROOTS=/abs/a:/abs/b

Inicie o servidor (com segredos via op run ou mcp-index stdio simples):

op run --env-file=.mcp.env -- mcp-index stdio

Registre cada repositório — registre um worktree por diretório comum do git. O repo_id estável vem do git rev-parse --git-common-dir do Nível 1, portanto, worktrees irmãos do mesmo repositório compartilham identidade e não são indexados independentemente na v3:

mcp-index repository register /abs/a
mcp-index repository register /abs/b

Escopo das consultas por repositório — passe repository=<name> (nome registrado ou caminho) para search_code / symbol_lookup:

search_code(query="def parse", repository="my-repo")
symbol_lookup(symbol="Parser", repository="my-repo")

Cliente Python (API local beta): para scripts e aplicações locais na mesma máquina do repositório registrado, use mcp_server.client em vez de iniciar STDIO ou chamar FastAPI. As ferramentas MCP continuam sendo a superfície LLM preferida.

from mcp_server.client import open_client
from mcp_server.client_types import ClientSearchOptions

with open_client(workspace_root="/path/to/repo") as client:
    result = client.search_code(
        ClientSearchOptions(
            query="TODO",
            source_type="friction",
            friction_categories=("todo",),
            include_source_metadata=True,
        )
    )
    if result.index_unavailable:
        print(result.index_unavailable.safe_fallback)
    else:
        print(result.results[0].file)

A superfície do cliente Python suportada é somente local: search_code, symbol_lookup, reindex e get_status compartilham o mesmo serviço ciente de prontidão da ferramenta MCP search_code. É uma API programática local, não um cliente de serviço remoto.

Os metadados de padrão de fricção estão disponíveis como um filtro aditivo em search_code. Use source_type="friction" com friction_categories opcional = ["todo", "fixme", "hack", "workaround", "wish", "extraction_hint"]. Defina include_source_metadata=true para anexar o envelope search_source_metadata.v1 armazenado aos resultados retornados. Chamadas lexicais comuns sem filtro mantêm a forma de resultado legada; categorias de fricção inválidas retornam um erro de validação somente de metadados em vez de um resultado vazio silencioso.

O contexto histórico de issues do GitHub usa o mesmo envelope de metadados e a mesma superfície de busca. Execute mcp-index history ingest --repo owner/repo para ingerir documentos de issues somente com metadados e, em seguida, filtre-os com source_type="history" mais history_labels=["reflection"] ou history_repos=["owner/repo"] opcionais. O contrato HISTORY é respaldado por fixtures em testes, não requer credenciais GitHub ativas e não persiste corpos de issues brutos por padrão.

Rastreamento de índice: o branch rastreado/padrão de cada repositório é seguido por MultiRepositoryWatcher (RefPoller a cada 30 s). Múltiplos worktrees do mesmo repositório e consultas de branches não padrão não são suportados no roteamento v3: eles retornam index_unavailable com safe_fallback: "native_search" e remediação de prontidão em vez de reutilizar o índice de outro checkout. Verifique get_status ou mcp-index repository list -v e confie nos resultados MCP indexados somente quando a prontidão for ready.

Sandbox de caminhos: as ferramentas search_code, symbol_lookup, summarize_sample e reindex rejeitam caminhos fora de MCP_ALLOWED_ROOTS com o código de erro path_outside_allowed_roots. Nomes de repositórios registrados ignoram a verificação.

Opções:

Defina MCP_AUTO_INDEX=false no ambiente do servidor para pular a indexação automática em segundo plano e chamar a ferramenta MCP reindex manualmente (recomendado para repositórios muito grandes).
Adicione {"enabled": false} a .mcp-index.json no repositório de destino para desabilitar a indexação desse repositório por completo.
Após uma reindexação completa ou alterações de código, chame a ferramenta MCP reindex para reconstruir o índice sob demanda.

Perfis semânticos: a busca BM25 não requer configuração extra. Para busca semântica (vetorial), o servidor carrega automaticamente code-index-mcp.profiles.yaml do próprio diretório de instalação — não é necessário copiá-lo para cada repositório. Para substituir por um arquivo de perfil personalizado, defina MCP_PROFILES_PATH=/abs/path/to/your-profiles.yaml no ambiente do servidor. Para substituir URLs de endpoint individuais sem editar o YAML, use as variáveis de ambiente referenciadas no arquivo (ex.: VLLM_EMBEDDING_BASE_URL, VLLM_SUMMARIZATION_BASE_URL).

⚡ Ative a Busca Semântica

A busca por palavras-chave BM25 funciona com configuração zero. Para adicionar busca vetorial (semântica), escolha um caminho:

Opção A — Voyage AI (recomendada):

export VOYAGE_API_KEY=your-key   # free tier available at voyageai.com

O perfil commercial_high é ativado automaticamente. Reinicie o servidor MCP — o log de inicialização confirmará que a busca semântica está ativa.

Opção B — OSS local (Qwen3-Embedding-8B via vLLM, sem necessidade de chave de API):

export VLLM_EMBEDDING_BASE_URL=http://localhost:8000/v1
# Start vLLM (requires ~20GB VRAM or shared CPU with --dtype float32):
docker run -p 8000:8000 vllm/vllm-openai --model Qwen/Qwen3-Embedding-8B

Ambos os perfis e seus nomes de coleção são definidos em code-index-mcp.profiles.yaml e podem ser personalizados.

code-index-mcp.profiles.yaml é um nome de arquivo de perfil enviado com o repositório, não um alvo de instalação via pip.

Custos e Recursos Opcionais

O pacote de contêiner documentado é ghcr.io/consiliency/code-index-mcp. A busca de código BM25 funciona sem credenciais de provedor. Busca semântica, reordenação, sincronização de artefatos e monitoramento dependem de extras, variáveis de ambiente e configuração de serviço. Consulte docs/SUPPORT_MATRIX.md para detalhes de suporte de linguagem/execução.

🚀 Início Rápido (Python)

Pré-requisitos

Python 3.12+
Git

Instalação

Opção 1: Use a instalação de origem do repositório (Recomendada)

# Clone the repository
git clone https://github.com/ViperJuice/Code-Index-MCP.git
cd Code-Index-MCP

# Install locked project dependencies
uv sync --locked

# Verify the canonical CLI entrypoint
uv run mcp-index --version

Opção 2: Compile a wheel local

# From the repo root
uv run --extra dev python -m build --wheel
python -m pip install dist/index_it_mcp-1.4.0-py3-none-any.whl
index-it-mcp --version

O nome canônico de distribuição Python permanece index-it-mcp, mas o PyPI ativo atualmente não tem artefato publicado para a superfície 1.4.0 preparada deste repositório. Use a wheel local ou a instalação de origem acima até que uma fase posterior de evidência de lançamento re-comprove a paridade de pacotes ativa.

Início Rápido Após a Instalação

# Authenticate GitHub artifact access once
gh auth login

# Check repo/artifact readiness before starting work
mcp-index preflight

# Pull the latest published index baseline for this repo
mcp-index artifact pull --latest

# Reconcile only your local drift after restore
mcp-index artifact sync

# The restored files live locally for MCP runtime use:
# - code_index.db
# - .index_metadata.json
# - vector_index.qdrant/

# Check index status
mcp-index index status

# Start the MCP STDIO runner (primary surface used by LLMs via .mcp.json)
mcp-index stdio

# Or start the FastAPI admin REST gateway (secondary, for diagnostics only;
# this is not the repo's MCP Streamable HTTP transport)
mcp-index serve
mcp-index serve --port 9123   # alternate port

De um LLM (Claude Code, Cursor, …) registre o executor STDIO em .mcp.json e invoque o indexador como chamadas de ferramenta MCP. As duas ferramentas principais são search_code (busca de padrão / palavra-chave / semântica, <500 ms) e symbol_lookup (consulta exata de classe/função, <100 ms). Chame get_status para confirmar que a prontidão do repositório é ready, ou trate uma resposta de consulta com code: "index_unavailable" e safe_fallback: "native_search" usando busca nativa enquanto segue a remediação retornada, como reindex:

{
  "tool": "search_code",
  "arguments": {
    "query": "def parse",
    "limit": 20,
    "semantic": false
  }
}

{
  "tool": "symbol_lookup",
  "arguments": {
    "symbol": "parse_file"
  }
}

Ambas as ferramentas aceitam um argumento "repository" opcional (nome de repositório registrado ou um caminho absoluto dentro de MCP_ALLOWED_ROOTS) para escopo multi-repositório. Consulte a seção "Usando com Muitos Repositórios" acima. Um índice pronto sem correspondências retorna payloads comuns de sem correspondência (results: [] para search_code ou result: "not_found" para symbol_lookup) com metadados de prontidão; índices indisponíveis retornam index_unavailable em vez disso.

A superfície STDIO tools/list é determinística e agora anuncia metadados MCP mais ricos para cada ferramenta pública: valores title estáveis, contratos de entrada JSON Schema explícitos (required, padrões e postura additionalProperties), anotações para comportamento somente leitura versus mutável, e rascunhos outputSchema de propriedade da implementação. A superfície STDIO tools/call agora retorna objetos CallToolResult nativos do SDK com structuredContent em formato de objeto, conteúdo de fallback de texto JSON preservado em content para clientes mais antigos e isError em ramos de recusa e erro. Payloads legados semelhantes a arrays, como resultados de busca lexical simples, são envolvidos sob structuredContent.results, enquanto falhas de prontidão ainda carregam index_unavailable com safe_fallback: "native_search" onde esse contrato já se aplicava.

reindex e write_summaries também suportam execução aumentada por tarefas através da superfície de tarefas MCP nativa do SDK. Ambas as ferramentas anunciam execution.taskSupport = "optional", para que os clientes possam manter o caminho síncrono atual ou incluir um objeto task em tools/call e então usar tasks/get, tasks/list, tasks/result e tasks/cancel para progresso, recuperação de payload terminal e cancelamento de melhor esforço. Recusas de prontidão, falhas de sandbox de caminho, erros de escopo conflitantes e pré-verificações de indisponibilidade do resumidor ainda falham sincronamente antes de qualquer tarefa ser criada.

A postura atual verificada do cliente MCP está resumida na matriz de compatibilidade MCP. O smoke direto de propriedade da fase é o SDK Python oficial sobre STDIO; Claude Code e outros lançadores STDIO são documentados contra esse mesmo contrato de servidor, enquanto o MCP remoto Streamable HTTP permanece adiado.

🔧 Configuração

Crie um arquivo .env para configuração:

# Semantic profile setup — set VOYAGE_API_KEY (free tier at voyageai.com) to enable vector search
VOYAGE_API_KEY=your_api_key_here
# Use 127.0.0.1 for local inference, or a Tailscale/SSH tunnel IP for remote GPUs
OPENAI_API_BASE=http://127.0.0.1:8001/v1
QDRANT_PATH=vector_index.qdrant
# Server-mode Qdrant: QDRANT_URL, plus QDRANT_API_KEY when the server sets
# QDRANT__SERVICE__API_KEY (leave unset for an unauthenticated server)
# QDRANT_URL=http://localhost:6333
# QDRANT_API_KEY=your_qdrant_api_key

# Server settings
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8000
MCP_LOG_LEVEL=INFO

# Workspace settings
MCP_WORKSPACE_ROOT=.
MCP_MAX_FILE_SIZE=10485760  # 10MB

# GitHub Artifact Sync (privacy settings)
MCP_ARTIFACT_SYNC=false  # Set to true to enable
AUTO_UPLOAD=false        # Auto-upload on changes
AUTO_DOWNLOAD=true       # Auto-download on clone

Os artefatos publicados agora carregam a linha de base lexical completa mais dois perfis semânticos:

commercial_high usando voyage-code-3
oss_high usando Qwen/Qwen3-Embedding-8B

Esses perfis são armazenados em coleções Qdrant separadas dentro do artefato, para que os consumidores possam puxar uma linha de base e usar qualquer perfil localmente.

Dica Profissional: Inferência Remota para o Perfil de Código Aberto Se sua máquina local não tiver potência de GPU para executar o modelo de embedding oss_high localmente (ex.: via vLLM ou Ollama), você pode executar a inferência em uma máquina remota e apontar o servidor MCP para ela:

Tailscale/VPN: Defina OPENAI_API_BASE=http://<tailnet-ip>:8001/v1
Túnel SSH: Execute ssh -L 8001:localhost:8001 user@remote-gpu-machine, e a configuração padrão 127.0.0.1:8001 fará túnel diretamente para seu servidor de inferência.

Os arquivos de índice gerados não devem viver no histórico do git. O repositório rastreia o código, o fluxo de trabalho e a configuração necessários para construí-los/publicá-los; os artefatos do GitHub distribuem a linha de base de execução real que o MCP restaura localmente.

Gerenciamento de Workspace Local

# Inspect all registered repositories and their readiness
mcp-index repository list -v

# Check all registered repos and their local artifact/runtime readiness
mcp-index artifact workspace-status

# Refresh readiness after restoring or rebuilding local indexes
mcp-index artifact reconcile-workspace

# Prepare per-repo local artifact payloads without requiring remote publication
mcp-index artifact publish-workspace

O MRREADY congela a interpretação voltada para lançamento desses comandos:

mcp-index repository list -v, mcp-index repository status e mcp-index artifact workspace-status agora exibem um status de lançamento por repositório: ready, local_only, publish_failed, wrong_branch, stale_commit, missing_index ou partial_index_failure.
As ferramentas de consulta permanecem uma superfície separada com falha fechada. Se a prontidão não for ready, a busca MCP retorna index_unavailable com safe_fallback: "native_search" em vez de tratar uma linha de status como um sucesso de consulta.
O veredito atual multi-repositório permanece controlled rollout only enquanto as superfícies multi-repositório e STDIO ainda estão em beta.

🔐 Privacidade e Sincronização de Artefatos do GitHub

Controle como seu índice de código é compartilhado:

// .mcp-index.json
{
  "github_artifacts": {
    "enabled": false,        // Disable sync entirely
    "auto_upload": false,    // Manual upload only
    "auto_download": true,   // Still get team indexes
    "exclude_patterns": [    // Additional exclusions
      "internal/*",
      "proprietary/*"
    ]
  }
}

Recursos de Privacidade:

Índices filtrados por .gitignore automaticamente
Padrões adicionais via .mcp-index-ignore
Logs de auditoria mostram o que foi excluído
Sincronização desabilitada por padrão na versão mínima do Docker

🆕 Recursos Avançados

Reordenação de Resultados de Busca

Três reordenadores estão disponíveis, configurados via variável de ambiente RERANKER_TYPE:

Valor	Reordenador	Notas
`flashrank`	FlashRank	OSS, local, rápido (~1–5 ms de overhead)
`cross-encoder`	Cross-Encoder	OSS, local, maior qualidade
`voyage`	Voyage Reranker	API em nuvem, requer `VOYAGE_API_KEY`
`none`	Desabilitado	Padrão

export RERANKER_TYPE=flashrank   # or cross-encoder, voyage, none

A reordenação se aplica somente ao caminho de recuperação semântica. Resultados BM25/FTS não são reordenados. Implementação: mcp_server/dispatcher/reranker.py.

Resumo de Chunks com LLM

Chunks semânticos podem ser aumentados com resumos gerados por LLM antes da incorporação, melhorando a recuperação de consultas baseadas em intenção. Configurado por perfil em code-index-mcp.profiles.yaml:

summarization:
  enabled: true
  mode: lazy           # lazy (on first query) | comprehensive (at index time)
  provider: openai_compatible
  model_name: gpt-4o-mini
  base_url: "https://api.openai.com/v1"
  api_key_env: OPENAI_API_KEY
  prompt_template: "Describe this code chunk's inputs, outputs, and purpose in 2 concise sentences."

⚠️ Segurança: Não resuma código não confiável com LLMs em nuvem. Instruções ocultas em comentários podem ser executadas pelo resumidor. Consulte a seção Notas de Segurança.

Implementação: mcp_server/indexing/summarization.py

Compartilhamento de Índice Ciente de Segurança

Evite o compartilhamento acidental de arquivos sensíveis:

# Analyze current index for security issues
python scripts/utilities/analyze_gitignore_security.py

# Create secure index export (filters gitignored files)
python scripts/utilities/secure_index_export.py

# The secure export will:
# - Exclude all gitignored files
# - Remove sensitive patterns (*.env, *.key, etc.)
# - Create audit logs of excluded files

Busca Híbrida BM25

Combina busca de texto completo tradicional com busca semântica:

# The system automatically uses hybrid search when available
# Configure weights in settings:
HYBRID_SEARCH_BM25_WEIGHT=0.3
HYBRID_SEARCH_SEMANTIC_WEIGHT=0.5
HYBRID_SEARCH_FUZZY_WEIGHT=0.2

🔧 Configuração do Despachante

Despachante Aprimorado (Padrão)

O despachante aprimorado inclui proteção de tempo limite e fallback automático:

from mcp_server.dispatcher.dispatcher_enhanced import EnhancedDispatcher
from mcp_server.storage.sqlite_store import SQLiteStore

store = SQLiteStore(".indexes/YOUR_REPO_ID/current.db")
dispatcher = EnhancedDispatcher(
    sqlite_store=store,
    semantic_search_enabled=True,  # Enable if Qdrant available
    lazy_load=True,               # Load plugins on-demand
    use_plugin_factory=True       # Use dynamic plugin loading
)

# Search with automatic optimization
results = list(dispatcher.search("your query", limit=10))

Despachante Simples (Alternativa Leve)

Para desempenho máximo com busca somente BM25:

from mcp_server.dispatcher.simple_dispatcher import create_simple_dispatcher

# Ultra-fast BM25 search without plugin overhead
dispatcher = create_simple_dispatcher(".indexes/YOUR_REPO_ID/current.db")
results = list(dispatcher.search("your query", limit=10))

Opções de Configuração

Configure o comportamento do despachante via variáveis de ambiente:

# Dispatcher settings
MCP_DISPATCHER_TIMEOUT=5          # Plugin loading timeout (seconds)
MCP_USE_SIMPLE_DISPATCHER=false   # Use simple dispatcher
MCP_PLUGIN_LAZY_LOAD=true        # Load plugins on-demand

# Performance tuning
MCP_BM25_BYPASS_ENABLED=true     # Enable direct BM25 bypass
MCP_MAX_PLUGIN_MEMORY=1024       # Max memory for plugins (MB)

# Auto-indexing (cross-repo use)
MCP_AUTO_INDEX=true               # Set false to skip background auto-index on first run
MCP_AUTO_INDEX_MAX_FILES=100000   # Skip auto-index if repo exceeds this file count
MCP_PROFILES_PATH=                # Absolute path to a custom profiles YAML (overrides built-in)

# Endpoint overrides (no need to edit profiles.yaml)
VLLM_EMBEDDING_BASE_URL=          # Override vLLM embedding endpoint (default: http://ai:8001/v1)
VLLM_SUMMARIZATION_BASE_URL=      # Override summarization endpoint (default: http://win:8002/v1)

🗂️ Gerenciamento de Índice

Armazenamento Centralizado de Índices

Todos os índices agora são armazenados centralmente em .indexes/ (relativo ao projeto MCP) para melhor organização e para evitar commits acidentais:

.indexes/
├── {repo_hash}/              # Unique hash for each repository
│   ├── main_abc123.db        # Index for main branch at commit abc123
│   ├── main_abc123.metadata.json
│   └── current.db -> main_abc123.db  # Symlink to active index
├── qdrant/                   # Semantic search embeddings
│   └── main.qdrant/          # Centralized Qdrant database

Benefícios:

Índices nunca são commitados acidentalmente no git
Reutilizáveis em múltiplos clones do mesmo repositório
Separação clara entre código e índices
Descoberta automática baseada no remote do git Migração: Para repositórios existentes com índices locais:

python scripts/move_indexes_to_central.py

Para Este Repositório

Este projeto usa GitHub Actions Artifacts para compartilhamento eficiente de índices, então a maioria dos usuários começa a partir de uma linha de base de índice publicada em vez de reconstruir localmente.

# First time setup - pull latest indexes
mcp-index artifact pull --latest

# After pull, reconcile only your branch/worktree drift
mcp-index artifact sync

# Share your indexes with the team
mcp-index artifact push

# Check sync status
mcp-index artifact sync

# Optional: Install git hooks for automatic sync
mcp-index hooks install
# Now indexes upload automatically on git push
# and download automatically on git pull

Para QUALQUER Repositório (MCP Index Kit)

Habilite o gerenciamento de índices portátil em qualquer repositório com custo zero de computação no GitHub:

Instalação Rápida

npm install -g mcp-index-kit
mcp-index init

Como Funciona

Arquitetura de Custo Zero:
- Toda a indexação acontece nas máquinas dos desenvolvedores
- Índices armazenados como GitHub Artifacts (gratuito para repositórios públicos)
- Download automático no clone, upload no push
- Nenhuma computação do GitHub Actions necessária
Design Portátil:
- Configuração com um único comando para qualquer repositório
- Auto-detectado por servidores MCP e ferramentas
- O comportamento de linguagem/execução segue os níveis de suporte explícitos em docs/SUPPORT_MATRIX.md
- Ativar/desativar por repositório

Uso:

# Initialize in your repo
cd your-repo
mcp-index init

# Build index locally
mcp-index build

# Push to GitHub Artifacts
mcp-index push

# Pull latest index
mcp-index pull

# Auto sync
mcp-index sync

Configuração

Configuração de Busca Semântica

Para habilitar recursos de busca semântica, você precisa de uma chave de API Voyage AI. Obtenha uma em https://www.voyageai.com/.

Método 1: Configuração do Claude Code (Recomendado)

Crie ou edite .mcp.json na raiz do seu projeto:

{
  "mcpServers": {
    "code-index-mcp": {
      "command": "mcp-index",
      "args": ["stdio"],
      "env": {
        "VOYAGE_API_KEY": "your-voyage-ai-api-key-here",
        "SEMANTIC_SEARCH_ENABLED": "true"
      }
    }
  }
}

O rótulo do servidor code-index-mcp nestes exemplos é um ID de servidor MCP local do cliente, não o nome da distribuição Python.

Método 2: CLI do Claude Code

claude mcp add code-index-mcp -e VOYAGE_API_KEY=your_key -e SEMANTIC_SEARCH_ENABLED=true -- mcp-index stdio

Método 3: Variáveis de Ambiente

export VOYAGE_API_KEY=your_key
export SEMANTIC_SEARCH_ENABLED=true

Método 4: Arquivo .env

Crie um arquivo .env na raiz do seu projeto:

VOYAGE_API_KEY=your_key
SEMANTIC_SEARCH_ENABLED=true

Verificar Configuração

Verifique sua configuração de busca semântica:

mcp-index index check-semantic

Configuração do Índice

Edite .mcp-index.json no seu repositório:

{
  "enabled": true,
  "auto_download": true,
  "artifact_retention_days": 30,
  "github_artifacts": {
    "enabled": true,
    "max_size_mb": 100
  }
}

Veja mcp-index-kit para documentação completa

Ver detalhes do artefato

mcp-index artifact info 12345


#### Index Management
```bash
# Check index status
mcp-index index status

# Check compatibility
mcp-index index check-compatibility

# Rebuild indexes locally only if artifact sync cannot catch up
mcp-index index rebuild

# Create backup
mcp-index index backup my_backup

# Restore from backup
mcp-index index restore my_backup

Integração com GitHub Actions

Pull Requests: Valida índices fornecidos pelo desenvolvedor (sem reconstrução)
Merges na Main: Promove índices validados para artefatos
Custo-Eficiente: Usa armazenamento gratuito de GitHub Actions Artifacts
Limpeza Automática: Artefatos antigos são limpos após 30 dias

Armazenamento e Custo

GitHub Actions Artifacts: GRATUITO para repositórios públicos, incluído nas cotas de repositórios privados
Retenção: 7 dias para artefatos de PR, 30 dias para branch main
Limites de Tamanho: 500MB por artefato (comprimido)
Compressão Automática: ~70% de redução de tamanho com tar.gz

Fluxo de Trabalho do Desenvolvedor

Clonar Repositório

git clone https://github.com/yourusername/Code-Index-MCP.git
cd Code-Index-MCP

Obter Índices Mais Recentes
```
 gh auth login
 mcp-index artifact pull --latest
```
- Isso baixa o snapshot completo do artefato GitHub atual.
- mcp-index artifact sync então reconcilia apenas o desvio do seu branch/worktree local quando a atualização incremental é apropriada.
Faça Suas Alterações
- Edite o código normalmente
- Os índices são atualizados automaticamente via observador de arquivos

Compartilhe Atualizações

# Your indexes are already updated locally
 mcp-index artifact push

Compatibilidade do Modelo de Embedding

O sistema rastreia versões de modelos de embedding para garantir compatibilidade:

commercial_high: voyage-code-3 — 2048 dimensões, produto escalar, float32
oss_high: Qwen/Qwen3-Embedding-8B — 4096 dimensões, produto escalar, l2-normalizado
Detecção Automática: O sistema verifica a compatibilidade do perfil antes do download

A configuração semântica multi-perfil pode ser fornecida em:

SEMANTIC_PROFILES_JSON (variável de ambiente), ou
code-index-mcp.profiles.yaml (raiz do repositório).

Estratégia de Artefatos

Os pulls de artefatos do GitHub são downloads de snapshot completos, não buscas remotas parciais de patch.
O artefato comprimido atual é modesto o suficiente para que downloads completos permaneçam mais simples do que um protocolo remoto de delta.
A eficiência vem da indexação incremental local após a restauração:
- puxe o artefato completo mais recente
- compare o commit do artefato restaurado com o HEAD local
- deixe o observador ou a reindexação incremental local reconciliar arquivos adicionados, modificados, excluídos e renomeados
Artefatos remotos específicos de branch são opcionais. A estratégia padrão é usar o artefato main mais recente como base e reconciliar o desvio do branch localmente.

Configuração Semântica Fácil (Docker-Primeiro)

Execute a integração com inicialização automática do Qdrant local:

mcp-index setup semantic

Precedência de configurações (da mais alta para a mais baixa):

Flags de CLI (para uma execução de comando)
Variáveis de ambiente / .env
code-index-mcp.profiles.yaml
SEMANTIC_PROFILES_JSON
Padrões integrados

Controles comuns:

# Preflight checks only
mcp-index setup semantic --dry-run

# Strict mode: fail command if semantic stack isn't ready
mcp-index setup semantic --strict

# Override local embedding endpoint
mcp-index setup semantic --openai-api-base http://127.0.0.1:8001/v1

O carregamento de plugins é auto-otimizado por padrão usando detecção rápida de linguagem do repositório:

MCP_AUTO_DETECT_LANGUAGES=true
MCP_LANGUAGE_DETECT_MAX_FILES=5000
MCP_LANGUAGE_DETECT_MIN_FILES=2

Para ambientes sensíveis à inicialização, habilite:

MCP_FAST_STARTUP=true (usa carregamento preguiçoso de plugins e pula a inicialização do observador de arquivos)

Quando MCP_AUTO_DETECT_LANGUAGES=true, a detecção automática tem precedência sobre plugins.yaml. Defina MCP_AUTO_DETECT_LANGUAGES=false para forçar a seleção de linguagem plugins.yaml.

Para uma configuração de perfil duplo (Voyage + vLLM/Qwen local), defina:

VOYAGE_API_KEY
OPENAI_API_BASE (por exemplo http://127.0.0.1:8000/v1)
OPENAI_API_KEY (placeholder aceito para configurações vLLM locais)

Se você usar um modelo de embedding diferente, o sistema detectará incompatibilidade e reconstruirá localmente com sua configuração.

💻 Desenvolvimento

Criando um Novo Plugin de Linguagem

Crie a estrutura do plugin

mkdir -p mcp_server/plugins/my_language_plugin
cd mcp_server/plugins/my_language_plugin
touch __init__.py plugin.py

Implemente a interface do plugin

from mcp_server.plugin_base import PluginBase

class MyLanguagePlugin(PluginBase):
    def __init__(self):
        self.tree_sitter_language = "my_language"
    
    def index(self, file_path: str) -> Dict:
        # Parse and index the file
        pass
    
    def getDefinition(self, symbol: str, context: Dict) -> Dict:
        # Find symbol definition
        pass
    
    def getReferences(self, symbol: str, context: Dict) -> List[Dict]:
        # Find symbol references
        pass

Registre o plugin

# In dispatcher.py
from .plugins.my_language_plugin import MyLanguagePlugin

self.plugins['my_language'] = MyLanguagePlugin()

Executando Testes

# Run all tests
pytest

# Run specific test
pytest test_python_plugin.py

# Measure the current local/offloaded coverage baseline
make coverage-baseline

# Generate the local/offloaded coverage report
make coverage

# Reject tracked or staged generated coverage outputs
make coverage-artifact-guard

O contrato de COBERTURA é local/descarregado primeiro: make coverage emite saída de linhas ausentes no terminal mais coverage.xml, e make agent-full é responsável pela geração rotineira de cobertura. O selo do README permanece adiado até que um evento confiável produza evidências reais enviadas.

Visualização da Arquitetura

# View C4 architecture diagrams
docker run --rm -p 8080:8080 \
  -v "$(pwd)/architecture":/usr/local/structurizr \
  structurizr/lite

# Open http://localhost:8080 in your browser

Interface REST de Administração (secundária)

A superfície canônica são chamadas de ferramentas MCP (search_code, symbol_lookup, etc.) via executor STDIO — veja as seções "Início Rápido" acima. O gateway REST FastAPI documentado aqui é uma interface administrativa secundária para diagnósticos, scripts e clientes que não podem falar MCP. Seus endpoints não são o caminho recomendado para fluxos de trabalho orientados por LLM.

Endpoints REST de Administração

`GET /symbol`

Obter definição de símbolo (superfície admin/debug — prefira a ferramenta MCP symbol_lookup):

GET /symbol?symbol_name=parseFile&file_path=/path/to/file.py

Parâmetros de consulta:

symbol_name (obrigatório): Nome do símbolo a ser encontrado
file_path (opcional): Arquivo específico para pesquisar

`GET /search`

Pesquisar padrões de código (superfície admin/debug — prefira a ferramenta MCP search_code):

GET /search?query=async+def.*parse&file_extensions=.py,.js

Parâmetros de consulta:

query (obrigatório): Padrão de pesquisa (regex suportado)
file_extensions (opcional): Lista separada por vírgulas de extensões
source_type (opcional): friction ou history
friction_categories (opcional): categorias de fricção separadas por vírgulas
history_labels (opcional): rótulos de problemas de histórico separados por vírgulas
history_repos (opcional): filtros de proprietário/repositório separados por vírgulas para documentos de problemas de histórico
include_source_metadata (opcional): incluir registros search_source_metadata.v1 nos resultados correspondentes

API de Cliente Python (API local beta)

Use o cliente Python quando precisar de acesso programático local da mesma máquina e checkout registrado. Use ferramentas MCP quando um assistente precisar da superfície principal de ferramentas LLM.

from mcp_server.client import open_client
from mcp_server.client_types import ClientSearchOptions

with open_client(workspace_root="/path/to/repo") as client:
    search = client.search_code(ClientSearchOptions(query="Reflection issue"))
    symbol = client.symbol_lookup("IndexItClient")
    status = client.get_status()

A prontidão permanece com falha fechada. Repositórios não prontos retornam dados index_unavailable tipados com safe_fallback="native_search" em vez de despachar contra um índice desatualizado. O cliente Python beta intencionalmente não tem cliente de serviço remoto.

Formato de Resposta

Todas as respostas da API seguem uma estrutura JSON consistente:

Resposta de Sucesso:

{
  "status": "success",
  "data": { ... },
  "timestamp": "2024-01-01T00:00:00Z"
}

Resposta de Erro:

{
  "status": "error",
  "error": "Error message",
  "code": "ERROR_CODE",
  "timestamp": "2024-01-01T00:00:00Z"
}

🚢 Implantação

Opções de Implantação Docker

O projeto inclui múltiplas configurações Docker para diferentes ambientes:

Desenvolvimento (Padrão):

# Uses docker-compose.yml + Dockerfile
docker-compose up -d
# - SQLite database
# - Uvicorn development server  
# - Volume mounts for code changes
# - Debug logging enabled

Produção:

# Uses docker-compose.production.yml + Dockerfile.production
docker-compose -f docker-compose.production.yml up -d
# - PostgreSQL database
# - Gunicorn + Uvicorn workers
# - Multi-stage optimized builds
# - Security hardening (non-root user)
# - Production logging

Desenvolvimento Aprimorado:

# Uses both compose files with development overrides
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d
# - Development base + enhanced debugging
# - Source code volume mounting
# - Read-write code access

Comportamento de Reinicialização do Contêiner

Importante: Por padrão, docker-compose restart usa a configuração DESENVOLVIMENTO:

docker-compose restart → Usa docker-compose.yml (Desenvolvimento)
docker-compose -f docker-compose.production.yml restart → Usa Produção

Implantação em Produção

Para ambientes de produção, fornecemos:

Builds Docker multi-estágio com endurecimento de segurança
Banco de dados PostgreSQL com suporte assíncrono
Cache Redis para otimização de desempenho
Banco de dados vetorial Qdrant para busca semântica
Stack de monitoramento Prometheus + Grafana
Manifestos Kubernetes no diretório k8s/
Configuração de proxy reverso nginx

Veja nosso Guia de Implantação para instruções detalhadas, incluindo:

Configurações de implantação Kubernetes
Configuração de auto-escalonamento
Otimização de banco de dados
Melhores práticas de segurança
Monitoramento e observabilidade

Requisitos do Sistema

Mínimo: 2GB RAM, 2 núcleos de CPU, 10GB de armazenamento
Recomendado: 8GB RAM, 4 núcleos de CPU, 50GB de armazenamento SSD
Bases de código grandes: 16GB+ RAM, 8+ núcleos de CPU, 100GB+ de armazenamento SSD

📦 Lançamentos e Índices Pré-construídos

Usando Índices Pré-construídos

Para configuração rápida, baixe índices pré-construídos dos nossos lançamentos do GitHub:

# List available releases
python scripts/download-release.py --list

# Download the current pre-built index artifact
python scripts/download-release.py --latest

# Download specific version
python scripts/download-release.py --tag v2024.01.15 --output ./my-index

Criando Lançamentos

Mantenedores podem criar novos lançamentos com índices pré-construídos:

# Prepare or update the release PR from the feature branch
gh workflow run "Release Automation" --ref <release-branch> -f mode=prepare -f version=v1.4.0 -f auto_merge=false

# After that PR merges, publish only from protected main
gh workflow run "Release Automation" --ref main -f mode=publish -f version=v1.4.0 -f auto_merge=false

Sincronização Automática de Índices

O projeto inclui hooks Git para sincronização automática de índices:

Pre-push: Envia alterações de índice para artefatos do GitHub
Post-merge: Baixa índices compatíveis após pull

Instale os hooks com: mcp-index hooks install

🤝 Contribuindo

Aceitamos contribuições! Veja nosso Guia de Contribuição para detalhes.

Processo de Desenvolvimento

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
Faça suas alterações
Adicione testes (busque 90%+ de cobertura)
Atualize a documentação
Envie um pull request

Estilo de Código

Siga PEP 8 para código Python
Use dicas de tipo para todas as funções
Escreva docstrings descritivas
Mantenha funções pequenas e focadas

📈 Desempenho

Benchmarks

Operação	Meta de Desempenho	Status Atual
Busca de Símbolo	<100ms (p95)	✅ Alcançado - Todas as consultas < 100ms
Busca de Código	<500ms (p95)	✅ Alcançado - Busca BM25 < 50ms
Indexação de Arquivos	10K arquivos/min	✅ Alcançado - 152K arquivos indexados

Benchmark de Matriz (2026-04-01)

Métrica	Somente BM25	voyage-code-3	Qwen3-Embedding-8B
Top-1 (sem reranker)	12/17 (70,6%)	17/17 (100%)	17/17 (100%)
Top-1 (flashrank)	13/17 (76,5%)	17/17 (100%)	17/17 (100%)
Top-1 (cross-encoder)	—	17/17 (100%)	17/17 (100%)
Top-1 (voyage-reranker)	—	15/17 (88,2%)	—
Consulta de símbolo BM25 p50	~1–5 ms	—	—
Consulta semântica p50 (híbrida)	—	~50–400 ms	~50–280 ms

Resultados completos: docs/benchmarks/matrix_benchmark.md / .json

🏗️ Visão Geral da Arquitetura

O sistema segue padrões de arquitetura do modelo C4:

Definição do Workspace: definido em architecture/workspace.dsl e validado com CLI do Structurizr
Contexto do Sistema (L1): Claude Code integra via sub-agentes MCP contra a superfície primária STDIO
Nível de Contêiner (L2): 8 contêineres principais, incluindo servidor MCP aprimorado e documentação do usuário
Nível de Componente (L3): Sistema de plugins, gerenciamento de memória e coordenação entre repositórios
Nível de Código (L4): 43 diagramas PlantUML documentando todos os componentes e fluxos do sistema

Para documentação arquitetural detalhada, veja o diretório architecture/.

🗺️ Roadmap de Desenvolvimento

Veja ROADMAP.md para planos de desenvolvimento detalhados e progresso atual. Status Atual: Superfície de endurecimento 1.4.0 preparada; publicação protegida principal ainda pendente

✅ Indexação Principal: SQLite + FTS5 para busca local rápida
✅ Multilíngue: Cobertura de linguagens especializada e baseada em registro; veja docs/SUPPORT_MATRIX.md
✅ Protocolo MCP: Compatibilidade verificada com SDK oficial Python via STDIO; veja docs/status/MCP_COMPATIBILITY_EVALUATION.md para postura de cliente nomeada
✅ Desempenho: Consultas abaixo de 100ms com otimização BM25
🔄 Sincronização de Índice: Suporte beta via GitHub Artifacts
🔄 Busca Semântica: Recurso opcional que requer API Voyage AI

Melhorias Recentes:

⚡ Otimização do Dispatcher: Proteção de timeout e bypass BM25 para confiabilidade
🔄 Busca Híbrida: BM25 + busca semântica com degradação graciosa
📊 Classificação de Resultados: Relevância melhorada com normalização de pontuação
🔧 Ferramentas CLI: Comando mcp-index completo para gerenciamento de índice

Dicas de Otimização

Os recursos de otimização de desempenho estão implementados e disponíveis:

Ativar cache: Cache Redis implementado e configurável via variáveis de ambiente
Ajustar tamanho do lote: Configurável via variável de ambiente INDEXING_BATCH_SIZE
Usar armazenamento SSD: Melhora significativamente a velocidade de indexação
Limitar tamanho do arquivo: Configurável via variável de ambiente INDEXING_MAX_FILE_SIZE
Processamento paralelo: Indexação multi-worker configurável via INDEXING_MAX_WORKERS

🔒 Segurança

Local-first: Todo o processamento ocorre localmente por padrão
Validação de caminho: Previne ataques de travessia de diretório
Sanitização de entrada: Todas as consultas são sanitizadas
Detecção de segredos: Redação automática de segredos detectados
Isolamento de plugins: Plugins executam em ambientes restritos
⚠️ Riscos de Resumo Semântico: Se você ativar resumos semânticos gerados por LLM (preguiçosos ou abrangentes), esteja ciente de vulnerabilidades de injeção de prompt. Atores maliciosos podem colocar instruções ocultas em comentários de código (por exemplo, em uma dependência de código aberto) que o LLM resumidor pode executar. Sempre revise os metadados de índice gerados se estiver resumindo código não confiável.

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🙏 Agradecimentos

Tree-sitter para análise de linguagem
Jedi para análise Python
FastAPI para o framework de API
Voyage AI para embeddings
Anthropic para o protocolo MCP

📬 Contato

Issues: GitHub Issues
Discussões: GitHub Discussions

Feito com ❤️ para a comunidade de desenvolvedores