tzzr/system-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add missing files from R2 skynet v10

Browse Source 
- 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
2026-01-06 04:59:03 +00:00
parent 386eef4d4b
commit a205cddac0
7 changed files with 30939 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

274
05_INTEGRACIONES/README_MCP.md Normal file
View 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

342
05_INTEGRACIONES/SPEC_MCP.md Normal file
View File

@@ -0,0 +1,342 @@
# 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)