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

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)