comind-mcp

Repositorio: https://github.com/comind-pro/comind-mcp

Puerta de enlace MCP — conecta varios servidores MCP y APIs REST, permite seleccionar y combinar herramientas, organizarlas en grupos (cada uno = un servidor MCP virtual separado con un único endpoint) y distribuirlas a los agentes. Un agente solo ve el conjunto limitado de herramientas que se le asignan y puede programar sus propios cron a través de MCP.

Autoalojado: un único servicio Node + Postgres. Multiusuario con aislamiento por cuenta.

Source (mcp │ openapi │ http) ──import──▶ Tool (native │ composite, curated)
                                              │
Group = virtual MCP ◀──toolset[]──────────────┘   + built-in self-cron tools
   └─▶  /g/:groupId/mcp   (Streamable HTTP, single endpoint)
            └─▶ Agent (Bearer key) — only granted V-MCPs, schedules itself
Vault (${secret.X}) · Scheduler · CallLog / Metrics

Inicio rápido

Requisitos: Node 20+, pnpm 9 (corepack enable), Docker (Postgres local).

make setup        # install deps, start Postgres, apply migrations
make dev          # Postgres + server :8787 + web :5173

• Interfaz web — http://localhost:5173 (registrar una cuenta, luego iniciar sesión)

• Puerta de enlace + API de control — http://localhost:8787 (GET /healthz)

• Postgres — se ejecuta en Docker (docker compose); el .env del repositorio asigna el puerto del host 5434

Consulte make help para todos los objetivos. Los scripts subyacentes de pnpm (pnpm dev, pnpm dev:server, pnpm dev:web) siguen funcionando pero no gestionan el contenedor de Postgres.

Modos de base de datos

El almacén se selecciona mediante el esquema de DATABASE_URL — mismo esquema, mismas migraciones:

PGlite es Postgres (WASM), por lo que todo (jsonb, percentile_cont, migraciones) funciona sin cambios — sin proceso de base de datos externo. Persistencia: el directorio file: es un directorio de datos real de Postgres; móntelo como un volumen (p. ej., /data) para conservar los datos entre versiones. Las migraciones son aditivas e idempotentes, por lo que una actualización nunca borra los datos existentes. El modo integrado es de un solo nodo (sin multi-instancia — un escritor).

# zero-infra: no Docker/Postgres needed
DATABASE_URL=file:/data/comind SERVER_ENV=dev pnpm --filter comind-server start

Related MCP server: Figma MCP Server

Escenario integral

1. Fuentes → añadir una fuente (proxy MCP, OpenAPI o HTTP) → Probar → Importar herramientas.

2. Herramientas → renombrar / ocultar las innecesarias / ensamblar una compuesta (una herramienta de intención a partir de varias llamadas).

3. Grupos → crear un grupo → marcar el conjunto de herramientas (casillas de verificación) → (opcional) añadir una programación.

4. Agentes → crear un agente en el grupo → obtener una clave API (una vez) + endpoint MCP.

5. Conectar cualquier cliente MCP a http://localhost:8787/g/<groupId>/mcp con Authorization: Bearer <key>. El cliente solo ve el conjunto de herramientas del grupo (+ herramientas de autocron).

6. Registros → llamadas, métricas, errores.

Conceptos

API (Plano de control, REST en :8787)

GET  /healthz
# sources
POST/GET /sources          GET/PATCH/DELETE /sources/:id
POST /sources/:id/test     POST /sources/:id/import
# tools
GET /tools  (?sourceId&kind&visible)   GET/PATCH/DELETE /tools/:id
# composites
POST/GET /composite-tools  GET/DELETE /composite-tools/:id   POST /composite-tools/:id/run
# python tools (gated — see "Python tools")
POST /python-tools         GET/PATCH/DELETE /python-tools/:id
POST /python-tools/test    POST /python-tools/:id/run
GET  /features
# groups
POST/GET /groups           GET/PATCH/DELETE /groups/:id
GET/PUT /groups/:id/tools
# agents
POST/GET /agents           GET/DELETE /agents/:id            POST /agents/:id/rotate-key
# schedules
POST/GET /groups/:id/schedules    DELETE /schedules/:id
POST /schedules/:id/run           GET /schedules/:id/runs
# secrets (metadata only; value/ciphertext is NEVER returned)
POST/GET /secrets          DELETE /secrets/:id
# observability
GET /logs (?groupId&agentId&toolName&status&limit)   GET /metrics
GET /agents/:id/inspect    POST /agents/:id/invoke

