Skip to main content
Glama
daswort

code-context-mcp

by daswort
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

🧩 code-context-mcp

Pipeline para segmentar código fuente en chunks, generar embeddings y almacenarlos en ChromaDB. Diseñado para dar contexto semántico a AI coding assistants (Antigravity, Cursor, VS Code Copilot) vía Model Context Protocol (MCP).

Arquitectura

┌────────────────────────────────────────────────────────┐
│  AI Assistant (Antigravity, Cursor, VS Code, etc.)     │
│  Usa tools MCP para buscar código relevante            │
└────────────────────┬───────────────────────────────────┘
                     │ MCP (stdio)
┌────────────────────▼───────────────────────────────────┐
│  chunking-mcp                                          │
│  MCP Server liviano · 10 tools de solo lectura         │
│  Sin modelo local — queries vía HTTP                   │
└────────────────────┬───────────────────────────────────┘
                     │ HTTP
┌────────────────────▼───────────────────────────────────┐
│  ChromaDB (Docker)                                     │
│  Genera embeddings server-side (all-MiniLM-L6-v2)      │
│  Almacena y busca vectores                             │
│  Named volume: code-context-chroma-data                │
└────────────────────────────────────────────────────────┘

Related MCP server: Paparats MCP

Instalación

# Clonar
git clone git@github.com:daswort/code-context-mcp.git && cd code-context-mcp

# Crear virtualenv e instalar
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Levantar ChromaDB
cd docker && docker compose up -d

Esto instala 3 comandos CLI:

Comando

Función

chunking-get

Segmenta código fuente en chunks JSONL

chunking-ingest

Ingesta chunks en ChromaDB (delta incremental)

chunking-mcp

MCP server para AI assistants

Uso rápido

1. Segmentar código

El indexador nunca mueve el repo: no hace checkout ni pull. La rama que se declara tiene que ser la rama activa, y si no coincide el comando falla indicando las órdenes a ejecutar.

chunking-get <rama> --repo /ruta/al/repo --output /ruta/chunks/mi-repo

Ejemplo:

chunking-get main --repo ~/projects/agenda2-app --output ~/projects/chunking/chunks/agenda2-app

Para indexar lo que hay en disco sin declarar el nombre de la rama, --current-tree toma la rama activa. Sirve cuando el árbol tiene cambios sin commitear, con un costo que conviene saber: el manifiesto queda con dirty: true, la herramienta status del MCP devuelve stale y kb doctor reporta ese repo como WARN hasta que se reindexe con el árbol limpio.

chunking-get --current-tree --repo ~/projects/agenda2-app --output ~/projects/chunking/chunks/agenda2-app

chunking-ingest acepta las mismas dos formas y la misma verificación, para que el manifiesto no pueda declarar una rama distinta de la que apunta su git_sha.

Esto genera un archivo JSONL con todos los fragmentos del código fuente:

chunks/agenda2-app/main/00001_chunks.jsonl

2. Ingestar en ChromaDB

chunking-ingest <rama> --repo /ruta/al/repo --chunks-dir /ruta/chunks/mi-repo

Ejemplo:

chunking-ingest main --repo ~/projects/agenda2-app --chunks-dir ~/projects/chunking/chunks/agenda2-app

La ingesta es delta: detecta chunks nuevos, modificados y eliminados. Solo re-procesa lo necesario:

🔍 Analizando cambios...
♻️ 3 fragmentos modificados o nuevos detectados.
🗑️ 1 fragmentos eliminados detectados.
🧠 Insertando 3 fragmentos (embeddings server-side)
🗑️ Eliminando 1 fragmentos obsoletos
✅ Ingesta completada: 3 actualizados, 1 eliminados en 'agenda2-app_main'.

3. Buscar código (MCP)

El MCP server expone herramientas con respuestas JSON limitadas para AI assistants:

Contrato de rutas: file es relativa a la raíz del repo indexado y es la única forma que puede citarse en respuestas, tickets o PRs; abs_path es absoluta y sirve solo para abrir el archivo en la máquina local. Las herramientas que reciben una ruta aceptan cualquiera de las dos formas.

