PatchFirst / Entwickler

API und MCP

Lesen Sie Befunde Ihrer bezahlten Server, erstellen Sie eine Patchliste und veranlassen Sie Neuberechnungen aus Ihren eigenen Werkzeugen.

Ein Token je Integration

Erstellen Sie ein persönliches API-Token im Bereich API-Tokens Ihrer Übersicht. Vergeben Sie einen Namen mit höchstens 64 Zeichen, wählen Sie read oder write (Lesen und Schreiben) und legen Sie eine Gültigkeit von 1 bis 365 Tagen fest. Bestätigen Sie die Erstellung erneut mit Ihrem aktuellen Passwort. Nach Passwortänderung oder Wiederherstellung werden alle API-Tokens widerrufen. Eine normale Abmeldung erhält den Zugriff von CI und MCP. Zum Widerruf aller Tokens dient die separate Schaltfläche „Alle Tokens widerrufen“ in der Übersicht. Dort erscheint der Widerrufsgrund. Sie können bis zu 50 aktive Tokens besitzen. Kopieren Sie das Geheimnis bei der Anzeige: Es wird nur einmal gezeigt. Der Dienst speichert nur einen Prüfhash. In der Übersicht können Sie Tokens auflisten, widerrufen und ihre Nutzung prüfen.

Verwenden Sie HTTPS und senden Sie das Token ausschließlich in Authorization: Bearer …. Tokens in URLs werden abgelehnt. Die Beispiele setzen voraus, dass PATCHFIRST_API_TOKEN in Ihrer Umgebung gesetzt ist; halten Sie das Geheimnis aus Versionsverwaltung, Bildschirmfotos und Protokollen heraus. Vorhandene Lese-/Schreibschlüssel für Serverbestände und Agenten-Tokens sind separate Zugangsdaten.

curl --fail-with-body "https://patchfirst.dev/v1/me/fleets" \
  -H "Authorization: Bearer $PATCHFIRST_API_TOKEN"

Das Token gilt nur für Serverbestände des Eigentümers. Ein fremder Bestand liefert 404, genau wie ein nicht vorhandener. Ein read-Token kann keine Neuberechnung starten. Browserzugriff von anderen Ursprüngen ist deaktiviert (geschlossenes CORS).

API und MCP erfordern bezahlte Überwachung. Ohne berechtigende Zahlung liefern Anfragen 402. Nach Ablauf der Überwachung umfasst der Archivzugriff gemäß Abrechnungsregeln nur gespeicherte Berichtssnapshots aus zuvor bezahlten Zeiträumen ohne neue Daten. CVE-Details erfordern eine aktive Zahlung: Andernfalls liefert die API 402 und cve_details liefert einen Zahlungsfehler im MCP-Ergebnis; aktuelle KEV-, EPSS-, Exploit-, Sichtungs- und Erwähnungsdaten sind im Archivmodus nicht verfügbar. Neue Berechnungen erfordern aktuelle Überwachungsberechtigung einschließlich einer gegebenenfalls geltenden Nachfrist; kostenlose Plätze allein gewähren keinen API-Zugriff.

API-v1-Endpunkte

Basis-URL: https://patchfirst.dev. Ersetzen Sie {fleet} und {server} durch UUIDs aus den Listenendpunkten. Alle folgenden Endpunkte verwenden ein persönliches Bearer-Token.

curl --fail-with-body "https://patchfirst.dev/v1/me/fleets/11111111-1111-4111-8111-111111111111/report" \
  -H "Authorization: Bearer $PATCHFIRST_API_TOKEN"

curl --fail-with-body -X POST "https://patchfirst.dev/v1/me/fleets/11111111-1111-4111-8111-111111111111/refresh" \
  -H "Authorization: Bearer $PATCHFIRST_API_TOKEN"

Die Tokenverwaltung der Übersicht verwendet Ihre angemeldete Browsersitzung, getrennt vom Bearer-Zugriff: GET/POST /v1/account/api-tokens, DELETE /v1/account/api-tokens/{token_id} und GET /v1/account/api-tokens/{token_id}/usage. Die Erstellung akzeptiert {"name":"acme integration","scope":"read","expires_in_days":30,"password":"CURRENT_PASSWORD"} und liefert 201 mit Tokenmetadaten und dem einmalig angezeigten token-Geheimnis. Schreibzugriffe per Sitzung erfordern eine Prüfung auf denselben Ursprung.

