Skip to main content
Glama
machette-tech

ContextVM MCP Bridge

by machette-tech
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

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

🤝 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

Última actualización: 23 de diciembre de 2025

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Resources

Related MCP Connectors