comind-mcp

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

MCP-Gateway – verbindet verschiedene MCP-Server und REST-APIs, ermöglicht das Kuratieren und Kombinieren von Tools, die Organisation in Gruppen (jede = ein separater virtueller MCP-Server mit einem einzigen Endpunkt) und deren Bereitstellung für Agenten. Ein Agent sieht nur die ihm zugewiesene schmale Auswahl an Tools und kann über MCP eigene Cron-Jobs planen.

Selbst gehostet: ein einzelner Node-Dienst + Postgres. Mehrbenutzer-fähig mit Isolation pro Konto.

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

Kurzstart

Voraussetzungen: Node 20+, pnpm 9 (corepack enable), Docker (lokales Postgres).

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

• Web-UI – http://localhost:5173 (Konto registrieren, dann anmelden)

• Gateway + Control-API – http://localhost:8787 (GET /healthz)

• Postgres – läuft in Docker (docker compose); die .env des Repos bildet den Host-Port 5434 ab

Siehe make help für alle Ziele. Die zugrundeliegenden pnpm-Skripte (pnpm dev, pnpm dev:server, pnpm dev:web) funktionieren weiterhin, verwalten aber den Postgres-Container nicht.

Datenbank-Modi

Der Speicher wird durch das Schema von DATABASE_URL ausgewählt – gleiches Schema, gleiche Migrationen:

PGlite ist Postgres (WASM), daher läuft alles (jsonb, percentile_cont, Migrationen) unverändert – kein externer DB-Prozess. Persistenz: Das file:-Verzeichnis ist ein echtes Postgres-Datenverzeichnis; binden Sie es als Volume ein (z.B. /data), um Daten über Releases hinweg zu behalten. Migrationen sind additiv und idempotent, daher löscht ein Upgrade niemals vorhandene Daten. Der eingebettete Modus ist Single-Node (keine Multi-Instanz – ein Schreiber).

# 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

End-to-End-Szenario

1. Quellen → eine Quelle hinzufügen (MCP-Proxy, OpenAPI oder HTTP) → Testen → Tools importieren.

2. Tools → umbenennen / unnötige ausblenden / ein Composite erstellen (ein Intent-Tool aus mehreren Aufrufen).

3. Gruppen → eine Gruppe erstellen → das Toolset markieren (Kontrollkästchen) → (optional) einen Zeitplan hinzufügen.

4. Agenten → einen Agenten in der Gruppe erstellen → einen API-Key (einmalig) + MCP Endpunkt erhalten.

5. Verbinden Sie einen beliebigen MCP-Client mit http://localhost:8787/g/<groupId>/mcp mit Authorization: Bearer <key>. Der Client sieht nur das Toolset der Gruppe (+ Self-Cron-Tools).

6. Protokolle → Aufrufe, Metriken, Fehler.

Konzepte

API (Control Plane, REST auf :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

Gateway (für Agenten, 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>)

SSE-Transport – geplant.

Verbinden von Claude / ChatGPT (Web): Schritt-für-Schritt-Anleitung mit Screenshots – docs/connect.md.

Python-Tools

Ein Tool, dessen Inhalt Python ist. Nützlich, wenn die Composite-Engine nicht mehr ausreicht: Schleifen, Arithmetik, Parsen, Zusammenfassen vieler Aufrufe in einer Tabelle.

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}

• Im Gültigkeitsbereich: args (die Eingabe des Tools), await call(name, args) → {"text", "structured", "is_error"}, und steps, wenn der Code ein Schritt innerhalb eines Composite ist ({"id": "x", "python": "..."}).

• Das Ergebnis ist, was auch immer Sie output zuweisen. Wenn das Skript main definiert, wird stattdessen main(args) aufgerufen (synchron oder asynchron). Wenn keines von beiden → ein expliziter Fehler, niemals ein stilles leeres Ergebnis.

• Ein return auf oberster Ebene ist ein Python SyntaxError und tötet das gesamte Skript – weisen Sie output zu, oder verpacken Sie die Logik in def main(args).

• print() wird erfasst und im Tool-Editor angezeigt.

Sandbox. Pyodide (CPython → WASM) in einem Worker-Thread: kein Netzwerk, kein Dateisystem, kein process. Die Netzwerkmodule von Node werden im Worker blockiert, bevor Pyodide geladen wird, daher schlagen auch Python-Sockets fehl – der einzige Weg aus einem Skript ist call(...), das durch die normale Tool-Laufzeit (Auth, SSRF-Schutz, Aufrufprotokoll) geht. Ein außer Kontrolle geratenes Skript wird durch Beenden des Workers abgebrochen.

Kosten. Ein Worker pro Verschachtelungsebene, träge gestartet und warm gehalten: erster Lauf nach Start ≈ 1s, folgende Läufe ≈ 10ms. Läufe auf derselben Ebene werden serialisiert, daher verzögert ein langes Skript andere Python-Tools (native/virtuelle Tools sind nicht betroffen). Ein Python-Tool, das ein Python-Tool aufruft, das ein Python-Tool aufruft, ist die Grenze – tiefere Verschachtelung wird abgelehnt.