Antwortvertrag und Namen

Das OpenAPI-Dokument definiert die v1-JSON-Schemas. Vorhandene Felder behalten Bedeutung und Datentyp; Clients sollten zusätzliche Felder akzeptieren. Erfolgsantworten sind JSON-Objekte. Listen verwenden fleets, servers oder history-Arrays. Tokenmetadaten, Bestandserstellung, Serveraktualisierungen und Verlauf recorded_at verwenden Unix-Sekunden (UTC); im Bericht verwendet computed_at eine UTC-Datumszeitzeichenfolge oder null.

Die Felder score und grade enthalten die Hauptbewertung der geprüften Komponenten. global_score und global_grade enthalten die Gesamtbewertung einschließlich des unbekannten Risikos. coverage enthält die Ganzzahlen checked (geprüft) und total (erkannt). Diese Felder stehen in Server- und Flottenberichten, Serverlisten und gespeicherten Verlaufsständen. Der Prüfumfang der Flotte summiert nur Server mit verfügbarer Gesamtbewertung; deren Gewichtung entspricht der Hauptbewertung. Die Note ? bedeutet, dass die Bewertung nicht verfügbar ist. Ältere Verlaufsstände können für die Gesamtbewertung null enthalten.

Die Felder complete, rating_complete, reasons und blind bleiben aus Kompatibilitätsgründen erhalten und beschreiben den Prüfumfang. Sie bestimmen weder Hauptbewertung noch Urteil. Berechnung von Gesamtbewertung und Prüfumfang →

Ein Serverbericht enthält id, name, name_kind, score, grade, counts und findings. Jeder Befund enthält priority (P0–P3), component, installierte version, fix, empfohlene action und top-CVE-Einträge. fix kann leer oder null sein, wenn keine bereinigte Version verfügbar ist; prüfen Sie unfixed, pro_only und action.

Offene Aliasnamen wie web-1 werden mit name_kind: "alias" zurückgegeben. Bei verschlüsselten oder ungesetzten Namen bezeichnet name_kind: "opaque" eine undurchsichtige Kennung. Der entfernte Dienst kennt verschlüsselte Servernamen nicht und kann sie nicht entschlüsseln. Verwenden Sie niemals Domain, IP-Adresse, Firmen- oder Kundennamen als offenen Alias.

Fehler, Grenzen und Nutzung

Fehler besitzen die stabile Struktur {"error":"Readable explanation","code":"machine_code"}. Verwenden Sie HTTP-Status und code für Programmlogik; der Erklärungstext kann sich ändern.

Das Limit beträgt 120 Anfragen pro Minute und Konto, gemeinsam für alle Tokens, API und MCP. Bestandsneuberechnung hat ein separates Limit von 10 Anfragen pro Minute und Konto, gemeinsam für API und MCP. Das Journal zeigt bis zu 100 zuletzt gespeicherte Anfragen. Gleiche Anfragen (Token, Methode, Pfad, Status) werden höchstens einmal pro Minute erfasst; 429-Antworten sind ausgeschlossen. Datensätze werden bis zu 30 Tage und höchstens 1000 je Token aufbewahrt; eine stündliche Bereinigung entfernt überschüssige Einträge. Der Bewertungsverlauf liefert bis zu 1000 letzte Einträge. Nutzungsdatensätze enthalten Zeitpunkt, Methode, Pfad und HTTP-Status; Anfrage- und Antwortinhalte sowie Tokengeheimnisse sind ausgeschlossen.

Entferntes MCP verbinden

Endpunkt: https://patchfirst.dev/v1/mcp. Transport: Streamable HTTP, Protokoll 2025-06-18, mit demselben Bearer-Token und denselben Eigentumsprüfungen und Zahlungsregeln. Beginnen Sie mit einem Lese-Token. Entfernte Werkzeuge sind list_servers, server_report, fleet_report, cve_details und patch_first (was zuerst aktualisiert werden sollte). Verwenden Sie refresh_fleet zum Start einer Neuberechnung: Erforderlich sind write, eine fleet-UUID und aktive Zahlung; es gilt das separate kontoweite Aktualisierungslimit.

