Codex-Aufträge per REST und MCP

Codex Master erhält eine asynchrone REST-v1-Schnittstelle und kompakte Streamable-HTTP-MCP-Werkzeuge. Beide Transporte verwenden dieselbe Service-, Policy-, Idempotenz- und Jobqueue-Schicht. MCP Central bindet den Dienst als optionalen generischen Upstream an; Central führt keinen zweiten Codex-Worker und keine abweichende Autorisierung ein.

Verifizierter Rolloutstatus

Bestätigter Blocker: kein autorisierter Forgejo-Pushweg für den Master

Das Repository stage_mcp_plugins verweist lokal direkt auf das Forgejo- Bare-Repository. Dessen fail-closed Hook lehnt Pushes ohne Forgejo-Umgebung ab; der vorhandene SSH-Schlüssel ist nicht für dieses Repository berechtigt. Der produktive dirty Helper-Worktree wurde deshalb nicht überschrieben und die öffentliche REST-Schreibschnittstelle nicht halb aktiviert. Der Central- Eintrag bleibt enabled: false.

Bestätigter Blocker: kein autorisierter Forgejo-Pushweg für die Wiki-App

Der reguläre Wiki-Releaser benötigt für jedes neue Content-Release einen neuen exakten App-Commit. Der geprüfte App-Kandidat ergänzt den verbindlichen Accountpfad-Lint vor dem Release, doch auch dieses Repository verweist lokal auf ein Bare-Repository, dessen Forgejo-Hook den normalen Push ohne verwalteten Schlüssel ablehnt. Ein manueller Content-Publish oder eine Wiederverwendung des bestehenden App-Releaseverzeichnisses wurde nicht als Sonderweg eingesetzt.

Gemeinsame Architektur

• autorisierter REST- oder MCP-Client
  • Stage Authorization Server: DCR, Authorization Code, PKCE S256
  • Codex Master: Principal-, Rollen-, Scope- und Audience-Prüfung
  • gemeinsame Operation- und Jobqueue
    • unveränderlicher Resolver- und Policy-Snapshot
    • genau ein Worker und ein terminaler Endzustand
  • kanonischer Dispatcher codex-current
• MCP Central
  • generischer Upstream-Broker
  • verschlüsselte Tokens pro Central-Principal
  • eindeutiges Prefix codex_remote
  • optionaler Fehlerzustand degraded

Der Master bindet einen angenommenen Auftrag an Principal, Client, Policy-Version, Registry- und Runtime-Fingerabdruck, Workspace, Profil, Modell, Reasoning, Sandbox und Timeout. Poll, Cancel und Resume prüfen diese Bindung; ein späterer Accountwechsel hängt einen bestehenden Job nicht um.

Korrelationsvertrag

LIVE: Korrelationsvertrag vollständig ausgerollt

Der komponentenübergreifende Vertrag ist für Central, Stage und Channel Manager aktiv. Central läuft als unveränderliches Release mcp-central-20260828T210345Z-d2bef5dd2980 integriert; Health, Rollback auf den Vorgänger und Reaktivierung waren erfolgreich. Stage läuft aus 3f9585569a00. Channel Manager läuft aus dem festen Git-Projektroot /home/wpmcp/codex-projects/channel-manager auf Forgejo-main 9327a6e18fc8022dc966dca176eed7dfc6fa36fc, Version 0.4.2 und Schema 13; Supervisor verwendet direkt dessen .venv/bin/channel-manager. Lokaler und öffentlicher Health, das unautorisierte 401-Gate, Datenbankintegrität und der exakte Prozess-CWD wurden nach der Migration verifiziert. Active und Fallback blieben unverändert und strikt read-only.

Ein logischer MCP-Vorgang besitzt genau eine kanonische correlation_id im Format corr_ plus 32 kleingeschriebene Hexadezimalzeichen. Central übernimmt einen syntaktisch gültigen Wert aus X-Correlation-ID; andernfalls erzeugt es einen neuen. Derselbe Wert erscheint im Central-Antwortheader, wird über den Upstream-Header an Stage weitergereicht und bleibt bei einem Retry unverändert. X-Correlation-Attempt zählt ausschließlich Transportversuche ab 1; es ist keine Job- oder Zustellungs-ID.

