DEV Community

Cover image for Was Claude Code wirklich sendet, wenn es eine App für einen osFoundry Room vorschlägt
BBT for BBT Deutsch

Posted on

Was Claude Code wirklich sendet, wenn es eine App für einen osFoundry Room vorschlägt

Das ist das Tool, das Claude Code aufruft, um eine kleine App in einen Cloud-Room in osFoundry zu bringen, so wie der Live-Server es in tools/list auflistet (ohne Token abgerufen, auf das Wesentliche gekürzt):

{
  "name": "propose_room_snippet_app",
  "description": "Prepare a Room snippet with source files. It appears in the cloud Room launcher only after its owner reviews and approves the full code in osFoundry.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "room_id": {"type": "string"},
      "name": {"type": "string", "maxLength": 200},
      "files": {"type": "object", "additionalProperties": {"type": "string"}},
      "idempotency_key": {"type": "string", "minLength": 8, "maxLength": 128}
    },
    "required": ["room_id", "name", "files", "idempotency_key"],
    "additionalProperties": false
  },
  "annotations": {"readOnlyHint": false, "destructiveHint": true, "openWorldHint": false},
  "securitySchemes": [{"type": "oauth2", "scopes": ["osfoundry:write"]}]
}
Enter fullscreen mode Exit fullscreen mode

Daneben gibt es vier weitere Room-Tools: read_room, list_room_apps (limit 1–50), read_room_app_status (braucht room_id und instance_id) und propose_room_repo_app (eine repository_id und eine version_id statt files). Alle drei lesenden Tools sind osfoundry:read und readOnlyHint: true. Beide Vorschlags-Tools sind osfoundry:write und destructiveHint: true, und genau deshalb fragt Claude Code nach, bevor es sie aufruft.

Entscheidend ist das Verb. Das Tool legt im Room nichts an. Es erstellt einen Vorschlag, und erst ein Mensch macht daraus einen Room-Tab. Im Folgenden: was das Schema erzwingt und was es dem Server überlässt, wie schwer ein Vorschlag ist, warum der Idempotency-Key Pflicht ist und wie ein Client auf einen Menschen warten sollte. Gemessen wurde alles mit einem Python-Ersatz für den Client, weil auf diesem Mac kein claude-Binary installiert ist.

Was fängt das Schema ab, und was bleibt dem Server überlassen?

room_proto.py validiert Aufrufe mit jsonschema gegen das oben gezeigte Live-inputSchema (gespeichert als tools-list.json). Zwei weitere Regeln ergeben sich daraus, wie osFoundry Snippet-Vorschläge behandelt. Der Einstiegspunkt der Room-Runtime, src/App.tsx, muss vorhanden sein. Und jeder Pfad muss ein sicherer relativer Pfad sein. Das Skript prüft beides zusätzlich zum Schema:

$ uv run --with jsonschema --with tiktoken python3 room_proto.py
== validation ==
ok               PASS
no App.tsx       REJECT  rule: src/App.tsx missing
absolute path    REJECT  rule: unsafe path '/etc/hosts'
dot-dot path     REJECT  rule: unsafe path 'src/../../x.ts'
backslash path   REJECT  rule: unsafe path 'src\\x.ts'
name 201 chars   REJECT  schema: 'nnnn…' is too long
key 7 chars      REJECT  schema: 'abcdefg' is too short
extra field      REJECT  schema: Additional properties are not allowed ('visibility' was unexpected)
non-string file  REJECT  schema: {'a': 1} is not of type 'string'
caught by published schema: 4, needs server rule: 4
Enter fullscreen mode Exit fullscreen mode

Die Hälfte der fehlerhaften Aufrufe kommt durch das JSON Schema. Pfad-Keys in einem files-Objekt lassen sich mit additionalProperties nicht einschränken. Dafür bräuchte man propertyNames mit einem Pattern, und ein Pattern, das .. nach der Normalisierung ablehnt, wird schnell hässlich. Also sagt das Schema „Map aus Strings“, und der Server beurteilt die Keys. Das additionalProperties: false auf oberster Ebene leistet dagegen echte Arbeit. Ein Modell, das sich "visibility": "public" ausdenkt, bekommt einen Schema-Fehler statt eines stillschweigend ignorierten Felds.

Wer einen Client baut, sollte dieselbe Prüfung vor dem Aufruf machen. Ein abgelehnter Vorschlag kostet einen Roundtrip und, schlimmer noch, die Output-Tokens, um die Dateien noch einmal zu schreiben.

Wie groß ist ein Vorschlag?

Die App im Beispiel ist ein Standup-Timer: src/App.tsx (63 Zeilen) und src/styles.css (14 Zeilen).

== size ==
src/App.tsx        2021 B   63 lines    583 tok
src/styles.css     1046 B   14 lines    399 tok
source bytes 3067, envelope bytes 3431, escape+frame overhead 11.9%
argument tokens (cl100k) 1141
   2 files: envelope    4463 B,   1394 tok
   6 files: envelope   12919 B,   4078 tok
  21 files: envelope   44639 B,  14143 tok
tools/list 45368 B for 59 tools; the 5 room tools 3482 B (939 tok)
Enter fullscreen mode Exit fullscreen mode

