Introdução ao Claude Context: faça a IA entender de verdade todo o seu repositório de código

O Claude Context é um plugin open source do MCP (Model Context Protocol), desenvolvido pelo fornecedor de bases de dados vetoriais Zilliz. Seu foco é bastante claro: injetar no assistente de codificação por IA a capacidade de entender semanticamente todo o repositório.

Nos fluxos de trabalho tradicionais, quando você quer que a IA entenda um repositório desconhecido, normalmente precisa copiar manualmente os caminhos dos arquivos, descrever a estrutura do projeto e explicar as relações entre módulos — tarefas que, em tese, deveriam ser feitas pela própria IA. Com o Claude Context, graças à busca por semântica, a IA consegue consultar diretamente funções, classes e estruturas de dados dentro do repositório, sem depender de você fazer injeção manual de contexto.

O projeto está hospedado no GitHub em zilliztech/claude-context, usa a licença MIT e todo o código é totalmente aberto.

---

Dificuldade/Duração/Resultados

Para iniciantes | Cerca de 20 minutos | Você vai aprender como dar a qualquer ferramenta de codificação capacidade de entendimento semântico de milhões de linhas com apenas 2 comandos, reduzindo ainda o consumo de tokens em aproximadamente 40%.

---

Público-alvo

• Desenvolvedores que usam no dia a dia ferramentas de programação com IA como Claude Code, Cursor, Windsurf, Cline etc.
• Pessoas com noções básicas de RAG (Retrieval-Augmented Generation) e busca vetorial, que querem colocar em prática de forma aprofundada
• Times que desejam reduzir custos de tokens e aumentar a precisão das respostas da IA

---

Dependências principais e ambiente

Requisitos do sistema

• Node.js >= 20.0.0 e < 24.0.0
• Sistema operacional: macOS, Windows ou Linux

Dependências de serviço

• Zilliz Cloud (cota gratuita é suficiente para uso individual): fornece o backend do banco de dados vetorial
• OpenAI API Key: usada para gerar vetores no modelo de embedding (também é possível substituir por outro provedor que ofereça embedding)

---

Árvore completa da estrutura do projeto

O Claude Context é um pacote npm puro, sem necessidade de clonar ou compilar qualquer código local. Após instalar, ele gerencia sua própria estrutura de armazenamento:

~/.claude/
└── plugins/
    └── claude-context/          # diretório do plugin MCP
        └── [arquivo de dados de índice]        # snapshot incremental da árvore Merkle

Se você integrar o pacote Core diretamente em uma aplicação, a estrutura fica assim:

your-project/
├── node_modules/
│   └── @zilliz/claude-context-core/
├── .env                        # onde ficam as chaves da API
└── your-codebase/              # código a ser indexado

---

Passo a passo

Passo 1: registre o Zilliz Cloud e obtenha as credenciais do banco de dados vetorial

O armazenamento vetorial do Claude Context depende do Zilliz Cloud (ou do Milvus self-hosted). Esta etapa exige que você crie uma conta gratuita.

Abra zilliz.com/cloud, faça o cadastro usando seu e-mail ou sua conta do GitHub. Depois de logar, crie um novo Serverless Cluster no console:

1. Clique em Create Cluster
2. Selecione o tipo Serverless (a cota gratuita é totalmente suficiente)
3. Escolha a região mais próxima (AWS us-west-2 ou Singapura são comumente usadas)
4. Dê um nome ao seu cluster, por exemplo claude-context

Quando a criação do cluster terminar, entre na página de detalhes do cluster e encontre Connection Info para copiar os dois valores abaixo para uso posterior:

• Public Endpoint: algo como https://xxx.api.gcp-us-west1.zillizcloud.com
• API Key: algo como xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Passo 2: obtenha a OpenAI API Key

O Claude Context usa um modelo de embedding para transformar trechos de código em vetores. Você precisa preparar uma OpenAI API Key para ativar o modelo padrão text-embedding-3-small.

Abra platform.openai.com/api-keys, clique em Create new secret key e copie o valor gerado (formato sk-xxxxxxxx...).

Passo 3: instale o Claude Context MCP no Claude Code

Agora registramos este servidor MCP no Claude Code. Abra o terminal, entre em qualquer diretório de projeto e execute os comandos abaixo:

claude mcp add claude-context \
  -e OPENAI_API_KEY=sk-your-openai-api-key \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

Substitua os placeholders a seguir pelos seus valores reais:

• sk-your-openai-api-key → sua OpenAI API Key
• your-zilliz-cloud-api-key → sua Zilliz Cloud API Key
• your-zilliz-cloud-public-endpoint → seu Zilliz Public Endpoint

