CodeAlive MCP

Fornece recursos de pesquisa semântica de código e interação com a base de código por meio da API CodeAlive.

Documentação

CodeAlive MCP: Mecanismo de Contexto Mais Profundo para seus projetos (especialmente para grandes bases de código)

Conecte seu assistente de IA à poderosa plataforma de compreensão de código da CodeAlive em segundos!

Este servidor MCP (Model Context Protocol) permite que clientes de IA como Claude Code, Cursor, Claude Desktop, Continue, VS Code (GitHub Copilot), Cline, Codex, OpenCode, SourceCraft Code Assistant, SourceCraft CLI, Zed, KodaCode, GigaCode, Qwen Code, Gemini CLI, Roo Code, Goose, Kilo Code, Windsurf, Kiro, Qoder, n8n e Amazon Q Developer acessem os recursos avançados de busca semântica de código e interação com bases de código da CodeAlive.

O que é CodeAlive?

CodeAlive é um Mecanismo de Contexto para grandes bases de código, alimentado por recuperação baseada em grafos e exposto por meio de MCP. Ele fornece a agentes de IA como Cursor, Claude Code, Codex e outras ferramentas compatíveis com MCP um contexto preciso do repositório, em vez de forçá-los a ler arquivos às cegas. Em nosso benchmark RepoQA, CodeAlive + Qwen3.6 deep alcançou qualidade de agente de fronteira com custo de modelo ~25x menor, e a busca semântica reduziu os tokens capturados em 45%.

É como o Context7, mas para suas bases de código (grandes).

Ele permite que Agentes de Codificação com IA:

Encontrem código relevante mais rápido com busca semântica
Compreendam o panorama geral além de arquivos isolados
Forneçam respostas melhores com contexto completo do projeto
Reduzam custos e tempo eliminando suposições

🛠 Ferramentas Disponíveis

Uma vez conectado, você terá acesso a estas ferramentas poderosas:

get_data_sources - Liste seus repositórios e espaços de trabalho indexados
semantic_search - Busca semântica canônica em artefatos indexados
grep_search - Busca exata de texto literal ou regex no conteúdo de arquivos, além de correspondência literal de nome/caminho de arquivo (retorna arquivos como Form.xml mesmo quando seu conteúdo nunca menciona o nome), com pré-visualizações em nível de linha para correspondências de conteúdo
get_repository_ontology - Obtenha orientação em nível de repositório para um repositório selecionado
get_file_tree - Inspecione uma árvore de arquivos limitada para um repositório
read_file - Leia um caminho de arquivo relativo ao repositório, opcionalmente com um intervalo de linhas
fetch_artifacts - Carregue o código-fonte completo para resultados de busca relevantes (identificadores ausentes ou inacessíveis são reportados, não descartados silenciosamente)
get_artifact_relationships - Expanda grafo de chamadas, herança e relações de referência para um artefato
get_artifact_query_schema - Inspecione entidades, campos e exemplos suportados do ArtifactQuery
query_artifact_metadata - Execute análises de metadados somente leitura em repositórios selecionados
chat - Perguntas e respostas sintetizadas sobre a base de código, sem estado e mais lentas; chame apenas quando solicitado explicitamente

🎯 Exemplos de Uso

Após a configuração, experimente estes comandos com seu assistente de IA:

"Mostre-me todos os repositórios disponíveis" → Usa get_data_sources
"Encontre código de autenticação no serviço de usuário" → Usa semantic_search
"Encontre o regex exato que corresponde a tokens JWT" → Usa grep_search
"Explique como o fluxo de pagamento funciona nesta base de código" → Geralmente começa com semantic_search/grep_search, e opcionalmente usa chat

semantic_search e grep_search devem ser as ferramentas padrão para a maioria dos agentes. chat é um fallback de síntese sem estado mais lento que pode levar substancialmente mais tempo do que a recuperação, e geralmente é desnecessário quando um agente pode executar um fluxo de trabalho em várias etapas com ontologia, busca, busca/leitura, relações, ArtifactQuery e leituras de arquivos locais. Se seu agente suporta subagentes, o caminho de maior confiança é delegar a um subagente focado que orquestra semantic_search e grep_search primeiro.

📚 Skill do Agente

Para uma experiência ainda melhor, instale a CodeAlive Agent Skill junto com o servidor MCP. O servidor MCP dá ao seu agente acesso às ferramentas da CodeAlive; a skill ensina os melhores fluxos de trabalho e padrões de consulta para usá-las de forma eficaz.

Para a maioria dos agentes (Cursor, Copilot, Gemini CLI, Codex e 30+ outros) — instale a skill:

npx skills add CodeAlive-AI/codealive-skills@codealive-context-engine

Para Claude Code — instale o plugin (recomendado), que inclui a skill além de melhorias específicas do Claude:

/plugin marketplace add CodeAlive-AI/codealive-skills
/plugin install codealive@codealive-marketplace

🚀 Início Rápido (Remoto)

A maneira mais rápida de começar - sem necessidade de instalação! Nosso servidor MCP remoto em https://mcp.codealive.ai/api fornece acesso instantâneo aos recursos da CodeAlive.

Passo 1: Obtenha Sua Chave de API

Cadastre-se em https://app.codealive.ai/
Navegue até MCP & API
Clique em "+ Create API Key"
Copie sua chave de API imediatamente - você não a verá novamente!

Passo 2: Abra o Guia do Seu Cliente

Escolha seu cliente nos guias de integração MCP e siga as instruções de configuração atuais.

🚀 Início Rápido (Instalação Agentica)

Você pode pedir ao seu agente de IA para instalar o servidor CodeAlive MCP para você.

Copie e cole o seguinte prompt no seu agente de IA. Não inclua sua chave de API no prompt:

Add the CodeAlive MCP server by following the guide for my client at https://docs.codealive.ai/integrations/mcp

Prefer the Remote HTTP option when available. Do not ask me to paste an API key into chat. When the key is needed, ask me to create a CodeAlive API key and copy it to my clipboard. After I confirm, insert it directly from the clipboard into the required secure configuration without displaying, echoing, logging, or exposing it in command arguments, command output, or model context. If you cannot safely use the clipboard without exposing the value, tell me exactly where to paste it myself.

Em seguida, permita a execução.

Reinicie seu agente de IA.

🤖 Integrações com Clientes de IA

A configuração específica de cada cliente é mantida na documentação da CodeAlive para que caminhos de arquivo, transportes e orientações de autenticação permaneçam atualizados.

Comece aqui: guias de integração MCP

Cliente	Guia de configuração
Claude Code	Claude Code
Claude Desktop	Claude Desktop
Cursor	Cursor
Visual Studio Code	VS Code
Windsurf	Windsurf
Cline	Cline
Continue	Continue
Codex	Codex
Gemini CLI	Gemini CLI
Amazon Q Developer	Amazon Q
OpenCode	OpenCode
SourceCraft Code Assistant e SourceCraft CLI	SourceCraft
Zed	Zed
ChatGPT	ChatGPT
OpenClaw	OpenClaw
KodaCode, GigaCode, Roo Code, Goose, Kilo Code, Qwen Code, Kiro, Qoder, JetBrains AI Assistant, n8n e outros	Outros agentes

Para um cliente não listado, use estes detalhes genéricos de conexão e adapte-os ao formato de configuração MCP do cliente:

Endpoint: https://mcp.codealive.ai/api
Transporte: Streamable HTTP
Cabeçalho de autenticação: Authorization: Bearer YOUR_API_KEY_HERE

Para uma implantação privada, substitua o endpoint pela URL /api do seu servidor. Consulte Self-Hosting para orientações de implantação.

Conectar o servidor é metade da configuração. Os agentes de codificação podem continuar usando sua busca integrada, a menos que as instruções do projeto digam para preferirem a CodeAlive. Regras prontas para AGENTS.md, CLAUDE.md e arquivos de instrução específicos de cada cliente estão em Instruindo Agentes de Codificação.

🔧 Avançado: Desenvolvimento Local

Para desenvolvedores que desejam personalizar ou contribuir com o servidor MCP.

Pré-requisitos

Python 3.11+
uv (recomendado) ou pip

Instalação

# Clone the repository
git clone https://github.com/CodeAlive-AI/codealive-mcp.git
cd codealive-mcp

# Setup with uv (recommended)
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e .

# Or setup with pip
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate  
pip install -e .

Configuração do Servidor Local

Após instalar o servidor localmente, aponte seu cliente MCP para .venv/bin/python com src/codealive_mcp_server.py como primeiro argumento e forneça CODEALIVE_API_KEY no ambiente do processo. A configuração específica de cada cliente pertence aos guias de integração MCP.

Executando o Servidor HTTP Localmente

# Start local HTTP server
export CODEALIVE_API_KEY="your_api_key_here"
python src/codealive_mcp_server.py --transport http --host localhost --port 8000

# Test health endpoint
curl http://localhost:8000/health

O transporte HTTP valida os cabeçalhos Host e Origin do navegador. Hosts de loopback (localhost, 127.0.0.1, ::1) funcionam sem configuração adicional. Para um hostname compartilhado, configure uma allowlist exata:

