Danila Poyarkov 4ad90d4819 Add MCP server package with stdio and HTTP transports

29 tools: open_file, save_file, new_document + all 26 from @open-pencil/core.
Stdio for MCP clients (Claude Code, Cursor), HTTP (Hono + Streamable HTTP
with sessions) for scripts, browser extensions, CI.
Runs on both Bun and Node.js (via tsx).

2026-03-02 14:20:49 +03:00

3.4 KiB

Raw Blame History

MCP Server

OpenPencil includes an MCP (Model Context Protocol) server that lets AI coding tools — Claude Code, Cursor, Windsurf, etc. — read and modify .fig files headlessly.

Two transports: stdio for MCP clients, HTTP for everything else.

Stdio (Claude Code, Cursor, etc.)

Add to your MCP config (e.g. ~/.claude/settings.json or .cursor/mcp.json):

::: code-group

{
  "mcpServers": {
    "open-pencil": {
      "command": "bun",
      "args": ["/path/to/open-pencil/packages/mcp/src/index.ts"]
    }
  }
}

{
  "mcpServers": {
    "open-pencil": {
      "command": "npx",
      "args": ["tsx", "/path/to/open-pencil/packages/mcp/src/index.ts"]
    }
  }
}

:::

HTTP

For browser extensions, scripts, CI, or any HTTP client:

# Bun
bun packages/mcp/src/http.ts

# Node.js
npx tsx packages/mcp/src/http.ts

Starts on port 3100 (override with PORT env var). Endpoints:

GET /health — server status
POST /mcp — MCP Streamable HTTP (SSE). Sessions via mcp-session-id header.

Workflow

Open — open_file to load an existing .fig, or new_document for a blank canvas
Read — get_page_tree, find_nodes, get_node, list_pages
Create — create_shape, render (JSX)
Modify — set_fill, set_stroke, set_layout, update_node, set_effects
Structure — reparent_node, group_nodes, clone_node, delete_node
Save — save_file to write back to .fig

Tools (29)

Document

Tool	Description
`open_file`	Open a `.fig` file for editing
`save_file`	Save the current document to a `.fig` file
`new_document`	Create a new empty document

Read

Tool	Description
`get_selection`	Get currently selected nodes
`get_page_tree`	Get the full node tree of the current page
`get_node`	Get detailed properties of a node by ID
`find_nodes`	Find nodes by name pattern and/or type
`list_pages`	List all pages
`list_variables`	List design variables
`list_collections`	List variable collections

Create

Tool	Description
`create_shape`	Create a shape (FRAME, RECTANGLE, ELLIPSE, TEXT, LINE, STAR, POLYGON, SECTION)
`render`	Render JSX to design nodes — create entire component trees in one call
`create_component`	Convert a frame/group into a component
`create_instance`	Create an instance of a component

Modify

Tool	Description
`set_fill`	Set fill color (hex)
`set_stroke`	Set stroke color, weight, alignment
`set_effects`	Add shadow or blur effects
`update_node`	Update position, size, opacity, corner radius, text, font
`set_layout`	Set auto-layout (flexbox) — direction, spacing, padding, alignment
`set_constraints`	Set resize constraints

Structure

Tool	Description
`delete_node`	Delete a node
`clone_node`	Duplicate a node
`rename_node`	Rename a node
`reparent_node`	Move a node into a different parent
`select_nodes`	Select nodes by ID
`group_nodes`	Group nodes
`ungroup_node`	Ungroup a group

Tool	Description
`switch_page`	Switch to a page by name or ID

Escape Hatch

Tool	Description
`eval`	Execute JavaScript with full Figma Plugin API access

3.4 KiB Raw Blame History