Entwickler-Tools

Für Entwickler. Wähle im Entwicklerhandbuch zwischen API-Anbindung, App-Veröffentlichung und Projektarbeit.

Diese Tools sind für Menschen, die Apps veröffentlichen. Du kannst deine App prüfen, beweisen, dass du sie kontrollierst, den Zugang mit deinem Team teilen, private Tests ausführen, die Aufnahme in den Index anfordern und Hinweise bekommen, wenn etwas kaputtgeht.

Nur der Aufruf zur Prüfung ist öffentlich. Alle anderen Aufrufe brauchen ein Nutzer-Token oder das Session-Cookie, und publish auf App. Siehe Authentifizierung.

IDs für Claims, Nachweise, Mitglieder, Berichte und Indexanfragen müssen UUID-Text sein. Das gilt auch für den Seitencursor before und die Vergleichs-ID other bei Berichten. Alte UUID-v4- und neue UUID-v7-Werte funktionieren. Die API weist anderen Text vor dem Zugriff auf die Speicherung zurück. Bearer-Tokens für Einladungen und Hinweis-IDs behalten ihre eigenen Formate.

---

Eine App prüfen

Jeder kann eine App prüfen. Du musst dich nicht anmelden. Die Prüfung liest nur öffentliche Dokumente. Sie speichert nichts und verbindet sich nicht mit der App.

curl -X POST https://api.example.com/v1/developer/inspect \
  -H "Content-Type: application/json" \
  -d '{ "input": "apps.example.com" }'

input kann eine Domain oder ein HTTPS-Link sein, bis zu 8192 Zeichen. Der Bericht hat:

Feld	Beschreibung
apps	Jede gefundene App. eligibility ist Eligible, Excluded oder Unconfirmed für den öffentlichen Index. stored zeigt die letzte gespeicherte Prüfung für den Index, wenn es eine gibt.
issues	Probleme, die du beheben sollst. Jedes hat einen code, eine stage, eine severity (blocking oder suggestion), eine message und einen Hinweis repair zur Reparatur.
stages	Jeder Prüfschritt: Input, Discovery, CardRead, CardSchema, Compatibility, PublisherAssociation und Eligibility. Jeder ist Passed, Failed, Unconfirmed oder NotChecked.

Ein Ergebnis Eligible heißt nicht, dass die App schon im Index ist. Siehe App Index.

---

Beweisen, dass du eine App kontrollierst

Die meisten Tools brauchen einen Beweis, dass du die App kontrollierst. Du kannst die Kontrolle auf zwei Arten beweisen:

Umfang	Was er abdeckt	Wo du das Token hinlegst
PublisherHostname	Jede App, deren Card auf diesem Host-Namen liegt und in einem Catalog auf demselben Host-Namen gelistet ist.	Ein DNS-TXT-Eintrag
AppCard	Eine App, über ihre genaue Card URL.	Die Server Card

Einen Anspruch starten

curl -X POST https://api.example.com/v1/developer/claims \
  -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "_tag": "PublisherHostname", "hostname": "apps.example.com" }'

Für eine einzelne App schickst du { "_tag": "AppCard", "cardUrl": "https://apps.example.com/mcp/server-card" }. Der Host-Name muss genau ein öffentlicher Name sein, ohne Port, Pfad oder Platzhalter.

Die Antwort hat eine id und ein token wie openbot-verification=.... Der Anspruch (Claim) gilt 24 Stunden.

Das Token veröffentlichen

Für einen Host-Namen fügst du einen DNS-TXT-Eintrag bei _openbot-verification.<hostname> hinzu. Nutze das ganze Token als Wert:

_openbot-verification.apps.example.com.  TXT  "openbot-verification=abc123..."

Für eine einzelne Card fügst du das Token zur Card hinzu:

{
  "_meta": {
    "openbot/developer-verification": {
      "version": 1,
      "tokens": ["openbot-verification=abc123..."]
    }
  }
}

OpenBot liest die Card an ihrer genauen URL, ohne Weiterleitungen. Deine robots.txt muss den User-Agent OpenBot erlauben.

Bestätigen

curl -X POST https://api.example.com/v1/developer/claims/<claim id>/verify \
  -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"commandKey":"proof-check-1"}'

