Code Index MCP

Code Index MCP

Visão Geral

Code Index MCP é um servidor Model Context Protocol que preenche a lacuna entre modelos de IA e bases de código complexas. Ele fornece indexação inteligente, recursos avançados de busca e análise detalhada de código para ajudar assistentes de IA a entender e navegar em seus projetos de forma eficaz.

Ideal para: Revisão de código, refatoração, geração de documentação, assistência de depuração e análise arquitetural.

Início Rápido

🚀 Configuração Recomendada (Para a Maioria dos Usuários)

A maneira mais fácil de começar com qualquer aplicativo compatível com MCP:

Pré-requisitos: Python 3.10+ e uv

1. Adicione à sua configuração MCP (ex.: claude_desktop_config.json ou ~/.claude.json):

   {
     "mcpServers": {
       "code-index": {
         "command": "uvx",
         "args": ["code-index-mcp"]
       }
     }
   }
   

   Opcional: acrescente --project-path /absolute/path/to/repo ao array args para que o servidor inicialize com esse repositório automaticamente (equivalente a chamar set_project_path após a inicialização).

2. Reinicie seu aplicativo – uvx gerencia automaticamente a instalação e execução

3. Comece a usar (dê estes comandos ao seu assistente de IA):

   Set the project path to /Users/dev/my-react-app
   Find all TypeScript files in this project  
   Search for "authentication" functions
   Analyze the main App.tsx file
   

   Se você iniciar com --project-path, pode pular o primeiro comando acima - o servidor já sabe a localização do projeto.

Configuração do Codex CLI

Se você estiver usando o Codex CLI da Anthropic, adicione o servidor ao ~/.codex/config.toml. No Windows, o arquivo fica em C:\Users\<you>\.codex\config.toml:

[mcp_servers.code-index]
type = "stdio"
command = "uvx"
args = ["code-index-mcp"]

Você pode acrescentar --project-path C:/absolute/path/to/repo à lista args para definir o projeto automaticamente na inicialização (mesmo efeito de executar a ferramenta set_project_path).

No Windows, o uvx precisa que os diretórios de perfil padrão estejam presentes. Mantenha a substituição de ambiente no mesmo bloco para que o MCP inicie de forma confiável:

env = {
  HOME = "C:\\Users\\<you>",
  APPDATA = "C:\\Users\\<you>\\AppData\\Roaming",
  LOCALAPPDATA = "C:\\Users\\<you>\\AppData\\Local",
  SystemRoot = "C:\\Windows"
}

Linux e macOS já expõem os caminhos XDG necessários e o HOME, então você geralmente pode omitir a tabela env nesse caso. Adicione substituições apenas se você executar o CLI dentro de um contêiner restrito.

FastMCP e Manifestos de Descoberta

• Execute fastmcp run fastmcp.json para iniciar o servidor via FastMCP com o entrypoint de origem correto e os metadados de dependência. Passe --project-path (ou chame a ferramenta set_project_path após a inicialização) para que o índice inicie com o repositório correto.
• Sirva ou copie .well-known/mcp.json para compartilhar um manifesto MCP compatível com padrões. Clientes que suportam a convenção .well-known (ex.: Claude Desktop, Codex CLI) podem importar este arquivo diretamente em vez de criar configurações manualmente.
• Publique .well-known/mcp.llmfeed.json quando quiser expor os metadados mais ricos do LLM Feed. Ele referencia a mesma definição de servidor code-index além de links de documentação/código-fonte, o que ajuda registros a apresentar descrições, tags e recursos automaticamente.

Ao compartilhar os manifestos, lembre os consumidores de fornecer --project-path (ou chamar set_project_path) para que o servidor indexe o repositório pretendido.

Casos de Uso Típicos

Revisão de Código: "Encontre todos os lugares que usam a API antiga"
Ajuda com Refatoração: "Onde esta função é chamada?"
Aprendizado de Projetos: "Mostre-me os principais componentes deste projeto React"
Depuração: "Busque todo o código relacionado a tratamento de erros"

Recursos Principais

🔍 Busca e Análise Inteligentes

• Arquitetura de Dupla Estratégia: Parsing especializado com tree-sitter para 10 linguagens principais, estratégia de fallback para mais de 50 tipos de arquivo
• Integração Direta com Tree-sitter: Sem fallbacks de regex para linguagens especializadas - falha rápida com erros claros
• Busca Avançada: Detecta e usa automaticamente a melhor ferramenta disponível (ugrep, ripgrep, ag ou grep)
• Suporte Universal de Arquivos: Cobertura abrangente, desde parsing avançado de AST até indexação básica de arquivos
• Análise de Arquivos: Insights profundos sobre estrutura, imports, classes, métodos e métricas de complexidade após executar build_deep_index

🗂️ Suporte a Múltiplas Linguagens