Tool

Descripción

search_repo

Búsqueda semántica por alias de repo y branch, sin conocer la colección

search_code

Búsqueda semántica por colección, con filtros por extensión y lenguaje

search_exact

Búsqueda full-text o regex exacto (no semántica, ideal para encontrar símbolos)

list_collections

Lista todas las colecciones con conteos

get_collection_summary

Resumen de colección con estadísticas precalculadas

get_file_chunks

Página acotada de chunks de un archivo específico

peek_collection

Vista previa de los primeros N documentos

get_document

Obtener un chunk específico por ID

search_by_file_pattern

Buscar archivos indexados por patrón o extensión (.go, .py)

status

Freshness del índice para un repo y branch

chunking-ingest escribe index_manifest.json junto a los chunks de cada rama. Incluye repo, colección, SHA, branch, fecha, estado dirty y estadísticas agregadas. El proceso MCP debe tener acceso a ese directorio. Por defecto usa ./chunks; se puede configurar con CODE_CONTEXT_CHUNKS_DIR:

{
  "env": {
    "CODE_CONTEXT_CHUNKS_DIR": "/ruta/a/chunks"
  }
}

Los resultados incluyen freshness (ok, stale o unknown) y una advertencia: el índice semántico sirve para descubrir candidatos, no como evidencia final. Verifique el archivo real antes de citarlo. Cada búsqueda se limita a 10 resultados, 4.000 caracteres por snippet y 12 KB de salida.

Los archivos .sql se clasifican como tsql; use language: "tsql" para filtrar procedimientos y scripts SQL. Tras esta actualización, ejecute chunking-ingest una vez por colección existente para renovar esa metadata.

El servidor MCP es de sólo lectura: no expone operaciones para eliminar colecciones. Después de actualizar el paquete o sus variables de entorno, reinicie el cliente MCP para que vuelva a cargar las herramientas y el directorio de manifests.

4. Preview sin procesar (dry-run)

chunking-get --current-tree --repo ~/projects/mi-repo --dry-run

Lista los archivos que se procesarían, agrupados por extensión, sin ejecutar nada. La verificación de rama corre antes que el listado, así que un dry-run sobre un directorio que no es repo Git, con HEAD suelto, o declarando una rama que no es la activa, falla sin listar nada.

🔎 Dry-run para repo '/home/user/projects/mi-repo' (rama 'main')

📋 Dry-run: 42 archivos serían procesados

  .go  (25 archivos)
    • backend/cmd/api/main.go
    • backend/internal/config/auth.go
    ...

  .sql  (12 archivos)
    • backend/migrations/000001_init_extensions.up.sql
    ...

Total: 42 archivos

Configuración por proyecto

Cada repositorio puede tener un archivo .chunking.yaml en su raíz para personalizar el comportamiento. Las listas extienden los defaults, no los reemplazan.

Copie .chunking.example.yaml como punto de partida:

cp /ruta/a/chunking/.chunking.example.yaml ~/projects/mi-repo/.chunking.yaml

Ejemplo completo

# ~/projects/mi-repo/.chunking.yaml

# Directorios adicionales a excluir
exclude_dirs:
  - vendor
  - tmp

# Extensiones adicionales a excluir
exclude_ext:
  - .log

# Extensiones adicionales a incluir
extra_valid_ext:
  - .go
  - .py
  - .html
  - .sql

# Parámetros de chunking
chunk_size: 800
chunk_overlap: 100

# Tuning del índice HNSW (ChromaDB)
hnsw_space: cosine            # cosine, l2, ip
hnsw_ef_construction: 200     # Calidad de indexación
hnsw_ef_search: 150           # Calidad de recall

# ChromaDB
collection_prefix: mi-proyecto     # → colección: mi-proyecto_main
chroma_host: localhost
chroma_port: 8000
# chroma_auth_token: mi-token     # Opcional

Defaults incluidos

.git, __pycache__, node_modules, dist, build, .venv, .idea, .vscode, .github, bin, obj, chunks

