Patch Penpot MCP: add design-token write endpoints (create/update color + typography + dimension tokens, themes) #60

New issue

Closed

opened 2026-04-18 17:42:10 +00:00 by claude-desktop · 0 comments

claude-desktop commented 2026-04-18 17:42:10 +00:00

Collaborator

Copy link

User story

As the designer agent (from #56), I want to create and modify design tokens — colors, typographies, dimensions, themes — programmatically through the Penpot MCP, so that when I open a new design file I can seed a proper token-backed palette instead of drawing visual swatches as regular shapes.

Context

Penpot has first-class design-token support (Tokens tab in the UI: Border Radius, Color, Dimensions, Font Family, Font Size, Font Weight, Letter Spacing, Number, Opacity, Rotation, Shadow, Sizing, Spacing, Stroke Width, Text Case, Text Decoration, Typography + Themes + Collections). The internal format is DTCG-compatible (Design Tokens Community Group / Tokens Studio).

Our patched MCP at ~/Workspace/penpot-mcp-server/ currently exposes:

• get_design_tokens(file_id) — read path, DB-only, fails on our OIDC Penpot instance because the DB pool isn't initialized (see #57's context; same symptom as list_teams).
• No write paths at all. No create_color, update_color, create_theme, apply_token_to_shape, nothing.

Consequence on #55: we drew 24 colored rectangles + 72 labels to mimic a token palette visually. That's not real tokens — shapes can't bind to the palette, theme-switch is impossible, and exporting for CSS/Style Dictionary means the operator copy-pastes from a handoff comment instead of pointing a tool at a JSON file.

The designer agent from #56 is blocked from doing this properly until the MCP can write tokens.

Short-term workaround (landing in parallel): hand-authored DTCG JSON at design/tokens.json in this repo, user imports it via Penpot's Tokens tab UI. Works for today but not sustainable for agent-driven design.

Acceptance criteria

MCP — new tools

Under penpot-mcp-server/src/penpot_mcp/tools/ (or equivalent):

• create_color_token(file_id, set_name, name, value, description?) — inserts a color token into the given token set (creating the set if missing).
• update_color_token(file_id, set_name, name, value) — updates an existing token; errors if missing.
• delete_color_token(file_id, set_name, name) — removes a token.
• create_typography_token(file_id, set_name, name, font_family, font_size, font_weight, letter_spacing?, line_height?) — typography composite.
• create_dimension_token(file_id, set_name, name, value, type) — type ∈ spacing / sizing / borderRadius / strokeWidth etc.
• create_theme(file_id, theme_name, set_names[]) — bundles token sets into a named theme.
• set_active_theme(file_id, theme_name) — marks which theme is active in the file's metadata.
• import_tokens_dtcg(file_id, json_string) — bulk import from DTCG / Tokens Studio JSON; one shot covers everything above.

MCP — fallback behavior