• 10 Linguagens com Parsing AST via Tree-sitter: Python, JavaScript, TypeScript, Java, Kotlin, C#, Go, Objective-C, Zig, Rust
• Mais de 50 Tipos de Arquivo com Estratégia de Fallback: C/C++, Ruby, PHP e todas as outras linguagens de programação
• Arquivos de Documento e Configuração: Markdown, JSON, YAML, XML com tratamento adequado
• Frontend Web: Vue, React, Svelte, HTML, CSS, SCSS
• Java Web e Build: Arquivos JSP/Tag (.jsp, .jspx, .jspf, .tag, .tagx), Grails/GSP (.gsp), builds Gradle e Groovy (.gradle, .groovy), .properties e Protocol Buffers (.proto)
• Banco de Dados: Variantes de SQL, NoSQL, stored procedures, migrações
• Configuração: JSON, YAML, XML, Markdown
• Ver lista completa

⚡ Monitoramento em Tempo Real e Atualização Automática

• Observador de Arquivos: Atualização automática do índice quando arquivos mudam
• Multiplataforma: Monitoramento nativo do sistema de arquivos do SO
• Processamento Inteligente: Agrupa mudanças rápidas para evitar reconstruções excessivas
• Atualização de Índice Raso: Observa mudanças de arquivos e mantém a lista de arquivos atualizada; execute uma reconstrução profunda quando precisar de metadados de símbolos

⚡ Desempenho e Eficiência

• Parsing AST com Tree-sitter: Parsing de sintaxe nativa para extração precisa de símbolos
• Cache Persistente: Armazena índices para acesso subsequente extremamente rápido
• Filtragem Inteligente: Exclusão inteligente de diretórios de build e arquivos temporários
• Eficiência de Memória: Otimizado para bases de código grandes
• Dependências Diretas: Sem mecanismos de fallback - falha rápida com mensagens de erro claras

Tipos de Arquivo Suportados

🛠️ Configuração de Desenvolvimento

Para contribuir ou desenvolvimento local:

1. Clone e instale:

   git clone https://github.com/johnhuang316/code-index-mcp.git
   cd code-index-mcp
   uv sync
   

2. Configure para desenvolvimento local:

   {
     "mcpServers": {
       "code-index": {
         "command": "uv",
         "args": ["run", "code-index-mcp"]
       }
     }
   }
   

3. Depure com o MCP Inspector:

   npx @modelcontextprotocol/inspector uv run code-index-mcp
   

pip install code-index-mcp

{
  "mcpServers": {
    "code-index": {
      "command": "code-index-mcp",
      "args": []
    }
  }
}

Ferramentas Disponíveis

🏗️ Gerenciamento de Projetos

Execute build_deep_index quando precisar de dados no nível de símbolos; o índice raso padrão permite descoberta rápida de arquivos.

🔍 Busca e Descoberta

🔄 Monitoramento e Atualização Automática

🛠️ Sistema e Manutenção

Exemplos de Uso

🎯 Fluxo de Trabalho de Início Rápido

1. Inicialize Seu Projeto

Set the project path to /Users/dev/my-react-app

Indexa automaticamente sua base de código e cria cache pesquisável 2. Explorar Estrutura do Projeto

Find all TypeScript component files in src/components

Usa: find_files com padrão src/components/**/*.tsx

3. Analisar Arquivos-Chave

Give me a summary of src/api/userService.ts

Usa: get_file_summary para mostrar funções, imports e complexidade Dica: execute build_deep_index primeiro se você receber uma resposta needs_deep_index.

🔍 Exemplos de Busca Avançada

Search for all function calls matching "get.*Data" using `regex=True`

Find authentication-related functions with fuzzy search for 'authUser'

Search for "API_ENDPOINT" only in Python files

Configure automatic index updates when files change

I added new components, please refresh the project index

Solução de Problemas

🔄 Atualização Automática Não Funcionando

Se as atualizações automáticas do índice não estiverem funcionando quando os arquivos mudam, tente:

• pip install watchdog (pode resolver problemas de isolamento de ambiente)
• Use atualização manual: Chame a ferramenta refresh_index após fazer alterações nos arquivos
• Verifique o status do observador de arquivos: Use get_file_watcher_status para confirmar que o monitoramento está ativo

Opções de Observador de Arquivos no macOS

O observador padrão FSEvents funciona bem para a maioria dos projetos. Se você tiver problemas, pode alternar para um observador alternativo via configure_file_watcher:

• "auto" (padrão): Padrão da plataforma (FSEvents no macOS)
• "kqueue": Observador Kqueue (macOS/BSD)
• "fsevents": Forçar FSEvents (somente macOS)
• "polling": Fallback de polling multiplataforma

Nota: Kqueue abre um descritor de arquivo por arquivo observado. Para projetos grandes usando kqueue, você pode precisar aumentar o limite: ulimit -n 10240

Desenvolvimento e Contribuição

🔧 Compilando a partir do Código-Fonte

git clone https://github.com/johnhuang316/code-index-mcp.git
cd code-index-mcp
uv sync
uv run code-index-mcp

🐛 Depuração

npx @modelcontextprotocol/inspector uvx code-index-mcp

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

📜 Licença

MIT License

🌐 Traduções

• 繁體中文
• 日本語