.exe, .bin, .dll, .pdb, .user, .jpg, .jpeg, .png, .gif, .zip, .tar, .gz, .lock

.cs, .csproj, .sln, .cshtml, .js, .ts, .md, .json, .yaml, .yml, .txt, .http

Configuración MCP para AI Assistants

Antigravity

Agregar a ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "code-context": {
      "command": "/ruta/a/code-context-mcp/.venv/bin/chunking-mcp",
      "env": {
        "CHROMA_HOST": "localhost",
        "CHROMA_PORT": "8000"
      }
    }
  }
}

Cursor

Agregar a .cursor/mcp.json:

{
  "mcpServers": {
    "code-context": {
      "command": "/ruta/a/code-context-mcp/.venv/bin/chunking-mcp",
      "env": {
        "CHROMA_HOST": "localhost",
        "CHROMA_PORT": "8000"
      }
    }
  }
}

VS Code (Copilot)

Agregar a .vscode/mcp.json:

{
  "servers": {
    "code-context": {
      "type": "stdio",
      "command": "/ruta/a/code-context-mcp/.venv/bin/chunking-mcp",
      "env": {
        "CHROMA_HOST": "localhost",
        "CHROMA_PORT": "8000"
      }
    }
  }
}

ChromaDB (Docker)

El servidor se levanta con Docker Compose:

cd docker/
docker compose up -d

Configuración

Editar docker/.env:

# Puerto (default: 8000)
CHROMA_PORT=8000

# Autenticación por token (opcional)
# CHROMA_AUTH_TOKEN=mi-token-secreto
# CHROMA_AUTH_PROVIDER=chromadb.auth.token_authn.TokenAuthenticationServerProvider

Operaciones comunes

# Ver estado
docker compose ps

# Ver logs
docker compose logs -f chromadb

# Parar
docker compose down

# Parar y borrar datos
docker compose down -v

Los datos persisten en un named volume (code-context-chroma-data) montado en /data, la ruta de persistencia de Chroma 1.5.6. Se mantienen entre reinicios del contenedor. La imagen local añade BusyBox exclusivamente para ejecutar un healthcheck HTTP real contra /api/v2/heartbeat.

Script de orquestación

run_branch_tasks.sh ejecuta el pipeline completo (get + ingest) para la rama actual o una específica:

# Rama actual
./run_branch_tasks.sh

# Rama específica
./run_branch_tasks.sh feature/mi-feature

Estructura del proyecto

code-context-mcp/
├── .chunking.example.yaml       # Template de configuración
├── pyproject.toml                # Paquete Python (v1.0.0)
├── run_branch_tasks.sh           # Orquestador get + ingest
├── docker/
│   ├── docker-compose.yml        # ChromaDB server
│   └── .env                      # Variables de entorno
└── chunking/
    ├── __init__.py
    ├── config.py                 # Defaults + merge con .chunking.yaml
    ├── get_chunks.py             # chunking-get: segmentación de código
    ├── ingest_delta.py           # chunking-ingest: ingesta delta en ChromaDB
    └── mcp_server.py             # chunking-mcp: MCP server (10 tools de solo lectura)

Requisitos

  • Python ≥ 3.10

  • Docker (para ChromaDB)

  • Git (los repos a procesar deben ser repositorios Git)

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Paparats MCP

    IBazylchuk
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides AI coding assistants with deep, semantic understanding of local codebases via AST-aware chunking, cross-repo symbol graphs, and architectural memory, enabling context-aware code search and dependency tracing.
    11
    MIT

  • Serena MCP Server

    Raheem-19
    A
    license
    B
    quality
    D
    maintenance
    Provides IDE-like semantic code retrieval and editing tools for LLMs, enabling precise code understanding and manipulation in large codebases via the Model Context Protocol.
    25
    MIT

  • CodeMind

    twly7ho2
    F
    license
    Not graded
    quality
    C
    maintenance
    Provides persistent codebase memory and semantic context for AI agents via AST-aware chunking and symbol graph indexing.
    1
    -