Add missing files from R2 skynet v10
- 00_VISION/MARCO_TEMPORAL.md - Marco conceptual temporal - 01_ARQUITECTURA/aplicaciones/09_APLICACIONES.md - Aplicaciones TZZR - 03_MODELO_DATOS/hst_standards_all.json - Tags HST JSON - 03_MODELO_DATOS/procesos_productivos.md - Procesos productivos - 05_INTEGRACIONES/README_MCP.md - MCP Server README - 05_INTEGRACIONES/SPEC_MCP.md - MCP Especificación técnica - 99_ANEXOS/ANEXO_1_REFERENCIA_TECNICA.md - Referencia técnica
This commit is contained in:
ARCHITECT
274
05_INTEGRACIONES/README_MCP.md
Normal file
274
05_INTEGRACIONES/README_MCP.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user