secureFlows MCP Server

In der Cloud bereitstellbarer MCP-Server, der die secureFlows OpenAPI-Oberfläche kapselt, die mit ai-safe und ai-optional getaggt ist.

Dieses Repository ist ein öffentlicher Spiegel, der regelmäßig aus dem privaten secureFlows-Monorepo veröffentlicht wird, in dem die Entwicklung tatsächlich stattfindet. Issues und PRs sind willkommen; größere Änderungen können einen Release-Zyklus benötigen, bevor sie zuerst upstream landen.

Was ist ein MCP-Server?

Ein MCP-Server ist ein kleiner HTTP-Dienst, der eine Reihe von „Tools“ bereitstellt, die ein KI-Client auf standardisierte Weise aufrufen kann.

In diesem Repository:

• Der secureFlows MCP server stellt Tools bereit, die automatisch aus Ihren OpenAPI-YAML-Spezifikationen generiert werden.

• Wenn ein Client ein Tool aufruft, leitet der MCP-Server den Aufruf an Ihr echtes secureFlows-Backend (connection.host) weiter und gibt die Antwort als normalisiertes Tool-Ergebnis zurück.

Dadurch kann ein KI-Client:

• verfügbare secureFlows-Operationen über listTools ermitteln,

• sie über callTool aufrufen,

• ohne die API-Oberfläche fest zu verdrahten oder manuelle Auth-/Header-Verkabelung.

Was es tut

Zwei Arten von Tools, die gemeinsam in src/server.ts registriert werden:

Generierte Tools (src/tools/build-tools.ts) — eines pro OpenAPI-Operation:

• Lädt:

  • docs/openapi/session/secure-flows-session-api.yaml

  • docs/openapi/user/secure-flows-user-api.yaml

  • docs/openapi/docs/secure-flows-docs-api.yaml

• Stellt nur Operationen, die mit ai-safe oder ai-optional getaggt sind, als MCP-Tools bereit.

• Leitet Anfragen an einen vom Aufrufer bereitgestellten secureFlows-Host weiter — ein dünner, generischer HTTP-Wrapper ohne secureFlows-spezifische Bewertung. Jede dieser Operationen erfordert ein gültiges auth.*-Token, daher sind sie nur nützlich, sobald bereits eine Sitzung existiert (siehe Laufzeitmodell unten).

• Ordnet secureFlows-Auth-Header aus MCP-Tool-Eingaben zu:

  • auth.firebaseToken

  • auth.sessionToken

  • auth.userToken

Statische Tools (src/tools/static-tools.ts) — handgeschrieben, nicht aus der Spezifikation generiert:

• secureflows_build_login_url / secureflows_build_logout_url — erstellen die URLs für das gehostete Login und das Redirect-Logout konstruktionsbedingt korrekt (immer /app/sessions/login, niemals das veraltete /app/login; lehnt ein redirect_uri nach dem Logout ab, das auf /callback zeigt oder session_token preisgibt). Kein secureFlows-Token erforderlich.

