# 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