Após executar com sucesso, você verá que o servidor MCP foi registrado. Verifique a instalação:

claude mcp list

Você deve ver claude-context na lista e com o status como running.

Se você estiver usando outra ferramenta de codificação com IA, a forma de configuração é um pouco diferente. Alguns cenários comuns:

Cursor (recomendado: via arquivo de configuração):

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

Windsurf (também usando configuração em JSON):

// ~/.windsurf/mcp_settings.json
{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_ADDRESS": "your-zilliz-cloud-public-endpoint",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

Passo 4: indexe seu primeiro repositório de código

Com a instalação concluída, entre no diretório do seu projeto e inicie o Claude Code:

cd your-project-directory
claude

No chat, digite o comando abaixo para iniciar o índice:

Index this codebase

O Claude Context começa a analisar o repositório imediatamente. Todo o processo acontece em duas etapas:

1. Varredura de arquivos: percorre os diretórios e filtra os arquivos de código a processar com base nas extensões
2. Embeddings vetoriais: para cada arquivo de código, divide em blocos via AST (Abstract Syntax Tree), chama o modelo de embedding para gerar vetores e salva no banco de dados vetorial

Durante a indexação, você pode perguntar a qualquer momento pelo progresso:

Check the indexing status

O resultado informa a porcentagem atual do progresso de indexação e a quantidade de arquivos já concluídos.

Passo 5: valide os resultados da busca e entenda o que as respostas significam

Quando a indexação termina, você pode começar a fazer busca semântica. A seguir, alguns cenários típicos de consulta:

Encontrar a implementação de uma funcionalidade específica:

Find functions that handle user authentication

O retorno incluirá nomes de funções relacionados, caminhos de arquivo, trechos de código e uma pontuação de relevância (entre 0 e 1; quanto maior, mais relevante).

Entender relações entre módulos:

How does the payment module connect to the order module?

Localizar rapidamente código relacionado a configurações:

Where is the database connection pool configured?

O formato do retorno é assim:

File: src/database/connection.ts:45-78
Score: 0.94
Content:
  const pool = new Pool({
    max: 20,
    idleTimeoutMillis: 30000,
    connectionTimeoutMillis: 2000,
  });

Se você quiser limpar o índice e recomeçar, execute:

Clear the index for this codebase

---

Solução de problemas (FAQ)

P1: versão do Node.js incompatível; erro ao executar o comando

Sintoma: claude mcp add falha ou o servidor MCP sai imediatamente após iniciar.

Causa: o Claude Context não oferece suporte ao Node.js 24.x atualmente.

Solução:

# Verifique a versão atual do Node
node -v

# Se for 24.x, faça downgrade para 20.x (LTS)
nvm install 20
nvm use 20

P2: configuração de variáveis de ambiente incorreta; falha na indexação

Sintoma: Index this codebase não responde ou retorna erro Milvus connection failed.

Verificações:

1. Confirme que MILVUS_ADDRESS não contém o prefixo https://, usando apenas a parte do host
2. Confirme que MILVUS_TOKEN é exatamente igual à API Key exibida no console do Zilliz Cloud
3. Confirme que OPENAI_API_KEY começa com sk-

Exemplo de formato correto:

-e MILVUS_ADDRESS=in-xx-xxxxxxxx.api.gcp-us-west1.zillizcloud.com
-e MILVUS_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-e OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

P3: o progresso da indexação fica travado, sem avanços

Sintoma: após o comando de indexação ser enviado, ele não responde por um longo período.

Solução:

1. Execute primeiro Check the indexing status para confirmar o estado atual
2. Verifique a conexão de rede (é necessário acessar a OpenAI API e o Zilliz Cloud)
3. Se o cluster foi criado há pouco, o endpoint pode ainda estar inicializando; aguarde 1 a 2 minutos e tente novamente

P4: a busca retorna vazio ou totalmente sem relação

Sintoma: a consulta deveria corresponder ao conteúdo, mas a busca retorna resultados vazios.

Causa: os arquivos de índice podem estar incompletos ou a formulação da consulta difere muito dos nomes usados no código.

Solução:

1. Verifique primeiro o estado do índice: Check the indexing status
2. Tente uma consulta mais específica (usando nomes de variáveis ou nomes de funções que realmente existam no código)
3. Se você tiver certeza de que o código existe, mas a busca não encontra, limpe o índice e reindexe:

Clear the index for this codebase
Index this codebase

P5: indexação incremental não surtiu efeito; o código alterado não foi encontrado

Sintoma: você alterou um arquivo, mas os resultados da busca semântica continuam apontando para a versão antiga.

Causa: o Claude Context usa snapshots da árvore Merkle para detectar mudanças em arquivos. Se você deletou manualmente o arquivo do snapshot, a detecção incremental pode deixar de funcionar.

Solução: limpe o índice e recomece:

Clear the index for this codebase
Index this codebase

P6: falha na conexão MCP; ferramenta indisponível

Sintoma: não aparece search_code, index_codebase etc. na lista de ferramentas.

Solução:

1. Reinicie o Claude Code (às vezes o servidor MCP precisa ser recarregado)
2. Confirme que não há erros de sintaxe na configuração do MCP (em JSON, atenção a vírgulas e aspas)
3. Verifique se o status do plugin na saída de claude mcp list está como running

claude mcp list

Se o status estiver stopped, reinicie manualmente:

claude mcp remove claude-context
# e então execute novamente o comando de instalação do Passo 3

---

Leitura adicional / Direções avançadas

Usar um modelo de embedding customizado

O text-embedding-3-small da OpenAI é a escolha padrão, mas o Claude Context oferece suporte a vários provedores de embedding, permitindo um deployment totalmente local:

Usar Ollama (modelo local):

claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=ollama \
  -e OLLAMA_BASE_URL=http://localhost:11434 \
  -e OLLAMA_MODEL=nomic-embed-text \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

Usar VoyageAI:

claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=voyageai \
  -e VOYAGEAI_API_KEY=your-voyageai-key \
  -e VOYAGEAI_MODEL=voyage-code-3 \
  -e MILVUS_TOKEN=your-zilliz-cloud-api-key \
  -e MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint \
  -- npx @zilliz/claude-context-mcp@latest

Integrar LangChain/LangGraph para RAG avançado

Se você quiser integrar diretamente as capacidades do Claude Context na sua própria aplicação, pode usar o pacote Core:

import { Context, MilvusVectorDatabase, OpenAIEmbedding } from '@zilliz/claude-context-core';

// Inicialize embedding e banco de dados vetorial
const embedding = new OpenAIEmbedding({
    apiKey: process.env.OPENAI_API_KEY || 'your-openai-api-key',
    model: 'text-embedding-3-small'
});

const vectorDatabase = new MilvusVectorDatabase({
    address: process.env.MILVUS_ADDRESS || 'your-zilliz-cloud-public-endpoint',
    token: process.env.MILVUS_TOKEN || 'your-zilliz-cloud-api-key'
});

const context = new Context({ embedding, vectorDatabase });

// Indexar repositório, monitorando progresso
const stats = await context.indexCodebase('./your-project', (progress) => {
    console.log(`${progress.phase} - ${progress.percentage}%`);
});
console.log(`Indexed ${stats.indexedFiles} files, ${stats.totalChunks} chunks`);

// Executar busca semântica
const results = await context.semanticSearch('./your-project', 'vector database operations', 5);
results.forEach(result => {
    console.log(`File: ${result.relativePath}:${result.startLine}-${result.endLine}`);
    console.log(`Score: ${(result.score * 100).toFixed(2)}%`);
    console.log(`Content: ${result.content.substring(0, 100)}...`);
});

Exemplos detalhados podem ser consultados em evaluation/retrieval/custom.py。

Visualização da busca no VSCode

Se você prefere operar dentro do IDE, pode instalar o plugin Semantic Code Search. Assim, você faz busca semântica diretamente no VS Code, sem precisar iniciar o Claude Code.

Estratégias para gerenciar múltiplos repositórios

O Claude Context suporta gerenciar vários repositórios ao mesmo tempo. Basta chamar Index this codebase em diretórios diferentes; cada diretório mantém seu próprio índice. Você pode usar o nome do diretório para distinguir:

# diretório de trabalho A
cd ~/projects/frontend && claude
# no chat, execute Index this codebase

# diretório de trabalho B
cd ~/projects/backend && claude
# no chat, execute Index this codebase

Princípio de chunking por AST e indexação incremental por árvore Merkle

A capacidade de compreensão do código do Claude Context se baseia em duas tecnologias centrais:

• Chunking baseado em AST: utiliza uma Abstract Syntax Tree para analisar a estrutura do código, dividindo em blocos por limites de funções, classes e módulos, e não apenas cortando por linhas. Isso garante que cada chunk seja uma unidade de código semanticamente completa.
• Indexação incremental por árvore Merkle: depois que um arquivo muda, o sistema compara com a árvore Merkle para reindexar apenas os arquivos alterados, em vez de reconstruir tudo do zero. Isso reduz drasticamente o custo de manutenção de grandes repositórios.

Se você tiver interesse nos detalhes de implementação dessas duas tecnologias, confira o código-fonte em packages/core no repositório zilliztech/claude-context。