MCP-Tool- & Sheet-Referenz
Serveroberfläche
Die v0.31-Serveroberfläche stellt über https://app.confbuild.com/mcp 39 Modellierungs-Tools, einen wiederverwendbaren Prompt, einen Skill-Katalogeintrag für Plugin-Import-Scans und 60 Ressourcen bereit. Welche Tools eine Verbindung sieht, legt das Toolset fest: modeling (Standard) enthält alle Projekt-, Render-, Export- und Vergleichs-Tools; ?toolset=video auf der MCP-URL (https://app.confbuild.com/mcp?toolset=video) listet die neun Video-Studio-Tools samt gemeinsamer Basis, ?toolset=all beides (48 Tools). Nicht gelistete Tools lassen sich auf dieser Verbindung nicht aufrufen; confbuild_start_design_session meldet das aktive Toolset. Neu in v0.30 sind außerdem die Sichtbarkeits- und Übernahmelogik des Browser-Kanals, asynchrone Checkpoints, deterministische Reparatur-Operationen und der Finish-Probelauf — jeweils bei den betroffenen Tools beschrieben. Der Katalog installiert den Skill nicht bei einer direkten MCP-Verbindung; confbuild-mcp-agent wird mit dem confBuild-Plugin gebündelt. Der Transport ist Streamable HTTP mit OAuth/PKCE. Strukturierte Ergebnisse erscheinen als MCP-Text und structuredContent, Screenshots zusätzlich als native Bildblöcke. Der lokale STDIO-Transport stellt dieselbe fachliche Oberfläche für Entwickler bereit.
Der wiederverwendbare Prompt heißt confbuild-design. Er weist den Client an, zuerst confbuild_start_design_session aufzurufen und den kompletten Erstellen-/Bearbeiten-/Render-Loop durchzuführen.
OAuth-Zugriff wird je Tool erzwungen: mcp deckt Protokoll und Prompts ab, projects:read Projekt- und Session-Lesezugriffe, projects:write Mutationen und render Render-/Exportjobs samt Artefaktauslieferung. Ein neuer Render oder Export braucht projects:read und render; ein fehlender Scope liefert INSUFFICIENT_SCOPE mit den konkret fehlenden Berechtigungen.
Der Server kündigt io.modelcontextprotocol/skills an. skills/list und skills/get liefern den vollständigen Skill samt Ressourcenmanifest und SHA-256-Digests; resources/read liefert jede deklarierte Datei. Nach aktueller OpenAI-Spezifikation verwendet Scan Tools diese Oberfläche für einen statischen Plugin-Import – nicht als Laufzeit-Installation im verbundenen Client. Direkte MCP-Verbindungen verwenden den Prompt confbuild-design als kompatiblen Einstieg.
Tools nach Phase
Orientierung und Prompts
| Tool | Zweck | Schreibend |
|---|---|---|
confbuild_start_design_session |
Verpflichtender erster Aufruf; erkennt Profil, löst optional das Ziel auf und liefert das Prompt-Bundle | Nein |
confbuild_plan_sheet_topology |
Deklariert vor jeder Mutation ein einzelnes unteilbares Sheet oder eine Composite-Struktur aus Main Part und funktionalen Child-Sheets |
Nein |
confbuild_get_prompt_sections |
Lädt Profil und ausgewählte semantische Prompt-Pakete für eine direkte Design-Session nach; optionale maxChars/offsetChars-Fenster |
Nein |
confbuild_explain_row_type |
Kanonische Header-Spalten, Beispielzeilen, Platzierungshinweise und der Doku-Auszug zu einem Zeilentyp (z. B. gear, aluprofile, pneumatic) — günstiger als das ganze Katalogpaket zu laden |
Nein |
confbuild_get_prompt_bundle |
Ruft ein Prompt-Bundle unabhängig von einer Design-Session ab | Nein |
confbuild_list_prompt_resources |
Listet Prompt-Ressourcen mit URI, Größe, MIME-Typ und SHA-256 | Nein |
Wichtige Eingaben für confbuild_start_design_session:
{
"request": "Vollständige Nutzeranfrage",
"projectReference": "optionale ID oder URL",
"client": "codex",
"model": "exakte öffentliche Modell-ID, falls bekannt",
"profile": "machine",
"promptDetail": "progressive",
"knownBundleHashes": ["sha256 eines bereits vorliegenden Bundles"],
"knownSectionHashes": ["sha256 bereits gecachter Bundle-Sektionen"]
}
Der Client klassifiziert die Domäne selbst und übergibt ein explizites profile (building, machine, 3dprint, structure für Hallen/Rahmen/Fachwerke, furniture, generic); auto löst nur einen Keyword-Fallback für Clients aus, die nicht klassifizieren können. Im Standardmodus liest er den kompakten Basiskontext, ruft confbuild_get_prompt_sections mit der designSessionId und den IDs aus progressiveLoading.requiredBeforeEditing auf und lädt anschließend nur tatsächlich benötigte Pakete. nextProjectTool zeigt den danach folgenden Projektaufruf. knownBundleHashes kann den bereits bekannten Basiskontext vollständig unterdrücken; knownSectionHashes unterdrückt bekannte Basis-, Profil- oder Pakettexte. essential und full bleiben als monolithische Kompatibilitätsmodi verfügbar.
Zugriff und Projekte
| Tool | Zweck | Schreibend |
|---|---|---|
confbuild_auth_status |
Prüft die OAuth-gebundene confBuild-Identität, ohne Token offenzulegen | Nein |
confbuild_resolve_project_reference |
Löst eine ID oder URL als eigenes privates oder öffentliches Projekt auf | Nein |
confbuild_create_project |
Erstellt ein privates Projekt, optional bereits mit Sheets | Ja |
confbuild_clone_project |
Kopiert ein öffentliches/schreibgeschütztes Projekt privat | Ja |
confbuild_read_project |
Liest Metadaten und hydratisierte Sheets, optional gefiltert | Nein |
confbuild_create_project und confbuild_clone_project unterstützen einen idempotencyKey. Derselbe Schlüssel im selben Nutzerkonto führt bei Wiederholung zur selben deterministischen Projekt-ID.
model ist optional. Der Client soll nur seine exakte öffentliche Modell-ID melden und das Feld sonst weglassen; der Server rät kein Modell. designSessionId soll an Erstellen, Klonen und Begin Edit weitergegeben werden.
Der Wert request in confbuild_start_design_session wird unverändert in der admin-only MCP-Historie gespeichert. Clients sollen dort ausschließlich den eigentlichen Nutzerauftrag übergeben, kein internes Reasoning, keine Screenshot-Analyse und keine Zugangsdaten. Nach erfolgreichen Commits speichert der Server zusätzlich den jeweils neuesten Sheet-Stand; Zwischen-Patches werden nicht als Historieneintrag archiviert.
Unabhängig davon führt der Server eine inhaltsfreie Usage-Statistik: Tool, Zeit, Nutzer-/Client-ID, optional gemeldetes Modell beim Start, Status/Fehlercode, Dauer, Bytes, Sheet-/Zeilen-/Zellmengen, Commits, Projekt- und Renderaktivität. Prompttexte, Zellwerte, Bilder und Reasoning werden nicht in diese Statistik kopiert. KI-Token des MCP-Clients sind für den Server technisch nicht sichtbar.
MCP-erstellte und -bearbeitete Projekte erhalten unter metadata.agentMcp eine kompakte Herkunftsmarkierung: erstellt/bearbeitet, Zeitpunkte/Zähler, Client/Tool, optional gemeldetes Modell, Profil und MCP-Clientname/-version. Der Admin-Bereich zeigt diese Felder in „MCP History“ und „Recent user work“; die Markierung enthält keine Prompts, Sheet-Werte, Screenshots, Antworten oder Reasoning-Inhalte.
confbuild_read_project kann Kontext begrenzen:
{
"reference": "PROJEKT_ID",
"sheetNames": ["Main Part", "Frame"],
"maxRowsPerSheet": 500
}
Wenn truncated: true zurückgegeben wird, darf ein Client das betroffene Sheet nicht vollständig ersetzen, bevor er es ohne Begrenzung gelesen hat.
Editieren und Speichern
| Tool | Zweck | Schreibend |
|---|---|---|
confbuild_begin_edit |
Lädt das vollständige Workbook und seine Basisrevision in eine temporäre Edit-Session | Nur bei automatischem Klonen |
confbuild_apply_sheet_patch |
Wendet bis zu 1.000 Operationen auf die Session-Arbeitskopie an, darunter die deterministischen Reparaturen wire_child, set_default_material und auto_fix; jede serverseitige Umschreibung steht in normalizations; noch kein Projekt-Commit |
Nur Sessionzustand |
confbuild_read_edit_workbook |
Liest die aktuelle Session-Arbeitskopie, optional nach Sheet-Namen | Nein |
confbuild_validate_edit |
Prüft zusätzlich Sheet-Topologie, zyklische/verwaiste Subsheets und Parent→Child-Parameterverträge sowie Struktur, Marker, IDs, Serialisierung, Größenlimits, Engine-Fallen-Lint und Konfigurations-Shadowing | Nein |
confbuild_commit_edit |
Speichert Workbook und scriptcode atomar mit optimistischem Revisionsschutz und zwingendem Pre-Commit-Rollback-Snapshot |
Ja |
confbuild_publish_checkpoint |
Schnellweg für eine kohärente Modellstufe: Patch, einmalige Validierung, atomarer Commit mit Rollback-Snapshot und In-Place-Rebuild im verbundenen sauberen Tab; kehrt standardmäßig direkt nach dem Speichern zurück (editorRevisionPending: true), der Tab baut im Hintergrund neu |
Ja |
confbuild_discard_edit |
Verwirft die temporäre Edit-Session; Commits bleiben erhalten | Session destruktiv |
confbuild_find_rows |
Sucht Zellinhalte (Teilstring/exakt/Regex, optional auf Spalten begrenzt) über die Sheets einer Edit-Session oder eines Projekts und liefert Treffer mit Sheet, Zeile, Spalte und Zeilenvorschau | Nein |
confbuild_list_edit_sessions |
Listet die eigenen offenen Edit-Sessions (Projekt, dirty-Status, Commit-Zähler, Ablauf) — eine verlorene editSessionId lässt sich so wiederfinden statt die Session zu verlieren |
Nein |
confbuild_list_project_snapshots |
Listet die Rollback-Snapshots eines eigenen Projekts, neueste zuerst | Nein |
confbuild_restore_project_snapshot |
Committet Workbook und scriptcode eines Snapshots als neue Revision; der Vorzustand wird zuerst gesichert |
Ja |
confbuild_diff_revisions |
Sheet-Zeilendifferenz plus inhaltsfreier SHA-256-/Größenvergleich des scriptcode zwischen Revisionen |
Nein |
confbuild_update_scene_settings |
Liest oder ändert project.sceneSettings (Grundlicht, Sonne, Environment-Map, Hintergrund, Nebel, Rendermodus, Ansichtsschalter), die keine Sheet-Zeile ausdrücken kann; revisionsgeschützt, liefert die Vorwerte als Rollback und wendet den Look ohne Rebuild im verbundenen Tab an |
Ja |
confbuild_create_project, confbuild_clone_project und confbuild_begin_edit sollten immer die von confbuild_start_design_session erhaltene designSessionId bekommen. Dadurch bleiben Attribution, Nutzerauftrag und committed Sheets auch bei mehreren parallelen Agenten eindeutig derselben Historie zugeordnet.
confbuild_commit_edit kann zusätzlich Projektfelder ändern:
{
"editSessionId": "edit-…",
"mutationId": "stable-client-mutation-42",
"projectPatch": {
"name": "Portalfräse 800",
"projectType": "machine-component",
"description": "Parametrische Portalfräse",
"metadata": { "source": "mcp-client" }
}
}
Jeder Commit sichert Workbook und Projekt-scriptcode vor der Änderung gemeinsam als Rollback-Snapshot (preCommitSnapshotId im Ergebnis). Diese Sicherung ist zwingend: Das alte Feld "snapshot": false wird nur noch kompatibel akzeptiert und ignoriert; schlägt die Snapshot-Erstellung fehl, bleibt das gespeicherte Projekt unverändert. Die Aufbewahrung behält die neuesten Snapshots pro Projekt und räumt ältere automatisch auf. Ein Restore committet den Snapshot als reguläre neue Revision und sichert vorher den ersetzten Zustand — er ist damit selbst rückgängig machbar. Alte Workbook-only-Snapshots bleiben lesbar und erhalten beim Restore ausdrücklich den aktuellen Quellcode.
confbuild_publish_checkpoint kehrt seit v0.30 standardmäßig direkt nach dem atomaren Speichern zurück (waitForEditorMs: 0): editorRevisionPending: true bedeutet, dass der verbundene saubere Tab die Revision angenommen hat und im Hintergrund neu baut; nextTool ist die normale Fortsetzung der Stufe. Render-, Inspektions-, Interaktions- und Export-Starts warten höchstens wenige Sekunden auf die exakte Revision und reihen sich sonst hinter dem laufenden Rebuild ein (editorRevisionPending im Poll). Ein zusätzlicher confbuild_prepare_browser-Aufruf ist nur nötig, wenn ein Ergebnis BROWSER_TAB_REQUIRED oder eine Nutzeraktion meldet.
Ab der Stufe interfaces startet ein Checkpoint außerdem standardmäßig einen asynchronen, rein diagnostischen Engine-Check der gespeicherten Revision im verbundenen Tab (engineCheck: 'async'; false für die frühen Stufen, true wartet im Aufruf). Das Ergebnis — Zeilen ohne Geometrie, verwertbare Engine-Warnungen, Platzierungs-Audit und Defektsignale — erscheint einmalig als previousEngineCheck am nächsten Patch-, Checkpoint- oder confbuild_validate_edit-Ergebnis.
Browser und visueller Loop
| Tool | Zweck | Schreibend |
|---|---|---|
confbuild_prepare_browser |
Pflichtschritt: beweist vor dem Erzeugen einen angemeldeten Tab, danach die exakte Projekt-/Konfigurationsrevision; liefert reuse, reload, navigate oder open-new samt anklickbarem Ziel |
Nein |
confbuild_browser_capabilities |
Meldet im Remote-Modus den privaten Browser-Tab-Kanal; lokal zusätzlich Playwright/CDP | Nein |
confbuild_open_editor |
Öffnet die interaktive confBuild-App (Dashboard oder ein Projekt) im Konversationsfenster des Hosts oder im Vollbild; nutzt die normale Anmeldung, die gegen das MCP-Konto geprüft wird; verändert keine Projekte und darf als einziges Tool einer Design-Session vorausgehen | Nein |
confbuild_render_and_wait |
Bevorzugt: startet den Render und long-pollt ihn im selben Aufruf; liefert das fertige Ergebnis innerhalb von waitMs oder den laufenden Job für Folge-Polls |
Nein |
confbuild_inspect_outputs |
Erstellt für exakte Output-IDs einen Vierbild-Inspektionssatz: gezoomter Fokus mit transparentem Umfeld, isolierte Ansicht, automatischer Mittelschnitt und X-Ray | Nein |
confbuild_run_project_interaction |
Führt eine gespeicherte Projektinteraktion in der exakt vorbereiteten Revision aus — den ONCLICK eines Input-Buttons, eine deklarierte Skriptfunktion oder eine registrierte Skript-Aktion — und liefert Vorher-/Nachher-Bilder samt Skriptdiagnose; der Ersatz für rohe Editor-Klicks |
Nein |
confbuild_validate_animation |
Deterministisches Animations-Gate für eine gespeicherte pose-Funktion: pose(0) ohne Wirkung, pose(mid) bewegt etwas, pose(1) schließt nahtlos an pose(0) an, Reset stellt den Ausgangszustand her; optional ein Posen-Sweep mit Zwischenbildern |
Nein |
confbuild_render_project |
Startet einen asynchronen Renderjob für ID/URL oder Edit-Session | Nein |
confbuild_get_render_result |
Long-Poll eines Jobs (Standard waitMs 25 s) mit Status, Diagnosen (outputIdAudit.rowsWithoutGeometry, engineWarnings, defectSignals, Bauteil-Bounds) und optional bis zu sieben PNGs; diagnosticsDetail: 'summary' für günstige Routine-Polls |
Nein |
confbuild_export_project |
Startet über die App-eigenen Exporter einen STEP/STL/GLB/3MF-, bereinigten BOM-, Zeichnungssatz-PDF-, Blech-Flachmuster-DXF-, Kosten-, Angebots-, Einkaufslisten- oder Variantenmetrik-Export | Nein |
confbuild_get_export_result |
Long-pollt den Export-Job; bettet Dateien bis maxContentBytes (Standard 8 MB) ein und verweist größere Dateien sicher auf den Chunk-Abruf |
Nein |
confbuild_get_export_chunk |
Liefert bis zu 4 MB eines fertigen Exports ab offsetBytes; mit chunk.nextOffsetBytes fortsetzen, bis chunk.complete wahr ist |
Nein |
confbuild_compare_variants |
Startet den sequenziellen Vergleich von 2–8 Projekt- oder gespeicherten Konfigurations-URLs nach Preis, Masse, CO2e oder Szenenabmessungen | Nein |
confbuild_get_variant_comparison_result |
Long-pollt den Vergleich und liefert Rankings, Abdeckung, Deltas, Warnungen und explizite Fehler je Variante | Nein |
confbuild_prepare_browser wird direkt nach dem Session-Setup aufgerufen. Gibt es noch kein Projekt, wird die Design-Session übergeben: Ein vorhandener angemeldeter confBuild-Tab wird wiederverwendet, sonst vor dem Erzeugen das Dashboard geöffnet. Danach folgt der Aufruf für das aufgelöste/erzeugte/geklonte Ziel und erneut nach jedem Commit oder Restore, bis connected: true gilt. Exakter sauberer Tab ⇒ reuse; sauber/veraltet ⇒ reload; Dashboard ⇒ navigate; anderes Projekt/Konfiguration, jeder schmutzige Tab oder kein Tab ⇒ open-new. Codex/Claude führt die Aktion mit seiner Browsersteuerung aus; ohne Browsersteuerung zeigt der Client den Resource-Link und wartet.
Die Tab-Präsenz trägt visibilityState, visibilityChangedAtMs und einen Herzschlag, den ein Worker-Takt alle 20 Sekunden erneuert, auch in Hintergrund-Tabs. Seit v0.31 fragt der Server wegen der Sichtbarkeit allein nie beim Nutzer nach: Ein Hintergrund-Tab baut weiter neu, übernimmt Jobs und nimmt auf, und weder ein verbundener Hintergrund-Tab noch ein übernommener Job wird unterbrochen, nur weil der Tab verdeckt ist. Ein zugewiesener Tab ohne Herzschlag seit 75 Sekunden (gemessen an der serverseitigen Schreibzeit, damit eine verstellte Client-Uhr keinen Stillstand vortäuscht) wird einmal ersetzt, bevor jemand gefragt wird: confbuild_prepare_browser übernimmt einen offenen, nicht zugewiesenen, antwortenden passenden Tab (replacedStalledTabId) oder liefert state: 'tab-stalled' mit action: 'open-new' für genau einen neuen Tab; solange dieser lädt, melden weitere Aufrufe tab-opening. Render-Polls auf dem stehengebliebenen Tab melden tabStalled: true mit nextTool: confbuild_prepare_browser, und ein nach dem Wechsel gestarteter Job zielt auf den neuen Tab. Ein nicht verbundener Handoff, ein BROWSER_TAB_REQUIRED-Fehler oder ein laufender Render-/Inspektions-Poll liefert userActionRequired: 'focus-tab' mit userAction.instruction nur noch, wenn der Ersatz-Tab sich nicht binnen 4 Minuten verbindet oder binnen 30 Minuten erneut stehen bleibt, wenn bekannte ausstehende Arbeit (ein In-Place-Rebuild oder ein nicht übernommener Job) 3 Minuten in einem antwortenden, durchgehend verdeckten Tab gewartet hat, oder wenn ein Job im verdeckten Tab unvollendet abgelaufen ist; ein verbundener stehengebliebener Tab ohne zugewiesene Session bleibt für Edits und Commits nutzbar, meldet aber renderRequiresVisibleTab: true. Der Server wartet nicht auf einen Handoff, der eine Nutzeraktion nennt — der Client bittet den Nutzer einmal in dessen Sprache, den confBuild-Tab nach vorn oder in ein eigenes Fenster zu holen. Öffnet der Nutzer das exakte Projekt in einem neuen Tab und gibt es genau einen sauberen passenden Tab, übernimmt die laufende Session ihn im selben Aufruf (browserConnectionAdoption); BROWSER_CONNECTION_REPLACED bleibt für mehrdeutige oder fehlende Ersatz-Tabs.
Ein fehlgeschlagener Browser-Tab-Job behält den Familiencode RENDER_FAILED beziehungsweise PROJECT_INTERACTION_FAILED und ergänzt einen stabilen failureCode (JOB_EXPIRED_UNCLAIMED, JOB_EXPIRED_WHILE_CAPTURING, MODEL_NOT_READY, CAPTURE_BLANK, AUTO_INSPECTION_FRAME_UNAVAILABLE, BROWSER_TAB_DIRTY, CONFIGURATION_CHANGED, …), failureStage, lastJobStatus, die Sichtbarkeit des Ziel-Tabs (tabVisibility) und einen konkreten nextTool oder userActionRequired. Nur ein unvollendet abgelaufener Job wird einem verdeckten oder stehengebliebenen Tab zugeschrieben; ein Job mit eigenem Fehler behält den nächsten Schritt dieses Fehlers. Der Client folgt diesem Schritt statt blind zu wiederholen.
confbuild_get_render_result unterstützt includeImages: false, wenn zunächst nur Status oder Diagnosen benötigt werden. Für die visuelle Abnahme setzt der Client includeImages: true und maxImages hoch genug für alle Ansichten. Das Ergebnis ordnet Caption und Bild für Codex/Claude und meldet ausgelassene Bilder in presentation.omittedImageCount. Die Render-Tools akzeptieren zusätzlich captureScope: isolateOutputIds rendert nur die genannten Teil-Subtrees, zoomToOutputIds rahmt die Kamera darauf, ghostOtherObjects hält den Fokus deckend und macht das Umfeld transparent, sectionPlane akzeptiert exakte Koordinaten oder {axis: "auto", position: "target-center"}, und xray macht das ganze Modell transparent. Meldet diagnostics.captureScopeApplied: false, lief die Aufnahme ungescoped. views akzeptiert default, right, front, left, back, top, bottom.
waitMs (0–120.000; unterhalb des eigenen Client-Tool-Timeouts wählen) macht aus dem Poll einen serverseitigen Long-Poll. Browser-Tab ist der Standard ohne automatischen Server-Fallback. rendererMode: "server-headless" ist nur zusammen mit serverRenderingExplicitlyRequested: true erlaubt, wenn der Nutzer Server-Rendering ausdrücklich verlangt hat; die Browser-Verbindung bleibt Pflicht.
Wenn ein Export größer als maxContentBytes ist, meldet confbuild_get_export_result delivery: "chunked", downloadWith: "confbuild_get_export_chunk" und nextOffsetBytes: 0. Der Client setzt die Bytebereiche zusammen; private Cloud-Storage- oder lokale Dateipfade werden nie offengelegt.
Die zusätzlichen Exportformate heißen drawing-pdf, sheetmetal-dxf, cost-json, quote-pdf, purchase-json, purchase-csv und variant-metrics-json. Zeichnungen werden vor dem PDF-Export vollständig hydriert; ein nur für den Job geöffnetes Zeichnungsfenster wird ohne Speichern geschlossen. Kosten, Angebot und Einkauf verwenden dieselbe BOM-/Preislogik wie die Anwendung. Angebot und Einkauf brechen bei gemischten Währungen ab; das Angebot zusätzlich bei fehlenden Pflichtpreisen. Einkaufslisten bleiben bei fehlenden Lieferpreisen nutzbar und weisen die geschätzte Kostenabdeckung aus. Eine Währungsumrechnung findet nicht statt. quote-pdf verlangt zusätzlich eine konfigurierte Verkäuferidentität: einen belastbaren Firmen- oder Verkäufernamen in companyName und entweder einen vollständigen postalischen Kontakt (street und zipCity) oder einen gültigen elektronischen Kontakt (email, phone oder website). Commercial-Fehler liefern maschinenlesbare Codes wie INVALID_SELLER_IDENTITY, MIXED_CURRENCIES oder MISSING_REQUIRED_PRICES sowie PII-freie Details, beispielsweise Feldnamen, fehlende Anforderungen, BOM-Positionen oder Währungscodes statt Verkäufer- oder Kundendaten.
Vor confbuild_compare_variants bereitet der Client jede Variantenreferenz einzeln über confbuild_prepare_browser vor und hält die Tabs geöffnet. Der Vergleich baut jede gespeicherte Variante nacheinander im echten Editor auf. Gespeicherte Konfigurationen werden auf Dokumentpfad und SHA-256-Stand festgelegt; fehlt oder ändert sich dieser Stand, schlägt nur die betreffende Variantenzeile fehl. price setzt eine eindeutige gemeinsame oder explizit angegebene Währung und vollständige Preisabdeckung voraus. mass wird nur bei vollständiger Positionsabdeckung gerankt. co2 nutzt generische cradle-to-gate-Materialfaktoren (keine EPD) und standardmäßig mindestens 80 % Massenabdeckung. boundsX, boundsY, boundsZ und boundsVolume sind explizite Szenenachsenwerte.
Fertige Ergebnisse enthalten zwei zusätzliche Evidenzblöcke:
diagnostics.geometry: ein näherungsweises Geometrie-Audit mit BVH-bestätigten Kollisionspaaren, AABB-verdächtigen Überlappungen, losgelösten Teilen ohne Kontakt, Ausreißern und Modellgrenzen. Die Funde sind Hinweise, keine Urteile; sie entsprechen den Defektkategorien des Model-Loops und werden vom Client an den Ansichten verifiziert.iterationDelta: Mesh-/Output-/Kollisions-/Ablösungs-/Bounds-Deltas gegen den vorherigen abgeschlossenen Render desselben Projekts — „hat mein Patch überhaupt etwas geändert“ braucht keinen Bildvergleich mehr.
Abschluss
| Tool | Zweck |
|---|---|
confbuild_finish_design_session |
Schließt Design-/Edit-Zustand nach finaler Bildprüfung und gibt die Projekt-URL zurück; dryRun: true listet vorher jeden verbleibenden Blocker, ohne etwas zu schließen |
Der Abschluss schlägt fehl, wenn die Edit-Session noch ungespeicherte Änderungen enthält oder der angegebene finale Renderjob nicht abgeschlossen ist.
Der Finish-Aufruf akzeptiert ein strukturiertes, inhaltsfreies Ergebnis: completionState (complete/partial/blocked), iterationsUsed sowie fixedDefectCategories/residualDefectCategories aus dem Defekt-Enum des Model-Loops. Gespeichert werden nur diese Enums und Zähler für Qualitätstrends; die Freitext-summary geht an den Client zurück und wird nie persistiert.
Mit dryRun: true bewertet der Finish-Aufruf jedes Abschluss-Gate für den gewünschten completionState (Standard complete) und liefert alle blockers mit ihrem nextTool sowie die passedGates, ohne etwas zu schließen oder zu protokollieren — sinnvoll nach dem letzten Commit und vor Inspektionsdurchgang und finalem Render. Der Vierbild-Inspektionsnachweis ist an die exakte Revision gebunden statt an die Design-Session und bleibt sieben Tage gültig, sodass eine Fortsetzungs-Session ihn wiederverwendet.
Workbook-Format
Eine Arbeitsmappe ist ein Array von Sheet-Objekten:
[
{
"name": "Main Part",
"visible": true,
"data": [
["INPUTID", "TYP", "VALUE", "VALIDATED", "UNIT", "LABEL", "VISIBLE", "MIN", "MAX", "PARAMS", "ONCLICK", "ONCHANGE"],
["width", "slider", 1000, true, "mm", "Breite", true, 500, 2000, "", "", ""],
["OUTPUTID"],
["#", "type", "width", "height", "depth", "material", "x", "y", "z", "rx", "ry", "rz"],
["body", "cube", "=C2", 600, 400, "#8C30F5", 0, 0, 0, 0, 0, 0]
]
}
]
Die vollständigen Spalten und Geometrieregeln kommen aus dem Prompt-Bundle. Das Schema-Ressource confbuild://schema/workbook beschreibt das kompakte MCP-Format.
Patch-Operationen
| Operation | Erforderliche Felder | Wirkung |
|---|---|---|
replace_workbook |
sheets |
Ersetzt alle Sheets |
upsert_sheet |
sheet |
Fügt ein Sheet anhand seines Namens hinzu oder ersetzt es |
delete_sheet |
sheetName oder sheetIndex |
Entfernt ein Sheet |
rename_sheet |
Sheet-Adresse, newName |
Benennt ein Sheet eindeutig um |
set_sheet_visibility |
Sheet-Adresse, visible |
Blendet ein Sheet ein oder aus |
set_cells |
Sheet-Adresse, cells |
Setzt einzelne Zellen per A1 oder Zeile/Spalte |
replace_rows |
Sheet-Adresse, startRow, rows |
Ersetzt so viele Zeilen, wie übergeben wurden |
insert_rows |
Sheet-Adresse, startRow, rows |
Fügt Zeilen vor der Startposition ein |
delete_rows |
Sheet-Adresse, startRow, count |
Entfernt Zeilen |
upsert_sheet_tsv |
sheetName, tsv |
Fügt ein Sheet aus Tab-getrenntem Text hinzu oder ersetzt es |
upsert_output_rows |
Sheet-Adresse, rows oder tsv |
Ersetzt Output-Zeilen anhand der OUTPUTID in Spalte A oder hängt neue an den Output-Block an |
patch_scriptcode |
replacements (find, replace, optional all/count) |
Ändert das Projektskript per Suchen/Ersetzen |
wire_child |
childName, optional parentSheetName, outputId, placement, parameters |
Schreibt oder repariert die SHEET: <Child>-Zeile des Parents samt steuerndem #-Header, der jeden geplanten Child-Input übergibt |
set_default_material |
Sheet-Adresse, mechanicalMaterialId, optional onlyMissing, rowTypes |
Füllt mechanicalMaterialId in physischen Zeilen des Sheets |
auto_fix |
optional fixes |
Repariert VALIDATED-Formeln derselben Zeile, groupend-Zellen und Steuerelement-Aliasse und leitet Fertigungsmetadaten aus dem Topologieplan ab |
Die drei Reparatur-Operationen sind deterministisch und werden wie jede andere Umschreibung des Servers pro Zeile in normalizations gemeldet — einschließlich der stillen 0/1-Zahl-zu-Checkbox-Normalisierung. Die Validierungsfehler TOPOLOGY_CHILD_REFERENCE_MISSING und TOPOLOGY_REFERENCE_PARAMETER_MISSING tragen die passende wire_child-Operation als suggestedOperation; PHYSICAL_MATERIAL_MISSING nennt je Zeilentyp einen Bibliotheksvorschlag (etwa S235JR, EN AW-6060, C45E; keinen für Gebäude- und Möbelzeilen). autoFix: true an Patch oder Checkpoint hängt die auto_fix-Operation automatisch an.
Indizierung
sheetIndexist nullbasiert.row, numerischecolumn,startRowund A1-Adressen sind einsbasiert.- Spalten können als Zahl oder Buchstaben angegeben werden.
Zellen setzen
{
"editSessionId": "edit-…",
"operations": [
{
"op": "set_cells",
"sheetName": "Main Part",
"cells": [
{ "a1": "C2", "value": 1200 },
{ "row": 2, "column": "F", "value": "Breite" }
]
}
]
}
Sheet hinzufügen oder ersetzen
{
"op": "upsert_sheet",
"sheet": {
"name": "Frame",
"visible": true,
"data": [["INPUTID"], ["OUTPUTID"]]
}
}
Validierung
Eine Validierung liefert valid, errors, warnings und Statistiken. Harte Fehler umfassen beispielsweise:
- leere Arbeitsmappe;
- leere oder doppelte Sheet-Namen;
- Zeilen, die keine Arrays sind;
- nicht serialisierbare Werte oder nicht endliche Zahlen;
- mehr als 2.000.000 Zellen.
Warnungen umfassen unter anderem einen fehlenden INPUTID-Header, fehlenden OUTPUTID-Marker oder doppelte Output-IDs. Ein deterministisches Engine-Fallen-Lint markiert zusätzlich Fehler, die sonst erst als falscher Render sichtbar würden: eine nackte Zellreferenz wie D4 statt =D4 (NAKED_CELL_REFERENCE), Text in Zahlspalten, den die Engine stumm zu 0 macht (NON_NUMERIC_VALUE), zwei aufeinanderfolgende #-Header, von denen nur der letzte wirkt (CONSECUTIVE_HEADER_ROWS), Datenzellen jenseits des Headers (ROW_WIDER_THAN_HEADER), Output-Zeilen ohne Header (MISSING_OBJECT_HEADER) und — neu in v0.30 — eine Output-Zeile unter einem #-Header, dem ihre Primärspalte fehlt und der mit der Spalte eines fremden Typs beginnt (ROW_TYPE_HEADER_MISMATCH): Die Engine ordnet Zellen nach Position zu und baut dann stumm degenerierte Geometrie. VALUE_SHADOWED_BY_CONFIGMODEL warnt, wenn ein gespeicherter Konfigurationsstand eine gepatchte VALUE-Zelle überdeckt — der Render zeigt dann den gespeicherten Wert, nicht den Patch. Ein Workbook kann trotz Warnungen formal gespeichert werden; der Client muss sie fachlich bewerten.
Seit v0.17 wird vor dem Modellieren mit confbuild_plan_sheet_topology festgelegt, ob wirklich nur ein unteilbares Bauteil vorliegt oder ob Main Part benannte funktionale Child-Sheets orchestriert. Composite-Projekte werden sofort mit den geplanten Subsheets angelegt. Die Validierung blockiert fehlende oder ungeplante Children, Zyklen, falsche Parent-Referenzen, fehlende Child-Inputs und leere Parameterzellen im referenzierenden Parent. Der Abschluss verlangt zusätzlich passende subsheetCount-/subprojectCount-Diagnostik. Weiterhin werden Formeln, SHEET:-/PROJECT:-Auflösung, Row-Types und Eingabebereiche geprüft. Ein fehlgeschlagener Commit liefert die Validierungs- oder Snapshot-Fehler direkt in der Antwort; ohne vollständigen Rollback-Snapshot wird keine neue Revision gespeichert.
Persistenz und große Sheets
Kleine Workbooks werden inline im Projekt gespeichert. Ab ungefähr 700 KB serialisierter Sheet-Daten verwendet der Server automatisch generationsspezifische Chunks von ungefähr 240 KB. Manifest und neue Chunks werden atomar geschrieben; alte Projekt-Sheet-Chunks werden danach bereinigt.
Der Client muss diese Speicherung nicht selbst verwalten. Beim Lesen hydratisiert der Server beide Varianten in dasselbe Workbook-Format.
Zustandsdauer
| Zustand | Lebensdauer |
|---|---|
| Design-Session | 6 Stunden |
| Edit-Session | 6 Stunden, bei Zugriff verlängert (mindestens 5,5 Stunden ab dem letzten Zugriff) |
| Renderjob | 24 Stunden |
| Render-Iterationsbasis (pro Projekt) | 7 Tage |
| Inspektionsnachweis (pro Revision) | 7 Tage |
| Rollback-Snapshots | Neueste pro Projekt, ältere werden beim Commit aufgeräumt |
| Committetes Projekt | Dauerhaft in confBuild/Firebase |
Im Remote-Modus werden Design-, Edit- und Renderzustände UID-getrennt und komprimiert in privatem Cloud Storage gespeichert. Dadurch überstehen sie zustandslose Function-Instanzen; nach Ablauf werden sie ungültig. Der lokale STDIO-Modus hält temporäre Zustände nur im Prozessspeicher. Commitete Projekte bleiben in beiden Modi dauerhaft erhalten.