Canvs

Returns guidance on diagram-creation workflow and tool selection: how to choose between Mermaid and manual element creation, and the recommended iteration workflow. Consult before building complex diagrams.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "guide": {
      "type": "string",
      "description": "Tool usage instructions text"
    }
  },
  "required": [
    "guide"
  ]
}

Creates elements on a canvas. Creates a new canvas if room_id is omitted, or adds to the existing canvas if room_id is provided. Use cases: wireframes, UI mockups, freeform illustrations, standalone shapes, and manual layouts that Mermaid does not cover well. For diagrams Mermaid can express, use add_elements_from_mermaid instead. Element types: rectangle, ellipse, diamond, arrow, line, freedraw, text, image. Rich text: the text field supports limited HTML for text elements and rectangle/ellipse/diamond shape labels. Supports the rich-text plugin HTML subset: <b>/<strong>, <i>/<em>, <u>, <br>, <div>/<p>, <ul>/<ol>/<li>, <a href>, <font color>, and <span style="color, background/background-color, font-size, font-family">. Use textAlign for left/center/right alignment; avoid unsupported HTML/CSS. TEXT IN SHAPES: use containerId on text element pointing to shape id. ARROWS: Position at EDGE of source shape. Auto-bound within 30px. Colors: strokeColor, backgroundColor (hex).

