convez.ai
MCP Server
Mickaell22

mcp-context-server

Mickaell22/mcp-context-server

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server for Claude Code — semantic codebase indexing with ChromaDB + DeepSeek Flash compression. Context-as-a-Service.

Instalação

$npx convez-ai Mickaell22/mcp-context-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
0
Acompanhando
1
Saúde
28%
Último commit
há 3 dias
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

MCP Context Server

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.


Python MCP DeepSeek ChromaDB PostgreSQL Tailscale


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

ToolParametrosDescripcion
query_contextquery, project (str o list), code_only (bool), top_k (int, opcional)Busqueda semantica con compresion DeepSeek. Soporta multi-proyecto. top_k por defecto 8; subelo en proyectos grandes.
index_projectproject, incremental (bool), acknowledge_drift (bool)Re-indexa un proyecto existente por nombre. Antes de indexar verifica drift git (local detras del remoto o con cambios sin commitear); si lo detecta devuelve needs_confirmation y no indexa hasta reintentar con acknowledge_drift=true.
list_projects—Lista todos los proyectos registrados en la BD.
clone_projectrepo_urlClona un repo de GitHub e indexa en un solo paso.
register_projectpath, name (opcional)Registra un path local sin clonar e indexa.
get_fileproject, file_pathRetorna el contenido completo de un archivo del indice.
audit_projectproject, categories (opcional), paired_with (opcional), raw (opcional)Auditoria automatica de codigo con hallazgos estructurados (severidad/archivo:linea/fix) + un summary consolidado y rankeado por severidad. raw=true devuelve los chunks crudos numerados sin compresion DeepSeek (coste 0, alta fidelidad). Autodetecta frontend vs backend. Categorias backend: correctness, security, code_quality, error_handling, deprecated, config_secrets, imports, io_operations, tests. Frontend: correctness, accessibility, performance, state_management, seo, component_design, error_handling, deprecated, tests, bundle_size, hydration, theming. Con paired_with=<repo hermano> añade una auditoria de contrato API cross-repo (campos, nullability, tipos y endpoints que no calzan entre front y back). Fallback: si no encuentra patrones via busqueda semantica, analiza los chunks mas relevantes con DeepSeek.
find_usagesproject, symbolBusca que archivos importan un simbolo o modulo especifico.

Stack

CapaTecnologia
ProtocoloMCP SDK (Python)
Embeddingssentence-transformers — all-MiniLM-L6-v2 (CPU)
Vector storeChromaDB con PersistentClient (disco local)
Compresion de contextoDeepSeek Flash via SDK Anthropic
Clonado de reposGitPython
Grafo de importsast (Python) + regex (JS/TS)
Base de datosPostgreSQL en Railway
Acceso remotoTailscale (openclaw-server)
DashboardNext.js en Railway → ia.novamicktools.com

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 con fallback DeepSeek
    │   ├── 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

VariableDescripcion
DEEPSEEK_API_KEYAPI key de DeepSeek
GITHUB_TOKENToken de GitHub (scope: repo) para repos privados
DATABASE_URLPostgreSQL en Railway (URL publica para acceso externo)
PROJECTS_BASE_PATHDirectorio base donde se clonan los repos
CHROMA_PERSIST_PATHDirectorio donde ChromaDB guarda los vectores en disco
LOG_LEVELNivel de log — INFO por defecto
MAX_DISTANCEUmbral de distancia coseno para filtrar chunks (default: 1.2). Con all-MiniLM-L6-v2, queries en lenguaje natural contra codigo suelen dar distancias de 0.6–1.1; valores menores a 1.0 filtran demasiado y devuelven contexto vacio.
DEEPSEEK_TIMEOUTTimeout en segundos para llamadas a DeepSeek (default: 60.0). El SDK Anthropic usa 10 min por defecto, demasiado para una tool MCP — bajarlo evita que query_context/audit_project se cuelguen.
EMBEDDING_MODELModelo SentenceTransformers para embeddings (default: all-MiniLM-L6-v2). Para mejor recall sobre codigo: jinaai/jina-embeddings-v2-base-code o nomic-ai/nomic-embed-text-v1.5. Cambiarlo invalida el indice Chroma (cambia la dimension del vector) y exige reindex full de todos los proyectos.
AUDIT_TOP_KNº de chunks que recupera cada categoria del audit (default: 18). El audit prioriza recall sobre costo; query_context sigue usando TOP_K_RESULTS=8.
RERANK_ENABLEDActiva el reranking híbrido semántico+léxico post-retrieval (default: true). false lo desactiva.
RERANK_CANDIDATE_MULT / RERANK_W_SEM / RERANK_W_LEXTamaño del pool de candidatos (top_k × mult, default 3) y pesos del score (default 0.7 semántico / 0.3 léxico).

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.


Costo estimado DeepSeek Flash

Precio
Input$0.14 / 1M tokens
Output$0.28 / 1M tokens
Query promedio (~5k input, ~1k output)~$0.001
1000 queries al mes~$1.00

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 todos los proyectos registrados desde cualquier maquina.
  • 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.
  • 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).
  • 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. 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

El golden set vive en tests/fixtures/expected.json (archivo, categoría, keywords, severidad por bug). 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.


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
Ver o original no GitHub

Bom para

Relacionados