Kontxt

Indexa repositórios de código locais para fornecer contexto de base de código para clientes de IA.

GitHub
10

Documentação

Verified on MseeP

Selos do Marketplace

MseeP.ai Security Assessment Badge

Servidor MCP Kontxt

Um servidor Model Context Protocol (MCP) que tenta resolver a indexação de bases de código (até que os agentes consigam).

Recursos

  • Conecta-se a um repositório de código local especificado pelo usuário.
  • Fornece a ferramenta (get_codebase_context) para clientes de IA (como Cursor, Claude Desktop).
  • Usa internamente a janela de entrada de 1M do Gemini 2.0 Flash para analisar a base de código e gerar contexto com base na consulta do usuário.
  • O próprio Flash pode usar ferramentas internas (list_repository_structure, read_files, grep_codebase) para entender o código.
  • Suporta tanto os protocolos de transporte SSE (recomendado) quanto stdio.
  • Suporta arquivos/documentos/contexto anexados pelo usuário nas consultas do cliente para uma análise mais direcionada.
  • Rastreia o uso de tokens e fornece análise detalhada do consumo da API.
  • Limite de tokens configurável pelo usuário para geração de contexto (opções: 500k, 800k ou 1M tokens; padrão: 800k).

Configuração

  1. Clonar/Baixar: Obtenha o código do servidor.
  2. Criar Ambiente: 
    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  3. Instalar Dependências: 
    pip install -r requirements.txt
  4. Instalar tree: Garanta que o comando tree esteja disponível no seu sistema.
    • macOS: brew install tree
    • Debian/Ubuntu: sudo apt update && sudo apt install tree
    • Windows: Requer a instalação de um port ou o uso de WSL.
  5. Configurar Chave da API:
    • Copie .env.example para .env.
    • Edite .env e adicione sua Chave da API Google Gemini: 
      GEMINI_API_KEY="YOUR_ACTUAL_API_KEY"
    • Alternativamente, você pode fornecer a chave via o argumento de linha de comando --gemini-api-key.

Executando como um Servidor Autônomo (Recomendado)

Por padrão, o servidor executa no modo SSE, o que permite que você:

  • Inicie o servidor de forma independente
  • Conecte-se a partir de vários clientes
  • Mantenha-o em execução enquanto reinicia os clientes

Execute o servidor:

python kontxt_server.py --repo-path /path/to/your/codebase

PS: você pode usar pwd para listar o caminho do projeto

O servidor iniciará em http://127.0.0.1:8080/sse por padrão.

Para opções adicionais:

python kontxt_server.py --repo-path /path/to/your/codebase --host 0.0.0.0 --port 6900

Desligando o Servidor

O servidor pode ser interrompido pressionando Ctrl+C no terminal onde está em execução. O servidor tentará encerrar graciosamente com um tempo limite de 3 segundos.

Conectando-se ao Servidor a partir do cliente (exemplo com Cursor)

Uma vez que seu servidor esteja em execução, você pode conectar o Cursor a ele editando seu arquivo ~/.cursor/mcp.json:

