249 lines
11 KiB
Markdown
249 lines
11 KiB
Markdown
# Lucid MCP Tool Reference Guide
|
|
|
|
Full detail on every Lucid MCP tool: what it does, when to use it, example prompts, and edge cases.
|
|
|
|
---
|
|
|
|
## Tool: Search Documents
|
|
|
|
**Purpose:** Full-text search across the user's entire Lucid library (Lucidchart + Lucidspark).
|
|
|
|
**Input:** Natural language query describing what to find.
|
|
|
|
**Output:** List of matching documents with titles, document types, and direct links.
|
|
|
|
**Example prompts:**
|
|
- "Find my Birmingham transit architecture diagram"
|
|
- "Search for any process flows related to display installation"
|
|
- "Do I have a diagram showing the RDMC API integration?"
|
|
- "Find last month's standup board"
|
|
|
|
**Edge cases:**
|
|
- If no results found: ask the user for alternate search terms or whether the document might be in a shared folder
|
|
- If many results: list top 5 with titles, ask user to select
|
|
- Search may not find content on pages 2+ of a document (known Lucid limitation as of May 2026)
|
|
|
|
---
|
|
|
|
## Tool: Get Document Content / Summary
|
|
|
|
**Purpose:** Retrieve the textual content, shape labels, connections, and structure of a specific Lucid document.
|
|
|
|
**Input:** Document ID or URL.
|
|
|
|
**Output:** Structured description of document content — shapes, labels, arrows, swim lanes, page titles.
|
|
|
|
**Example prompts:**
|
|
- "Summarize the key steps in this process diagram: [URL]"
|
|
- "What nodes are in the architecture diagram I just found?"
|
|
- "List all the shapes and connections in this flowchart"
|
|
- "What's the data flow shown in this ER diagram?"
|
|
|
|
**Usage pattern:** Typically follows a search — take the document URL from search results and pass it to this tool.
|
|
|
|
**Edge cases:**
|
|
- Complex diagrams with many pages: summarize page by page, ask user which pages matter
|
|
- Diagrams with embedded images or custom shapes: describe layout and label text only
|
|
- If content is sparse/empty: report that the document appears blank or contains mostly images
|
|
|
|
---
|
|
|
|
## Tool: Create Diagram
|
|
|
|
**Purpose:** Generate a new Lucid diagram with standard shapes based on a text description.
|
|
|
|
**Input:** Structured description including:
|
|
- Diagram type (flowchart, sequence, ER, user flow, network, swim lane, etc.)
|
|
- Node/shape names and labels
|
|
- Connections (which node connects to which, direction, label on arrow if any)
|
|
- Any branching/decision logic
|
|
|
|
**Output:** Link to newly created Lucidchart document.
|
|
|
|
**Supported diagram types (standard shapes):**
|
|
- Process flowcharts
|
|
- User flow diagrams
|
|
- Sequence diagrams
|
|
- Entity-relationship (ER) diagrams
|
|
- Network / system architecture diagrams
|
|
- Swim lane diagrams
|
|
- Mind maps
|
|
- Org charts (see dedicated org chart tool below)
|
|
|
|
**NOT supported (as of May 2026):**
|
|
- Custom shape libraries (DFD, AWS, GCP, Azure specific icons) — these require manual editing in Lucidchart
|
|
- Custom/branded shape sets
|
|
|
|
**Example prompts:**
|
|
- "Create a user flow for the display provisioning process in Lucid. Start at 'New Display', show 'Register in RDMC', branch to 'Online Check', and end at 'Deployed'."
|
|
- "Build a sequence diagram in Lucid showing the RDMC polling a display every 60 seconds — include the status response."
|
|
- "Make a swim lane flowchart in Lucid for our helpdesk escalation: lanes for Customer, L1 Support, and Engineering."
|
|
- "Create an ER diagram in Lucid for our display inventory schema: Display, Location, Agency, and ServiceRecord tables."
|
|
|
|
**Before invoking:** If the user's description is high-level (e.g., "make a diagram for our deployment process"), ask for the key steps or nodes before generating. This avoids a useless first draft.
|
|
|
|
---
|
|
|
|
## Tool: Create Org Chart
|
|
|
|
**Purpose:** Generate a structured org chart diagram in Lucid from text or CSV data.
|
|
|
|
**Input (text):** Natural language description of hierarchy.
|
|
- Example: "Create an org chart where Bryan is at the top. Under Bryan are Sarah (Director of Ops) and Mike (Director of Engineering). Under Mike are four engineers: Alex, Jamie, Chris, and Dana."
|
|
|
|
**Input (CSV):** Uploaded CSV with at minimum:
|
|
- Name column
|
|
- Manager/Reports-To column
|
|
- Optional: Title, Department, Email
|
|
|
|
**CSV column mapping — confirm before generating:**
|
|
- Name → person's full name
|
|
- Manager → their direct manager's name (blank = top of hierarchy)
|
|
- Title → job title (optional but recommended)
|
|
- Department → used for grouping/color (optional)
|
|
|
|
**Output:** Link to newly created org chart in Lucid.
|
|
|
|
**Example prompts:**
|
|
- "Build an org chart for MPM where Bryan is CEO. Under Bryan: Sarah (COO), Mike (CTO), and Jess (VP Sales)."
|
|
- "Generate an org chart from this CSV file I'm uploading. Name is column A, Manager is column C."
|
|
- "Create a department hierarchy for our Engineering team in Lucid."
|
|
|
|
**Edge cases:**
|
|
- Circular references in CSV (A reports to B, B reports to A): flag and ask user to resolve before generating
|
|
- Missing manager names that don't match any Name in the dataset: flag as orphaned nodes
|
|
- Very large org charts (50+ people): warn that generation may take longer and the diagram will need layout adjustment in Lucidchart
|
|
|
|
---
|
|
|
|
## Tool: Share Document
|
|
|
|
**Purpose:** Share a Lucid document with a specific person by email.
|
|
|
|
**Input:**
|
|
- Document ID or URL
|
|
- Recipient email address
|
|
- Permission level: View, Comment, Edit, or Edit and Share
|
|
|
|
**Output:** Confirmation that the share was sent.
|
|
|
|
**Example prompts:**
|
|
- "Share my 'Installation Process Flow' Lucid doc with sarah@messagepoint.media with edit permissions."
|
|
- "Give bryan@messagepoint.media view-only access to the Birmingham architecture diagram."
|
|
- "Share this board with my whole team at messagepoint.media — give them comment access."
|
|
|
|
**Permission level guide:**
|
|
- **View:** Can see the document, cannot edit or share
|
|
- **Comment:** Can add comments, cannot edit shapes
|
|
- **Edit:** Can modify diagram content
|
|
- **Edit and Share:** Full access including re-sharing with others
|
|
|
|
**Always confirm before executing:** "I'll share [document title] with [email] at [permission level]. Confirm?"
|
|
|
|
---
|
|
|
|
## Tool: Create Share Link
|
|
|
|
**Purpose:** Generate a shareable URL to a Lucid document with specified permissions.
|
|
|
|
**Input:**
|
|
- Document ID or URL
|
|
- Link permission type: View, Comment, or Edit
|
|
|
|
**Output:** Shareable URL string.
|
|
|
|
**Example prompts:**
|
|
- "Create a view-only share link for the Project Proposal diagram."
|
|
- "Get me a comment-enabled link for this board so stakeholders can leave feedback."
|
|
- "Make a shareable link for this flowchart — edit permissions."
|
|
|
|
**Use cases:**
|
|
- Embedding in emails, Slack messages, or proposals
|
|
- Sharing with people who don't have a Lucid account (view links work without login)
|
|
- Distributing to external clients or transit agencies
|
|
|
|
**After generating:** Offer to send the link via email or copy it into an open document/email draft.
|
|
|
|
---
|
|
|
|
## Tool: Convert SVG to Diagram (lucid_convert_svg_to_diagram)
|
|
|
|
**Purpose:** Convert a complete SVG directly into a new editable Lucidchart document. This is the **preferred tool for creating most diagrams** — it preserves color, handles custom shapes, and produces higher-fidelity output than the JSON spec path.
|
|
|
|
**When to use:**
|
|
- Any time a flowchart, process flow, network diagram, architecture diagram, user flow, or ER diagram is needed — generate the SVG, then pass it here verbatim
|
|
- Any time Claude has already drawn an SVG (e.g. a visualize widget in chat) and the user wants it editable in Lucid
|
|
- Any time custom or branded shapes need to be embedded in a Lucid diagram
|
|
|
|
**When NOT to use:**
|
|
- Sequence diagrams → use `lucid_create_sequence_diagram` (PlantUML)
|
|
- Org charts → use `lucid_create_org_chart`
|
|
- Diagrams requiring Lucid-native shape types: BPMN pools, UML class blocks, named AWS/GCP/Azure library shapes, lucidCard, tables → use `lucid_create_diagram_from_specification`
|
|
|
|
**Input:**
|
|
- `title`: Document title
|
|
- `svg`: A valid SVG string with `<svg>` tag, max 256KB. Pass **verbatim** — do not simplify or rewrite before calling.
|
|
- `product`: `"lucidchart"` (default) or `"lucidspark"`
|
|
|
|
**Supported SVG elements:** `<rect>`, `<polygon>`, `<ellipse>`, `<circle>`, `<line>`, `<path>`, `<text>`. These map to Lucid flowchart shapes (process boxes, decision diamonds, terminators, circles) with connecting lines.
|
|
|
|
**Color handling:** Colors applied via inline `fill` and `stroke` attributes are preserved. Theme classes `c-purple`, `c-teal`, `c-coral`, `c-blue`, `c-green`, `c-amber`, `c-red`, `c-pink`, `c-gray` are also supported.
|
|
|
|
**Custom shape embedding:**
|
|
To include a custom shape (MPM hardware icon, branded element, shape from "My Library"):
|
|
1. Ask the user to export/share the SVG source of their custom shape
|
|
2. Embed it as a `<g transform="translate(x,y)">...</g>` block in the diagram SVG
|
|
3. Pass the full composed SVG to this tool
|
|
The custom shape lands in Lucidchart as a fully editable element — same end result as placing it from a shape library.
|
|
|
|
**Custom shape libraries (My Library):** NOT accessible via the MCP API. Only AWS 2024, GCP 2021, and Azure 2024 libraries are exposed via `get_mcp_resource`. The SVG embed approach above is the correct workaround.
|
|
|
|
**Example prompts:**
|
|
- "Build a display provisioning flowchart and push it to Lucid."
|
|
- "Take that SVG diagram you just generated and make it editable in Lucidchart."
|
|
- "Create an architecture diagram using our custom Escalator shape — here's the SVG source."
|
|
- "Convert this process flow to a Lucid document."
|
|
|
|
**Output:** Edit URL and view URL for the new Lucidchart document.
|
|
|
|
**Verified:** Smoke-tested 2026-05-21. Colors, shapes, and connections confirmed working.
|
|
|
|
---
|
|
|
|
## Authentication & Setup Notes
|
|
|
|
The Lucid MCP server uses OAuth. First-time setup requires:
|
|
|
|
1. A Lucid account (Team or Enterprise plan)
|
|
2. Lucid Admin Panel → Security → Feature Controls → enable "Allow users to connect" under MCP Access
|
|
3. In CoWork: open the lucid-mcp plugin → Connectors → connect the Lucid connector (OAuth flow)
|
|
4. Authorize Claude to access your Lucid account
|
|
|
|
If tools return authentication errors, go to CoWork plugin settings → lucid-mcp → Connectors → disconnect and reconnect to re-trigger the OAuth flow.
|
|
|
|
---
|
|
|
|
## Plan Requirements
|
|
|
|
| Feature | Team Plan | Enterprise Plan |
|
|
|---------|-----------|-----------------|
|
|
| Search, fetch, summarize | ✅ | ✅ |
|
|
| Create diagrams (all types) | ✅ | ✅ |
|
|
| Export as PNG | ✅ | ✅ |
|
|
| Add / edit / delete shapes | ✅ | ✅ |
|
|
| Create share links | ❌ | ✅ |
|
|
| Share with collaborators by email | ❌ | ✅ |
|
|
|
|
The `lucid_create_document_share_link` and `share_document_with_collaborators` tools require an **Enterprise Lucid plan**. On Team plan these return 400/403 errors. Direct the user to share manually from within Lucidchart, or note that upgrading to Enterprise unlocks this capability.
|
|
|
|
---
|
|
|
|
## Known Limitations (as of May 2026)
|
|
|
|
- Search may not reliably find content on page 2+ of multi-page documents
|
|
- AWS 2024, GCP 2021, and Azure 2024 shape libraries ARE accessible via `get_mcp_resource` — cloud provider shapes work fine (earlier documentation incorrectly said they were unavailable)
|
|
- **Custom user shape libraries ("My Library") are NOT accessible via the MCP API** — only the three cloud provider libraries above are exposed. Workaround: ask the user to share the SVG source of their custom shape, embed it into the diagram SVG, and push via `lucid_convert_svg_to_diagram`
|
|
- Cannot edit existing diagram content via MCP — only read and create new documents
|
|
- Editing/opening Kiro-generated diagrams not supported
|
|
- `lucid_convert_svg_to_diagram` was added to the MCP in May 2026 and is now the preferred diagram creation path for standard flowcharts and structured diagrams
|