Die API gibt 202 mit einer executionId zurück. Nutze denselben commandKey, wenn die Antwort verloren geht. Lies /v1/executions/:executionId oder folge seinen Ereignissen. Nach dem Abschluss liest du den Beweis mit GET /v1/developer/proofs/<claim id>. Du wirst administrator für diesen Umfang. Ein Fehler hat eine sichere Fehlerklasse und eine errorId. Die volle Ursache bleibt im verschlüsselten Fehlerdatensatz. Ein fehlendes Token oder ein abgelaufener Anspruch gibt conflict. Ein Netzwerkfehler gibt external. Das Schließen des Ereignisstroms stoppt die Prüfung nicht. Nutze dafür den Endpunkt zum Abbruch der Ausführung.

Das SDK hat Proofs.verifyClaim(id) und Proofs.verifyProof(id). Beide geben einen Befehl mit einem festen Schlüssel und einem send-Effect zurück. Nutze denselben Befehl für einen neuen Versuch.

Lass das Token an seinem Platz. Ein Beweis gilt 7 Tage, und OpenBot prüft ihn jeden Tag noch einmal:

• Wenn das Token weg ist, wird der Beweis sofort Suspended.
• Wenn die Prüfung nicht laufen kann, wird der Beweis Unconfirmed. Er funktioniert weiter, bis er abläuft. OpenBot versucht es nach etwa einer Minute noch einmal.
• Ein Beweis mit Suspended gibt keinen Zugang.

Um jetzt zu prüfen, rufe POST /v1/developer/proofs/:id/verify mit einem neuen commandKey auf. Auch das gibt einen Ausführungsbeleg zurück. Um einen Beweis aufzugeben, rufe POST /v1/developer/proofs/:id/relinquish auf. Um einen Anspruch abzubrechen, rufe POST /v1/developer/claims/:id/revoke auf.

GET /v1/developer gibt deine Apps, deine Beweise und deine Zugänge in grants zurück.

---

Mitglieder und Rollen

Der Administrator kann andere Konten einladen.

Rolle	Was sie tun können
administrator	Das Konto, das den Beweis erbracht hat. Alles, auch Mitglieder verwalten.
maintainer	Berichte speichern, Tests ausführen und die Aufnahme in den Index anfordern.
viewer	Apps, Berichte und Anfragen zur Aufnahme lesen. Keine Änderungen.

1. Einladen: POST /v1/developer/proofs/:id/invitations mit { "role": "maintainer" } oder "viewer". Die Einladung gilt 7 Tage.
2. Schicke die id der Einladung an die Person. Sie liest sie mit GET /v1/developer/invitations/:id und nimmt sie mit POST /v1/developer/invitations/:id/accept an.
3. Verwalten: GET /v1/developer/proofs/:id/members, PUT /v1/developer/members/:id mit einer neuen role und DELETE /v1/developer/members/:id. Mitglieder können sich auch selbst entfernen.

Um eine Einladung abzubrechen, rufe POST /v1/developer/invitations/:id/revoke auf. Wenn ein Beweis endet, verlieren auch seine Mitglieder den Zugang.

---

Berichte

Ein Bericht ist eine gespeicherte Prüfung. Nutze Berichte, um zu sehen, wie sich deine App mit der Zeit ändert.

Aufgabe	Request
Einen neuen Bericht speichern	POST /v1/developer/reports mit { "cardUrl" }
Berichte für eine App auflisten	GET /v1/developer/reports?cardUrl=... (neueste zuerst, 50 pro Seite, Seiten mit before)
Einen Bericht lesen	GET /v1/developer/reports/:id
Zwei Berichte vergleichen	GET /v1/developer/reports/:id/compare?other=<id>
Einen Bericht löschen, den du gespeichert hast	DELETE /v1/developer/reports/:id
Berichte auflisten, die du gespeichert hast	GET /v1/developer/personal-reports

Ein Vergleich listet die Probleme, die introduced (neu), resolved (behoben) und persisting (geblieben) sind.

---

Private Tests der Verbindung

Ein Test verbindet sich von OpenBot aus mit deiner App, so wie ein Nutzer. Er ist privat. Er speichert keine Connection eines Nutzers und fügt die App nicht zum Index hinzu. Ein Test endet nach einer Stunde.

1. Erstelle einen Test mit deiner eigenen UUID: POST /v1/developer/tests mit { "id", "cardUrl", "remoteIndex" }.
2. Wenn der Endpoint Einstellungen braucht, schicke sie: PUT /v1/developer/tests/:id/configuration mit einem Objekt aus Keys und Werten. Die Keys sind dieselben wie bei Connections.
3. Starte ihn mit POST /v1/developer/tests/:id/run und { "commandKey": "test-run-1" }. Die Antwort ist 202 mit einem Beleg für die Ausführung. Lies den Test mit GET /v1/developer/tests/:id und die gespeicherten Ereignisse mit GET /v1/executions/:executionId/observe.

