MCP-Tool- & Sheet-Referenz

Serveroberfläche

Die gehostete Version 0.4 stellt über https://app.confbuild.com/mcp 20 Tools, einen wiederverwendbaren Prompt, einen Skill-Katalogeintrag für Plugin-Import-Scans und 28 Ressourcen bereit. 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.

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": "essential",
  "knownBundleHashes": ["sha256 eines bereits vorliegenden Bundles"]
}

Der Client klassifiziert die Domäne selbst und übergibt ein explizites profile (building, machine, 3dprint, generic); auto löst nur einen Keyword-Fallback für Clients aus, die nicht klassifizieren können. knownBundleHashes ist optional: Enthält es die zurückgegebene bundleSha256, kommt das Bundle ohne seinen Text zurück (bundleTextOmitted: true) — das entfernt den größten wiederholten Payload aus Folgesessions.

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 das Workbook vor der Änderung als Rollback-Snapshot (preCommitSnapshotId im Ergebnis); "snapshot": false schaltet das ab. 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 — er ist damit selbst rückgängig machbar und umgeht nie den Revisionsschutz.

Browser und visueller Loop

confbuild_get_render_result unterstützt includeImages: false, wenn zunächst nur Status oder Diagnosen benötigt werden. maxImages liegt zwischen 1 und 4.

waitMs (0–30.000) macht aus dem Poll einen serverseitigen Long-Poll: Der Aufruf wartet, bis der Job fertig ist oder die Wartezeit abläuft, statt den Client zu schnellem Polling zu zwingen. Solange ein gehosteter Job unbeansprucht ist, meldet die Antwort, wie lange er schon wartet, und nach wenigen Sekunden einen expliziten Hinweis, dass kein angemeldeter Editor-Tab mit dem Zielprojekt geöffnet ist.

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.

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