Kontxt

Indexa repositorios de código locales para proporcionar contexto del código fuente a clientes de IA.

GitHub
10

Documentación

Verified on MseeP

Insignias del mercado

MseeP.ai Security Assessment Badge

Servidor MCP Kontxt

Un servidor de Protocolo de Contexto de Modelo (MCP) que intenta resolver la indexación de bases de código (hasta que los agentes puedan hacerlo).

Características

  • Conecta con un repositorio de código local especificado por el usuario.
  • Proporciona la herramienta (get_codebase_context) para clientes de IA (como Cursor, Claude Desktop).
  • Usa internamente la ventana de entrada de 1M de Gemini 2.0 Flash para analizar la base de código y generar contexto según la consulta del cliente.
  • Flash puede usar herramientas internas (list_repository_structure, read_files, grep_codebase) para comprender el código.
  • Soporta protocolos de transporte SSE (recomendado) y stdio.
  • Soporta archivos/documentos/contexto adjuntos por el usuario en las consultas del cliente para un análisis más específico.
  • Realiza seguimiento del uso de tokens y proporciona análisis detallado del consumo de API.
  • Límite de tokens configurable por el usuario para la generación de contexto (opciones: 500k, 800k o 1M tokens; por defecto: 800k).

Configuración

  1. Clonar/Descargar: Obtén el código del servidor.
  2. Crear entorno: 
    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  3. Instalar dependencias: 
    pip install -r requirements.txt
  4. Instalar tree: Asegúrate de que el comando tree esté disponible en tu sistema.
    • macOS: brew install tree
    • Debian/Ubuntu: sudo apt update && sudo apt install tree
    • Windows: Requiere instalar un puerto o usar WSL.
  5. Configurar clave de API:
    • Copia .env.example a .env.
    • Edita .env y agrega tu clave de API de Google Gemini: 
      GEMINI_API_KEY="YOUR_ACTUAL_API_KEY"
    • Alternativamente, puedes proporcionar la clave mediante el argumento de línea de comandos --gemini-api-key.

Ejecutar como servidor independiente (recomendado)

Por defecto, el servidor se ejecuta en modo SSE, lo que te permite:

  • Iniciar el servidor de forma independiente
  • Conectar desde varios clientes
  • Mantenerlo en ejecución mientras reinicias los clientes

Ejecuta el servidor:

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

Nota: puedes usar pwd para listar la ruta del proyecto

El servidor se iniciará en http://127.0.0.1:8080/sse por defecto.

Para opciones adicionales:

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

Apagar el servidor

El servidor se puede detener presionando Ctrl+C en la terminal donde se está ejecutando. El servidor intentará cerrarse de forma correcta con un tiempo de espera de 3 segundos.

Conectar al servidor desde el cliente (ejemplo con Cursor)

Una vez que tu servidor esté en ejecución, puedes conectar Cursor editando tu archivo ~/.cursor/mcp.json:

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

Nota: recuerda siempre refrescar el servidor MCP en la Configuración de Cursor u otro cliente para conectarse al MCP mediante SSE.

Alternativa: Ejecutar con transporte stdio

Si prefieres que el cliente inicie y gestione el proceso del servidor:

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

Para este modo, configura tu archivo ~/.cursor/mcp.json de la siguiente manera:

{
  "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 línea de comandos

  • --repo-path PATH: Requerido. Ruta absoluta al repositorio de código local a analizar.
  • --gemini-api-key KEY: Clave de API de Google Gemini (sobrescribe .env si se proporciona).
  • --token-threshold NUM: Cantidad máxima de tokens objetivo para el contexto. Valores permitidos:
    • 500000
    • 800000 (predeterminado)
    • 1000000
  • --gemini-model NAME: Modelo específico de Gemini a usar (predeterminado: models/gemini-2.5-flash-preview-04-17).
  • --tokenizer-model NAME: Identificador de tokenizador de Hugging Face para la estimación de tokens (predeterminado: google/gemma-7b; se puede sobrescribir mediante KONTXT_TOKENIZER_MODEL).
  • --transport {stdio,sse}: Protocolo de transporte a usar (predeterminado: sse).
  • --host HOST: Dirección del host para el servidor SSE (predeterminado: 127.0.0.1).
  • --port PORT: Puerto para el servidor SSE (predeterminado: 8080).
  • --cors-origins ORIGINS: Lista separada por comas de orígenes CORS permitidos. Si se omite, solo se permiten orígenes de loopback.
  • --cors-credentials: Permitir credenciales para CORS (deshabilitado por defecto).

Configuración CORS

Por seguridad, no se usa comodín CORS. Por defecto, solo se permiten orígenes de loopback:

  • http://127.0.0.1, http://localhost y el host:port vinculado.

Para permitir clientes web específicos durante el desarrollo, pasa orígenes explícitos o usa una variable de entorno:

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. Encabezados: todos. Credenciales: desactivadas a menos que se configure --cors-credentials.

Acceso y recuperación automática del tokenizador (Gemma)

Este servidor usa el tokenizador google/gemma-7b para estimar tokens. El modelo está restringido por Google en Hugging Face.

Qué sucede si aún no tienes acceso:

  • Al iniciar, si el tokenizador no se puede descargar, el servidor registra un mensaje claro y abre automáticamente: https://huggingface.co/google/gemma-7b
  • El servidor continúa ejecutándose usando un estimador de tokens heurístico (no falla).
  • Reintenta periódicamente cargar el tokenizador; una vez que obtengas acceso, cambia automáticamente (no se necesita reinicio).

Cómo obtener acceso (gratis, ~2 minutos):

  1. Visita https://huggingface.co/google/gemma-7b e inicia sesión (crea una cuenta si es necesario).
  2. Acepta los términos de Google en la página del modelo.
  3. Si ejecutas sin interfaz gráfica/CI o en un contenedor, autentica el entorno: huggingface-cli login (o configura HF_TOKEN).

Configuración:

  • --tokenizer-model o KONTXT_TOKENIZER_MODEL: usar un identificador de tokenizador de HF diferente si lo deseas.
  • KONTXT_TOKENIZER_RELOAD_INTERVAL (segundos, valor predeterminado 60): con qué frecuencia el servidor re-intenta cargar el tokenizador.

Uso básico

Ejemplos de consultas:

  • "¿De qué trata esta base de código?"
  • "¿Cómo funciona el sistema de autenticación?"
  • "Explica el flujo de datos en la aplicación."

Nota: también puedes especificar al agente que use la herramienta MCP si no la está usando: "¿Cuál es la última palabra del tercer bloque de código del archivo auth? Usa la herramienta MCP disponible."

Adjuntar contexto

Los archivos/contexto que referencies en tus consultas se incluyen como contexto para el análisis:

  • "Explica cómo funciona este archivo: @kontxt_server.py"
  • "Encuentra todos los archivos que interactúan con @user_model.py"
  • "Compara la implementación de @file1.js y @file2.js"

El servidor mencionará estos archivos a Gemini, pero NO los leerá ni incluirá su contenido automáticamente. En su lugar, Gemini decidirá qué archivos leer usando sus herramientas según el contexto de la consulta.

Este enfoque permite que Gemini solo lea los archivos realmente necesarios y evita que el contexto se llene de contenido de archivos irrelevantes.

Seguimiento del uso de tokens

El servidor realiza seguimiento del uso de tokens en diferentes operaciones:

  • Listado de la estructura del repositorio
  • Lectura de archivos
  • Búsquedas grep
  • Archivos adjuntos de las consultas del usuario
  • Respuestas generadas

Esta información se registra durante la operación, ayudándote a monitorear el uso de API y optimizar tus consultas.

PD: ¿Quieres que la herramienta mejore? Los PR están abiertos.