Nutze denselben Befehlsschlüssel, wenn eine Antwort verloren geht. Ein neuer Schlüssel startet nach dem Ende des letzten Laufs einen neuen Lauf. Der Test behält seine letzte executionId. DeveloperTests.run(id) im SDK erstellt einen Befehl. Seine Methode send nutzt den Schlüssel erneut. Das Schließen des Ereignisstroms stoppt den Test nicht. Brich ihn über die Ausführungs-API ab, oder nutze die Testbereinigung. Diese stoppt den Lauf und wartet auf die Freigabe der Verbindung, bevor sie private Daten löscht. Ein weiterer Serverstart ändert keinen aktiven Workflow-Lauf. Nach dem Verlust eines Knotens nutzt der Lauf bereits gespeicherte Ergebnisse. Ein offener Leseaufruf darf erneut laufen.

Jeder Lauf hat stages: configuration, negotiation, tools, resources, resourceTemplates und prompts. Jede Stufe ist Passed, Failed, NotAdvertised oder NotChecked. Der status des Tests endet als Succeeded oder Failed.

Während eines Tests anmelden

Wenn die App ein Konto braucht, wird der Status des Tests AwaitingAuthorization.

1. Starte die Anmeldung: POST /v1/developer/tests/:id/authorization mit { "scopes": [], "commandKey": "test-sign-in-1" }. Füge issuer hinzu, wenn die App mehrere Anbieter hat. Die Antwort ist 202 mit einem Beleg. Folge den Ereignissen und lies danach authorization.authorizationUrl aus dem Test. PreparingAuthorization zeigt, dass die Arbeit noch läuft. Link und verschlüsselter Flow werden zusammen gespeichert. Nutze den Schlüssel nach einer verlorenen Antwort erneut. Der SDK-Helfer DeveloperTests.authorize(id, { scopes: [] }) behält ihn.
2. Öffne authorization.authorizationUrl in deinem Browser und melde dich an.
3. Der Anbieter schickt dich zu /auth/developer/apps/callback. OpenBot schickt dich dann zu /?developerTest=<testId>.
4. Beende es mit POST /v1/developer/tests/:id/authorization/complete und einem neuen commandKey. Die Antwort ist ein 202-Ausführungsbeleg. Bei verlorener Antwort nutze denselben Schlüssel. DeveloperTests.completeAuthorization im SDK behält ihn. Warte auf das Ende, lies den Test und starte ihn erneut.

Der Austausch behält den Aufrufer vom Beginn der Anmeldung als Rechtegrenze. Vor der Nutzung eines gespeicherten Ergebnisses werden seine Rechte und die des abschließenden Aufrufers geprüft. Codes und Tokens bleiben verschlüsselt. Ein Verbindungsabbruch stoppt keinen eingereichten Austausch. Bei unbekanntem Ergebnis wartet die Ausführung auf eine Entscheidung über die Ausführungs-API. OpenBot sendet den Code nicht selbst erneut. Nicht installierte Tokens erhalten einen Auftrag zum Aufräumen durch die Plattform.

Wenn du fertig bist, rufe POST /v1/developer/tests/:id/cleanup mit einem commandKey auf. Der Endpunkt cancel nutzt denselben Body. Beide geben 202 mit einem Ausführungsbeleg zurück. DELETE /v1/developer/tests/:id?commandKey=... gibt auch einen Beleg zurück. Behalte den Schlüssel bei einem neuen Versuch. Das SDK bietet DeveloperTests.cleanup, cancel und remove.

cleanupExecutionId nennt den Dienst, der Ablauf und Aufräumen des Tests verwaltet. Beobachte ihn über die Ausführungs-API. Der Test bleibt Cancelling, solange Arbeit oder das Aufräumen von Tokens läuft. Ist das Ergebnis eines Code-Austauschs unbekannt, braucht dessen Ausführung erst eine Entscheidung. Dann zieht OpenBot die Anmeldung zurück, wo der Anbieter das erlaubt. Private Daten und der Abschluss werden in einer Transaktion geändert. Ein Löschbefehl entfernt dabei auch den Test. Das Ende der Beobachtung hält das Aufräumen nicht an.