Central schreibt für jede Anfrage strukturierte Ereignisse für Request-Start, Upstream-Start und -Ende, Response-Ende sowie Fehler. Alle Ereignisse tragen dieselbe Korrelation und UTC-Zeit; End- und Fehlerereignisse tragen zusätzlich die Dauer. Soweit vorhanden folgen Werkzeug, Request-/Jobkennung, Pollparameter, Versuch, Phase, Reason-Code, Dispatchzustand und terminaler Status. Erfolgreiche und fehlgeschlagene Werkzeugaufrufe erscheinen im Audit. JSONL-Datensätze werden unter Lock vollständig geschrieben und synchronisiert; ein Short Write gilt als expliziter Logfehler und nicht als erfolgreicher Audit.

Öffentliche JSON-RPC-Fehler bleiben kompatibel und ergänzen unter error.data mindestens correlation_id, stabile Kategorie, phase, reason_code, retryable und dispatch_state. Die Transporttaxonomie trennt Verbindungs- und Lese-Timeout, unvollständige Antwort, Antwort-Parsing, Audit-/Logschreiben und Clientschreiben. Interne Pfade, Roh-Exceptions, Prompts, Ergebnisse, Zugangsdaten, Konto- oder Empfängerkennungen werden weder reflektiert noch in allgemein lesbare Logs übernommen.

Kanonische Account-Auswahl

Neue Jobs starten ausschließlich über /home/wpmcp/.local/bin/codex-current. Der Dienst hält beim Preflight und Start denselben Shared Lock wie die zentrale Schema-2-Registry. Der Worker nimmt den Lock erneut und vergleicht den gespeicherten Snapshot, bevor er die CLI ausführt.

/home/wpmcp/.local/bin/codex-current --status
/home/wpmcp/.local/bin/codex-current --preflight
/home/wpmcp/.local/bin/codex-select <profile>

Nur der rollenbeschränkte Selektor darf die Auswahl ändern. Ein Kandidat wird vor dem atomaren Wechsel vollständig geprüft. SSH, Supervisor, REST, MCP, Worker und Resume dürfen weder einen Account erraten noch einen direkten Account-, CODEX_HOME-, Wrapper- oder Companion-Pfad festschreiben. Der private Statusvertrag ist codex-current/status-v1; öffentliche Health- Antworten enthalten weder Profilbezeichner noch Pfade.

REST v1

Nach Aktivierung liegen Vertrag und Endpunkte auf Codex Master:

Start und Resume benötigen Idempotency-Key. Dieselbe Kombination aus Principal, Operation und Request liefert den ersten Job erneut; eine abweichende Wiederholung endet mit operation_conflict. Ein Timeout nach Annahme löst keinen lokalen oder zweiten Remote-Fallback aus. Job-IDs sind opak, principalgebunden und nicht aufzählbar.

Der OAuth-Scope lautet mcp; Codex Master verlangt zusätzlich eine aktuell introspektierte Stage-Adminrolle und die exakte Audience https://codex-master.webdevmedia.de/codex-mcp. Anonyme Schreibzugriffe, Tokens in URLs und freie CLI-Flags sind nicht vorgesehen.

Streamable HTTP MCP

Der bestehende Endpunkt https://codex-master.webdevmedia.de/codex-mcp unterstützt im Kandidaten MCP 2025-11-25, Initialisierung, initialized- Notification, Ping, Toolliste und Toolaufrufe über JSON oder SSE. Für Remote- Clients sind diese kleinen Werkzeuge vorgesehen:

Das nicht beworbene Werkzeug basic__current_principal liefert ausschließlich eine dienstübergreifende Principalbindung und Rolle an den Central-Broker. Es beweist nach dem OAuth-Codeaustausch, dass Central und Master denselben Principal meinen; bei Abweichung werden neue Tokens verworfen und widerrufen.

