system-docs/05_INTEGRACIONES/SPEC_MCP.md

MCP Server TZZR - Especificación Técnica

Versión: 1.0.0
Fecha: 2026-01-04
Estado: Listo para implementación

---

1. Visión General

1.1 Propósito

El MCP Server TZZR actúa como puente entre el ecosistema MCP (clientes como Claude Desktop, Cursor, etc.) y los servicios internos TZZR que utilizan S-CONTRACT v2.1.

┌────────────────────┐
│  Clientes MCP      │
│  (Claude Desktop)  │
└─────────┬──────────┘
          │ MCP Protocol
          ▼
┌────────────────────┐
│  MCP Server TZZR   │  ◄── Este componente
└─────────┬──────────┘
          │ S-CONTRACT v2.1
          ▼
┌────────────────────┐
│  Servicios TZZR    │
│  (GRACE, HST, etc) │
└────────────────────┘

1.2 Beneficios

Sin MCP Server	Con MCP Server
Acceso solo vía API REST	Acceso desde cualquier cliente MCP
Integración manual por servicio	Integración automática estandarizada
Solo desarrolladores	Usuarios finales vía Claude Desktop
Contexto manual	Recursos y prompts predefinidos

---

2. Arquitectura

2.1 Componentes

mcp-server-tzzr/
├── src/
│   ├── __init__.py
│   └── server.py          # Servidor principal
│       ├── SContractBuilder   # Constructor S-CONTRACT
│       ├── GraceClient        # Cliente RunPod/GRACE
│       ├── HSTClient          # Cliente Directus/HST
│       ├── Tools              # 12 herramientas MCP
│       ├── Resources          # 5+ recursos estáticos
│       └── Prompts            # 3 plantillas
├── tests/
├── pyproject.toml
└── README.md

2.2 Flujo de Datos

1. Cliente MCP llama tool "clasificar" con {texto: "..."}
                    │
                    ▼
2. MCP Server recibe la llamada
                    │
                    ▼
3. SContractBuilder genera S-CONTRACT v2.1:
   {
     "contract_version": "2.1",
     "routing": {"module": "CLASSIFIER"},
     "payload": {"content": "..."}
   }
                    │
                    ▼
4. GraceClient envía a RunPod endpoint
                    │
                    ▼
5. GRACE procesa y devuelve resultado
                    │
                    ▼
6. MCP Server parsea respuesta y devuelve TextContent
                    │
                    ▼
7. Cliente MCP recibe resultado formateado

---

3. Mapeo MCP ↔ S-CONTRACT

3.1 Tools → Módulos GRACE

Tool MCP	Módulo S-CONTRACT	Familia
clasificar	CLASSIFIER	Semántica
resumir	SUMMARIZER	Semántica
ocr	OCR_CORE	Visión
transcribir	ASR_ENGINE	Voz
traducir	TRANSLATOR	Semántica
extraer_campos	FIELD_EXTRACTOR	Utilidades
embeddings	EMBEDDINGS	Semántica
detectar_idioma	LANG_DETECT	Utilidades
generar_hash	HASHER	Utilidades

3.2 Traducción de Parámetros

Ejemplo: Tool clasificar

MCP Input:
{
  "texto": "Factura de servicios...",
  "idioma": "es"
}

S-CONTRACT Output:
{
  "contract_version": "2.1",
  "profile": "LITE",
  "envelope": {
    "trace_id": "uuid",
    "idempotency_key": "sha256",
    "timestamp": "ISO8601"
  },
  "routing": {
    "module": "CLASSIFIER",
    "version": "1.0"
  },
  "context": {
    "lang": "es",
    "mode": "strict"
  },
  "payload": {
    "type": "text",
    "encoding": "utf-8",
    "content": "Factura de servicios..."
  }
}

3.3 Cadenas de Fallback

Algunos módulos tienen fallback automático:

Módulo	Fallback Chain
OCR_CORE	OCR_LOCAL → OCR_GROQ → OCR_OPENAI
ASR_ENGINE	ASR_WHISPER_LOCAL → ASR_FASTER_WHISPER → ASR_GROQ