• DB-first / RPC-fallback path on the read side: make get_design_tokens work on the OIDC instance (mirrors the get_file_info RPC fallback we landed on #55). If the DB pool is None, fall through to api.command("get-file", ...) and pluck the tokens-lib section.

Write path — implementation strategy

Two viable approaches, pick one:

1. Direct Penpot RPC — Penpot's update-file command accepts mod-token / add-token / del-token change operations. This is how the UI itself does it. Mirrors the existing changes.py style — cleanest, zero new dependencies.
2. Plugin script via execute_plugin_script — Penpot's plugin API has library.colors.createColor(...), library.typographies.createTypography(...), etc. Works but adds a runtime layer.

Strong preference: (1) direct RPC — matches the rest of services/api.py, same auth model, same apply_changes flow.

Tests

• Unit: each new tool round-trips a token (create → get_design_tokens → assert present → delete → assert absent).
• Import: feed the design/tokens.json bundle from this repo, check all theme-dark colors exist in the file afterwards.
• Bulk: create 50 tokens in parallel, assert no revision-conflict errors (the apply_changes revn handling must cover token writes).

Image + deployment

• claude-hooks:dev rebuild picks up the new tools (since penpot-mcp-server/ is baked in per #57's infra work or its predecessor).
• The designer agent container (#56) sees the new tools via the Penpot MCP binding.

Documentation

• penpot-mcp-server/README.md: document the new token tools.
• penpot-mcp-server/CHANGELOG.md (or equivalent): note the addition.
• If we upstream the MCP patches (out of scope for this ticket), queue a PR for the public repo.

Out of scope

• UI-side token editing (that's Penpot's existing Tokens tab).
• Importing non-DTCG formats (Figma Tokens, Style Dictionary YAML, etc.) — the import_tokens_dtcg tool is enough.
• Binding existing shapes to tokens retroactively — shapes created pre-token stay as literal hex. Future story.
• Multi-file token libraries / shared libraries across files — Penpot supports it, but we only need per-file tokens for now.

References

• Debugging context on #55 where we discovered the gap (drew 24 swatches manually instead of tokens).
• Workaround file: design/tokens.json in this repo — DTCG JSON the operator imports manually via Penpot UI.
• Penpot RPC change-op reference: the existing services/changes.py in our patched MCP (same patterns, new change types).
• Penpot UI Tokens tab: file → left panel → Tokens (third tab after Layers, Resources).
• Tokens Studio / DTCG format: https://design-tokens.github.io/community-group/format/
• Tracking issue: #47. Milestone: Agent pool + customization (#16).

Dependencies

• Blocked by: #56 (designer agent type lands + image is set up to carry the patched MCP). Technically this ticket could land first and sit unused, but it's more coherent sequenced after #56.
• Blocks: full agent-driven design workflow (designer agent seeding its own token palette on every new file instead of asking the operator to import a JSON).
• Branch off: main, or the penpot-mcp-server/ vendored copy if we fork it into the claude-hooks repo.

## User story As the **designer agent** (from #56), I want to create and modify design tokens — colors, typographies, dimensions, themes — programmatically through the Penpot MCP, so that when I open a new design file I can seed a proper token-backed palette instead of drawing visual swatches as regular shapes. ## Context Penpot has first-class design-token support (Tokens tab in the UI: Border Radius, Color, Dimensions, Font Family, Font Size, Font Weight, Letter Spacing, Number, Opacity, Rotation, Shadow, Sizing, Spacing, Stroke Width, Text Case, Text Decoration, Typography + Themes + Collections). The internal format is DTCG-compatible (Design Tokens Community Group / Tokens Studio). Our patched MCP at `~/Workspace/penpot-mcp-server/` currently exposes: - `get_design_tokens(file_id)` — **read path, DB-only, fails on our OIDC Penpot instance** because the DB pool isn't initialized (see #57's context; same symptom as `list_teams`). - **No write paths at all.** No `create_color`, `update_color`, `create_theme`, `apply_token_to_shape`, nothing. Consequence on #55: we drew 24 colored rectangles + 72 labels to mimic a token palette visually. That's not real tokens — shapes can't bind to the palette, theme-switch is impossible, and exporting for CSS/Style Dictionary means the operator copy-pastes from a handoff comment instead of pointing a tool at a JSON file. The `designer` agent from #56 is blocked from doing this properly until the MCP can write tokens. Short-term workaround (landing in parallel): hand-authored DTCG JSON at `design/tokens.json` in this repo, user imports it via Penpot's Tokens tab UI. Works for today but not sustainable for agent-driven design. ## Acceptance criteria ### MCP — new tools Under `penpot-mcp-server/src/penpot_mcp/tools/` (or equivalent): - [ ] `create_color_token(file_id, set_name, name, value, description?)` — inserts a color token into the given token set (creating the set if missing). - [ ] `update_color_token(file_id, set_name, name, value)` — updates an existing token; errors if missing. - [ ] `delete_color_token(file_id, set_name, name)` — removes a token. - [ ] `create_typography_token(file_id, set_name, name, font_family, font_size, font_weight, letter_spacing?, line_height?)` — typography composite. - [ ] `create_dimension_token(file_id, set_name, name, value, type)` — `type` ∈ `spacing` / `sizing` / `borderRadius` / `strokeWidth` etc. - [ ] `create_theme(file_id, theme_name, set_names[])` — bundles token sets into a named theme. - [ ] `set_active_theme(file_id, theme_name)` — marks which theme is active in the file's metadata. - [ ] `import_tokens_dtcg(file_id, json_string)` — bulk import from DTCG / Tokens Studio JSON; one shot covers everything above. ### MCP — fallback behavior - [ ] DB-first / RPC-fallback path on the read side: make `get_design_tokens` work on the OIDC instance (mirrors the `get_file_info` RPC fallback we landed on #55). If the DB pool is `None`, fall through to `api.command("get-file", ...)` and pluck the `tokens-lib` section. ### Write path — implementation strategy Two viable approaches, pick one: 1. **Direct Penpot RPC** — Penpot's `update-file` command accepts `mod-token` / `add-token` / `del-token` change operations. This is how the UI itself does it. Mirrors the existing `changes.py` style — cleanest, zero new dependencies. 2. **Plugin script via `execute_plugin_script`** — Penpot's plugin API has `library.colors.createColor(...)`, `library.typographies.createTypography(...)`, etc. Works but adds a runtime layer. Strong preference: **(1) direct RPC** — matches the rest of `services/api.py`, same auth model, same `apply_changes` flow. ### Tests - [ ] Unit: each new tool round-trips a token (create → `get_design_tokens` → assert present → delete → assert absent). - [ ] Import: feed the `design/tokens.json` bundle from this repo, check all theme-dark colors exist in the file afterwards. - [ ] Bulk: create 50 tokens in parallel, assert no revision-conflict errors (the `apply_changes` revn handling must cover token writes). ### Image + deployment - [ ] `claude-hooks:dev` rebuild picks up the new tools (since `penpot-mcp-server/` is baked in per #57's infra work or its predecessor). - [ ] The `designer` agent container (#56) sees the new tools via the Penpot MCP binding. ### Documentation - [ ] `penpot-mcp-server/README.md`: document the new token tools. - [ ] `penpot-mcp-server/CHANGELOG.md` (or equivalent): note the addition. - [ ] If we upstream the MCP patches (out of scope for this ticket), queue a PR for the public repo. ## Out of scope - UI-side token editing (that's Penpot's existing Tokens tab). - Importing non-DTCG formats (Figma Tokens, Style Dictionary YAML, etc.) — the `import_tokens_dtcg` tool is enough. - Binding existing shapes to tokens retroactively — shapes created pre-token stay as literal hex. Future story. - Multi-file token libraries / shared libraries across files — Penpot supports it, but we only need per-file tokens for now. ## References - Debugging context on #55 where we discovered the gap (drew 24 swatches manually instead of tokens). - Workaround file: `design/tokens.json` in this repo — DTCG JSON the operator imports manually via Penpot UI. - Penpot RPC change-op reference: the existing `services/changes.py` in our patched MCP (same patterns, new change types). - Penpot UI Tokens tab: file → left panel → Tokens (third tab after Layers, Resources). - Tokens Studio / DTCG format: https://design-tokens.github.io/community-group/format/ - Tracking issue: #47. Milestone: Agent pool + customization (#16). ## Dependencies - **Blocked by:** #56 (designer agent type lands + image is set up to carry the patched MCP). Technically this ticket *could* land first and sit unused, but it's more coherent sequenced after #56. - **Blocks:** full agent-driven design workflow (designer agent seeding its own token palette on every new file instead of asking the operator to import a JSON). - **Branch off:** `main`, or the `penpot-mcp-server/` vendored copy if we fork it into the claude-hooks repo.

claude-desktop added the

area:agents

area:infra

type:user-story

labels 2026-04-18 17:42:18 +00:00

dev was assigned by claude-desktop 2026-04-18 17:42:18 +00:00

claude-desktop added this to the Agent pool + customization milestone 2026-04-18 17:42:18 +00:00

dev referenced this issue from a commit 2026-04-18 17:51:10 +00:00

feat(penpot-mcp): add design-token write endpoints and get_design_tokens RPC fallback

dev referenced this issue from a pull request that will close it, 2026-04-18 17:51:21 +00:00

feat(penpot-mcp): add design-token write endpoints and get_design_tokens RPC fallback #61

reviewer referenced this issue 2026-04-18 18:03:32 +00:00

feat(penpot-mcp): add design-token write endpoints and get_design_tokens RPC fallback #61

dev referenced this issue from a commit 2026-04-18 18:04:16 +00:00

feat(penpot-mcp): add design-token write endpoints and get_design_tokens RPC fallback

dev referenced this issue from a commit 2026-04-18 18:14:50 +00:00

feat(penpot-mcp): add design-token write endpoints and get_design_tokens RPC fallback

code-lead closed this issue 2026-04-18 18:20:53 +00:00

code-lead referenced this issue from a commit 2026-04-18 18:20:53 +00:00

feat(penpot-mcp): add design-token write endpoints and get_design_tokens RPC fallback (#61)

charles referenced this issue from a commit 2026-04-18 19:11:49 +00:00

feat(design): add Tokyo Night design tokens (DTCG)

claude-desktop referenced this issue 2026-04-18 20:19:17 +00:00

Bind patched Penpot MCP into designer + design-reviewer containers #64

claude-desktop referenced this issue 2026-04-18 22:44:39 +00:00

Patch Penpot MCP: add canvas primitive tools (create_file / create_page / create_frame / create_text / export_frame_png) #69

designer referenced this issue 2026-04-18 23:05:10 +00:00

Design: rework the claude-hooks monitor (dashboard home screen) #70

design-reviewer referenced this issue 2026-04-19 18:35:16 +00:00

Design: rework the claude-hooks monitor (dashboard home screen) #70

designer referenced this issue 2026-04-19 23:47:09 +00:00

Design: rework the claude-hooks monitor (dashboard home screen) #70

code-lead referenced this issue from a commit 2026-04-20 10:40:09 +00:00

feat(dashboard): implement #70 monitor mockups (#122)

code-lead referenced this issue 2026-04-20 10:40:28 +00:00

feat(dashboard): implement #70 monitor mockups #126

code-lead referenced this issue from a commit 2026-04-20 10:58:25 +00:00

feat(dashboard): implement #70 monitor mockups

Sign in to join this conversation.

No Branch/Tag specified

Branches Tags

main

chore/sync-pre-push-from-forge-base

fix/flows-yaml-dispatch-identity

feat/board-tap-to-assign

dev/1107

code-lead/1106

code-lead/1108

dev/1104

code-lead/1103

code-lead/1080

dev/1087

feat/flows-yaml-ci-events

chore/board-drop-stalled-and-density-controls

fix/flows-yaml-routes-always-register

flows-yaml/api-defaults

dev/1023

fix/event-log-history-bleed

fix/janitor-fix-ci-logs-and-cap

dev/1022

fix/board-card-provider

code-lead/1036

dev/1025

code-lead/1020

dev/1017

code-lead/1026

feat/web-shortcut-registry-1018

dev/1015

code-lead/1009

code-lead/1008

dev/975

dev/969

dev/973

dev/967

code-lead/968

code-lead/953

dev/970

dev/976

code-lead/966

code-lead/956

code-lead/951

dev/962

dev/963

dev/977

dev/955

dev/983

dev/961

dev/974

code-lead/950

code-lead/939

dev/941

dev/940

dev/937

dev/938

dev/936

dev/935

feat/web-i18n-fr-locale

feat/spec-editor-ui-polish

chore/drop-legacy-compat

fix/skills-drop-preview-pane

fix/882-skills-safety-rail

dev/911

dev/909

dev/923

dev/917

dev/915

feat/879-sr11-m2-drop-legacy-skill

code-lead/873

dev/881

code-lead/869

dev/867

code-lead/845

code-lead/843

code-lead/844

dev/837

dev/861

dev/849

code-lead/837

code-lead/842

fix/dedup-rebase-inflight

dev/838

code-lead/847

dev/833

code-lead/848

pr/838

code-lead/841

feat/settings-save-bar/836

code-lead/840

dev/846

code-lead/839

dev/832

fix/board-sse-stale-cache

dev/834

dev/835

feat/settings-breadcrumbs

feat/forge-oauth-credentials

refactor/service-config-consolidation

feat/agent-tokens-to-secrets

feat/gitlab-oauth-to-db

feat/authelia-rip-and-voice-fixes

fix/rebase-storm-and-dead-letter

code-lead/797

code-lead/796

dev/811

code-lead/798

dev/810

code-lead/795

dev/808

code-lead/794

dev/805

dev/802

dev/803

feat/avatar-menu-settings-entry

feat/per-agent-token-tracking

dev/793

dev/747

dev/752

code-lead/790

code-lead/759

dev/756

dev/760

dev/741

dev/767

dev/740

dev/709

dev/644

dev/637

boss/614

dev/600

dev/611

dev/585

fix/login-bonus-fixes

boss/544

dev/542

refactor/api-prefix-and-session-gate

dev/489

boss/531

boss/518

dev/499

boss/516

dev/530

dev/517

dev/519

dev/515

dev/522

dev/503

dev/471

boss/329

dev/417

dev/418

dev/402

boss/327

dev/334

dev/332

boss/326

boss/325

dev/331

boss/324

boss/323

boss/322

dev/294

test/s11-task-analytics

dev/262

boss/270

dev/268

foreman/ui-consolidation-spec

dev/234

boss/196

boss/176

boss/164

fix/124-session-persist-bind

boss/52

dev/87

boss/73

dev/77

dev/81

dev/82

boss/79

dev/42

dev/35

boss/7

No results found.

Labels

Clear labels   

area:agents

Agent types, pool scheduling, per-instance config

  

area:dashboard

Dashboard UI and observability surfaces

  

area:database

DB layer — schema, migrations, ORM, raw SQL

  

area:design

UI/UX mockup work — routes to designer agent

  

area:design-review

Design review dispatch — routes to design-reviewer agent

  

area:flows

Flow runner — YAML loader, executor, op registry, expression eval

  

area:infra

Deployment, isolation, containers, systemd units

  

area:meta

Tracking, scaffolding, project setup

  

area:security

Security — routes to reviewer-security (opus)

  

area:sessions

Session-id store, Claude SDK resume logic

  

area:webhook

Forgejo webhook routing and handlers

  

area:workdir

Clone cache, worktrees, git identity

  

security

Security-sensitive issue

  

type:bug

Bug

  

type:chore

Chore

  

type:meta

Tracking or decisions, not implementation work

  

type:user-story

User story

No labels

area:agents

area:dashboard

area:database

area:design

area:design-review

area:flows

area:infra

area:meta

area:security

area:sessions

area:webhook

area:workdir

security

type:bug

type:chore

type:meta

type:user-story

Milestone

Clear milestone

No items

No milestone

Agent pool + customization

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

dev

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

charles/claude-hooks#60

No description provided.