Central-Upstream und OAuth

Der Central-Endpunkt bleibt https://mcp.webdevmedia.de/central. Der generische Broker nutzt die feste Callback-URL https://mcp.webdevmedia.de/oauth/upstream/callback und prüft:

1. Protected-Resource-Discovery ohne Redirectfolge.
2. exakte Master-Resource und exakten Stage-Issuer;
3. DCR mit ausschließlich der festen Callback-URL;
4. Authorization Code und PKCE S256;
5. Scope mcp, Resource und Principal-/Rollenbindung;
6. resource-gebundenen Refresh und bestmögliche Revocation beider Tokens.

Access- und Refresh-Tokens werden AES-GCM-verschlüsselt pro Principal im owner-only Central-State gespeichert. Central erhält kein Benutzerpasswort. Ein optionaler Discovery-, Login-, Initialize- oder Catalog-Fehler darf native Central-Werkzeuge und andere Upstreams nicht entfernen; er wird redigiert als degraded geführt.

Feste Policy und Limits

Workspace-Auflösung lehnt Traversal und Symlink-Ausbruch ab. Private Zustandsverzeichnisse sind 0700, Dateien 0600; SQLite verwendet WAL, vollständige Synchronisation und atomare Operation-Claims. Cancel und Timeout beenden die Prozessgruppe. Öffentliche Fehler enthalten nur stabile Reason- Codes, niemals Prompt, Ergebnis, Account, private Pfade, rohes stderr oder Credentials.

Release und Rollback

Central läuft über den stabilen privaten Zeiger /home/wpmcp/.mcp-central/service-current. Der aktuelle Release wurde aus dem Forgejo-Commit gebaut, durch 96 Python-Tests und Health-Gates geprüft sowie einmal erfolgreich auf den vorherigen Checkout zurück- und wieder vorgerollt. Konfiguration, OAuth-State, Tokens und Logs bleiben außerhalb des Artefakts.

scripts/release-central-service.sh activate mcp-central-YYYYMMDDTHHMMSSZ-COMMIT12
/home/wpmcp/.mcp-central/service-current/scripts/release-central-service.sh rollback

Für Codex Master ist analog der private Zeiger /home/wpmcp/.codex-mcp/codex-mcp-current vorgesehen. Der Releaser archiviert den exakten Commit, prüft PHP-Syntax, REST-/MCP-Policy und den Negativ-Lint, schaltet atomar und stellt bei fehlgeschlagenem Health-Gate den vorherigen Stand wieder her. Er darf erst nach einem autorisierten Forgejo-Push verwendet werden.

codex_mcp_php/bin/release-master.sh activate codex-mcp-YYYYMMDDTHHMMSSZ-COMMIT12
/home/wpmcp/.codex-mcp/codex-mcp-current/bin/release-master.sh rollback

Der Wiki-Releaser des App-Kandidaten prüft vor Build und Maintenance den exakten App- und Content-Checkout auf direkte account-spezifische Codex-Home-/Wrapperpfade sowie hartcodierte CODEX_ACCOUNT_PROFILE- E-Mailwerte. Beanstandete Werte werden nicht in der Ausgabe wiederholt. Kanonischer Dispatcher, helper-tools und ausdrücklich markierte Profilplatzhalter bleiben zulässig. Der Lint ist erst nach einem autorisierten App-Push und Release produktiv wirksam.

Aktivierungsreihenfolge nach Auflösung des Blockers

Master-Commit pushen und in main integrieren, unveränderliches Artefakt aktivieren, öffentliche Liveness/Readiness/OpenAPI und einen eigenen harmlosen REST-Job prüfen, den Central-Upstream atomar aktivieren, den persönlichen OAuth-Flow durchlaufen, initialize, tools/list, Start und Poll bis terminal prüfen, danach Disconnect/Revocation und Rollback proben.