MCP tool & Sheet reference

Server surface

Local version 0.1 exposes 18 tools, one reusable prompt, and local resources. Transport is STDIO; structured results are returned as MCP text and structuredContent, with screenshots additionally returned as native image blocks.

The reusable prompt is named confbuild-design. It instructs the client to call confbuild_start_design_session first and follow the complete create/edit/render loop.

Tools by phase

Orientation and prompts

Tool Purpose Writes
confbuild_start_design_session Mandatory first call; infers profile, optionally resolves the target, and returns the prompt bundle No
confbuild_get_prompt_bundle Gets a prompt bundle without creating a design session No
confbuild_list_prompt_resources Lists prompt resources with URI, size, MIME type, and SHA-256 No

Important confbuild_start_design_session inputs:

{
  "request": "Complete user request",
  "projectReference": "optional ID or URL",
  "client": "codex",
  "profile": "auto",
  "promptDetail": "essential"
}

Access and projects

Tool Purpose Writes
confbuild_auth_status Verifies normal user authentication without revealing the secret No
confbuild_resolve_project_reference Resolves an ID or URL as an owned private or public project No
confbuild_create_project Creates a private project, optionally with initial Sheets Yes
confbuild_clone_project Copies a public/read-only project into a private project Yes
confbuild_read_project Reads metadata and hydrated Sheets, optionally filtered No

confbuild_create_project and confbuild_clone_project support an idempotencyKey. Reusing the same key in the same user account resolves to the same deterministic project ID.

confbuild_read_project can limit context:

{
  "reference": "PROJECT_ID",
  "sheetNames": ["Main Part", "Frame"],
  "maxRowsPerSheet": 500
}

If truncated: true is returned, the client must not replace that complete Sheet until it has read the untruncated content.

Editing and persistence

Tool Purpose Writes
confbuild_begin_edit Loads the complete workbook and base revision into memory Only when auto-cloning
confbuild_apply_sheet_patch Applies up to 1,000 operations to the local working copy Local only, not remote yet
confbuild_read_edit_workbook Reads the current local working copy, optionally by Sheet name No
confbuild_validate_edit Checks structure, markers, IDs, serialization, and size limits No
confbuild_commit_edit Saves atomically with optimistic revision protection Yes
confbuild_discard_edit Drops the local edit session; committed data remains Locally destructive

confbuild_commit_edit can also update project fields:

{
  "editSessionId": "edit-…",
  "mutationId": "stable-client-mutation-42",
  "projectPatch": {
    "name": "Portal Mill 800",
    "projectType": "machine-component",
    "description": "Parametric portal milling machine",
    "metadata": { "source": "mcp-client" }
  }
}

Browser and visual loop

Tool Purpose Writes
confbuild_browser_capabilities Reports CDP, visible, and headless capabilities No
confbuild_render_project Starts an asynchronous render job for an ID/URL or edit session No
confbuild_get_render_result Returns job status, diagnostics, and optionally up to four PNGs No

confbuild_get_render_result supports includeImages: false when the client initially needs only status or diagnostics. maxImages can be 1–4.

Completion

Tool Purpose
confbuild_finish_design_session Closes design/edit state after final image inspection and returns the project URL

Completion fails while the edit session contains uncommitted changes or the specified final render job is incomplete.

Workbook format

A workbook is an array of Sheet objects:

[
  {
    "name": "Main Part",
    "visible": true,
    "data": [
      ["INPUTID", "TYP", "VALUE", "VALIDATED", "UNIT", "LABEL", "VISIBLE", "MIN", "MAX", "PARAMS", "ONCLICK", "ONCHANGE"],
      ["width", "slider", 1000, true, "mm", "Width", 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]
    ]
  }
]

The complete columns and geometry rules come from the prompt bundle. Resource confbuild://schema/workbook describes the compact MCP format.

Patch operations

Operation Required fields Effect
replace_workbook sheets Replaces all Sheets
upsert_sheet sheet Adds a Sheet by name or replaces it
delete_sheet sheetName or sheetIndex Removes a Sheet
rename_sheet Sheet address, newName Renames a Sheet uniquely
set_sheet_visibility Sheet address, visible Shows or hides a Sheet
set_cells Sheet address, cells Sets individual cells by A1 or row/column
replace_rows Sheet address, startRow, rows Replaces as many rows as supplied
insert_rows Sheet address, startRow, rows Inserts rows before the start position
delete_rows Sheet address, startRow, count Removes rows

Indexing

  • sheetIndex is zero-based.
  • row, numeric column, startRow, and A1 addresses are one-based.
  • Columns may be numbers or letters.

Set cells

{
  "editSessionId": "edit-…",
  "operations": [
    {
      "op": "set_cells",
      "sheetName": "Main Part",
      "cells": [
        { "a1": "C2", "value": 1200 },
        { "row": 2, "column": "F", "value": "Width" }
      ]
    }
  ]
}

Add or replace a Sheet

{
  "op": "upsert_sheet",
  "sheet": {
    "name": "Frame",
    "visible": true,
    "data": [["INPUTID"], ["OUTPUTID"]]
  }
}

Validation

Validation returns valid, errors, warnings, and statistics. Hard errors include:

  • empty workbook;
  • empty or duplicate Sheet names;
  • rows that are not arrays;
  • unserializable values or non-finite numbers;
  • more than 2,000,000 cells.

Warnings include a missing INPUTID header, missing OUTPUTID marker, or duplicate output IDs. A workbook may be formally saved despite warnings; the client must evaluate them professionally.

Persistence and large Sheets

Small workbooks are stored inline in the project. Above approximately 700 KB of serialized Sheet data, the server automatically uses generation-specific chunks of approximately 240 KB. The manifest and new chunks are written atomically; stale project-Sheet chunks are cleaned afterward.

The client does not manage this storage. On read, the server hydrates both variants into the same workbook format.

State lifetime

State Lifetime
Design session 6 hours of inactivity
Edit session 6 hours, extended on access
Render job 24 hours
Committed project Persistent in confBuild/Firebase

Sessions and render jobs live in the local MCP process memory. Restarting loses only this temporary state; committed projects remain intact.

See also

Back to Documentation