Der JSON-RPC-Envelope legt 11.9% auf den reinen Quellcode drauf, vor allem durch escapte Zeilenumbrüche und Anführungszeichen. Das sind aber nicht die Kosten, auf die es ankommt. Jedes Byte in files ist Modell-Output: Claude Code schreibt die Datei und schreibt sie dann ein zweites Mal als Tool-Argument. Ein Vorschlag mit zwei Dateien sind etwa 1,100 Tokens an Argumenten. Eine App mit 21 Dateien, gebaut durch Wiederholen derselben Komponente, sind 14,143. Gezählt wurde mit tiktoken cl100k_base, dem Tokenizer von OpenAI, die Werte sind also Näherungen.

Das Schema veröffentlicht kein Byte-Limit für files. In der Praxis setzt der Reviewer die Grenze. Die Freigabekarte zeigt jede Datei vollständig unter „Review all proposed files (N)“, jede in einer eigenen Scrollbox. Niemand liest 21 Dateien auf einer Karte. Für alles in dieser Größe passt propose_room_repo_app besser: Es verweist auf eine gepinnte Version eines GitNest-Repositorys im selben Projekt, und die Karte verlinkt auf „Review repository code before approving“, statt den Code einzufügen.

Was garantiert die Review-Schranke?

Die Tool-Beschreibung sagt es ganz direkt: Das Snippet „appears in the cloud Room launcher only after its owner reviews and approves the full code“. Im Room ist der Launcher die Tab-Leiste der Apps. Auf der Karte steht „Approval makes this code available in the Room app launcher. Review the files before approving.“ „Approve and create“ fügt den Tab ein. „Decline“ verwirft ihn. Ein offener Vorschlag kann von Room-Mitgliedern nicht geöffnet werden, ein ungeprüftes Snippet läuft also nie in irgendeiner Session.

Damit landet das Retry-Problem beim Client. Bei MCP über HTTP kann eine Antwort verloren gehen, nachdem der Server schon gehandelt hat. Wenn der Client dann mit einem neuen Key erneut sendet, bekommt der Owner zwei Karten für eine App. room_proto.py bildet das mit einem In-Memory-Server nach, der Vorschläge nach Key speichert, mit 1,000 Vorschlägen und einer Wahrscheinlichkeit von 5%, dass eine Antwort verloren geht:

== review gate, 1000 proposals, 5% lost responses ==
random   calls 1074  owner cards 1074  duplicates 74  in launcher before approval 0
content  calls 1057  owner cards 1000  duplicates 0  in launcher before approval 0
Enter fullscreen mode Exit fullscreen mode

Mit einer neuen UUID pro Versuch sind 74 der 1,074 Karten Duplikate, die der Owner erkennen und ablehnen muss. Mit einem aus dem Inhalt abgeleiteten Key, "snip-" + sha256(room_id, name, files)[:32], trägt ein Retry denselben Key, und die Zahl der Duplikate ist 0. Eine bewusste Änderung an den Dateien ergibt einen neuen Key und eine neue Karte, und genau das will man. Das Minimum von 8 Zeichen im Schema hält Keys wie "1" draußen. In keinem der beiden Durchläufe ist vor der Freigabe etwas im Launcher gelandet. Das ist Aufgabe des Servers, nicht des Clients.

Wie sollte Claude Code auf den Owner warten?

initialize liefert "capabilities": {"tools": {"listChanged": false}} und sonst nichts. Es gibt keinen Push à la „dein Vorschlag wurde freigegeben“. Der Client hat drei Möglichkeiten. Er kann den Nutzer bitten, Bescheid zu geben, sobald er freigegeben hat, er kann read_room_app_status pollen (oder list_room_apps, bis die neue Instanz auftaucht), oder er kann poll_resource_events für den Room fortsetzen, das resource_type: "room" akzeptiert. Ohne Token habe ich nicht überprüft, welche Events eine Freigabe dort schreibt, deshalb pollt die Simulation den Status.

Die Eingangsgröße ist die Zeit, die ein Mensch fürs Review braucht. Das Skript zieht sie aus einer Log-Normalverteilung mit einem Median von 6 Minuten und einem Budget von einer Stunde. Das ist eine Annahme, keine Messung, aber die Form (die meisten antworten innerhalb von Minuten, ein paar brauchen eine halbe Stunde) ist der realistische Teil:

== polling while the owner reviews (n=2000, median review 6 min, 1 h budget) ==
review delay p50 357s  p95 1816s
fixed 5s                   calls mean  111.8  lag p50   2.4s  p95    4.7s  gave up 14
fixed 30s                  calls mean   19.0  lag p50  14.5s  p95   28.4s  gave up 14
backoff 5s x1.5 cap 120s   calls mean   10.8  lag p50  47.0s  p95  111.0s  gave up 14
backoff 10s x2 cap 300s    calls mean    6.1  lag p50 105.2s  p95  273.8s  gave up 14
Enter fullscreen mode Exit fullscreen mode

