system-docs/05_INTEGRACIONES/README_MCP.md

# MCP Server TZZR

Servidor MCP (Model Context Protocol) que expone los servicios del sistema TZZR, traduciendo entre el protocolo MCP estándar y S-CONTRACT v2.1.

## Arquitectura

```
┌─────────────────────────────────────────────────────────────────┐
│                     CLIENTE MCP                                  │
│         (Claude Desktop, Cursor, otro cliente MCP)               │
└─────────────────────────────────┬───────────────────────────────┘
                                  │ MCP Protocol (stdio/SSE)
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                    MCP SERVER TZZR                               │
│                                                                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │   TOOLS     │  │  RESOURCES  │  │   PROMPTS   │              │
│  │             │  │             │  │             │              │
│  │ clasificar  │  │ hst://tags  │  │ analizar_   │              │
│  │ resumir     │  │ tzzr://     │  │ factura     │              │
│  │ ocr         │  │ grace://    │  │ clasificar_ │              │
│  │ transcribir │  │             │  │ documento   │              │
│  │ ...         │  │             │  │ ...         │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
│                           │                                      │
│              ┌────────────┴────────────┐                         │
│              │   S-CONTRACT BUILDER    │                         │
│              │      (v2.1)             │                         │
│              └────────────┬────────────┘                         │
└───────────────────────────┼─────────────────────────────────────┘
                            │ S-CONTRACT JSON
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │  GRACE   │  │   HST    │  │ Context  │
        │ (RunPod) │  │(Directus)│  │ Manager  │
        └──────────┘  └──────────┘  └──────────┘
```

## Instalación

### Opción 1: pip (recomendado)

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

### Opción 2: Desde código fuente

```bash
git clone https://gitea.tzzr.me/tzzr/mcp-server-tzzr.git
cd mcp-server-tzzr
pip install -e .
```

## Configuración

### Variables de entorno

Crea un archivo `.env` o configura las siguientes variables:

```bash
# RunPod API Key (para GRACE)
RUNPOD_API_KEY=rpa_XXXXXXXXXXXXXXXXXXXXXXXXXX

# Token de Directus HST
HST_TOKEN=your_directus_token

# (Opcional) Context Manager
CONTEXT_MANAGER_URL=https://captain-claude.tzrtech.org/api/v2
```

### Configuración en Claude Desktop

Añade al archivo `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tzzr": {
      "command": "python",
      "args": ["-m", "mcp_server_tzzr"],
      "env": {
        "RUNPOD_API_KEY": "rpa_XXXXXXX",
        "HST_TOKEN": "your_token"
      }
    }
  }
}
```

Ubicación del archivo:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

## Herramientas Disponibles (Tools)

### GRACE - Procesamiento Cognitivo

| Tool | Descripción | Módulo S-CONTRACT |
|------|-------------|-------------------|
| `clasificar` | Clasifica texto y asigna tags HST | CLASSIFIER |
| `resumir` | Resume textos largos | SUMMARIZER |
| `ocr` | Extrae texto de imágenes | OCR_CORE |
| `transcribir` | Transcribe audio a texto | ASR_ENGINE |
| `traducir` | Traduce entre idiomas | TRANSLATOR |
| `extraer_campos` | Extrae CIF, fechas, importes | FIELD_EXTRACTOR |
| `embeddings` | Genera vectores semánticos | EMBEDDINGS |
| `detectar_idioma` | Detecta idioma de texto | LANG_DETECT |
| `generar_hash` | Genera SHA-256 o UUID | HASHER |

### HST - Sistema de Tags

| Tool | Descripción |
|------|-------------|
| `buscar_tags` | Busca tags por texto |
| `listar_tags` | Lista tags de un grupo (hst, spe, flg, vsn) |

### Sistema

| Tool | Descripción |
|------|-------------|
| `grace_health` | Verifica estado de GRACE en RunPod |

## Recursos Disponibles (Resources)