Puerta de enlace (para agentes, MCP)

POST /a/mcp            — agent-wide endpoint: union of tools across the agent's groups
POST /g/:groupId/mcp   — Streamable HTTP endpoint (Authorization: Bearer <agent-key>)

Transporte SSE — planificado.

Conectar desde Claude / ChatGPT (web): guía paso a paso con capturas de pantalla — docs/connect.md.

Herramientas Python

Una herramienta cuyo cuerpo es Python. Útil cuando el motor compuesto se queda sin camino: bucles, aritmética, análisis, convertir muchas llamadas en una tabla.

rows = []
for tok in args["tokens"]:
    book = await call("market.get_order_book", {"token_id": tok})   # any tool you own
    if book["is_error"]:
        continue
    rows.append(book["structured"])

output = {"count": len(rows), "rows": rows}

• En alcance: args (la entrada de la herramienta), await call(name, args) → {"text", "structured", "is_error"}, y steps cuando el código es un paso dentro de una compuesta ({"id": "x", "python": "..."}).

• El resultado es lo que sea que asigne a output. Si el script define main, se llama a main(args) en su lugar (síncrono o asíncrono). Si no hay ninguno → un error explícito, nunca un resultado vacío silencioso.

• Un return de nivel superior es un SyntaxError de Python y mata todo el script — asigne a output, o envuelva la lógica en def main(args).

• print() se captura y se muestra en el editor de herramientas.

Entorno aislado. Pyodide (CPython → WASM) en un hilo de trabajo: sin red, sin sistema de archivos, sin process. Los módulos de red de Node están bloqueados en el hilo de trabajo antes de que se cargue Pyodide, por lo que los sockets de Python también fallan — la única forma de salir de un script es call(...), que pasa por el tiempo de ejecución normal de la herramienta (autenticación, protección SSRF, registro de llamadas). Un script descontrolado se elimina terminando el hilo de trabajo.

Costo. Un hilo de trabajo por nivel de anidamiento, iniciado de forma diferida y mantenido caliente: primera ejecución después del inicio ≈ 1s, ejecuciones posteriores ≈ 10ms. Las ejecuciones en el mismo nivel se serializan, por lo que un script largo retrasa otras herramientas python (las herramientas nativas/virtuales no se ven afectadas). Una herramienta python que llama a una herramienta python que llama a una herramienta python es el límite — se rechaza un anidamiento más profundo.

Desactivada por defecto. Establezca PYTHON_TOOLS=1 (abre la función para cada cuenta en la instancia — desarrollo local / autoalojamiento de un solo usuario), o concédala por usuario:

INSERT INTO user_features (id, user_id, feature, enabled)
VALUES (gen_random_uuid()::text, '<user-id>', 'python_tools', true);

Revocar la fila también detiene las herramientas existentes — la ACL se vuelve a comprobar en cada llamada, no solo en el momento de la creación. Ajuste: PYTHON_TOOL_TIMEOUT_MS (30000), PYTHON_TOOL_MAX_CALLS (100), PYTHON_TOOL_MAX_CODE_BYTES (65536).

Estructura

Detalles de desarrollo — DEVELOPMENT.md.

Seguridad

• Los secretos se cifran en reposo (AES-256-GCM); el agente/configuración solo ve el marcador de posición ${secret.NAME}, el valor se sustituye en tiempo de ejecución.

• Un agente solo obtiene el conjunto de herramientas de su grupo; las llamadas están controladas por el conjunto de herramientas en cada solicitud.

• Las claves API se almacenan como un hash sha256, el token se muestra una vez.

