MCP-Server (nodepilot-mcp)

Ein Model-Context-Protocol-Server, mit dem ein KI-Agent (Claude Desktop/Code oder ein beliebiger MCP-Client) NodePilot-Workflows steuern und bearbeiten sowie Daten auslesen kann. Wie die np-CLI ist er ein reiner HTTP-Client gegen die bestehende REST-API — kein neuer Backend-Pfad; jedes Tool ruft einen vorhandenen Endpoint auf oder rechnet in-proc gegen NodePilot.Core. 116 Tools über 12 Gruppen, plus 3 MCP-Resources.

Agentenwerkzeuge

Die Agentengruppe bietet list_agent_runs, get_agent_events, list_agent_mcp_servers, discover_agent_mcp_tools, save_agent_mcp_server, list_agent_skills, import_agent_skill, set_agent_skill_enabled, delete_agent_mcp_server und delete_agent_skill. Läufe/Ereignisse verwenden die Workflow-Leseberechtigung. Registry- Lesen benötigt Admin/Operator, Änderungen Admin, Löschen zusätzlich das Destruktiv-Gate. Discovery kann den registrierten stdio-Prozess starten. Die Transporte des Agenten-Clients sind unabhängig von diesem stdio-Server.

Installation

Der Server ist kein .NET Global Tool: PackAsTool verträgt das geerbte net10.0-windows-TFM nicht (NETSDK1146), dotnet pack scheitert also. Ausgeliefert wird per dotnet publish; der MCP-Client zeigt auf die erzeugte .exe.

# Beide Installer liefern den Server bereits mit: <install>\tools\mcp\nodepilot-mcp.exe.
# Nur aus einem Source-Checkout selbst bauen:
dotnet publish src/NodePilot.Mcp -c Release -o C:\Tools\NodePilot-Mcp

np auth login          # der MCP-Server nutzt diese CLI-Session weiter

// .mcp.json — Client auf den Server zeigen
{
  "mcpServers": {
    "nodepilot": {
      "command": "C:\\Tools\\NodePilot-Mcp\\nodepilot-mcp.exe",
      "env": { "NODEPILOT_MCP_SERVER": "https://nodepilot.example.com", "NODEPILOT_MCP_PROFILE": "default" }
    }
  }
}

Konfiguration & Auth

Headless (vom MCP-Client gestartet) → env-first, mit Fallback auf die CLI-Config/-Session:

Ohne NODEPILOT_MCP_TOKEN liest der Server die Session aus np auth login bei jeder Anfrage neu. Ein Login nach dem Start des MCP-Servers wirkt deshalb ab dem nächsten Tool-Aufruf, ohne Neustart.

TLS: Eine fehlerfreie Zertifikatsprüfung (Kette und Hostname) wird akzeptiert, auch wenn zusätzlich ein Pin konfiguriert ist. Bei einem TLS-Prüffehler entscheidet ein gesetzter SHA-256-Pin: passt er, wird das Zertifikat akzeptiert — ausdrücklich auch bei einem Hostnamen-Mismatch; passt er nicht, hilft auch der Bypass nicht. Nur ohne Pin kann NODEPILOT_MCP_TLS_NO_VERIFY einen Prüffehler übergehen. Ein passender Pin behebt den Namensfehler nicht, sondern erlaubt dieses konkrete Zertifikat trotz des Fehlers. Eine URL mit einem Namen aus dem Zertifikat bleibt der reguläre Weg.

Ein Pin aus dem CLI-Profil gilt nur für dessen Server-Origin. Ein ungültiges Fingerprint-Format führt bei Tool-Aufrufen zu einem reparierbaren Konfigurationsfehler (np config set tls-thumbprint <SHA256> beziehungsweise none zum Löschen). Die generischen NODEPILOT_TLS_*-Variablen teilen sich CLI und MCP-Server.

Transport ist stdio (Streamable HTTP ist als spätere Option vorgesehen). Windows-only (net10.0-windows, DPAPI).

Sicherheit