export CODEALIVE_MCP_ALLOWED_HOSTS="mcp.codealive.yourcompany.com"
# Only for browser callers; ordinary MCP clients do not send Origin.
export CODEALIVE_MCP_ALLOWED_ORIGINS="https://mcp.codealive.yourcompany.com"
python src/codealive_mcp_server.py --transport http --host 0.0.0.0 --port 8000

As opções CLI repetíveis equivalentes são --allowed-host e --allowed-origin. Não use * para um servidor exposto à Internet.

Testando Sua Instalação Local

Após fazer alterações, verifique rapidamente se tudo funciona:

# Match pyproject.toml exactly; older uv versions reject the locked setup.
uv --version  # expected: uv 0.11.28
uv sync --locked --extra test

# Install the repository pre-push dependency audit once per clone
./scripts/setup-hooks.sh

# Quick smoke test (recommended)
make smoke-test

# Or run directly
python smoke_test.py

# With your API key for full testing
CODEALIVE_API_KEY=your_key python smoke_test.py

# Run unit tests
make unit-test

# Run all tests
make test

# Equivalent direct locked test run
uv run pytest src/tests/ -q

O teste de fumaça verifica:

O servidor inicia e conecta corretamente
Todas as ferramentas estão registradas
Cada ferramenta responde adequadamente
A validação de parâmetros funciona
Executa em ~5 segundos

🌐 Plugins da Comunidade

🚢 Implantação HTTP (Self-Hosted & Nuvem)

Implante o servidor MCP como um serviço HTTP para acesso em toda a equipe ou integração com instâncias CodeAlive self-hosted.

Opções de Implantação

O servidor CodeAlive MCP pode ser implantado como um serviço HTTP usando Docker. Isso permite que vários clientes de IA se conectem a uma única instância compartilhada e possibilita a integração com implantações CodeAlive self-hosted.

Docker Compose (Recomendado)

Crie um arquivo docker-compose.yml com base em nosso exemplo:

# Download the example
curl -O https://raw.githubusercontent.com/CodeAlive-AI/codealive-mcp/main/docker-compose.example.yml
mv docker-compose.example.yml docker-compose.yml

# Edit configuration (see below)
nano docker-compose.yml

# Start the service
docker compose up -d

# Check health
curl http://localhost:8000/health

Opções de Configuração:

Para CodeAlive Cloud (padrão):
- Remova a variável de ambiente CODEALIVE_BASE_URL (usa o padrão https://app.codealive.ai)
- Para clientes remotos com suporte a OAuth, configure apenas https://mcp.codealive.ai/api e conclua o login no navegador quando solicitado
- Clientes existentes com chave de API continuam suportados via Authorization: Bearer YOUR_KEY
Para CodeAlive Self-Hosted:
- Defina CODEALIVE_BASE_URL para a URL da sua instância CodeAlive (por exemplo, https://codealive.yourcompany.com)
- Defina CODEALIVE_MCP_ALLOWED_HOSTS para o hostname exato que os clientes usam para este servidor MCP
- Os clientes devem fornecer sua chave de API via cabeçalho Authorization: Bearer YOUR_KEY

Consulte docker-compose.example.yml para o modelo de configuração completo.

Por exemplo, os clientes atuais Codex e Claude Code podem usar OAuth no navegador sem armazenar uma chave de API da CodeAlive:

codex mcp add codealive --url https://mcp.codealive.ai/api
codex mcp login codealive

claude mcp add --transport http codealive https://mcp.codealive.ai/api
# Start Claude Code and run /mcp to authenticate.

Cursor e OpenCode também descobrem OAuth automaticamente a partir da mesma URL. Use cursor-agent mcp login codealive ou opencode mcp auth codealive quando a interface deles não solicitar automaticamente. A configuração com chave de API permanece disponível como opção de compatibilidade.

Perfil de implantação OAuth 2.1

Implantações HTTP remotas podem habilitar a autorização no navegador enquanto mantêm os clientes legados com chave de API funcionando durante a implantação. O modo OAuth publica Metadados de Recurso Protegido MCP, valida JWTs exatos vinculados a emissor/recurso e os troca por um token separado de API de Ferramenta de curta duração. O token de portador MCP recebido nunca é encaminhado adiante.

Variável de ambiente	Finalidade
`CODEALIVE_MCP_OAUTH_ENABLED=true`	Habilita a validação OAuth e a descoberta de autorização MCP para transporte HTTP
`CODEALIVE_OAUTH_ISSUER`	Emissor OpenIddict exato, com barra final
`CODEALIVE_MCP_RESOURCE`	URL pública exata do recurso MCP; seu caminho também é o caminho HTTP MCP
`CODEALIVE_TOOL_API_RESOURCE`	Público downstream; padrão é `urn:codealive:tool-api`
`CODEALIVE_OAUTH_INTERNAL_CLIENT_ID`	Cliente confidencial de servidor de recursos usado apenas para troca de tokens
`CODEALIVE_OAUTH_INTERNAL_CLIENT_SECRET`	Segredo obrigatório para esse cliente interno; a inicialização falha de forma segura quando ausente
Os valores do servidor de autorização e do serviço MCP devem corresponder exatamente. No CodeAlive Web.Server, as configurações correspondentes ficam em `McpOAuth` (`Enabled`, `Issuer`, `Resource`, `ToolApiResource`, `InternalClientId` e `InternalClientSecret`). Persista o anel de chaves do Data Protection do Web.Server e os certificados de assinatura/criptografia do OpenIddict entre réplicas e reinicializações. Para uma rotação interna de credenciais sem tempo de inatividade, atribua um novo client ID à nova credencial, implante o Web.Server com o par atual e o `PreviousInternalClientId`/`PreviousInternalClientSecret`, faça o rollout das réplicas MCP para o novo par atual e, em seguida, remova o par anterior. O Web.Server falha deliberadamente na inicialização em vez de alterar um segredo no lugar sob um client ID existente.

Ative os flags do Web.Server e do MCP no mesmo rollout; uma implantação parcialmente ativada não é um estado estável válido. As credenciais de chave de API mantêm sua gramática legada explícita e nunca são usadas como fallback após a falha da validação OAuth.

Conectando Clientes MCP à Sua Instância Implantada

Use os mesmos detalhes de conexão genéricos do CodeAlive Cloud, substituindo o endpoint pela URL /api da sua implantação:

Endpoint: https://your-server.example.com/api
Transporte: Streamable HTTP
Cabeçalho de autenticação: Authorization: Bearer YOUR_API_KEY_HERE

Para o formato exato de configuração, abra o guia de integração do cliente relevante.

🪟 Windows e WSL

Use a documentação específica do cliente para configuração no Windows e WSL:

Para servidores auto-hospedados em execução no WSL2, os clientes Windows devem conseguir acessar o endpoint /api do servidor. Use rede espelhada (mirrored networking) em versões compatíveis do Windows 11 ou conecte-se pelo endereço da VM WSL2.

🐞 Solução de Problemas

Diagnóstico Rápido

Teste o serviço hospedado:
```
curl https://mcp.codealive.ai/health
```

Verifique sua chave de API:

curl -H "Authorization: Bearer YOUR_API_KEY" https://app.codealive.ai/api/v1/data_sources

Ative o log de depuração: Adicione --debug aos argumentos do servidor local

Problemas Comuns

"Conexão recusada" → Verifique a conexão com a internet
"401 Não autorizado" → Verifique sua chave de API
"Nenhum repositório encontrado" → Verifique as permissões da chave de API no painel do CodeAlive
Logs específicos do cliente → Consulte a documentação do seu cliente de IA para logs MCP

Problemas no Windows / WSL

docker: command not found no WSL → Ative a integração WSL do Docker Desktop para sua distribuição (Configurações → Recursos → Integração WSL) ou use o caminho completo /usr/bin/docker
ENOENT ou spawn error para npx/python → Shells WSL não interativos não herdam caminhos nvm/pyenv. Use caminhos absolutos nas configurações MCP
Connection refused para servidor auto-hospedado no WSL2 → O WSL2 usa rede NAT; localhost difere entre Windows e WSL2. Ative a rede espelhada em .wslconfig ou use o IP da VM WSL2 (hostname -I)
O Claude Desktop não consegue se conectar ao servidor MCP do WSL → O Claude Desktop não suporta a criação de subprocessos WSL. Use HTTP Remoto (https://mcp.codealive.ai/api), Docker Desktop ou o padrão de proxy wsl.exe (consulte a seção Windows e WSL)

Obtendo Ajuda

📧 E-mail: support@codealive.ai
🐛 Problemas: GitHub Issues

📦 Publicando no Registro MCP

Para mantenedores: consulte DEPLOYMENT.md para instruções sobre como publicar novas versões no Registro MCP.

Política de Privacidade

O CodeAlive processa os repositórios e as consultas que você envia por meio desta extensão para fornecer pesquisa semântica e análise de base de código. Para detalhes completos de privacidade, consulte a Política de Privacidade do CodeAlive.

📄 Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Pronto para turbinar seu assistente de IA com compreensão profunda de código? Comece agora →