feat: add create_page MCP tool

[julioservan]

Closes #27

Problem

The bridge exposes a fairly complete authoring surface — frames, text, shapes, images, groups, auto-layout, effects — but there is no way to create a page. As reported in #27, agents working in a file have to place everything on the current page, and the common workaround is pushing new frames far off-canvas so they don't collide with existing work.

Solution

Adds a create_page tool following the same pattern as the other create_* tools:

• server/src/schema.ts — createPageInput (name?, setAsCurrent?, fileKey?), plus entries in toolInputSchemas and rpcToArgs, so the request goes through the same validateRpc path as every other tool.
• server/src/tools.ts — registers the tool with parseToolInput / renderResponse, mirroring create_frame.
• plugin/src/main/code.ts — adds create_page to the RequestType union and to EDIT_REQUEST_TYPES, and implements the handler.
• README.md — one row in the tools table and a note under Editing Notes.

The tool returns the new page's ID, so it composes with the existing tools without needing to switch the editor:

create_page { name: "Wireframes" }     → { pageId: "12:0", pageName: "Wireframes", index: 3, isCurrentPage: false }
create_frame { parentId: "12:0", ... } → frame is created on the new page

getParentNodeById already accepts any node with appendChild, so PageNode works as a parentId with no changes on that path.

Notes

• setCurrentPageAsync — the manifest sets documentAccess: "dynamic-page", where assigning figma.currentPage directly throws. The optional setAsCurrent flag uses the async setter instead. It defaults to false so creating a page is non-disruptive.
• Dev Mode — create_page is added to EDIT_REQUEST_TYPES so it returns the existing "requires the design editor" message instead of an opaque runtime error.
• name is .min(1) — an empty string would produce an unnamed page, so it's rejected at the schema level.

Verification

• tsc --noEmit on server/ — clean.
• tsc --noEmit on plugin/ — same pre-existing errors as main, no new ones.
• vite build — plugin bundle builds with create_page present in dist/code.js.
• Booted the built server over stdio with an MCP client: 38 tools registered, create_page among them with the expected input schema.
• Schema validation exercised directly: valid inputs pass, {name:""} and {setAsCurrent:"yes"} are rejected with readable messages.

Haven't been able to exercise the handler inside a live Figma file yet — happy to test further if useful.

Summary by CodeRabbit

• New Features

  • Added a tool for creating pages with an optional name.
  • Pages can optionally be selected as the current page after creation.
  • Creation results include the new page’s ID, name, position, and current-page status.
  • The returned page ID can be used as a parent when creating nodes without switching pages.

• Documentation

  • Added guidance for using the new page creation tool.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d7800aaa-6577-45e7-83a1-913812177c35

📥 Commits

Reviewing files that changed from the base of the PR and between 9dce7f9 and 5cb23da.

📒 Files selected for processing (1)

• plugin/src/main/code.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• plugin/src/main/code.ts

---

📝 Walkthrough

Walkthrough

The PR adds the create_page tool. It validates optional parameters, creates and optionally selects a Figma page, returns page metadata, loads page parents before child insertion, and documents page ID usage.

Changes

Page creation

Layer / File(s)	Summary
Server schema and tool wiring server/src/schema.ts, server/src/tools.ts	The server validates name, setAsCurrent, and fileKey, registers create_page, maps its RPC arguments, and forwards the request.
Plugin page creation and parent handling plugin/src/main/code.ts	The plugin registers create_page, loads page parents before appending child nodes, creates and names pages, optionally selects them, and returns page metadata. Existing logic also receives formatting-only reflows.
Tool usage documentation README.md	The README documents create_page and using its returned page ID as parentId for node creation.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant MCPClient
  participant MCPServer
  participant FigmaPlugin
  participant FigmaPage
  MCPClient->>MCPServer: submit create_page parameters
  MCPServer->>FigmaPlugin: forward validated request
  FigmaPlugin->>FigmaPage: create and name page
  FigmaPlugin->>FigmaPage: optionally select page
  FigmaPage-->>FigmaPlugin: return page metadata
  FigmaPlugin-->>MCPServer: return standardized result
  MCPServer-->>MCPClient: return page ID and metadata

Loading

Possibly related PRs

• gethopp/figma-mcp-bridge#20: Adds multi-file RPC plumbing extended here with create_page.
• gethopp/figma-mcp-bridge#23: Extends the authoring tool surface with page creation and page-parent handling.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the main change: adding the create_page MCP tool.
Linked Issues check	✅ Passed	The PR adds and documents the requested create_page tool, satisfying issue #27.
Out of Scope Changes check	✅ Passed	The schema, tool registration, plugin handling, and README updates directly support the create_page objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@plugin/src/main/code.ts`:
- Around line 1251-1276: Update appendToParentIfProvided to detect when the
resolved parent is a PageNode and await its loadAsync() before calling
parent.appendChild(node), including non-current pages created by create_page.
Preserve the existing behavior for all other parent node types.

In `@server/src/schema.ts`:
- Around line 404-407: Update the page name validator in the schema’s name field
to reject whitespace-only values by validating the trimmed string has positive
length, while preserving optionality and acceptance of non-whitespace names.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 560eb11f-49da-4fac-9402-7926cb414503

📥 Commits

Reviewing files that changed from the base of the PR and between dc2ea5a and 9dce7f9.

📒 Files selected for processing (4)

• README.md
• plugin/src/main/code.ts
• server/src/schema.ts
• server/src/tools.ts

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ konsalex
❌ julioservan
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[konsalex]

@julioservan could you sing the CLA please? Pushed also a minor fix, everything looks great!

#42 (comment)