ContextVM MCP Bridge

Expone servicios ContextVM (Event Sourcing + FSM + DDD) a LLMs mediante Model Context Protocol sobre Nostr.

🎯 ¿Qué hace este Bridge?

Este bridge actúa como traductor bidireccional entre:

• MCP (Model Context Protocol): Protocolo estándar para que LLMs interactúen con servicios externos
• ContextVM: Nuestra arquitectura de Event Sourcing + FSM + DDD

LLMs (Claude, GPT, etc.)
    ↓ MCP (kind 25910)
MCP Bridge (Traductor)
    ↓ DVM (kind 5051-6054)
ContextVM Services (sin cambios)

✨ Características

• ✅ No invasivo: Los ContextVMs existentes no se modifican
• ✅ Nostr como BUS: Un solo relay para MCP y DVM
• ✅ Bidireccional: Traduce peticiones y respuestas
• ✅ Configurable: Mapeos externos en JSON
• ✅ Observable: Logs detallados y métricas
• ✅ Production-ready: Docker, health checks, error handling

🚀 Quick Start

1. Instalación

# Clonar repositorio
git clone https://github.com/your-org/contextvm-mcp-bridge.git
cd contextvm-mcp-bridge

# Instalar dependencias
npm install

# Configurar
cp .env.example .env
# Editar .env con tu configuración

2. Generar Keypair

# Generar nueva keypair para el bridge
npx tsx scripts/generate-keypair.ts

# Copiar el private key a .env
# BRIDGE_PRIVATE_KEY=<hex-key>

3. Configurar Contextos

Editar config/contexts.json con los ContextVMs disponibles:

{
  "contexts": [
    {
      "id": "cbz_tesoreria_pagos",
      "name": "CBZ Tesorería - Pagos Ejecutados",
      "namespace": "cbz-tesoreria-pagos-ejecutados",
      "jobRequestKind": 5053,
      "jobResultKind": 6053,
      "rootEntity": {
        "type": "pago-tesoreria",
        "initialState": "planificado",
        "schema": { ... },
        "transitions": [ ... ]
      }
    }
  ]
}

4. Ejecutar

# Modo desarrollo
npm run dev

# Modo producción
npm run build
npm start

# Con Docker
docker-compose up -d

📋 Uso para LLMs

Conectar desde Claude/GPT

import { NostrMCPProxy } from '@contextvm/sdk/proxy';

// Crear proxy MCP
const proxy = new NostrMCPProxy({
  privateKey: "llm-private-key-hex",
  relays: ["wss://relay.controller-ai.com"],
  serverPubkey: "bridge-public-key-hex"
});

await proxy.start();

// Listar herramientas disponibles
const tools = await proxy.request({
  method: "tools/list"
});

// Llamar herramienta
const result = await proxy.request({
  method: "tools/call",
  params: {
    name: "cbz_tesoreria_pagos_create",
    arguments: {
      importe: 1500.00,
      concepto: "Pago nómina",
      beneficiario: "Juan Pérez"
    }
  }
});

🏗️ Arquitectura

src/
├── core/
│   ├── bridge.ts              # Clase principal del bridge
│   ├── translator.ts          # MCP ↔ DVM translator
│   └── routing.ts             # Routing logic
├── mcp/
│   ├── mcp-listener.ts        # Escucha kind 25910
│   ├── mcp-publisher.ts       # Publica kind 25910
│   └── mcp-types.ts           # Tipos MCP
├── dvm/
│   ├── dvm-listener.ts        # Escucha kind 5051-6054
│   ├── dvm-publisher.ts       # Publica kind 5051-6054
│   └── dvm-types.ts           # Tipos DVM
├── mapping/
│   ├── capabilities.ts        # Mapeo de capabilities
│   ├── schemas.ts             # Schemas de validación
│   └── contexts.ts            # Contextos disponibles
├── config/
│   └── index.ts               # Configuración
└── index.ts                   # Entry point

🔧 Configuración Avanzada

Mapeo de Contextos

Ver docs/context-mapping.md para detalles sobre cómo mapear ContextVMs a MCP tools.

Queries sin Eventos

Para consultas de solo lectura, el bridge puede consultar directamente la API/PostgreSQL sin generar eventos DVM:

// En config/contexts.json
{
  "queries": {
    "enabled": true,
    "apiEndpoint": "https://api.cbz-tesoreria.controller-ai.com",
    "cacheEnabled": true,
    "cacheTTL": 300
  }
}

📊 Monitoring

Health Check

curl http://localhost:4000/health

# Response:
{
  "status": "healthy",
  "uptime": 3600,
  "relay": "connected",
  "contexts": 4,
  "requests": {
    "total": 1234,
    "success": 1200,
    "errors": 34
  }
}

Métricas

El bridge expone métricas en formato Prometheus:

curl http://localhost:4000/metrics

🧪 Testing

# Tests unitarios
npm test

# Tests con watch
npm run test:watch

# Tests de integración (requiere relay activo)
npm run test:integration

🐳 Docker

Build

docker build -t contextvm-mcp-bridge:latest .

Run

docker run -d \
  --name mcp-bridge \
  -p 4000:4000 \
  -e BRIDGE_PRIVATE_KEY=your-key \
  -e RELAY_URL=ws://relay:8080 \
  contextvm-mcp-bridge:latest

Docker Compose

docker-compose up -d

📖 Documentación

• Arquitectura completa
• Análisis de integración
• Context Mapping Guide
• API Reference

🤝 Contribuir

1. Fork el repositorio
2. Crear feature branch (git checkout -b feature/amazing-feature)
3. Commit cambios (git commit -m 'Add amazing feature')
4. Push al branch (git push origin feature/amazing-feature)
5. Abrir Pull Request

📄 Licencia

MIT License - ver LICENSE

🔗 Links

• ContextVM Docs: https://contextvm.org
• MCP Protocol: https://modelcontextprotocol.io
• Nostr Protocol: https://nostr.com
• GitHub: https://github.com/your-org/contextvm-mcp-bridge

---

Última actualización: 23 de diciembre de 2025