# 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
```bash
# 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
```bash
# 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:
```json
{
"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
```bash
# 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
```typescript
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](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:
```typescript
// En config/contexts.json
{
"queries": {
"enabled": true,
"apiEndpoint": "https://api.cbz-tesoreria.controller-ai.com",
"cacheEnabled": true,
"cacheTTL": 300
}
}
```
## 📊 Monitoring
### Health Check
```bash
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:
```bash
curl http://localhost:4000/metrics
```
## 🧪 Testing
```bash
# Tests unitarios
npm test
# Tests con watch
npm run test:watch
# Tests de integración (requiere relay activo)
npm run test:integration
```
## 🐳 Docker
### Build
```bash
docker build -t contextvm-mcp-bridge:latest .
```
### Run
```bash
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
```bash
docker-compose up -d
```
## 📖 Documentación
- [Arquitectura completa](../ARQUITECTURA-MCP-BRIDGE.md)
- [Análisis de integración](../ANALISIS-INTEGRACION-CONTEXTVM-OFICIAL.md)
- [Context Mapping Guide](docs/context-mapping.md)
- [API Reference](docs/api-reference.md)
## 🤝 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](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
