Servidor MCP de Directrices Glanser

Búsqueda semántica sobre el corpus de directrices de codificación del equipo. Desarrollado con FastMCP + ChromaDB + sentence-transformers (all-MiniLM-L6-v2). 100% gratuito: sin claves API, sin servicios externos, funciona totalmente offline tras la configuración.

Estructura de carpetas

mcp-server/
├── server.py          ← MCP server (run this on the host)
├── ingest.py          ← One-time ingestion script
├── requirements.txt   ← Python dependencies
├── documents/         ← Drop your .md guideline files here
│   └── CODING_GUIDELINES.md
└── chroma_db/         ← Created automatically by ingest.py (do not edit)

Configuración (ejecutar una vez en la máquina host)

1. Instalar dependencias

pip install -r requirements.txt

sentence-transformers descargará el modelo all-MiniLM-L6-v2 (~80 MB) en la primera ejecución y lo almacenará en caché. Las ejecuciones posteriores son totalmente offline.

2. Añadir tus documentos

Copia los archivos markdown en la carpeta documents/:

cp /path/to/CODING_GUIDELINES.md documents/

3. Ingesta (incrustar una vez, guardado en disco)

python ingest.py

Esto lee cada archivo .md en documents/, incrusta cada sección y persiste los vectores en chroma_db/. Solo vuelves a ejecutar esto cuando añades un nuevo documento.

Flags útiles:

python ingest.py --file documents/NEW_DOC.md   # add a single new doc
python ingest.py --reset                        # wipe and re-ingest everything
python ingest.py --list                         # see what is currently indexed

4. Iniciar el servidor

python server.py

El servidor se inicia en http://0.0.0.0:8000.

Alojamiento (acceso del equipo)

Despliega en Railway o Render (ambos tienen niveles gratuitos):

1. Envía esta carpeta mcp-server/ a un repositorio git

2. Crea un nuevo servicio apuntando a ese repositorio

3. Establece el comando de inicio: python server.py

4. Monta un volumen persistente en /app/chroma_db (para que las incrustaciones sobrevivan a los despliegues)

5. Ejecuta python ingest.py una vez a través de la consola del host después del despliegue

Railway/Render proporcionan automáticamente una URL HTTPS como: https://glanser-guidelines-mcp.railway.app

Entrada .mcp.json del equipo

Cada miembro del equipo añade esto a su .mcp.json:

{
  "mcpServers": {
    "coding-guidelines": {
      "type": "http",
      "url": "https://your-hosted-domain.com/mcp"
    }
  }
}

Herramientas disponibles

Añadir un nuevo documento

# 1. Copy the new doc
cp NEW_GUIDELINES.md documents/

# 2. Ingest only the new file (does not re-embed existing docs)
python ingest.py --file documents/NEW_GUIDELINES.md

# 3. No server restart needed — ChromaDB is queried live

Desarrollo local / pruebas (sin alojamiento)

{
  "mcpServers": {
    "coding-guidelines": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}