{
  "mcpServers": {
    "kontxt-server": {
      "serverType": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

PS: lembre-se de sempre atualizar o servidor MCP nas Configurações do Cursor ou em outro cliente para conectar ao MCP via SSE

Alternativa: Executando com Transporte stdio

Se você preferir que o cliente inicie e gerencie o processo do servidor:

python kontxt_server.py --repo-path /path/to/your/codebase --transport stdio

Para este modo, configure seu arquivo ~/.cursor/mcp.json assim:

{
  "mcpServers": {
    "kontxt-server": {
      "serverType": "stdio",
      "command": "python",
      "args": ["/absolute/path/to/kontxt_server.py", "--repo-path", "/absolute/path/to/your/codebase", "--transport", "stdio"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Argumentos de Linha de Comando

  • --repo-path PATH: Obrigatório. Caminho absoluto para o repositório de código local a ser analisado.
  • --gemini-api-key KEY: Chave da API Google Gemini (substitui .env se fornecida).
  • --token-threshold NUM: Contagem máxima de tokens alvo para o contexto. Os valores permitidos são:
    • 500000
    • 800000 (padrão)
    • 1000000
  • --gemini-model NAME: Modelo Gemini específico a ser usado (padrão: models/gemini-2.5-flash-preview-04-17).
  • --tokenizer-model NAME: ID do tokenizador Hugging Face para estimativa de tokens (padrão: google/gemma-7b; substituível via KONTXT_TOKENIZER_MODEL).
  • --transport {stdio,sse}: Protocolo de transporte a ser usado (padrão: sse).
  • --host HOST: Endereço do host para o servidor SSE (padrão: 127.0.0.1).
  • --port PORT: Porta para o servidor SSE (padrão: 8080).
  • --cors-origins ORIGINS: Lista separada por vírgulas de origens CORS permitidas. Se omitido, o padrão é apenas loopback.
  • --cors-credentials: Permitir credenciais para CORS (desabilitado por padrão).

Configuração CORS

Por segurança, o CORS curinga não é usado. Por padrão, apenas origens de loopback são permitidas:

  • http://127.0.0.1, http://localhost e o host:port vinculado.

Para permitir clientes web específicos durante o desenvolvimento, passe origens explícitas ou use uma variável de ambiente:

python kontxt_server.py \
  --repo-path /path/to/your/codebase \
  --cors-origins http://localhost:3000,http://127.0.0.1:5173

# or via environment variable
KONTXT_CORS_ORIGINS="http://localhost:3000,http://127.0.0.1:5173" \
python kontxt_server.py --repo-path /path/to/your/codebase

Notas:

  • Métodos permitidos: GET, OPTIONS. Cabeçalhos: todos. Credenciais: desativadas, a menos que --cors-credentials esteja definido.

Acesso ao Tokenizador (Gemma) e Recuperação Automática

Este servidor usa o tokenizador google/gemma-7b para estimar tokens. O modelo é restrito pelo Google no Hugging Face.

O que acontece se você ainda não tiver acesso:

  • Na inicialização, se o tokenizador não puder ser baixado, o servidor registra uma mensagem clara e abre automaticamente: https://huggingface.co/google/gemma-7b
  • O servidor continua em execução usando um estimador de tokens heurístico (não trava).
  • Ele tenta recarregar o tokenizador periodicamente; assim que você obtiver acesso, ele alterna automaticamente (sem necessidade de reiniciar).

Como obter acesso (gratuito, ~2 minutos):

  1. Visite https://huggingface.co/google/gemma-7b e faça login (crie uma conta se necessário).
  2. Aceite os termos do Google na página do modelo.
  3. Se estiver executando headless/CI ou um contêiner, autentique o ambiente: huggingface-cli login (ou defina HF_TOKEN).

Configuração:

  • --tokenizer-model ou KONTXT_TOKENIZER_MODEL: use um ID de tokenizador HF diferente, se desejado.
  • KONTXT_TOKENIZER_RELOAD_INTERVAL (segundos, padrão 60): com que frequência o servidor tenta novamente carregar o tokenizador.

Uso Básico

Exemplos de consultas:

  • "Sobre o que é esta base de código"
  • "Como funciona o sistema de autenticação?"
  • "Explique o fluxo de dados no aplicativo"

PS: você pode especificar ainda mais para o agente usar a ferramenta MCP se ele não estiver usando: "Qual é a última palavra do terceiro bloco de código do arquivo de autenticação? Use a ferramenta MCP disponível."

Anexo de Contexto

Seus arquivos/contexto referenciados em suas consultas são incluídos como contexto para análise:

  • "Explique como este arquivo funciona: @kontxt_server.py"
  • "Encontre todos os arquivos que interagem com @user_model.py"
  • "Compare a implementação de @file1.js e @file2.js"

O servidor mencionará esses arquivos para o Gemini, mas NÃO lerá ou incluirá automaticamente seus conteúdos. Em vez disso, o Gemini decidirá quais arquivos ler usando suas ferramentas com base no contexto da consulta.

Essa abordagem permite que o Gemini leia apenas os arquivos realmente necessários e evita que o contexto seja inflado com conteúdo de arquivos irrelevantes.

Rastreamento de Uso de Tokens

O servidor rastreia o uso de tokens em diferentes operações:

  • Listagem da estrutura do repositório
  • Leitura de arquivos
  • Pesquisas grep
  • Arquivos anexados de consultas do usuário
  • Respostas geradas

Essas informações são registradas durante a operação, ajudando você a monitorar o uso da API e otimizar suas consultas.

PD: quer que a ferramenta melhore? PRs estão abertos.