---

4. Recursos MCP

4.1 Recursos Estáticos

URI	Fuente	Descripción
tzzr://hst/tags/hst	Directus	639 tags base
tzzr://hst/tags/spe	Directus	145 tags iluminación
tzzr://hst/tags/flg	Directus	65 países
tzzr://grace/modules	Hardcoded	Catálogo 18 módulos
tzzr://servers/status	Config	Estado servidores

4.2 Templates Dinámicos

Template	Parámetro	Uso
tzzr://hst/tag/{ref}	ref	Tag individual
tzzr://context/{agent_id}	agent_id	Contexto de agente

---

5. Prompts MCP

5.1 analizar_factura

Propósito: Extracción estructurada de datos de factura

Argumentos:

• texto_factura (required): Texto de la factura

Campos extraídos:

• CIF/NIF emisor y receptor
• Número y fechas
• Base imponible, IVA, total
• IBAN
• Líneas de factura

5.2 clasificar_documento

Propósito: Clasificación y asignación de tags

Argumentos:

• contenido (required): Texto del documento
• contexto (optional): Contexto adicional

Output:

• Categoría principal
• Tags HST sugeridos
• Nivel de confidencialidad
• Resumen breve

5.3 resumir_reunion

Propósito: Extracción de información de reuniones

Argumentos:

• transcripcion (required): Transcripción de la reunión

Output:

• Participantes
• Temas tratados
• Decisiones
• Tareas asignadas
• Próximos pasos

---

6. Configuración

6.1 Variables de Entorno

Variable	Requerida	Descripción
RUNPOD_API_KEY	Sí	API key para GRACE
HST_TOKEN	Sí	Token Directus HST
GRACE_ENDPOINT_ID	No	Override endpoint GRACE
LOG_LEVEL	No	DEBUG/INFO/WARNING/ERROR

6.2 Configuración Claude Desktop

{
  "mcpServers": {
    "tzzr": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/opt/mcp-server-tzzr",
      "env": {
        "RUNPOD_API_KEY": "...",
        "HST_TOKEN": "..."
      }
    }
  }
}

---

7. Despliegue

7.1 Opción A: Local (desarrollo)

cd /opt/mcp-server-tzzr
python -m src.server

7.2 Opción B: Como paquete pip

pip install mcp-server-tzzr
mcp-server-tzzr

7.3 Opción C: Docker

FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install -e .
CMD ["python", "-m", "src.server"]

---

8. Integración con Sistema TZZR

8.1 Posición en la Arquitectura

                    ┌─────────────────┐
                    │  Claude Desktop │
                    │    (Usuario)    │
                    └────────┬────────┘
                             │ MCP
                    ┌────────▼────────┐
                    │  MCP Server     │
                    │     TZZR        │
                    └────────┬────────┘
                             │ S-CONTRACT
        ┌────────────────────┼────────────────────┐
        │                    │                    │
┌───────▼───────┐   ┌────────▼────────┐   ┌──────▼──────┐
│    GRACE      │   │      HST        │   │   Context   │
│   (RunPod)    │   │   (Directus)    │   │   Manager   │
└───────────────┘   └─────────────────┘   └─────────────┘

8.2 Servicios Conectados

Servicio	Protocolo	Puerto	Función
GRACE	HTTPS/RunPod	-	Procesamiento cognitivo
HST Directus	HTTPS	8055	Tags semánticos
Context Manager	HTTPS	5500	Orquestación (futuro)

---

9. Roadmap

v1.0 (actual)

• Tools GRACE básicos
• Recursos HST
• Prompts predefinidos
• Traducción S-CONTRACT

v1.1 (planificado)

• Integración FELDMAN (validación Merkle)
• Integración NOTARIO (sellado blockchain)
• Caché de respuestas frecuentes

v1.2 (futuro)

• Streaming para respuestas largas
• Context Manager integration
• Métricas Prometheus

---

10. Referencias

• MCP Specification
• S-CONTRACT v2.1
• GRACE Modules
• HST System