Standardmäßig deaktiviert. Entweder setzen Sie PYTHON_TOOLS=1 (öffnet die Funktion für jedes Konto auf der Instanz – lokale Entwicklung / Single-User-Self-Host), oder gewähren Sie sie pro Benutzer:

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

Das Entfernen der Zeile stoppt auch vorhandene Tools – die ACL wird bei jedem Aufruf erneut überprüft, nicht nur zur Erstellungszeit. Tuning: PYTHON_TOOL_TIMEOUT_MS (30000), PYTHON_TOOL_MAX_CALLS (100), PYTHON_TOOL_MAX_CODE_BYTES (65536).

Struktur

Entwicklungsdetails – DEVELOPMENT.md.

Sicherheit

• Geheimnisse werden im Ruhezustand verschlüsselt (AES-256-GCM); der Agent / die Konfiguration sehen nur den Platzhalter ${secret.NAME}, der Wert wird zur Laufzeit eingesetzt.

• Ein Agent erhält nur das Toolset seiner Gruppe; Aufrufe werden bei jeder Anfrage durch das Toolset abgesichert.

• API-Keys werden als sha256-Hash gespeichert, der Token wird nur einmal angezeigt.

• Ein Ausfall eines Upstreams bringt nicht den Endpunkt zum Absturz (Fehlerisolation in der Laufzeit).

Module & Funktionen

Schrittweise entwickelt, Modul für Modul. Alles unten ist implementiert und funktioniert.

Kern-Gateway

• ✅ Connectors – einen bestehenden MCP-Server als Proxy verwenden, eine REST-API aus OpenAPI 3.x importieren (eigener Parser → Tools) oder einen HTTP-Dienst mit expliziten Endpunkten anbinden.

• ✅ Tool-Registry & Kuratierung – Tools importieren, umbenennen, Beschreibungen bearbeiten, Sichtbarkeit umschalten, eindeutige Namen pro Besitzer.

• ✅ Composite-Engine – Intent-Tools, die mehrere Aufrufe nacheinander ausführen; bedingtes when; Templating ($.input.*, $.steps.ID.text); Ausgabevorlage; Trace pro Schritt zur Optimierung.

• ✅ Gemeinsame Laufzeit (invokeTool) – ein Dispatcher für Gateway, Composites und Scheduler; native→Connector, Composite→Rekursion (tiefenbegrenzt); Fehlerisolation (ein schlechter Upstream bringt den Aufrufer nie zum Absturz).

• ✅ Gruppen = virtuelles MCP – kuratierte Tools in einem einzigen MCP-Endpunkt bündeln /g/:groupId/mcp (Streamable HTTP).

• ✅ Agenten – Verbraucheridentitäten mit einem API-Key (sha256-gehasht, einmalig angezeigt) + Key-Rotation.

• ✅ Agent ↔ V-MCP-Berechtigungen (M2M) – Zugriff pro Gruppe gewähren/entziehen; ein Agent kann viele Gruppen-Endpunkte erreichen; der Key funktioniert nur für gewährte Gruppen.

Planung

• ✅ Scheduler — Cron-Registry (node-cron), JobRun-Log, sofortige Ausführung, wird beim Start geladen.

• ✅ Self-cron über MCP — integrierte schedule_task / list_schedules / cancel_schedule-Werkzeuge innerhalb einer Gruppe; ein verbundener Agent plant sich selbst.

Secrets & Authentifizierung zu Upstreams

• ✅ Vault — Anmeldeinformationen ruhend verschlüsselt (AES-256-GCM); zur Laufzeit über ${secret.NAME} injiziert; Agents/Konfiguration sehen den Wert nie.

• ✅ Quellbereichsbezogene Secrets — gleicher Name kann pro Quelle existieren; bereichsbezogen überschreibt global.

• ✅ Statische Authentifizierung — Bearer/API-Key/Benutzerdefinierte Header, Basic (Benutzername/Passwort).

• ✅ Dynamische Token-Abläufe — oauth2_client_credentials, token_request (Login→JSON-Pfad), oauth2_refresh (zwischengespeichert + automatische Aktualisierung).

• ✅ Benutzer-OAuth — oauth2_authorization_code (Connect-Fluss) und MCP-natives OAuth (mcp_oauth: SDK-Erkennung + DCR + PKCE + Aktualisierung, mit optionalem vorregistriertem clientId).

Konten & Isolation

• ✅ Authentifizierung — E-Mail/Passwort (scrypt) + HS256-Sitzungs-JWTs; Registrierung / Anmeldung / Ich.

• ✅ Mehrbenutzer-Isolation — jede Ressource gehört einem Benutzer; alle Routen durch den Eigentümer begrenzt; Werkzeuge lösen nur innerhalb des Namensraums des Eigentümers auf. Kein kontenübergreifender Zugriff.

Beobachtbarkeit

• ✅ Aufrufprotokolle — wer/welches Werkzeug/Status/Dauer/Token-Schätzung pro Aufruf.

• ✅ Metriken — Gesamtzahlen + nach Werkzeug + nach Agent.

