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)

pip install mcp-server-tzzr

Opción 2: Desde código fuente

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:

# 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:

{
  "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

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)

{
  "name": "clasificar",
  "arguments": {
    "texto": "Documento de ejemplo...",
    "idioma": "es"
  }
}

S-CONTRACT generado

{
  "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

pytest tests/ -v

Ejecutar en modo desarrollo

python -m src.server

Verificar con MCP Inspector

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