Wer alle 5 Sekunden pollt, bemerkt die Freigabe innerhalb von 5 s, bei 112 Aufrufen pro Vorschlag, und jeder Aufruf ist ein Modell-Turn, der für Tool-Output draufgeht. Ein festes Intervall von 30 Sekunden sind 19 Aufrufe mit 28 Sekunden im schlechtesten Fall. Backoff bis zu einer Obergrenze von 2 Minuten drückt das auf 11 Aufrufe, bei einer p95-Verzögerung von 111 s. 14 der 2,000 Reviews dauerten länger als eine Stunde, und bei denen gaben alle Strategien gleichermaßen auf. In einer interaktiven Session ist die günstigste korrekte Antwort null Aufrufe: den Turn mit „approve it under Connected → Needs your approval and tell me“ beenden und danach einen einzigen list_room_apps-Aufruf machen. Polling lohnt sich nur, wenn Claude Code zwischendurch anderes zu tun hat.

Echte Roundtrips zur Einordnung: je zehn nicht authentifizierte Aufrufe von diesem Mac in Japan an den Live-Endpoint.

$ python3 probe.py
initialize                       HTTP 200     308 B  median    680 ms  min   358  max   968
tools/list                       HTTP 200   45368 B  median    687 ms  min   429  max  1253
tools/call read_room (no token)  HTTP 401     337 B  median    559 ms  min   427  max   847
  www-authenticate: Bearer resource_metadata="https://api.osfoundry.io/.well-known/oauth-protected-resource/api/v1/external-mcp", error="invalid_token", error_description="Connect osFoundry to continue"
Enter fullscreen mode Exit fullscreen mode

Etwa 0.6 s pro Aufruf. Eine 5-Sekunden-Schleife verbringt also ein Zehntel ihrer Zeit im Netzwerk, und ein Modell-Turn pro Aufruf kostet deutlich mehr als das.

Was bedeutet „build state“ bei einem Snippet?

read_room_app_status liefert „the safe launcher and latest build state of one app“, ohne Config, Dateien, Logs oder Secrets. Ein Snippet hat keinen Server-Build. Der Room kompiliert die Dateien dort, wo der Tab geöffnet wird: in der Desktop-App in einem sandboxed iframe mit Sucrase, im Browser in einer Sandpack-Sandbox. Der Repository-Weg ist ebenfalls gepinnt, und seine Freigabekarte sagt „This path does not build or deploy a bundle.“ Bei beiden Vorschlagsarten ist der Launcher-Eintrag das, worauf man wartet. Ein Build-State erscheint erst, wenn jemand den Tab deployt, und das passiert in osFoundry.

Warum kommt es nicht an einen lokalen Room heran?

read_room sagt „Local Rooms are unavailable“, und initialize enthält die allgemeine Regel: „Local-only data is unavailable to cloud clients.“ Ein lokaler Room liegt in der eigenen Datenbank der Desktop-App und wird nie synchronisiert. Der MCP-Endpoint ist ein Cloud-Dienst mit einem auf den Workspace beschränkten OAuth-Token und hat keinen Weg zu einem bestimmten Laptop. Um dorthin zu kommen, bräuchte es ein Relay, das die Desktop-App betreibt: pro Gerät und Projekt aktiviert, mit Online/Offline-Status und einer Allowlist von Befehlen. Die Tool-Oberfläche tut nicht so, als wäre es anders. Dieselbe Grenze gilt für Daten innerhalb eines Snippets. Dessen SDK-Speicher bleibt auf dem Gerät der Person, die den Tab nutzt, und keines der lesenden Tools liefert Datenbankinhalte zurück.

Wenn du das selbst verdrahtest

  • Validiere Pfad-Keys auf dem Server, auch wenn du ein Schema veröffentlichst. JSON Schema kann „Map aus Strings“ beschreiben, aber nicht „sicherer relativer Pfad“, und in diesem Test war die Hälfte der fehlerhaften Aufrufe ein Pfadproblem.
  • Leite den Idempotency-Key aus dem Inhalt ab, nicht aus dem Versuch. Verlorene Antworten kosten dann nichts, und eine echte Änderung bekommt trotzdem ihre eigene Karte.
  • Lass die Aufmerksamkeit des Reviewers das Größenlimit bestimmen. Wenn die Karte jede Datei zeigt, halte Snippets bei einer Handvoll Dateien und schicke größere Apps als gepinnte Repository-Version.
  • Lass den Agenten standardmäßig nicht auf einen Menschen pollen. Lass ihn seinen Turn beenden und einmal den Status lesen, wenn der Nutzer zurückkommt, und nutze Backoff nur, wenn er anderes zu tun hat.
  • Halte das Zurücklesen schlank. Gib Identität und Launcher-Status zurück, nie Config oder App-Daten, damit Status-Abfragen nicht zum Weg werden, zu lesen, was Leute gespeichert haben.
  • Schreib in die Tool-Beschreibung, was außer Reichweite ist („Local Rooms are unavailable“), damit das Modell es dem Nutzer sagt, statt es erneut zu versuchen.

Die Room-Seite mit Tab-Leiste und Einstellungen findest du auf der Room-Seite. Zum Protokoll allgemein siehe den MCP-Glossareintrag.

Top comments (0)