MCP-Tool- & Sheet-Referenz

Serveroberfläche

Die v0.17-Serveroberfläche stellt über https://app.confbuild.com/mcp 35 Tools, einen wiederverwendbaren Prompt, einen Skill-Katalogeintrag für Plugin-Import-Scans und 49 Ressourcen bereit. Neu ist die verpflichtende Composite-Topologieplanung für Main Part plus benannte Subsheets. 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

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

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

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.

Browser und visueller Loop

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.

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

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.

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

Indizierung

• sheetIndex ist nullbasiert.
• row, numerische column, startRow und 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) und Output-Zeilen ohne Header (MISSING_OBJECT_HEADER). 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

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.

Siehe auch

• Agentischer Projekt-Workflow
• Master-Prompts & KI-Grenze
• Sicherheit & Fehlerbehebung