server_report akzeptiert fleet und server-UUIDs; fleet_report akzeptiert fleet; cve_details akzeptiert cve. list_servers liefert die Bestands-UUID in fleet. Für list_servers und patch_first ist fleet optional und entspricht standardmäßig Ihrem Serverbestand. Ermitteln Sie Eingabeschemas mit tools/list. Protokollfehler verwenden JSON-RPC-Fehlerantworten; Fehler der Werkzeugausführung einschließlich Zahlungs- und Aktualisierungslimits liefern HTTP 200 mit isError: true.

Es wird ausschließlich statische Bearer-Authentifizierung unterstützt: Erstellen Sie ein Token manuell in der Übersicht und konfigurieren Sie es im Client. Es gibt weder einen OAuth-Autorisierungsserver noch automatische OAuth-Tokenbeschaffung. Dies ist ein begrenzter Modus mit statischem Token; der vollständige OAuth-Autorisierungsablauf der MCP-Spezifikation ist nicht implementiert. Der öffentliche /.well-known/oauth-protected-resource-Endpunkt veröffentlicht MCP-URL, Dokumentation und den Link zur Tokenausgabe in der Übersicht (token_issuance_uri). Bei 401 verweist der WWW-Authenticate: Bearer resource_metadata="…"-Header auf diese Metadaten. Verwenden Sie einen Client, der ein manuell konfiguriertes Bearer-Token akzeptiert.

Claude Code

Setzen Sie das Token in Ihrer Umgebung und fügen Sie den HTTP-Server hinzu:

claude mcp add --transport http patchfirst "https://patchfirst.dev/v1/mcp" \
  --header "Authorization: Bearer $PATCHFIRST_API_TOKEN"

Codex

Ergänzen Sie dies in ~/.codex/config.toml und starten Sie Codex mit gesetztem PATCHFIRST_API_TOKEN:

[mcp_servers.patchfirst]
url = "https://patchfirst.dev/v1/mcp"
bearer_token_env_var = "PATCHFIRST_API_TOKEN"

Offizielle OpenAI-Dokumentation zur Codex-MCP-Konfiguration.

Cursor

Fügen Sie den Server in den MCP-Einstellungen oder lokal in ~/.cursor/mcp.json hinzu. Ersetzen Sie den Platzhalter durch Ihr Token und schützen Sie diese Datei als Geheimnis:

{
  "mcpServers": {
    "patchfirst": {
      "url": "https://patchfirst.dev/v1/mcp",
      "headers": {"Authorization": "Bearer YOUR_API_TOKEN"}
    }
  }
}

Protokollbeispiel

Der Server ist zustandslos. Senden Sie Accept: application/json, text/event-stream und Content-Type: application/json. Initialisieren Sie zuerst, senden Sie notifications/initialized und verwenden Sie danach tools/list oder tools/call mit MCP-Protocol-Version: 2025-06-18. Benachrichtigungen liefern 202 ohne Inhalt zurück; eine Serversitzungskennung ist nicht erforderlich. GET /v1/mcp liefert 405 mit dem Header Allow: POST.

curl --fail-with-body "https://patchfirst.dev/v1/mcp" \
  -H "Authorization: Bearer $PATCHFIRST_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"acme","version":"1.0"}}}'

Über MCP neu berechnen

Ein tools/call-Beispiel für ein Schreib-Token; ersetzen Sie die Bestands-UUID:

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"refresh_fleet","arguments":{"fleet":"11111111-1111-4111-8111-111111111111"}}}

Lokales MCP mit Namensentschlüsselung

Das bestehende core/mcp_server.py bleibt über stdio verfügbar. Führen Sie python3 /path/to/patchfirst/core/mcp_server.py lokal mit Ihrer eingerichteten Eigentümer-CLI und lokalen Bestandsdateien (PSR_FLEETS, PSR_INVENTORY) aus. Es kann Namen über Ihr lokales verschlüsseltes Verzeichnis wiederherstellen. Entferntes MCP belässt verschlüsselte Namen als undurchsichtige Kennungen.