| URI | Descripción |
|-----|-------------|
| `tzzr://hst/tags/hst` | 639 tags del sistema base |
| `tzzr://hst/tags/spe` | 145 tags de iluminación técnica |
| `tzzr://hst/tags/flg` | 65 banderas/países |
| `tzzr://grace/modules` | Catálogo de 18 módulos GRACE |
| `tzzr://servers/status` | Estado de servidores TZZR |
| `tzzr://hst/tag/{ref}` | Tag individual por referencia |

## Prompts Disponibles

| Prompt | Descripción | Argumentos |
|--------|-------------|------------|
| `analizar_factura` | Extrae campos de factura | `texto_factura` |
| `clasificar_documento` | Clasifica y sugiere tags | `contenido`, `contexto` |
| `resumir_reunion` | Resume transcripción | `transcripcion` |

## Ejemplos de Uso

### Desde Claude Desktop

```
Usuario: Clasifica este documento: "Factura nº 2024-001 de Luminarias S.L..."

Claude: [Ejecuta tool: clasificar]
Resultado:
{
  "categoria": "FINANZAS",
  "confidence": 0.95,
  "tags": ["hst:factura", "spe:luminaria", "hst:proveedor"]
}
```

### Desde código Python

```python
from mcp import ClientSession
from mcp.client.stdio import stdio_client

async with stdio_client(["python", "-m", "mcp_server_tzzr"]) as client:
    async with ClientSession(*client) as session:
        # Llamar a una herramienta
        result = await session.call_tool(
            "clasificar",
            {"texto": "Contrato de servicios de iluminación LED..."}
        )
        print(result)
        
        # Leer un recurso
        tags = await session.read_resource("tzzr://hst/tags/spe")
        print(tags)
```

## Traducción MCP → S-CONTRACT

El servidor traduce automáticamente las llamadas MCP a S-CONTRACT v2.1:

### Entrada MCP (Tool call)
```json
{
  "name": "clasificar",
  "arguments": {
    "texto": "Documento de ejemplo...",
    "idioma": "es"
  }
}
```

### S-CONTRACT generado
```json
{
  "contract_version": "2.1",
  "profile": "LITE",
  "envelope": {
    "trace_id": "550e8400-e29b-41d4-a716-446655440000",
    "idempotency_key": "a1b2c3d4e5f6...",
    "timestamp": "2026-01-04T12:00:00Z"
  },
  "routing": {
    "module": "CLASSIFIER",
    "version": "1.0"
  },
  "context": {
    "lang": "es",
    "mode": "strict"
  },
  "payload": {
    "type": "text",
    "encoding": "utf-8",
    "content": "Documento de ejemplo..."
  }
}
```

## Desarrollo

### Ejecutar tests

```bash
pytest tests/ -v
```

### Ejecutar en modo desarrollo

```bash
python -m src.server
```

### Verificar con MCP Inspector

```bash
npx @modelcontextprotocol/inspector python -m src.server
```

## Estructura del Proyecto

```
mcp-server-tzzr/
├── src/
│   └── server.py          # Servidor MCP principal
├── tests/
│   └── test_server.py     # Tests
├── pyproject.toml         # Configuración del proyecto
├── README.md              # Este archivo
└── .env.example           # Ejemplo de variables de entorno
```

## Servicios TZZR Integrados

| Servicio | Función | Endpoint |
|----------|---------|----------|
| **GRACE** | 18 módulos cognitivos | RunPod Serverless |
| **HST** | Sistema de tags semánticos | Directus API |
| **Context Manager** | Orquestación de contexto | API interna |

## Roadmap

- [ ] Soporte para FELDMAN (validación Merkle)
- [ ] Integración con NOTARIO (sellado blockchain)
- [ ] Streaming para respuestas largas
- [ ] Caché de resultados frecuentes
- [ ] Métricas y observabilidad

## Licencia

MIT License - TZZR Systems 2026