mcp-server-claude: Instructions file for Claude Code

CLAUDE.md — mcp-server-claude

MCP Memory Server para Claude Code. Proporciona contexto persistente entre sesiones via RAG (ChromaDB + sentence-transformers). Diseñado para el entorno Zurich Insurance GenAI Platform (LiteLLM proxy UAT, WSL2 Ubuntu 24).

Stack

• Framework MCP: FastMCP (Python) — genera JSON schemas automáticamente desde type hints Pydantic v2
• Vector store: ChromaDB (local, sin servidor)
• Relational store: SQLite (metadatos de sesiones)
• Embeddings: sentence-transformers all-MiniLM-L6-v2 (local, ~80MB, ~10ms/embedding)
• Transporte: STDIO — corre como proceso hijo de Claude Code

Estructura

mcp-server-claude/
├── CLAUDE.md
├── README.md
├── requirements.txt
├── .env.example
├── mcp_config.example.json     ← snippet para ~/.claude/settings.json
├── docs/
│   ├── ANALYSIS.md             ← arquitectura, decisiones, investigación
│   └── projects.md             ← inventario de repos gestionados
└── src/
    ├── server.py               ← punto de entrada FastMCP
    ├── memory_store.py         ← abstracción ChromaDB + SQLite
    └── embeddings.py           ← wrapper sentence-transformers

Comandos

# Instalar dependencias
pip install -r requirements.txt

# Correr el server en modo debug (stderr visible)
python src/server.py

# Registrar en Claude Code (copiar snippet de mcp_config.example.json a ~/.claude/settings.json)

Regla crítica de implementación

Nunca escribir a stdout. El transporte STDIO reserva stdout exclusivamente para JSON-RPC 2.0. Todo logging debe ir a sys.stderr:

import sys, logging
logging.basicConfig(stream=sys.stderr, level=logging.INFO)
# NUNCA: print(...)  ← corrompe el protocolo

Variables de entorno

Ver .env.example. Las variables relevantes:

Variable	Descripción
MEMORY_DB_PATH	Ruta al directorio de datos ChromaDB + SQLite (fuera del repo)
EMBEDDING_MODEL	Modelo sentence-transformers a usar
LOG_LEVEL	Nivel de logging (INFO por defecto)