• secureflows_lint_integration — prüft generierten App-Quellcode gegen die Integrationsregeln und meldet strukturierte Befunde, anstatt sie als Prosa zu belassen, die der Agent selbst überwachen muss. Kein secureFlows-Token erforderlich. Zwei Arten von Befunden:

  • scope: "file" — ein verbotenes Konstrukt ist vorhanden, an einer exakten file:line: Umgebungsvariablen-Konfigurationskonstanten, Token in localStorage, veraltetes /app/login, fetch/XHR-Logout, clientseitiges JWT-Decoding, Widerruf bei Abmeldung, leeres catch {}, Wiederherstellen von setSession(null) bei Nicht-Authentifizierungsfehlern, Weiter-CTA abhängig von session === null, …

  • scope: "project" — die erforderliche Behandlung ist nicht vorhanden in allen übergebenen Dateien: 401/410 erkennen, aber das Token nie löschen, 403 nie behandeln oder 403 ohne die BILLING_GRACE_LOCK-Ausnahme behandeln.

  Die Abwesenheitsprüfungen existieren, weil die Musterregeln strukturell die Fehlerklasse nicht erkennen konnten, die reale generierte Apps dominiert. Gemessen: Bei der App einer echten Testversion, die der LLM-Bewerter des Evaluierungs-Harness mit 4/10 bewertete — unter Berufung auf „veraltetes Token nach Abmeldung nie gelöscht“, „403-Varianten unbehandelt“, „keine Fehlerbehandlung“ — erzeugten die Musterregeln allein null Befunde, weil jeder dieser Fehler eine Abwesenheit ist und ein Regex nur sehen kann, was vorhanden ist. Mit den Abwesenheitsprüfungen erzeugt es 3 Befunde, einschließlich des Token-Lösch-Befunds mit Schweregrad error. Beide Prüfarten werden gegen das kanonische Starter-Template templates/web-app-secureflows validiert, das bei null Befunden bleiben muss.

  Es ist weiterhin heuristische Textanalyse, kein Parser oder Typprüfer: Es übersieht, wofür es keine Regel gibt, eine Projektprüfung kann durch das richtige Schlüsselwort an der falschen Stelle erfüllt werden, und es kann die Prüfungen nicht abdecken, die eine laufende App erfordern (Auth-Guard-Mount-Races, die Fresh-Reload-Prüfung). Ein schneller erster Durchlauf — kein Ersatz für die Agent-Implementierungscheckliste in SKILL.md.

Diese statischen Tools existieren, weil die generierten Tools nicht bei dem Teil einer Integration helfen können, der vor dem Bestehen einer Sitzung stattfindet — dem Erstellen des Redirect-/Callback-/Token-Lebenszyklus-Codes — und genau dort passieren die meisten secureFlows-Integrationsfehler.

Verwendet einen zustandslosen HTTP-MCP-Transport, sodass der Server keine Mandantenkonfiguration oder Geheimnisse speichert.

Laufzeitmodell

Jeder Tool-Aufruf erhält:

• connection.host: secureFlows-Basis-URL

• connection.workspaceName: optionaler Standard-Workspace

• connection.appId: optionale Standard-Anwendungs-ID

• auth.*: das Token, das der ausgewählte Endpunkt benötigt

workspaceName und appId werden als stabile App-Konfiguration behandelt. Der Server fügt sie in bekannte secureFlows-Anfrageformen ein, wenn sie vom Aufrufer ausgelassen werden.

Für Agenten (der einzige unterstützte Client-Pfad)

Richten Sie den MCP-Client auf die gehostete URL — derselbe Host wie das Produkt, Pfad /mcp (keine Subdomain):

{
  "mcpServers": {
    "secureflows": {
      "url": "https://www.secure-flows.com/mcp"
    }
  }
}

Weisen Sie Agenten nicht an, npx auszuführen oder localhost zu verwenden — das spaltet die Geschichte und schließt alle aus, die nie einen lokalen Prozess starten. Im Web-Docker-Image integriert (Node auf 127.0.0.1:8787, nginx location = /mcp; siehe docs/ROUTING.md). Der Node-Prozess installiert uncaughtException-/unhandledRejection-Guards, sodass eine einzelne fehlerhafte Anfrage den Prozess nicht beendet; docker/entrypoint.sh startet MCP außerdem neu, falls der Prozess dennoch beendet wird.

Lokale Entwicklung (Maintainer dieses Pakets)

cd mcp-server
npm install
npm run build
npm test
npm run dev

Der Server startet standardmäßig auf http://0.0.0.0:8787 (POST /mcp, GET /health). Dies dient dazu, den MCP-Server selbst zu ändern — nicht den Pfad, den Produkt-Agenten konfigurieren sollten.

Umgebungsvariablen