Das Aufräumen sichert alle gespeicherten Tokens in verschlüsselten Aufträgen, bevor es die lokale Anmeldung entfernt. Die gemeinsame Bereinigung der Zugangsrechte führt Aufrufe beim Anbieter und neue Versuche aus. Private Testdaten bleiben bis zum Ende dieser Arbeit erhalten. cleanupRemote wird nur nach der bestätigten Rücknahme zu Complete. Hat der Anbieter keine Möglichkeit zur Rücknahme, steht dort LocalOnly.

Derselbe Dienst hält den gespeicherten Ablauf-Timer. Er prüft einmal pro Minute, ob der Test noch Zugriff auf die App hat. Er räumt auch nach dem Entzug des Zugriffs auf. Ein Serverneustart setzt weder Tests noch Anmeldevorgänge zurück.

---

Ein OAuth-Test behält den Grund für einen abgelehnten Schritt, etwa FlowExpired oder CallbackMismatch. Eine nicht nutzbare Verbindung ergibt ConnectionUnavailable. Fehlt der Test, kommt 404 DeveloperNotFound. Netz- und Speicherfehler ergeben 503 DeveloperUnavailable.

Die Aufnahme in den Index anfordern

Du musst nicht warten, bis ein Nutzer deine App verbindet. Bitte OpenBot, sie zu prüfen:

curl -X POST https://api.example.com/v1/developer/indexing \
  -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cardUrl": "https://apps.example.com/mcp/server-card", "commandKey": "index-check-1" }'

OpenBot prüft zuerst deine aktuellen Rechte und die App-Beschränkung. Eine gesperrte App gibt 403 DeveloperRestricted zurück. Die öffentliche Prüfung läuft im Hintergrund und speichert ihr Ergebnis.

Behalte commandKey, wenn eine Antwort verloren geht. Derselbe Schlüssel gibt dieselbe Anfrage zurück. Jede Anfrage hat eine executionId. Lies oder beobachte sie über /v1/executions/:executionId. Nutze den Endpunkt zum Abbrechen der Ausführung. Dein Abbruch beendet nicht die gemeinsame öffentliche Prüfung.

Der status der Anfrage beschreibt die gemeinsame Prüfung: Waiting, Verifying, dann Completed. check enthält das Ergebnis. Der Ausführungsdatensatz zeigt den Zustand deiner Anfrage, auch Abbruch und Fehler. Liste Anfragen mit GET /v1/developer/indexing auf oder lies eine mit GET /v1/developer/indexing/:id. Eine fertige Anfrage behält ihr Ergebnis bei späteren Prüfungen und Neustarts.

---

Benachrichtigungen

OpenBot prüft die Apps, die du verwaltest, etwa jede Stunde. Es schickt dir einen Hinweis, wenn sich etwas ändert.

Regelmäßige App- und Beweisprüfungen nutzen den gemeinsamen Ausführer. PostgreSQL speichert die nächste Prüfzeit und jedes Ergebnis. Ein neuer Server setzt mit diesen Daten fort. Der Beweisstatus und die Zugriffsmitteilungen werden in einer Transaktion gespeichert. Ein älteres Ergebnis ersetzt keinen neueren Beweisstatus. Das erneute Lesen eines gespeicherten App-Ergebnisses sendet keine doppelte Mitteilung.

Art	Wann
IssueAppeared	Ein neues blockierendes Problem erscheint.
IssueResolved	Ein blockierendes Problem verschwindet.
AccessChanged	Ein Beweis ändert seinen Zustand, oder du verlierst den Zugang als Mitglied.

Lies Hinweise mit GET /v1/developer/notifications. Nutze before, um ältere Seiten zu lesen. Markiere einen als gelesen mit POST /v1/developer/notifications/:id/read.

Hinweise zu Problemen sind für jede App an. Um sie für eine App auszuschalten, schicke PUT /v1/developer/subscriptions mit { "cardUrl": "...", "enabled": false }. Liste deine Einstellungen mit GET /v1/developer/subscriptions auf.

Die vollständigen Formen findest du in der API-Referenz.

Die Datenmigration behält bestehende Ansprüche, Nachweise, Mitglieder, Einladungen, Apps, Berichte und Nachrichteneinstellungen. App- und Nachweisprüfungen behalten ihren nächsten Prüftermin. Ein aufgegebener Nachweis startet keine neue Prüfung. Alte Indexanfragen behalten ihre IDs und erhalten eine Ausführung für ihren Verlauf. Ein gespeichertes Ergebnis bleibt abgeschlossen. Eine Anfrage ohne Ergebnis wird unterbrochen, da der ursprüngliche Aufrufer fehlt. Die Plattform kann die getrennte öffentliche Prüfung abschließen.