{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string",
      "description": "Room ID of an existing canvas to add to. If the user is continuing a canvas already referenced in this conversation (by room_id, or a URL like ?room=[room_id] or /gdrive?id=[room_id]), pass it here. Omit to create a new canvas."
    },
    "elements": {
      "type": "array",
      "description": "Array of element definitions to create",
      "items": {
        "type": "object",
        "description": "Per-type required fields: rectangle/ellipse/diamond → x, y (width/height default to 100). text → x, y, text (width/height auto-sized; omit or set to 0). rectangle/ellipse/diamond may also include text, which creates a bound label. arrow/line → x, y, points (e.g. [[0,0],[100,0]]); optionally startBinding/endBinding instead of points. image → x, y, width, height, fileId. freedraw → x, y, points. type is inferred from fields if omitted (text field → text, points → line, fileId → image, else rectangle).",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique element ID. IMPORTANT: Always set explicit IDs for shapes that arrows will connect to!"
          },
          "type": {
            "type": "string",
            "enum": [
              "rectangle",
              "ellipse",
              "diamond",
              "arrow",
              "line",
              "freedraw",
              "text",
              "image"
            ],
            "description": "Element type. Inferred from fields if omitted: text field → text, points → line, fileId → image, else rectangle."
          },
          "x": {
            "type": "number",
            "description": "X coordinate (defaults to 0 if omitted)"
          },
          "y": {
            "type": "number",
            "description": "Y coordinate (defaults to 0 if omitted)"
          },
          "width": {
            "type": "number",
            "description": "Width (default: 100; omit for text — auto-sized)"
          },
          "height": {
            "type": "number",
            "description": "Height (default: 100; omit for text — auto-sized)"
          },
          "strokeColor": {
            "type": "string",
            "description": "Stroke color in hex (default: #1e1e1e)"
          },
          "backgroundColor": {
            "type": "string",
            "description": "Fill color in hex or 'transparent' (default: transparent)"
          },
          "fillStyle": {
            "type": "string",
            "description": "Fill style: solid, hachure, cross-hatch (default: solid)"
          },
          "strokeWidth": {
            "type": "number",
            "description": "Stroke width (default: 2)"
          },
          "roughness": {
            "type": "number",
            "description": "Roughness: 0=architect, 1=artist, 2=cartoonist (default: 1)"
          },
          "opacity": {
            "type": "number",
            "description": "Opacity 0-100 (default: 100)"
          },
          "text": {
            "type": "string",
            "description": "Text content. Required for type=text. For text elements and rectangle/ellipse/diamond shape labels, Supports the rich-text plugin HTML subset: <b>/<strong>, <i>/<em>, <u>, <br>, <div>/<p>, <ul>/<ol>/<li>, <a href>, <font color>, and <span style=\"color, background/background-color, font-size, font-family\">. Use textAlign for left/center/right alignment; avoid unsupported HTML/CSS. Also used as arrow label when set on an arrow."
          },
          "fontSize": {
            "type": "number",
            "description": "Font size (default: 20). Applies to text elements."
          },
          "fontFamily": {
            "type": "number",
            "description": "Font family: 5=Excalifont, 6=Nunito, 7=Lilita One, 8=Comic Shanns (default: 5). Applies to text elements."
          },
          "points": {
            "type": "array",
            "description": "Required for arrow/line/freedraw. Coordinates relative to element x,y. Example: [[0,0],[100,0]] for horizontal arrow.",
            "items": {
              "type": "array",
              "items": {
                "type": "number"
              }
            }
          },
          "containerId": {
            "type": "string",
            "description": "For type=text: ID of the shape this text is bound to. Set x,y to 0,0 for auto-centering inside the shape."
          },
          "startBinding": {
            "description": "For type=arrow: binds the arrow start to a shape. Use instead of or alongside points.",
            "type": "object",
            "properties": {
              "elementId": {
                "type": "string"
              },
              "focus": {
                "type": "number"
              },
              "gap": {
                "type": "number"
              }
            },
            "required": [
              "elementId",
              "focus",
              "gap"
            ]
          },
          "endBinding": {
            "description": "For type=arrow: binds the arrow end to a shape. Use instead of or alongside points.",
            "type": "object",
            "properties": {
              "elementId": {
                "type": "string"
              },
              "focus": {
                "type": "number"
              },
              "gap": {
                "type": "number"
              }
            },
            "required": [
              "elementId",
              "focus",
              "gap"
            ]
          },
          "label": {
            "type": "string",
            "description": "For type=arrow: text label displayed on the arrow"
          }
        },
        "required": [
          "x",
          "y"
        ]
      }
    }
  },
  "required": [
    "elements"
  ]
}

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Canvas room URL"
    },
    "room_id": {
      "type": "string",
      "description": "Canvas room ID"
    },
    "isNew": {
      "type": "boolean",
      "description": "Whether a new canvas was created"
    },
    "collabUrl": {
      "type": "string",
      "description": "Collaboration server URL for Socket.IO"
    },
    "elements": {
      "type": "array",
      "description": "All elements currently on the canvas",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "appState": {
      "type": "object",
      "description": "Canvas app state (viewBackgroundColor, etc.)",
      "properties": {
        "viewBackgroundColor": {
          "type": "string"
        }
      },
      "additionalProperties": true
    }
  },
  "required": [
    "url",
    "isNew",
    "collabUrl",
    "elements",
    "appState"
  ]
}

Update elements on a canvas. Requires room_id from a previous Canvs tool result. Pass elements array with id and fields to update. IMPORTANT: in each update object ONLY `id` is required; all other fields are optional patch fields. Include ONLY elements that need changes; elements omitted from the request remain unchanged on the board. Prefer this tool for SMALL edits to existing diagrams (rename/move/restyle a few elements), typically after query_elements.