• Una falla de un ascendente no derriba el endpoint (aislamiento de fallos en el tiempo de ejecución).

Módulos y características

Construido de forma iterativa, módulo por módulo. Todo lo siguiente está implementado y funcionando.

Puerta de enlace principal

• ✅ Conectores — proxy de un servidor MCP existente, importar una API REST desde OpenAPI 3.x (analizador propio → herramientas), o conectar un servicio HTTP con endpoints explícitos.

• ✅ Registro y selección de herramientas — importar herramientas, renombrar, editar descripciones, alternar visibilidad, nombres únicos por propietario.

• ✅ Motor compuesto — herramientas de intención que ejecutan varias llamadas en secuencia; when condicional; plantillas ($.input.*, $.steps.ID.text); plantilla de salida; traza por paso para ajuste.

• ✅ Tiempo de ejecución compartido (invokeTool) — un despachador para puerta de enlace, compuestos y programador; nativo→conector, compuesto→recursión (limitada por profundidad); aislamiento de fallos (un ascendente defectuoso nunca bloquea al llamante).

• ✅ Grupos = MCP virtual — agrupar herramientas seleccionadas en un único endpoint MCP /g/:groupId/mcp (HTTP transmisible).

• ✅ Agentes — identidades de consumidor con una clave API (hash sha256, mostrada una vez) + rotación de claves.

• ✅ Concesiones Agente ↔ V-MCP (M2M) — conceder/revocar acceso por grupo; un agente puede alcanzar muchos endpoints de grupo; la clave solo funciona para los grupos concedidos.

Programación

• ✅ Scheduler — registro cron (node-cron), registro de ejecución de trabajos, ejecución ahora, cargado al inicio.

• ✅ Auto-cron vía MCP — herramientas integradas schedule_task / list_schedules / cancel_schedule dentro de un grupo; un agente conectado se auto-programa.

Secretos y autenticación hacia fuentes externas

• ✅ Vault — credenciales cifradas en reposo (AES-256-GCM); inyectadas en tiempo de ejecución mediante ${secret.NOMBRE}; agentes/configuración nunca ven el valor.

• ✅ Secretos con ámbito por fuente — el mismo nombre puede existir por fuente; el ámbito por fuente anula el ámbito global.

• ✅ Autenticación estática — encabezados bearer/api-key/personalizados, básico (usuario/contraseña).

• ✅ Flujos de token dinámicos — oauth2_client_credentials, token_request (inicio de sesión→ruta JSON), oauth2_refresh (en caché + actualización automática).

• ✅ OAuth de usuario — oauth2_authorization_code (flujo de conexión) y OAuth nativo de MCP (mcp_oauth: descubrimiento SDK + DCR + PKCE + actualización, con clientId opcional previamente registrado).

Cuentas y aislamiento

• ✅ Autenticación — correo electrónico/contraseña (scrypt) + sesiones JWT HS256; registro / inicio de sesión / perfil.

• ✅ Aislamiento multiusuario — cada recurso pertenece a un usuario; todas las rutas limitadas por propietario; las herramientas se resuelven solo dentro del espacio de nombres del propietario. Sin acceso entre cuentas.

Observabilidad

• ✅ Registros de llamadas — quién/qué herramienta/estado/duración/estimación de tokens por invocación.

• ✅ Métricas — totales + por herramienta + por agente.

• ✅ Inspector y prueba de invocación — ver lo que un agente ve por V-MCP concedido; ejecutar cualquier herramienta para ver la respuesta en bruto.

Interfaz web (Vite + React)

• ✅ Autenticación — inicio de sesión / registro, bloqueo por token, cierre de sesión.

• ✅ Constructores de formulario ⟷ JSON para fuentes y compuestos (editar un formulario o el JSON en bruto, bidireccional).

• ✅ Secretos en línea en el asistente de fuentes (con ámbito para la fuente).

• ✅ Selector y registro de herramientas agrupado, plegable y buscable (se adapta a APIs importadas grandes).

• ✅ Fragmentos de conexión por V-MCP (claude mcp add …, curl) con botones de copia.