• ✅ Inspektor & Testaufruf — sehen, was ein Agent pro gewährtem V-MCP sieht; jedes Werkzeug ausführen, um die rohe Antwort anzuzeigen.

Web-Benutzeroberfläche (Vite + React)

• ✅ Authentifizierung — Anmeldung / Registrierung, Token-Sperre, Abmeldung.

• ✅ Formular ⟷ JSON-Ersteller für Quellen und Zusammensetzungen (Formular oder rohes JSON bearbeiten, bidirektional).

• ✅ Inline-Secrets im Quellen-Assistenten (auf die Quelle beschränkt).

• ✅ Gruppierte, einklappbare, durchsuchbare Werkzeugauswahl & -register (skalierbar auf große importierte APIs).

• ✅ Verbindungsausschnitte pro V-MCP (claude mcp add …, curl) mit Kopierschaltflächen.

• ✅ Registerkarten: Quellen · Werkzeuge · V-MCP · Agents · Secrets · Protokolle.

Infrastruktur

• ✅ Postgres über Drizzle (Migrationen werden beim Start automatisch angewendet).

• ✅ Docker Compose für lokales Postgres + Makefile (make setup / make dev / make db-*).

• ✅ .env-Laden, generierte Entwicklungs-Secrets.

Noch nicht (optional als nächstes)

• ⬜ Organisations-/Projektebene (Teams, Freigabe).

• ⬜ SSE-Transport auf dem Gateway (heute nur Streamable HTTP).

• ⬜ Hot-Reload tools/changed-Benachrichtigungen.

• ⬜ OpenAPI-Endpunkt für ein Werkzeugset; Ablaufverfolgungen.

Roadmap

• Ratenbegrenzung /auth (Passwort-Brute-Force), das Gateway und Kontingente pro Agent.

• Den Scheduler mehrfach-Replikat-sicher machen (Postgres-Advisory-Lock oder dedizierter Worker) — heute feuert der In-Memory-Cron N-mal mit N Instanzen.

• Migrationen in einen separaten Bereitstellungsschritt verschieben (sie laufen bei jedem Instanzstart → Wettlauf mit mehreren Replikaten).

• JWT-Widerruf — kurzlebige Zugriffs- + Aktualisierungstoken (ein durchgesickertes 7-Tage-Token kann nicht ungültig gemacht werden; Abmeldung ist nur lokal).

• Secret-Verwaltung — KMS + Rotation für VAULT_KEY / JWT_SECRET; CORS verschärfen (Standard ist *); den TLS-Reverse-Proxy dokumentieren.

• Die Web-Benutzeroberfläche für die Produktion bereitstellen (dist hinter einem CDN/Proxy bauen & bereitstellen; heute nur Vite-Entwicklung).

• Paginierung bei Listenendpunkten (Werkzeuge, Protokolle).

• Scheduler-Wiederholung / Backoff / Benachrichtigungen.

• OpenAPI-Parser — komplexe Spezifikationen verarbeiten (allOf, tiefe $ref).

• Passwort-Zurücksetzen / E-Mail-Verifizierung; Benutzer-Audit-Protokoll.

Verteilung

Verpackt als OCI-Image (ghcr.io/comind-pro/comind-mcp) und gelistet im offiziellen MCP-Register (registry.modelcontextprotocol.io) — die kanonische Quelle, die nachgelagerte Kataloge (PulseMCP, Smithery, Docker Hub, …) konsumieren. Die Metadaten leben in server.json unter dem GitHub-verifizierten Namespace io.github.comind-pro/comind-mcp.

Führen Sie das Image aus (Null-Infrastruktur, eingebettetes Postgres):

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

Das Veröffentlichen ist automatisiert — einen Versions-Tag pushen und CI (release.yml) erstellt & pusht das Image zu GHCR, veröffentlicht dann server.json im Register über GitHub OIDC (keine Tokens):

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

Hinweis: ComindMCP ist ein Gateway für mehrere Mandanten (HTTP MCP unter /g/:slug/mcp, Agent-Key-Authentifizierung), kein einzelner stdio-Server — Register-Clients stellen es selbst bereit und verbinden ihre eigenen Agents.

Mitwirken

comind-mcp ist Open Source (MIT) und Beiträge sind willkommen — Fehlerberichte, Funktionen, Dokumentationen, Tests.

1. Forken & Branch von main (feat/..., fix/...).

2. Lokal einrichten — siehe DEVELOPMENT.md. Kurzfassung: corepack enable && pnpm install, dann pnpm dev.

3. Vor dem Öffnen eines PR: pnpm typecheck und pnpm -r test müssen bestehen.

4. Conventional Commits für Nachrichten verwenden (feat:, fix:, docs:, chore:).

5. Einen PR gegen comind-pro/comind-mcp mit einer klaren Beschreibung öffnen; auf ein zugehöriges Issue verlinken.

Fragen oder Ideen? Öffnen Sie ein Issue. Siehe CONTRIBUTING.md für Details.

Lizenz

MIT © comind — Open Source, kostenlos nutzbar, modifizierbar und überall verteilbar, auch kommerziell.

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