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

```json
{
  "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)

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

### 7.2 Opción B: Como paquete pip

```bash
pip install mcp-server-tzzr
mcp-server-tzzr
```

### 7.3 Opción C: Docker

```dockerfile
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)
- [x] Tools GRACE básicos
- [x] Recursos HST
- [x] Prompts predefinidos
- [x] 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](https://spec.modelcontextprotocol.io)
- [S-CONTRACT v2.1](gitea://tzzr/contratos-comunes)
- [GRACE Modules](gitea://tzzr/grace)
- [HST System](gitea://tzzr/hst)