• ✅ Pestañas: Fuentes · Herramientas · V-MCP · Agentes · Secretos · Registros.

Infraestructura

• ✅ Postgres vía Drizzle (migraciones aplicadas automáticamente al inicio).

• ✅ Docker Compose para Postgres local + Makefile (make setup / make dev / make db-*).

• ✅ Carga de .env, secretos de desarrollo generados.

Aún no (opcional, próximo)

• ⬜ Capa de organización/proyecto (equipos, uso compartido).

• ⬜ Transporte SSE en la puerta de enlace (solo HTTP Streamable hoy).

• ⬜ Notificaciones de recarga en caliente de tools/changed.

• ⬜ Punto final OpenAPI para un conjunto de herramientas; trazas.

Hoja de ruta

• Limitar velocidad /auth (fuerza bruta de contraseña), la puerta de enlace y cuotas por agente.

• Hacer que el programador sea seguro para múltiples réplicas (bloqueo de asesoramiento de Postgres o un trabajador dedicado) — hoy el cron en memoria se ejecuta N veces con N instancias.

• Mover migraciones a un paso de despliegue separado (se ejecutan en cada arranque de instancia → conflicto con múltiples réplicas).

• Revocación de JWT — tokens de acceso de corta duración + tokens de actualización (un token filtrado de 7 días no se puede invalidar; el cierre de sesión es solo local).

• Gestión de secretos — KMS + rotación para VAULT_KEY / JWT_SECRET; restringir CORS (por defecto a *); documentar el proxy inverso TLS.

• Servir la interfaz web para producción (compilar y servir dist detrás de un CDN/proxy; solo Vite dev hoy).

• Paginación en puntos finales de listado (herramientas, registros).

• Reintento/retroceso/alertas del programador.

• Analizador OpenAPI — manejar especificaciones complejas (allOf, $ref profundo).

• Restablecimiento de contraseña / verificación de correo electrónico; registro de auditoría de usuario.

Distribución

Empaquetado como una imagen OCI (ghcr.io/comind-pro/comind-mcp) y listado en el Registro MCP oficial (registry.modelcontextprotocol.io) — la fuente canónica que consumen los catálogos descendentes (PulseMCP, Smithery, Docker Hub, …). Los metadatos residen en server.json bajo el espacio de nombres verificado por GitHub io.github.comind-pro/comind-mcp.

Ejecutar la imagen (sin infraestructura, Postgres integrado):

docker run -p 8787:8787 -v comind-data:/data \
  -e SERVER_ENV=dev ghcr.io/comind-pro/comind-mcp:latest
# prod: drop SERVER_ENV=dev and set VAULT_KEY + JWT_SECRET

El lanzamiento es automatizado — impulsar una etiqueta de versión y CI (release.yml) compila y empuja la imagen a GHCR, luego publica server.json al registro vía GitHub OIDC (sin tokens):

git tag v0.2.0 && git push origin v0.2.0

Nota: ComindMCP es una puerta de enlace multiinquilino (HTTP MCP en /g/:slug/mcp, autenticación por clave de agente), no un servidor stdio único — los clientes del registro lo autodespliegan y conectan sus propios agentes.

Contribuir

comind-mcp es de código abierto (MIT) y las contribuciones son bienvenidas — informes de errores, funcionalidades, documentación, pruebas.

1. Haz un fork y crea una rama desde main (feat/..., fix/...).

2. Configura localmente — consulta DEVELOPMENT.md. Resumen: corepack enable && pnpm install, luego pnpm dev.

3. Antes de abrir un PR: pnpm typecheck y pnpm -r test deben pasar.

4. Usa Conventional Commits para los mensajes (feat:, fix:, docs:, chore:).

5. Abre un PR contra comind-pro/comind-mcp con una descripción clara; vincula cualquier problema relacionado.

¿Preguntas o ideas? Abre un issue. Consulta CONTRIBUTING.md para más detalles.

Licencia

MIT © comind — código abierto, libre de usar, modificar y distribuir en cualquier lugar, incluso comercialmente.

Repositorio: https://github.com/comind-pro/comind-mcp