{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string",
      "description": "Room ID from a previous Canvs tool result. If you only have a URL, extract it from https://[host]/?room=[room_id] or https://[host]/gdrive?id=[room_id]."
    },
    "elements": {
      "type": "array",
      "description": "Array of element updates (each must have id)",
      "items": {
        "type": "object",
        "description": "Patch object: only id is required. Include only the fields you want to change.",
        "properties": {
          "id": {
            "type": "string",
            "description": "ID of the element to update (required)"
          },
          "type": {
            "type": "string",
            "enum": [
              "rectangle",
              "ellipse",
              "diamond",
              "arrow",
              "line",
              "freedraw",
              "text",
              "image"
            ],
            "description": "New element type"
          },
          "x": {
            "type": "number",
            "description": "New X coordinate"
          },
          "y": {
            "type": "number",
            "description": "New Y coordinate"
          },
          "width": {
            "type": "number",
            "description": "New width"
          },
          "height": {
            "type": "number",
            "description": "New height"
          },
          "strokeColor": {
            "type": "string",
            "description": "New stroke color (hex)"
          },
          "backgroundColor": {
            "type": "string",
            "description": "New fill color (hex or 'transparent')"
          },
          "fillStyle": {
            "type": "string",
            "description": "New fill style (solid, hachure, cross-hatch)"
          },
          "strokeWidth": {
            "type": "number",
            "description": "New stroke width"
          },
          "roughness": {
            "type": "number",
            "description": "New roughness (0=architect, 1=artist, 2=cartoonist)"
          },
          "opacity": {
            "type": "number",
            "description": "New opacity (0-100)"
          },
          "text": {
            "type": "string",
            "description": "New text content. For text elements and rectangle/ellipse/diamond shape labels, Supports the rich-text plugin HTML subset: <b>/<strong>, <i>/<em>, <u>, <br>, <div>/<p>, <ul>/<ol>/<li>, <a href>, <font color>, and <span style=\"color, background/background-color, font-size, font-family\">. Use textAlign for left/center/right alignment; avoid unsupported HTML/CSS. Shape text updates the bound label."
          },
          "fontSize": {
            "type": "number",
            "description": "New font size (for text elements)"
          },
          "fontFamily": {
            "type": "number",
            "description": "New font family (5=Excalifont, 6=Nunito, 7=Lilita One, 8=Comic Shanns)"
          },
          "points": {
            "type": "array",
            "description": "New points array (for arrow/line/freedraw elements)",
            "items": {
              "type": "array",
              "items": {
                "type": "number"
              }
            }
          },
          "locked": {
            "type": "boolean",
            "description": "Lock/unlock the element"
          }
        },
        "required": [
          "id"
        ]
      }
    }
  },
  "required": [
    "room_id",
    "elements"
  ]
}

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Canvas room URL"
    },
    "room_id": {
      "type": "string",
      "description": "Canvas room ID"
    },
    "isNew": {
      "type": "boolean",
      "description": "Whether a new canvas was created"
    },
    "collabUrl": {
      "type": "string",
      "description": "Collaboration server URL for Socket.IO"
    },
    "elements": {
      "type": "array",
      "description": "All elements currently on the canvas",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "appState": {
      "type": "object",
      "description": "Canvas app state (viewBackgroundColor, etc.)",
      "properties": {
        "viewBackgroundColor": {
          "type": "string"
        }
      },
      "additionalProperties": true
    }
  },
  "required": [
    "url",
    "isNew",
    "collabUrl",
    "elements",
    "appState"
  ]
}

Delete elements from a canvas. Requires room_id from a previous Canvs tool result. Pass ids array of element IDs to delete.

{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string",
      "description": "Room ID from a previous Canvs tool result. If you only have a URL, extract it from https://[host]/?room=[room_id] or https://[host]/gdrive?id=[room_id]."
    },
    "ids": {
      "type": "array",
      "description": "Array of element IDs to delete",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "room_id",
    "ids"
  ]
}

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Canvas room URL"
    },
    "room_id": {
      "type": "string",
      "description": "Canvas room ID"
    },
    "isNew": {
      "type": "boolean",
      "description": "Whether a new canvas was created"
    },
    "collabUrl": {
      "type": "string",
      "description": "Collaboration server URL for Socket.IO"
    },
    "elements": {
      "type": "array",
      "description": "All elements currently on the canvas",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "appState": {
      "type": "object",
      "description": "Canvas app state (viewBackgroundColor, etc.)",
      "properties": {
        "viewBackgroundColor": {
          "type": "string"
        }
      },
      "additionalProperties": true
    }
  },
  "required": [
    "url",
    "isNew",
    "collabUrl",
    "elements",
    "appState"
  ]
}