• Destructive-Gate: delete_*, force_unlock_workflow, cancel_all_executions, restart_service, test_step werden nur bei NODEPILOT_MCP_ALLOW_DESTRUCTIVE=true registriert — sonst tauchen sie nicht einmal in tools/list auf. get_safety_status zeigt den Modus.
• Secrets: Workflow-Definitionen werden vor Tool-Output redigiert (secret/apiKey/password/ authToken/bearer/connectionString → ***). Bei publish/update/apply_workflow_patch werden echte Secrets per Node-ID aus der gespeicherten Version wiederhergestellt — das *** des Agenten überschreibt nie einen echten Wert. Ein *** auf einer neuen Node- oder Edge-ID hat kein Original, deshalb wird der Aufruf abgelehnt und nichts gespeichert. Dasselbe gilt für eine Änderung an einem Bedingungs- oder Case-Array, das ein *** enthält; diese Änderung erfolgt im Designer. Credentials/Globals geben Secrets nie aus.
• Versionsprüfung: publish_workflow/update_workflow_definition verlangen expectedVersion, die Version, die get_workflow_definition geliefert hat. Hat zwischenzeitlich jemand gespeichert, antwortet der Server mit 409 workflow_version_conflict, und der neuere Workflow bleibt unverändert.
• Annotations: Read-Tools readOnly, gated Tools destructive, enable/disable/lock idempotent. execute_workflow ist nicht idempotent: ein erneuter Aufruf startet eine weitere Ausführung. Einen unklar beantworteten Start zuerst über die Ausführungen prüfen.

Tool-Gruppen

• Abhängigkeiten (lesend): list_dependency_objects, get_dependencies, get_dependency_evidence. Workflows, Maschinen, Zugangsdaten, globale Variablen und Custom Activities suchen, nach Problemen oder fehlender Verwendung filtern und nach Verwendung sortieren; direkte und mittelbare Verwendung, mögliche Agent-Aufrufe und Fundstellen untersuchen. Berichte berücksichtigen Ordnerrechte, enthalten keine Secret-Werte und weisen Analysegrenzen sowie an den gespeicherten Stand gebundene Folgeseiten aus. Sie beschreiben gespeicherte Konfiguration, keine Ausfallvorhersage.

• Discovery: whoami, get_safety_status, list_activity_types, get_activity_config_reference, validate_cron

• Workflow lesen: list_workflows, get_workflow, get_workflow_definition (redigiert), get_workflow_contract, Versionen, export_workflow

• Workflow editieren: lock/unlock/publish_workflow/update_workflow_definition, validate_workflow_definition, preview/apply_workflow_patch (Merge-by-ID, Secret-Schutz, Validate-before-Save), create/duplicate/enable/disable/rollback/import (JSON via import_workflow, SCOrch-.ois_export via import_scorch_workflow), step-test context

• Gated destructive: test_step (führt eine echte Activity aus; Config-Override zusätzlich nur mit Edit + eigenem Lock), delete/force-unlock/cancel-all

• Executions: list/get/steps/paused-steps, execute_workflow, cancel/retry/resume, trigger_external_workflow

• Telemetrie: dashboard, coverage/step-health/step-stats, get_failure_causes, get_operations_graph, query_audit_log (Admin), get_support_diagnostics (Admin)

• DB / text2sql (Admin, nur lesend): list_db_tables (Schema-Katalog; Secret-Spalten hidden, GlobalVariable.Value maskiert), get_db_info (Provider + Row-/Timeout-Limits), run_readonly_sql (ein Read-Only-Statement, Server erzwingt Keyword-Whitelist + Rollback; kein Write-Tool). Secret-Spalten sind auch über Raw-SQL unerreichbar — Ein direkter Verweis liefert protected_column; Wildcard-Projektionen (SELECT *, alias.*, PostgreSQL TABLE t) und die Serialisierung einer ganzen Zeile (to_json/row_to_json/::text/FOR JSON) einer Tabelle mit Secret-Spalte liefern protected_row_projection; Ergebnisspalten mit geschützten Namen werden zusätzlich als *** maskiert. COUNT(*) funktioniert weiter, explizit benannte, ungeschützte Spalten funktionieren immer. Die Übersetzung natürlicher Sprache nach SQL übernimmt der Agent.

• Supporting: Machines, Credentials, Globals (Secrets nie ausgegeben)

• Alerting: get_alerting_catalog (Regel-Vokabular) + list/get/create/update/test_fire_alerting_rule + list_alerting_deliveries (Ledger) (+ gated delete_alerting_rule; Route-Secrets nie ausgegeben, Webhook-URLs nur als Schema, Host und Port)

• System-Alerts (ADR 0008): get_system_alert_catalog + list/get/create/update/enable/disable/test_fire_system_alert_policy (+ gated delete_system_alert_policy)

• Canvas-Assistent (für den Designer-Chat, überwiegend in-proc): analyze_workflow, get_available_variables, get_failure_context, find_unresolved_references, validate_edge_condition, validate_activity_config, preview_template_resolution, suggest_layout, diff_workflow_definition, get_workflow_node, check_styleguide

Resources

• nodepilot://activity-catalog — alle Activity-/Trigger-Typen (Kategorie, isTrigger/isRemote, Output-Params)
• nodepilot://activity-config-reference — kuratierte per-Activity Config-Key-Schemata
• nodepilot://styleguide — der Workflow-Layout-Styleguide

Vollständige Referenz im Repo: docs/mcp-server.md.