• PORT: HTTP-Port, Standard 8787 (im Web-Container setzt der Entrypoint PORT=8787 nur für den MCP-Kindprozess, damit nginx den öffentlichen $PORT von Render behält)

• HOST: Bind-Host, Standard 0.0.0.0 (Web-Container verwendet 127.0.0.1)

• ALLOWED_HOSTS: optionale, durch Kommas getrennte Host-Allowlist für die MCP-Host-Header-Validierung

• MCP_ALLOWED_HOSTS: Entrypoint-Override für ALLOWED_HOSTS beim Starten des In-Image-Prozesses

Endpunkte

• POST /mcp: MCP-Streamable-HTTP-Endpunkt

• GET /health: Health-Check (öffentlich als GET /mcp/health über nginx verfügbar)

Einbetten von secureFlows in eine Anwendung

Produkt-Apps integrieren direkt mit den secureFlows-HTTP-APIs und dem gehosteten Login. Beginnen Sie mit:

• docs/integration/quickstart.md — Bereitstellung (Workspace + Anwendung) und gehostetes Login zur Laufzeit

• docs/integration/CONCEPT.md — Basisreihenfolge: Login → Workspace erstellen vor erweiterten Funktionen

• docs/openapi/integration-auth.yaml — /app/sessions/login (Session-Apps) vs. /app/login (Legacy/Konsole)

Produkt-Apps integrieren weiterhin direkt mit den oben genannten HTTP-APIs, nicht über diesen Server. Die generierten Tools hier sind für Agents/Automatisierung, die bereits ein Token haben (Tests, skriptgestützte Verifizierung). Die statischen Tools (secureflows_build_login_url, secureflows_build_logout_url, secureflows_lint_integration) benötigen kein Token und sollen von einem Coding-Agenten aufgerufen werden, während er die Integration noch aufbaut — siehe Was es tut oben.

Testen dieses MCP-Servers

1. npm test in mcp-server/ — Unit-Tests plus HTTP-Smoke-Test (test/http-smoke.test.ts): startet die Express-App auf einem ephemeren Port, prüft GET /health, GET /mcp → 405 und einen echten Streamable-HTTP-Client listTools + callTool(secureflows_build_login_url).

2. Nach dem Deployment: Playwright tests/smoke/mcp-health.spec.ts ruft das öffentliche GET /mcp/health und GET /mcp auf dem Zielhost auf (Produktions-Smoke-Job).

3. Lokale Maintainer-Schleife: npm run dev, dann curl -sS http://127.0.0.1:8787/health.

4. Optional: MCP-Client gegen POST /mcp mit connection.host + auth.* für generierte Tools.

Bereitstellung

Wird im Web-Docker-Image ausgeliefert und unter /mcp auf www.secure-flows.com / Staging bereitgestellt (siehe Für Agenten oben). Keine separate Subdomain.

Das npm-Paket secureflows-mcp-server ist der Weg, über den CI ein versioniertes Artefakt veröffentlicht (und wie ein eigenständiger Container aus mcp-server/Dockerfile gebaut werden kann); es ist nicht der für Agenten gedachte Einrichtungspfad. Veröffentlichung über v*.*.*-Tags mittels .github/workflows/publish-secureflows-mcp-server.yml.

docker build -f mcp-server/Dockerfile -t secureflows-mcp-server .
docker run --rm -p 8787:8787 secureflows-mcp-server

Hinweise

• Gehostete Login-/Redirect-Endpunkte werden nur bereitgestellt, wenn sie in den OpenAPI-Spezifikationen mit ai-safe oder ai-optional getaggt sind.

• Dokumentationssuche (get_docs_search) ist ai-safe, erfordert kein auth.* — nur connection.host und die Abfrage q.

• Nur für Menschen gedachte Admin-Konsolen-APIs sind absichtlich ausgeschlossen.

• Die Antwort-Payload jedes Tools enthält:

  • status

  • ok

  • url

  • headers

  • data