Query elements on a canvas. Requires room_id from a previous Canvs tool result. Returns elements matching optional filters. Use this before update_elements when making small edits to existing diagrams. If no browser has the canvas open, returns an error — ask the user to open the canvas URL in their browser and retry.

{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string",
      "description": "Room ID from a previous Canvs tool result. If you only have a URL, extract it from https://[host]/?room=[room_id] or https://[host]/gdrive?id=[room_id]."
    },
    "type": {
      "type": "string",
      "enum": [
        "rectangle",
        "ellipse",
        "diamond",
        "arrow",
        "line",
        "freedraw",
        "text",
        "image"
      ],
      "description": "Filter by element type"
    },
    "filter": {
      "type": "object",
      "description": "Additional key-value filters (e.g., {locked: true})"
    }
  },
  "required": [
    "room_id"
  ]
}

{
  "type": "object",
  "properties": {
    "count": {
      "type": "number",
      "description": "Number of matching elements"
    },
    "elements": {
      "type": "array",
      "description": "Matching elements"
    }
  },
  "required": [
    "count",
    "elements"
  ]
}

Creates diagram elements from a Mermaid definition. Creates a new canvas if room_id is omitted, or adds to the existing canvas if room_id is provided. Preferred over add_elements for new diagrams and large changes to existing diagrams whenever the content can be represented in Mermaid. Supports: flowchart, graph, flowchart-elk, sequenceDiagram, classDiagram, classDiagram-v2, stateDiagram, stateDiagram-v2, erDiagram, journey, gantt, pie, gitGraph, mindmap, timeline, C4Context, C4Container, C4Component, C4Dynamic, C4Deployment, sankey, sankey-beta, quadrantChart, xychart, xychart-beta, requirement, requirementDiagram, kanban, architecture, block, block-beta, packet, packet-beta, radar-beta, treemap, info. Example: "flowchart TD\n A[Start] --> B{Decision}\n B -->|Yes| C[OK]\n B -->|No| D[Cancel]"

{
  "type": "object",
  "properties": {
    "room_id": {
      "type": "string",
      "description": "Room ID of an existing canvas to add to. If the user is continuing a canvas already referenced in this conversation (by room_id, or a URL like ?room=[room_id] or /gdrive?id=[room_id]), pass it here. Omit to create a new canvas."
    },
    "mermaid": {
      "type": "string",
      "description": "Mermaid diagram definition. Prefer converting compatible user requests into Mermaid instead of using add_elements."
    },
    "config": {
      "type": "object",
      "description": "Optional Mermaid rendering config. flowchart.curve is handled automatically.",
      "properties": {
        "flowchart": {
          "type": "object",
          "properties": {
            "curve": {
              "type": "string",
              "enum": [
                "basis",
                "linear"
              ],
              "description": "Edge curve style (handled server-side; no need to set explicitly)."
            }
          }
        }
      }
    },
    "timeout": {
      "type": "number",
      "description": "Room lifetime in seconds (default: 3600, max: 86400). Only used when creating new canvas",
      "default": 3600
    }
  },
  "required": [
    "mermaid"
  ]
}

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Canvas room URL"
    },
    "room_id": {
      "type": "string",
      "description": "Canvas room ID"
    },
    "isNew": {
      "type": "boolean",
      "description": "Whether a new canvas was created"
    },
    "collabUrl": {
      "type": "string",
      "description": "Collaboration server URL for Socket.IO"
    },
    "elements": {
      "type": "array",
      "description": "All elements currently on the canvas",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "appState": {
      "type": "object",
      "description": "Canvas app state (viewBackgroundColor, etc.)",
      "properties": {
        "viewBackgroundColor": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "pendingMermaid": {
      "type": "object",
      "description": "Mermaid definition pending client-side rendering",
      "properties": {
        "definition": {
          "type": "string",
          "description": "Mermaid diagram source"
        },
        "config": {
          "type": "object",
          "additionalProperties": true
        }
      }
    }
  },
  "required": [
    "url",
    "isNew",
    "collabUrl",
    "elements",
    "appState"
  ]
}