@pinepaper.studio/mcp-server 1.6.23 → 1.6.25

package/README.de.md

@@ -19,7 +19,7 @@
 
 Der PinePaper MCP-Server lässt KI-Assistenten über das Model Context Protocol Grafiken in [PinePaper Studio](https://pinepaper.studio) erstellen und animieren. Funktioniert mit jeder KI, die MCP-Tool-Aufrufe unterstützt (Claude, GPT, Gemini, lokale Modelle usw.).
 
-Der Server bietet **177 Tools**: Zeichnen, Animation, Diagramme, Karten, Typografie, Physik, Bildbearbeitung, Datenvisualisierung und Export:
+Der Server bietet **178 Tools**: Zeichnen, Animation, Diagramme, Karten, Typografie, Physik, Bildbearbeitung, Datenvisualisierung und Export:
 
 - Text, Formen, Geometrie und komplexe Grafiken erstellen
 - Mit deklarativen **Relationen** animieren statt mit Keyframes

package/README.es.md

@@ -19,7 +19,7 @@
 
 El servidor MCP de PinePaper permite a los asistentes de IA crear y animar gráficos en [PinePaper Studio](https://pinepaper.studio) a través del Model Context Protocol. Funciona con cualquier IA que soporte llamadas a herramientas MCP (Claude, GPT, Gemini, modelos locales, etc.).
 
-Expone **177 herramientas**: dibujo, animación, diagramas, mapas, tipografía, física, edición de imágenes, visualización de datos y exportación:
+Expone **178 herramientas**: dibujo, animación, diagramas, mapas, tipografía, física, edición de imágenes, visualización de datos y exportación:
 
 - Crear texto, formas, geometría y gráficos complejos
 - Animar con **relaciones** declarativas en lugar de fotogramas clave

package/README.fr.md

@@ -19,7 +19,7 @@
 
 Le serveur MCP PinePaper permet aux assistants IA de créer et d'animer des graphiques dans [PinePaper Studio](https://pinepaper.studio) via le Model Context Protocol. Compatible avec toute IA gérant les appels d'outils MCP (Claude, GPT, Gemini, modèles locaux, etc.).
 
-Il expose **177 outils** : dessin, animation, diagrammes, cartes, typographie, physique, retouche d'image, visualisation de données et export :
+Il expose **178 outils** : dessin, animation, diagrammes, cartes, typographie, physique, retouche d'image, visualisation de données et export :
 
 - Créer du texte, des formes, de la géométrie et des graphiques complexes
 - Animer avec des **relations** déclaratives plutôt que des images clés

package/README.hi.md

@@ -19,7 +19,7 @@
 
 PinePaper MCP सर्वर AI असिस्टेंट्स को Model Context Protocol के ज़रिए [PinePaper Studio](https://pinepaper.studio) में ग्राफ़िक्स बनाने और एनिमेट करने देता है। MCP टूल कॉलिंग वाले किसी भी AI (Claude, GPT, Gemini, लोकल मॉडल आदि) के साथ काम करता है।
 
-सर्वर **177 टूल** देता है — ड्रॉइंग, एनिमेशन, डायग्राम, नक्शे, टाइपोग्राफ़ी, फिज़िक्स, इमेज एडिटिंग, डेटा विज़ुअलाइज़ेशन और एक्सपोर्ट:
+सर्वर **178 टूल** देता है — ड्रॉइंग, एनिमेशन, डायग्राम, नक्शे, टाइपोग्राफ़ी, फिज़िक्स, इमेज एडिटिंग, डेटा विज़ुअलाइज़ेशन और एक्सपोर्ट:
 
 - टेक्स्ट, आकृतियाँ, ज्यामिति और जटिल ग्राफ़िक्स बनाना
 - कीफ़्रेम की जगह व्यवहार बताने वाले **रिलेशन** से एनिमेशन

package/README.ja.md

@@ -19,7 +19,7 @@
 
 PinePaper MCP サーバーは、MCP 経由で AI アシスタントが [PinePaper Studio](https://pinepaper.studio) 上にグラフィックを作成・アニメーションさせるためのサーバーです。MCP ツールコールに対応した AI（Claude、GPT、Gemini、ローカルモデルなど）で動作します。
 
-**177 個のツール**を提供 — 描画・アニメーション・図・地図・タイポグラフィ・物理・画像編集・データ可視化・エクスポート：
+**178 個のツール**を提供 — 描画・アニメーション・図・地図・タイポグラフィ・物理・画像編集・データ可視化・エクスポート：
 
 - テキスト、図形、ジオメトリ、複雑なグラフィックの作成
 - キーフレームではなく、ふるまいを宣言する**リレーション**でアニメーション

package/README.ko.md

@@ -19,7 +19,7 @@
 
 PinePaper MCP 서버는 AI 어시스턴트가 MCP를 통해 [PinePaper Studio](https://pinepaper.studio)에서 그래픽을 만들고 애니메이션하게 해줍니다. MCP 툴 콜을 지원하는 모든 AI(Claude, GPT, Gemini, 로컬 모델 등)와 호환됩니다.
 
-**177개의 툴** 제공 — 드로잉, 애니메이션, 다이어그램, 지도, 타이포그래피, 물리, 이미지 편집, 데이터 시각화, 내보내기:
+**178개의 툴** 제공 — 드로잉, 애니메이션, 다이어그램, 지도, 타이포그래피, 물리, 이미지 편집, 데이터 시각화, 내보내기:
 
 - 텍스트·도형·기하·복잡한 그래픽 생성
 - 키프레임 대신 행동을 선언하는 **릴레이션**으로 애니메이션

package/README.md

@@ -30,7 +30,7 @@
 
 PinePaper MCP Server enables AI assistants to create and animate graphics in [PinePaper Studio](https://pinepaper.studio) via the Model Context Protocol (MCP). Works with any AI that supports MCP tool calling (Claude, GPT, Gemini, local models, etc.).
 
-The server exposes **177 tools** across drawing, animation, diagrams, maps, typography, physics, image editing, data visualization, and export. Using natural language, you can:
+The server exposes **178 tools** across drawing, animation, diagrams, maps, typography, physics, image editing, data visualization, and export. Using natural language, you can:
 
 - Create geometric shapes, text collages, diagrams, and data charts
 - Apply 37+ character-level text effects and 28+ vertex deformation presets
@@ -41,7 +41,7 @@ The server exposes **177 tools** across drawing, animation, diagrams, maps, typo
 
 ## Running it: local or hosted
 
-**Local is free and complete.** Every one of the 177 tools works when you run
+**Local is free and complete.** Every one of the 178 tools works when you run
 this server yourself. There is no reduced tier and nothing held back.
 
 What it needs:
@@ -240,6 +240,8 @@ If you do not want an agent executing anything, `code` mode is a first-class pat
 
 **What guards execution.** On current engine builds the snippet goes through `app.runGenerated(code, { source: 'agent' })` — a governor with seeded determinism, loop and item budgets, and a machine-readable report — rather than a bare `eval`. Older engine builds fall back to `eval`.
 
+**Found a vulnerability?** Report it privately, as [SECURITY.md](SECURITY.md) describes, not in a public issue.
+
 **What to weigh before running it.**
 
 - Code an agent writes runs with whatever that browser page has. Give this server the same trust you would give anything else you let write and run code on your machine — which is the trust you already extend to an MCP client with tool access.
@@ -247,6 +249,198 @@ If you do not want an agent executing anything, `code` mode is a first-class pat
 - Puppeteer itself is an **optional** peer dependency, kept out of the default tree precisely because a headless browser plus an install script is what scanners flag hardest. Install it only if you want the executing mode.
 - The server itself fetches the images, SVGs and media a tool call names by URL, and reads local files named by path. URLs that resolve to loopback, private, link-local or reserved addresses are refused, redirects included, and so are cloud metadata addresses. Local files are read only from the working directory, the export folder, and folders listed in `PINEPAPER_ASSET_DIRS`. `PINEPAPER_ALLOW_PRIVATE_NETWORK=1` allows local and LAN hosts. Metadata addresses stay refused even with it set.
 
+## What's new in 1.6.25
+
+### Added
+
+- `pinepaper_pattern` kinds `ring` and `orbit`: members spaced evenly round a
+  turning circle, with a fixed `center` or a `target` item the centre follows.
+  The list of kinds now comes from the studio, so a kind it adds appears here
+  too.
+
+### Changed
+
+- The server speaks MCP itself instead of through the MCP SDK, so installing
+  it pulls in 2 packages (`zod` and `undici`) instead of 78. It behaves the
+  same on the wire: the same protocol versions (2024-10-07 to 2025-11-25),
+  errors, progress, cancellation and logging, checked against recordings of
+  the previous server. `createServer()` still accepts any MCP transport,
+  including the SDK's.
+- The published code no longer uses `eval` or runs `git`, and it reads
+  environment variables in one place.
+- New sessions start with a leaner tool list: the `core` toolkit, about half
+  the context of the previous default, with every craft tool the server
+  recommends. Other tools load when needed with `pinepaper_set_toolkit`
+  `{"load": ["map"]}` (a group) or a tool's name, and the list updates at
+  once. Claude Desktop, Cursor and Windsurf used to get all 178 tools.
+  `PINEPAPER_TOOLKIT=agent` or `full` restores a larger list.
+- Exports are saved to `~/Downloads/PinePaper` instead of a temporary folder,
+  so Desktop users can find them (`PINEPAPER_EXPORT_DIR` still overrides it,
+  and machines without a Downloads folder keep the temporary folder). Each
+  saved file also comes back as a link the client can open, and
+  `resources/read` returns files up to 10 MB from the export folder.
+- A Claude Desktop extension (`.mcpb`) can be built with `bun run
+  build:mcpb`: one file to open, no config to edit. It uses your installed
+  Chrome for the canvas tools. Without full `puppeteer`, the server now also
+  works with `puppeteer-core` and your installed Chrome, or another browser
+  set in `PINEPAPER_CHROME_PATH`.
+
+### Fixed
+
+- `pinepaper_pattern` no longer warns "NO CHANGE" after a `create` or
+  `modify` that has not moved anything yet, such as a wave at time 0 or one
+  whose window starts later.
+- A failed batch step addressed by `$N` names the item that `$N` resolved to,
+  not `"$N"`.
+- Batch `animate` and `relation` operations quote their `animationType` and
+  `relationType` correctly in the generated code.
+- The scene lint that batches and custom code run on every call no longer
+  checks every pair of items, which made each call on a large scene slower.
+  It reports the same warnings.
+- A video export that goes over the bitrate you asked for says so: the studio
+  reports `bitrate_exceeded` with the bitrate the file actually has, and how
+  to land under the target.
+- The agent toolkit's export description now says what each format returns:
+  only MP4 and WebM carry a frame digest, and a small SVG comes back inline
+  rather than as a file.
+- `on_event_fire_if` is documented: its predicate is an ExpressionIR object
+  (comparisons, and/or/not, reads of an item's data, active or visible
+  state), and it fires the event in `params.event`, not its target. A
+  predicate written as a string, or a relation with no event to fire, is
+  refused with the shape that works, wherever the relation comes from:
+  `pinepaper_add_relation`, a batch `relation` step, `pinepaper_create_scene`,
+  `pinepaper_instantiate_ontology`, or an `on_event_add_relation` that adds
+  one later. Before, the relation silently never fired.
+- An emitter given a `[min, max]` range for a key that takes one number
+  (such as `gravity`, `opacity` or `count`) now gets a warning: the key draws
+  one value for every particle, not a spread. Before, there was no warning.
+- `pinepaper_import_image` takes a `name`, so a batch `patch` can address an
+  imported image by name.
+- Custom code that returns nothing is reported as returning nothing, not as
+  `{}`, when the scene lint has warnings.
+- An export whose file was saved but could not be hashed or read back says
+  so. It used to report the save as failed.
+- A batch step other than `create` that carries a key it does not read
+  now gets an `IGNORED ARGUMENTS` note naming the step and the key. Before,
+  the key had no effect and nothing said so. The common mix-ups get a hint:
+  `params` on a `relation` step (it takes `relationOptions`), and `x`/`y` on
+  a `modify` step (changes go inside `properties`).
+- Clearing the canvas starts item ids again at `item_1`
+  (`pinepaper_clear_canvas`, `pinepaper_agent_start_job` and
+  `pinepaper_agent_reset`), so a batch sent after a clear gets the same ids
+  every time. Before, the numbering carried on from the cleared items, and
+  only a server restart reset it.
+- A `group` step in a batch now takes the next `$N`, as a `create` does, so
+  a later step can animate the group: in `[create, create, group, …]` the
+  group is `$2`. This renumbers batches that create items after a group:
+  in `[create, create, group, create]` the last item was `$2` and is now
+  `$3`. Before, a `$N` meant for the group failed with "it has created 2 so
+  far".
+- An event reaction that shows or hides an item (`on_event_set_visibility`,
+  and its `on_enter_` and `on_exit_` forms) refuses `value` and asks for
+  `visible`, the field it reads. Before, `{"value": false}` showed the item
+  instead of hiding it.
+- A PNG, JPG, WebP, SVG or PDF of a scene that is playing is its first frame
+  (time 0), the frame a video starts on, and the result says so. Before, it
+  was whatever frame playback had reached, so items moved by relations (an
+  orbit) were in a different place on every export. `time` still picks
+  another moment.
+- A closed shape given a `strokeColor` and no fill is drawn as an outline.
+  Before, it got the default fill, or the active brand's colour.
+- A batch no longer flags `ttl` or `bornAt` on a `line` as a likely typo.
+- A line created with `from` and `to` reports where it actually is, and says
+  that `position` does not move it: `from` and `to` are canvas coordinates.
+  Before, the result reported the position asked for while the line was
+  drawn at the top left.
+- `pinepaper_transform` `nudge` moves an item the way `pinepaper_modify_item`
+  does, so an item with a loop animation keeps its new place, and the
+  result no longer reports the move as no change.
+- `create_item` documents `properties.id`: an id of your own, so replays
+  address the same items. An id with a quote, backslash or line break is
+  refused, since later calls could not address it.
+- An item id containing a quote no longer breaks `pinepaper_modify_item`,
+  `pinepaper_delete_item`, `pinepaper_animate`,
+  `pinepaper_keyframe_animate`, `pinepaper_apply_effect` or
+  `pinepaper_query_relations`. Before, the call failed with a syntax error.
+- The `lane` toolkit adds `pinepaper_event`, for things that happen at a
+  set time or on a click (a panel that hides at 3 s), and
+  `pinepaper_clear_canvas`, to start over. Its batch description shows how
+  to attach an event's reactions and triggers.
+
+## What's new in 1.6.24
+
+### Added
+
+- `pinepaper_pattern`: one stored declaration moves many items, with no
+  keyframes on each. `phase_wave` sends a wave through the members, `stagger`
+  offsets them in turn. Members are chosen by id, by name pattern or by tag.
+  `create`, `modify`, `remove`, `list` and `get` manage patterns afterwards.
+- A five-tool toolkit for agents, `PINEPAPER_TOOLKIT=lane`:
+  `pinepaper_agent_batch_execute`, `pinepaper_keyframe_animate`,
+  `pinepaper_pattern`, `pinepaper_agent_export` and `pinepaper_lint_scene`,
+  with descriptions written to be read on their own.
+- Batch operations `ring`, `grid`, `orbit`, `stagger` and `patch`.
+  - `ring` and `grid` lay out many items in one operation. Each item is made
+    the same way `create` makes it and fills the next `$N` slot.
+  - `orbit` binds an orbiting item to a centre, making the orbiting item if
+    you pass `itemType`.
+  - `stagger` plays the same keyframes on several items, one after another.
+  - `patch` changes an item by its name.
+- Batch operation `timeline`: GSAP-style tweens written as JSON (`to`, `from`,
+  `at`, `stagger`, `ease`, `repeat`, `yoyo`, labels), turned into ordinary
+  keyframe tracks, so the result exports, saves and edits like hand-written
+  keyframes. A tween that cannot be built is refused before anything runs,
+  with the path of the bad value. The result says what each tween became.
+- `pinepaper_agent_export` returns the saved file's `sha256` and size. When
+  the studio reports per-frame hashes, it also returns a `frameDigest`, so two
+  renders can be compared in one field. When `ffprobe` is installed, the saved
+  video is checked against what the studio encoded, and any field that
+  disagrees is named (`PINEPAPER_FFPROBE=off` turns this off).
+- `pinepaper_execute_custom_code` and `pinepaper_agent_batch_execute` return
+  the scene lint's warnings (`lintWarnings`), such as a title that runs out of
+  the frame. Every failed step is listed in `failures` as
+  `{ step, itemId, reason }`.
+
+### Fixed
+
+- An atomic batch that fails removes the items it created, so it can be fixed
+  and sent again without making them twice. Changes it made to items that
+  already existed are not undone, and the result says what was removed.
+- An argument a tool ignores is now also named when it is nested, at its full
+  path (for example `keyframes[1].ease`). Keys that a batch operation reads
+  directly (`content`, `fontSize`, `x`, `y`, `timeOffset` and the like) are
+  not reported.
+- No export reports success without a file. Every saved file is read back
+  from disk and must exist and not be empty. A failure names its step, the
+  path and the reason.
+- A batch `modify` or `patch` addressed by a name that several items hold is
+  refused, and the result lists their ids. It used to change whichever of them
+  was made first.
+- Item ids and colours in batch operations are always quoted correctly in the
+  generated code.
+- `pinepaper_choreograph` with `sound: true` now plays a launch sound at the
+  start of a `bounce`, as it already did for a `hop`.
+- `pinepaper_emitter` accepts `velocities` and `offsets` written as
+  `[{ x, y }, …]` as well as `[[x, y], …]`. Before, the object form was
+  dropped and the particles had no velocity. The reply now warns when a
+  burst's `count` differs from the number of `velocities`.
+- A `letterSpacing` set on a text item in `pinepaper_create_item` or
+  `pinepaper_modify_item` is applied. It was reported as ignored at creation
+  and only took effect through keyframes.
+
+### Security
+
+- `pinepaper_import_scene` reads only from the working directory, the export
+  folder and `PINEPAPER_ASSET_DIRS`, like image and media imports. A path
+  outside them gets the same refusal whether or not the file exists, so the
+  error no longer shows what is on disk. Restoring a scene that
+  `pinepaper_export_scene` saved still works: it saves to the export folder.
+- The `pinepaper://docs/readme` resource accepts only a language code after
+  the slash (such as `/ja` or `/pt-BR`). Anything else is refused.
+- Dependency updates clear published advisories in `body-parser`, `fast-uri`,
+  `ip-address`, `hono` and `zod` (now zod 4).
+- [SECURITY.md](SECURITY.md) explains how to report a vulnerability privately.
+
 ## What's new in 1.6.23
 
 ### Fixed
@@ -1635,32 +1829,26 @@ Fourteen new tools (121 → 135) and new actions across the surface — the rele
 
 ## Toolkits & Token Budget
 
-177 tools is a lot of context. The server ships a **toolkit** system that serves only the tools a given client needs, plus a **verbosity** system that controls how long each tool description is.
+178 tools is a lot of context. The server ships a **toolkit** system that serves only the tools a given client needs, plus a **verbosity** system that controls how long each tool description is.
 
 **Toolkit profiles** (`PINEPAPER_TOOLKIT`):
 
 | Profile | Contents |
 |---------|----------|
+| `core` | **The default.** The craft tools the server's instructions point to, the agent workflow, canvas and query tools, plus every tool those name, so no listed tool points at a missing one. About half the tokens of `agent`. Anything else loads on demand (below) |
 | `full` | Every tool, no filtering |
-| `agent` | Every tool except the diagnostics (`pinepaper_get_performance_metrics`, `pinepaper_diagnostic_report`) and `pinepaper_register_item`. The default for a client not listed below |
+| `agent` | Every tool except the diagnostics (`pinepaper_get_performance_metrics`, `pinepaper_diagnostic_report`) and `pinepaper_register_item` |
 | `diagram` | Canvas + diagram + query/export |
 | `map` | Canvas + map + query/export |
 | `font` | Canvas + font + letter collage + export |
 | `minimal` | Agent, browser, canvas, and guide only |
+| `lane` | **The agent lane**: exactly seven tools — `pinepaper_agent_batch_execute`, `pinepaper_keyframe_animate`, `pinepaper_pattern`, `pinepaper_agent_export`, `pinepaper_lint_scene`, `pinepaper_event`, `pinepaper_clear_canvas` — shown with descriptions that carry the rules an agent otherwise learns by failing (the keyframe shape, an item's words and look inside `properties`, a position being the item's centre, the export's 5 s default). The whole contract, instructions included, is ~4.3k tokens. For scripted builds of shapes, text, keyframes and relations; use `core` for characters, styled scenes, maps, diagrams and sound |
 
 **Verbosity tiers** (`PINEPAPER_VERBOSITY`): `verbose`, `compact` (default), `minimal`.
 
-**Client auto-detection.** When neither env var is set explicitly, the server picks a profile from the MCP `initialize` handshake:
-
-| Client | Toolkit | Verbosity |
-|--------|---------|-----------|
-| `claude-ai` | `minimal` | `compact` |
-| `claude-desktop` | `full` | `compact` |
-| `claude-code` | `agent` | `compact` |
-| `cursor` | `full` | `compact` |
-| `windsurf` | `full` | `compact` |
+**Load on demand.** Every client starts on `core`. When a task needs more, the model calls `pinepaper_set_toolkit` with `load`: a group (`{"load": ["map"]}`, `["diagram"]`, `["font"]`, `["physics"]`, …) or a tool's own name. The tools are added for the session, along with any tools they mention, and the client is told the list changed. The server logs each client's name at start-up.
 
-Explicit env vars always win. You can also hand-pick tools with `PINEPAPER_TOOLS` (comma-separated names), or switch profiles at runtime with the `pinepaper_set_toolkit` tool. Start with `pinepaper_tool_guide` to have the server explain its own surface.
+`PINEPAPER_TOOLKIT` always wins. You can also hand-pick tools with `PINEPAPER_TOOLS` (comma-separated names), or switch profiles at runtime with the `pinepaper_set_toolkit` tool. Start with `pinepaper_tool_guide` to have the server explain its own surface.
 
 ## Features
 
@@ -1838,7 +2026,7 @@ Generate instruction/code pairs for LLM fine-tuning:
 
 ## Tools Reference
 
-All 177 tools, grouped by the tag used for toolkit filtering.
+All 178 tools, grouped by the tag used for toolkit filtering.
 
 ### Canvas (`canvas`)
 | Tool | Description |
@@ -1903,6 +2091,7 @@ All 177 tools, grouped by the tag used for toolkit filtering.
 | `pinepaper_choreograph` | Acting for any item: hop, bounce, roll, fly, peek with squash and stretch |
 | `pinepaper_play_timeline` | Control playback, rate, progress, scroll-driven scrubbing |
 | `pinepaper_stagger` | Shape a delay across many items |
+| `pinepaper_pattern` | Move many items with one stored declaration (wave, stagger) |
 | `pinepaper_flip` | Animate a layout change without describing the motion |
 | `pinepaper_get_animatable_properties` | List animatable properties |
 | `pinepaper_get_available_easings` | List easing functions |
@@ -2244,6 +2433,10 @@ bun install
 bun run build
 ```
 
+### Claude Desktop extension (.mcpb)
+
+`bun run build:mcpb` builds `mcpb/pinepaper-mcp-server-<version>.mcpb`, a one-file Claude Desktop extension: open it and Desktop installs the server, with no config file to edit. The extension drives your installed Google Chrome (choose another Chromium-based browser in its settings), and its settings also set the export folder and the tool list.
+
 ### Test with MCP Client (Local)
 
 1. Build the server:
@@ -2359,9 +2552,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 | `PINEPAPER_API_KEY` | Service-account key (`pp_sa_…`) for the cloud-backed tools (`pinepaper_generate`) | — |
 | `PINEPAPER_CLOUD_URL` | The PinePaper cloud those tools call | `https://cloud.pinepaper.studio` |
 | `PINEPAPER_EXECUTION_MODE` | `puppeteer` (execute in a real browser) or `code` (return generated code only) | `puppeteer` |
-| `PINEPAPER_EXPORT_DIR` | Directory for exported files | `<tmpdir>/pinepaper-exports` |
+| `PINEPAPER_CHROME_PATH` | A Chromium-based browser for the canvas tools when full `puppeteer` is not installed (the Desktop extension uses your installed Chrome by default) | installed Google Chrome |
+| `PINEPAPER_EXPORT_DIR` | Directory for exported files | `~/Downloads/PinePaper` (`<tmpdir>/pinepaper-exports` where there is no Downloads folder) |
 | `PINEPAPER_LOCALE` | Language locale code | `en` |
-| `PINEPAPER_TOOLKIT` | Toolkit profile (`full`/`agent`/`diagram`/`map`/`font`/`minimal`) | auto-detected |
+| `PINEPAPER_TOOLKIT` | Toolkit profile (`core`/`full`/`agent`/`diagram`/`map`/`font`/`minimal`/`lane`) | `core` |
 | `PINEPAPER_TOOLS` | Explicit comma-separated tool allowlist | unset |
 | `PINEPAPER_VERBOSITY` | Description verbosity (`verbose`/`compact`/`minimal`) | `compact` |
 | `PINEPAPER_TOOL_VERBOSITY` | Deprecated alias for `PINEPAPER_VERBOSITY` | unset |
@@ -2375,6 +2569,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 | `PINEPAPER_GOVERNOR` | `off` runs code by raw eval — no governor report, no error codes, no seeded determinism | on |
 | `PINEPAPER_ASSET_DIRS` | Extra folders local image and media imports may read from, separated by `:` (`;` on Windows). The working directory and the export folder are always allowed | unset |
 | `PINEPAPER_ALLOW_PRIVATE_NETWORK` | `1` lets URL imports reach loopback, private and LAN addresses, for a local dev server. Cloud metadata addresses stay refused | unset |
+| `PINEPAPER_FFPROBE` | `off` skips the ffprobe check of a saved video export. Without `ffprobe` on `PATH` the check is skipped and the result says so | on |
 
 Behind a proxy, or against a Studio with analytics or polling connections open,
 `networkidle2` may never settle: set `PINEPAPER_WAIT_UNTIL` only if you need the

package/README.pt-BR.md

@@ -19,7 +19,7 @@
 
 O servidor MCP do PinePaper permite que assistentes de IA criem e animem gráficos no [PinePaper Studio](https://pinepaper.studio) via Model Context Protocol. Funciona com qualquer IA que suporte chamadas de ferramenta MCP (Claude, GPT, Gemini, modelos locais etc.).
 
-São **177 ferramentas**: desenho, animação, diagramas, mapas, tipografia, física, edição de imagens, visualização de dados e exportação:
+São **178 ferramentas**: desenho, animação, diagramas, mapas, tipografia, física, edição de imagens, visualização de dados e exportação:
 
 - Criar texto, formas, geometria e gráficos complexos
 - Animar com **relações** declarativas em vez de keyframes

package/README.zh-CN.md

@@ -19,7 +19,7 @@
 
 PinePaper MCP 服务器让 AI 助手通过 MCP 协议在 [PinePaper Studio](https://pinepaper.studio) 中创建和驱动图形动画。兼容任何支持 MCP 工具调用的 AI（Claude、GPT、Gemini、本地模型等）。
 
-服务器提供 **177 个工具**，覆盖绘图、动画、图表、地图、排版、物理、图像编辑、数据可视化与导出：
+服务器提供 **178 个工具**，覆盖绘图、动画、图表、地图、排版、物理、图像编辑、数据可视化与导出：
 
 - 创建文本、形状、几何图形与复杂图稿
 - 用行为驱动的**关系（relations）**做动画，而不是逐帧关键帧

package/SECURITY.md

@@ -0,0 +1,46 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please report security issues privately, through GitHub's private vulnerability reporting:
+
+**[Report a vulnerability](https://github.com/pinepaper/mcp-server/security/advisories/new)**
+
+Please don't open a public issue, pull request or discussion for a security problem. A private report reaches the maintainers without exposing users before a fix is out.
+
+A useful report includes:
+
+- the version of `@pinepaper.studio/mcp-server` (`npx @pinepaper.studio/mcp-server --version`, or the version in your MCP client's config);
+- the tool call or input that triggers it, and what happens as a result;
+- the execution mode (`puppeteer` or `code`) and any `PINEPAPER_*` environment variables you set;
+- what an attacker gains, and what they need to control to get it (for example, a URL in a tool call, a file on disk, or a web page the server visits).
+
+You don't need a working exploit. If you aren't sure whether something counts, report it anyway.
+
+## What happens next
+
+The report becomes a draft security advisory that only you and the maintainers can see. We follow up in that thread: to confirm the issue, ask questions, and tell you which release fixes it. Once a fixed version is published to npm, we publish the advisory with the affected and fixed versions, and request a CVE for it. With your agreement, we credit you by name.
+
+## Supported versions
+
+Fixes ship in a new patch release of the latest version. Older versions do not get backported fixes, so upgrade to the latest release to pick one up:
+
+```
+npm install @pinepaper.studio/mcp-server@latest
+```
+
+## Scope
+
+This package is an MCP server that runs on your machine and drives PinePaper Studio in a browser page.
+
+**Executing JavaScript in the studio page is the design, not a vulnerability.** Every tool compiles to a snippet that runs against your canvas, and `pinepaper_execute_custom_code` runs a snippet the agent writes. The README's [security section](README.md#security-yes-it-executes-code) explains what runs where, and how `code` mode avoids executing anything.
+
+Examples of what is in scope:
+
+- the server process fetching what it should not, such as private or loopback addresses or cloud metadata endpoints (server-side request forgery);
+- reading or writing files outside the folders the server is allowed to use (path traversal);
+- tool input that escapes the generated snippet and runs in the server process instead of the page;
+- exposing a credential such as `PINEPAPER_API_KEY`, or sending it somewhere it should not go;
+- a crash or hang of the server caused by a single crafted tool call.
+
+The server's own defences, `PINEPAPER_ALLOW_PRIVATE_NETWORK` and `PINEPAPER_ASSET_DIRS`, are documented in the README. Bypassing either one is in scope.