docs: generate real MCP tool reference pages

.github/workflows/ci.yml

@@ -31,6 +31,12 @@ jobs:
           git add -N content/docs/api/rest
           git diff --exit-code -- content/docs/api/rest
 
+      - name: gen-mcp-docs drift check
+        run: |
+          node scripts/gen-mcp-docs.mjs
+          git add -N content/docs/api/mcp
+          git diff --exit-code -- content/docs/api/mcp
+
       - name: test-docs (Learn examples)
         run: node scripts/test-docs.mjs
 

content/docs/api/mcp/chart-insert.mdx

@@ -0,0 +1,129 @@
+---
+title: "chart:insert"
+description: "Inserts a chart."
+---
+
+{/* GENERATED by scripts/gen-mcp-docs.mjs from scripts/mcp-source/tool-schemas.json — do not edit. */}
+
+## Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `sheet` | `string` | yes | The sheet `range` is relative to. |
+| `range` | `{ from: string; to: string }` | yes | The rectangle to bind the chart to, as A1 corners. |
+| `chartType` | `string` | yes | The chart form to draw, a closed wire vocabulary. |
+| `options` | `object` | no | Renderer-specific knobs, opaque here on purpose, defaults to `{}`. |
+
+## Returns
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `chartId` | `string` | yes | The new chart's id. |
+| `range` | `{ from: string; to: string }` | yes | Canonicalized top-left/bottom-right corners. |
+| `chartType` | `string` | yes | — |
+
+## Schema
+
+Request payload, as JSON Schema:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Payload",
+  "type": "object",
+  "properties": {
+    "sheet": {
+      "description": "The sheet `range` is relative to.",
+      "type": "string"
+    },
+    "range": {
+      "description": "The rectangle to bind the chart to, as A1 corners.",
+      "$ref": "#/$defs/CellRange"
+    },
+    "chartType": {
+      "description": "The chart form to draw, a closed wire vocabulary.",
+      "type": "string"
+    },
+    "options": {
+      "description": "Renderer-specific knobs, opaque here on purpose, defaults to `{}`.",
+      "type": "object",
+      "additionalProperties": true,
+      "default": {}
+    }
+  },
+  "required": [
+    "sheet",
+    "range",
+    "chartType"
+  ],
+  "$defs": {
+    "CellRange": {
+      "description": "An inclusive rectangle. `from`/`to` may be equal, a single cell.",
+      "type": "object",
+      "properties": {
+        "from": {
+          "description": "Top-left cell, e.g. `\"A1\"`.",
+          "type": "string"
+        },
+        "to": {
+          "description": "Bottom-right cell, e.g. `\"B3\"`.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "from",
+        "to"
+      ]
+    }
+  }
+}
+```
+
+Response payload, as JSON Schema:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Output",
+  "type": "object",
+  "properties": {
+    "chartId": {
+      "description": "The new chart's id.",
+      "type": "string"
+    },
+    "range": {
+      "description": "Canonicalized top-left/bottom-right corners.",
+      "$ref": "#/$defs/CellRange"
+    },
+    "chartType": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "chartId",
+    "range",
+    "chartType"
+  ],
+  "$defs": {
+    "CellRange": {
+      "description": "An inclusive rectangle. `from`/`to` may be equal, a single cell.",
+      "type": "object",
+      "properties": {
+        "from": {
+          "description": "Top-left cell, e.g. `\"A1\"`.",
+          "type": "string"
+        },
+        "to": {
+          "description": "Bottom-right cell, e.g. `\"B3\"`.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "from",
+        "to"
+      ]
+    }
+  }
+}
+```
+

content/docs/api/mcp/chart-remove.mdx

@@ -0,0 +1,63 @@
+---
+title: "chart:remove"
+description: "Removes a chart."
+---
+
+{/* GENERATED by scripts/gen-mcp-docs.mjs from scripts/mcp-source/tool-schemas.json — do not edit. */}
+
+## Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `chartId` | `string` | yes | The chart to remove. |
+
+## Returns
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `chartId` | `string` | yes | — |
+| `removed` | `boolean` | yes | — |
+
+## Schema
+
+Request payload, as JSON Schema:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Payload",
+  "type": "object",
+  "properties": {
+    "chartId": {
+      "description": "The chart to remove.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "chartId"
+  ]
+}
+```
+
+Response payload, as JSON Schema:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Output",
+  "type": "object",
+  "properties": {
+    "chartId": {
+      "type": "string"
+    },
+    "removed": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "chartId",
+    "removed"
+  ]
+}
+```
+

content/docs/api/mcp/chart-update.mdx

@@ -0,0 +1,83 @@
+---
+title: "chart:update"
+description: "Updates a chart."
+---
+
+{/* GENERATED by scripts/gen-mcp-docs.mjs from scripts/mcp-source/tool-schemas.json — do not edit. */}
+
+## Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `chartId` | `string` | yes | The chart to patch. |
+| `chartType` | `string or null` | no | The new chart form, or omitted to leave it unchanged. Defaults to `null`. |
+| `options` | `object or null` | no | Replaces the chart's options wholesale, or omitted to leave them unchanged. Defaults to `null`. |
+
+## Returns
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `chartId` | `string` | yes | — |
+| `chartType` | `string` | yes | The EFFECTIVE, post-patch chart form, the patch's own value if it supplied one, else the chart's unchanged existing type. |
+
+## Schema
+
+Request payload, as JSON Schema:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Payload",
+  "type": "object",
+  "properties": {
+    "chartId": {
+      "description": "The chart to patch.",
+      "type": "string"
+    },
+    "chartType": {
+      "description": "The new chart form, or omitted to leave it unchanged.",
+      "type": [
+        "string",
+        "null"
+      ],
+      "default": null
+    },
+    "options": {
+      "description": "Replaces the chart's options wholesale, or omitted to leave them unchanged.",
+      "type": [
+        "object",
+        "null"
+      ],
+      "additionalProperties": true,
+      "default": null
+    }
+  },
+  "required": [
+    "chartId"
+  ]
+}
+```
+
+Response payload, as JSON Schema:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Output",
+  "type": "object",
+  "properties": {
+    "chartId": {
+      "type": "string"
+    },
+    "chartType": {
+      "description": "The EFFECTIVE, post-patch chart form, the patch's own value if it supplied one, else the chart's unchanged existing type.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "chartId",
+    "chartType"
+  ]
+}
+```
+

content/docs/api/mcp/clipboard-paste.mdx

@@ -0,0 +1,61 @@
+---
+title: "clipboard:paste"
+description: "Pastes previously copied or cut cells into a range."
+---
+
+{/* GENERATED by scripts/gen-mcp-docs.mjs from scripts/mcp-source/tool-schemas.json — do not edit. */}
+
+## Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `sheet` | `string` | yes | — |
+| `source` | `string` | yes | The cell the clipboard content was copied/cut FROM, e.g. `"A1"`. |
+| `raw` | `string` | yes | The clipboard contents AT COPY/CUT TIME, a literal, a formula, leading `=`, or `""`. |
+| `target` | `string` | yes | The cell being pasted INTO, e.g. `"B2"`. |
+| `cut` | `boolean` | no | `false` = copy, the default, `true` = cut, move. |
+
+## Returns
+
+Nothing beyond the standard MCP success envelope.
+
+## Schema
+
+Request payload, as JSON Schema:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Payload",
+  "type": "object",
+  "properties": {
+    "sheet": {
+      "type": "string"
+    },
+    "source": {
+      "description": "The cell the clipboard content was copied/cut FROM, e.g. `\"A1\"`.",
+      "type": "string"
+    },
+    "raw": {
+      "description": "The clipboard contents AT COPY/CUT TIME, a literal, a formula, leading `=`, or `\"\"`.",
+      "type": "string"
+    },
+    "target": {
+      "description": "The cell being pasted INTO, e.g. `\"B2\"`.",
+      "type": "string"
+    },
+    "cut": {
+      "description": "`false` = copy, the default, `true` = cut, move.",
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "required": [
+    "sheet",
+    "source",
+    "raw",
+    "target"
+  ]
+}
+```
+