Skip to main content
Glama
machette-tech

ContextVM MCP Bridge

by machette-tech
OverviewSchemaRelated ServersScoreDiscussions
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

  • 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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/machette-tech/contextvm-mcp-bridge'

If you have feedback or need assistance with the MCP directory API, please join our Discord server