Context Server

Memoria inteligente de proyectos para Claude Code — responde con contexto comprimido, no con archivos enteros.

Indexa tu codebase y busca por similitud semantica; DeepSeek Flash comprime lo relevante antes de que llegue al contexto. Menos tokens en Claude Code, mismo contexto util. 12 tools MCP, metricas de uso en PostgreSQL.

🧩 Stack

🚀 Instalacion • 🛠️ Tools MCP • ⚙️ Como funciona • 🧩 Stack • 🌐 Dashboard

🔧 Config en Claude Code • 🔑 Variables de entorno • 🧪 Tests • 🔒 Seguridad

Servidor MCP que actua como memoria inteligente de proyectos para Claude Code. Indexa codebases, responde queries con contexto relevante comprimido y registra metricas de uso. Reduce el consumo de tokens en Claude Code usando DeepSeek Flash como preprocesador barato en lugar de mandar archivos completos al contexto.

Como funciona

Claude Code (cualquier maquina)
        |
        | MCP protocol (local o via Tailscale)
        v
Servidor MCP (local en Kali SSD o en openclaw-server)
        |
        | Indexador de codigo (CPU only, all-MiniLM-L6-v2)
        | ChromaDB persistente en disco
        |
        | fragmentos relevantes
        v
DeepSeek Flash API  ──────────────────────────────────────────► PostgreSQL (Railway)
                                                                         ^
                                                                         |
                                                                Next.js Dashboard
                                                                ia.novamicktools.com

1. Claude Code llama a query_context con una pregunta en lenguaje natural
2. El servidor busca fragmentos relevantes en ChromaDB por similitud semantica
3. Los fragmentos se envian a DeepSeek Flash para comprimir y filtrar
4. Claude Code recibe solo lo relevante — menos tokens, mismo contexto util
5. Cada operacion queda registrada en PostgreSQL con tokens y costo

Tools MCP

Stack

Instalacion

git clone https://github.com/Mickaell22/mcp-context-server
cd mcp-context-server/server

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Copia .env.example a .env y completa las variables:

cp .env.example .env

Aplica el schema en tu PostgreSQL de Railway (solo la primera vez):

psql $DATABASE_URL -f ../sql/schema.sql

Levanta el servidor:

.venv/bin/python main.py

Paths en openclaw-server

/home/mickaell/Escritorio/Proyectos MICKAELL/mcp-context-server/
└── server/
    ├── main.py              # Entry point
    ├── tools/                    # Tools MCP
    │   ├── audit_project.py      # Auditoria (llamadas a DeepSeek en paralelo)
    │   ├── describe_project.py   # Reconocimiento: patrones, paleta, interacciones
    │   ├── check_updates.py      # Frescura vs GitHub y vs el indice
    │   ├── query_context.py      # Busqueda semantica
    │   ├── register_project.py
    │   ├── index_project.py
    │   └── ...
    ├── indexer.py            # Indexacion en ChromaDB
    ├── retriever.py          # Recuperacion semantica
    ├── deepseek_client.py    # Cliente DeepSeek Flash
    └── db.py                 # PostgreSQL (Railway)

Configuracion en Claude Code

claude mcp add --scope user mcp-context -- /ruta/a/server/.venv/bin/python /ruta/a/server/main.py

Para verificar que esta corriendo:

claude mcp list

Instalacion como servicio (systemd)

Para que arranque automaticamente en openclaw-server:

# /etc/systemd/system/mcp-context.service
[Unit]
Description=MCP Context Server
After=network.target

[Service]
User=mickaell
WorkingDirectory=/ruta/a/mcp-context-server/server
ExecStart=/ruta/a/server/.venv/bin/python main.py
Restart=on-failure
EnvironmentFile=/ruta/a/server/.env

[Install]
WantedBy=multi-user.target

sudo systemctl enable mcp-context
sudo systemctl start mcp-context

Variables de entorno

Las variables criticas (DEEPSEEK_API_KEY, DATABASE_URL, PROJECTS_BASE_PATH, CHROMA_PERSIST_PATH) son validadas al arrancar el servidor: si falta alguna, el proceso falla con un RuntimeError que indica exactamente cual variable falta.

Mantener el server al dia en varios equipos

Cada equipo corre su propia copia del server desde su clon del repo. Cuando subis un cambio desde una maquina, las demas no se enteran solas — para eso esta check_server_version:

• El aviso llega solo: al arrancar, y despues como mucho cada 6 horas, el server compara su commit con el remoto. Si hay version nueva, list_projects incluye un bloque server_update con cuantos commits faltan y de que son. Como list_projects es la primera llamada al entrar a un proyecto, el aviso aparece sin pedirlo.
• Para actualizar: check_server_version(update=true) hace el git pull --ff-only y reinstala dependencias si el commit toco requirements.txt. Despues reinicia Claude Code — el proceso en marcha sigue ejecutando el codigo que ya tenia en memoria.
• El repo del server se localiza por la ruta del propio self_update.py, no por la base de datos: funciona aunque el server no este registrado como proyecto indexado en ese equipo.
• Si el repo tiene cambios sin commitear, no se hace pull (no se pisa trabajo en curso). Si el pip install falla, avisa de no reiniciar hasta resolverlo: arrancar con dependencias a medias te deja sin MCP justo cuando lo necesitas para diagnosticar.

Recorda que un cambio en db.py afecta a la Postgres compartida: conviene actualizar todos los equipos, porque uno con la version vieja puede pisar datos del nuevo.

Multi-dispositivo (misma Postgres, varios equipos)

Como varios equipos comparten la misma base en Railway pero tienen los repos en rutas distintas, cada proyecto guarda una ruta por dispositivo en la columna projects.device_paths ({device_id: path}). La columna path legacy queda como fallback.

• Define DEVICE_ID distinto en el .env de cada equipo (ej. desktop, laptop).
• Al arrancar, el server aplica la migracion (idempotente) y adopta para este dispositivo las rutas legacy que existan en su disco (claim_local_paths).
• register_project sobre un proyecto ya registrado en otro equipo no lo pisa: solo agrega la ruta local de este dispositivo.
• list_projects devuelve la ruta de este dispositivo y un flag on_this_device; si es false, registra el proyecto aca con register_project apuntando a su ruta local.
• El estado de indexado tambien es por dispositivo (indexed_files.device_id, projects.device_indexed_at): los vectores viven en un Chroma local, asi que los hashes del delta indexing describen el indice de UNA maquina. list_projects expone indexed_here y un last_indexed que es el de ESTE equipo (last_indexed_anywhere para el global).
• find_usages es la excepcion: lee file_imports de Postgres, no de Chroma, asi que responde desde cualquier equipo.

Costo estimado DeepSeek Flash

DeepSeek factura por franja horaria: off-peak cuesta la mitad que peak. Las horas peak son 01:00-04:00 y 06:00-10:00 UTC, solo de lunes a viernes (el fin de semana es off-peak todo el dia), que en hora de Ecuador (UTC-5) caen en 20:00-23:00 y 01:00-05:00 — trabajando de dia siempre pagas off-peak. El calculo de costo elige la tarifa segun la hora UTC de cada llamada (deepseek_client._rates()) y cobra aparte la entrada que DeepSeek ya tenia en cache (cache_read_input_tokens). Las seis tarifas son env vars. Precios revisados el 2026-10-09:

Referencia de uso real: 152 llamadas en 26 dias (1.07M input + 161K output) cuestan $0.26 off-peak o $0.51 peak sin contar cache hits.

El ratio input/output es de ~6.7:1, asi que lo que mas pesa es el input. El cache hit es 50x mas barato que el miss y DeepSeek lo aplica solo cuando el inicio del prompt se repite: el audit repite el mismo bloque de instrucciones en cada lote, asi que conviene que ese bloque vaya siempre primero.

Arquitectura multi-maquina

PostgreSQL es compartido en la nube entre todas las maquinas que usen el servidor. ChromaDB es local de cada maquina (CHROMA_PERSIST_PATH).

Consecuencias importantes:

• list_projects muestra completos los proyectos que esta maquina tiene en disco o en su Chroma; indexed_here distingue los que puede consultar. Los registrados solo en otro equipo van como nombres en other_devices (sus rutas de otra maquina no sirven aca y eran la mayor parte de la respuesta).
• query_context, audit_project y get_file solo funcionan para proyectos indexados en esa maquina. Un proyecto que aparece en la lista pero devuelve contexto vacio normalmente fue indexado en otra maquina — no esta corrupto. query_context lo dice explicitamente en un campo warning en vez de devolver un contexto vacio mudo.
• Para usar un proyecto en una nueva maquina, hay que re-indexarlo localmente aunque ya aparezca en la lista: index_project (si el path en Postgres coincide con la ruta local) o register_project (si el path es distinto).
• El delta indexing no confia en el indexado de otro equipo: los hashes se guardan por device_id, asi que el primer index_project(incremental=true) de cada maquina se comporta como un full y reconstruye su Chroma. Antes los hashes eran globales y el incremental respondia "sin cambios" mientras el indice local estaba vacio o viejo — el proyecto quedaba inconsultable ahi sin forma obvia de arreglarlo.
• No usar delete_project para limpiar proyectos de otra maquina: borra la fila de PostgreSQL compartido y rompe el indice en todas las maquinas que lo usen. delete_project es irreversible y afecta a todos.

Re-indexar por script (sin iniciar el servidor)

Si se llama indexer.index_project() directamente desde un script, la whitelist en memoria esta vacia y is_file_allowed() rechaza todos los archivos — se indexan 0 archivos mientras el modo full borra los chunks previos. Hay que poblar la whitelist antes:

import security, indexer
security.add_allowed_path("/ruta/al/proyecto")
indexer.index_project(project_id, "/ruta/al/proyecto")

Tests y evaluación

Dos capas, separadas a propósito:

Capa 1 — recall de retrieval (determinista, gratis, CI-able). tests/test_retrieval_recall.py indexa las fixtures con bugs sembrados (tests/fixtures/fake_backend + fake_frontend) en un ChromaDB efímero y verifica que el archivo de cada bug se recupere con la query de su categoría. No usa DeepSeek ni Postgres; mide chunking + embeddings + reranking. Se salta solo si no hay sentence-transformers.

cd server && ./.venv/bin/python -m pytest tests/ -q

Capa 2 — recall end-to-end del audit (no-determinista, ~centavos). eval/run_eval.py corre el audit completo (con paired_with para el contrato) contra las fixtures y mide cuántos bugs REPORTA de verdad, con un scorecard ✓/✗ por bug. También verifica los must_not_flag: código legítimo (locks, validación de input externo) que NO debe aparecer en los hallazgos — el termómetro de falsos positivos, clave para over-engineering. Usa DeepSeek + Postgres; correr a mano al afinar prompts/modelo/AUDIT_TOP_K, no en CI.

cd server && ./.venv/bin/python eval/run_eval.py

Benchmark de latencia (eval/bench.py). Mide sobre este mismo repo la latencia de una llamada a Postgres, query_context (3 queries fijas: segundos y tokens), list_projects (segundos y tamaño de la respuesta) y un incremental sin cambios. Sirve para comparar ramas: correrlo en cada una (por ejemplo con git worktree) y diffear los JSON. No escribe en queries.

cd server && ./.venv/bin/python eval/bench.py /tmp/bench.json

El golden set vive en tests/fixtures/expected.json (archivo, categoría, keywords, severidad por bug, más must_not_flag para los falsos positivos). Para medir recall hay que tener ground truth, y la única forma confiable es sembrar los bugs uno mismo: por eso las fixtures son sintéticas, no un repo real.

Junto a la Capa 1 corren los tests de las demás piezas, todos offline: test_audit_parallel.py (los lotes se reparten en la pool y se re-agrupan en orden), test_check_updates.py (repos git temporales de verdad para index_stale, y el guardarrail que impide el git pull sobre un repo con cambios sin commitear), test_describe_project.py (extractores deterministas: paleta, manifiestos, estructura, naming) y test_git_client.py. test_device_index.py es la excepción: necesita una Postgres real y solo corre con MCP_TEST_DATABASE_URL exportada.

Seguridad

• Solo opera dentro de rutas explicitamente permitidas (whitelist dinamica desde PostgreSQL)
• Bloquea archivos sensibles: .env, .pem, .key, secrets.json, CLAUDE.md, etc.
• Extensiones indexadas: .py .js .ts .jsx .tsx .java .go .rs .dart .kt .swift .rb .php .c .cpp .h .html .css .scss .md .json .yaml .sql .sh
• No ejecuta ningun comando del sistema — unica excepcion es git clone via GitPython
• No expuesto a internet — acceso local o via Tailscale