PinePaper MCP Server

Create animated vector graphics with AI using the Model Context Protocol

English · 简体中文 · 日本語 · 한국어 · Español · Português (BR) · Français · Deutsch · हिन्दी

Everything above and below moves — these are animated SVGs exported straight from PinePaper tool calls, no video files, no GIFs. Open this README on GitHub and watch.

Overview

PinePaper MCP Server enables AI assistants to create and animate graphics in 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 135 tools across drawing, animation, diagrams, maps, typography, physics, image editing, data visualization, and export. Using natural language, you can:

• Create text, shapes, geometry, and complex graphics

• Animate items with behavior-driven relations rather than keyframes

• Build long scenes as event-driven chains that stay scrub- and replay-stable

• Generate procedural backgrounds and parametric/equation-driven paths

• Author diagrams, maps, charts, and letter collages

• Edit images: crop, chroma-key background removal, GPU filters, lasso cutouts, object detection

• Export animated SVG, video frames, embeddable widgets, and LLM training data

Related MCP server: ASCII & SVG Art Studio

Made with tool calls

Every graphic below is an animated SVG produced through this server's tool surface — the arguments shown with each result are what an AI agent passes to the named tool. They aren't shell commands; Run these yourself below shows the three ways to execute them.

// The scene IS a graph: two items, two declared edges —
// the canvas view and the graph view are the same data.
{ "sourceId": "$dot",
  "relationType": "moves_along_path",
  "relationOptions": { "path": "$p1",   // an ellipse path
    "duration": 6, "easing": "easeInOut", "loop": true } }
{ "itemId": "$square", "animationType": "rotate",
  "options": { "speed": 0.18 } }

// Five rails, five named easings, one loop — each dot is
// a moves_along_path down its rail with a different easing
for (const easing of ['linear', 'easeIn', 'easeOut',
                      'easeInOut', 'pingpong']) {
  add_relation($dot, 'moves_along_path', {
    equation: { kind: 'parametric', xExpr: '0', yExpr: 't',
                min: -1, max: 1, scale: 58 },
    duration: 2.6, easing, loop: true });
}

// The engine solves the curve; the exporter bakes the
// motion to native SVG keyframes. pinepaper_add_relation:
{ "sourceId": "$dot", "relationType": "moves_along_path",
  "relationOptions": { "equation": {
    "kind": "parametric",
    "xExpr": "cos(2*t)*cos(t)",
    "yExpr": "cos(2*t)*sin(t)",
    "scale": 108, "cx": 280, "cy": 118 },
    "duration": 8, "loop": true } }

// Status chip: pale panel, slate bar, green dot blinking
{ "itemType": "rectangle", "properties": { "width": 264,
  "height": 72, "fillColor": "#e8eff5" } }
{ "itemType": "circle", "properties": { "radius": 9,
  "fillColor": "#2e9b4e" } }
{ "itemId": "$1", "animationType": "fade",
  "options": { "speed": 1.0 } }   // only the dot blinks

All five showcase files (including the banner) live in assets/ — tiny (4–11 KB), dependency-free, loop forever, and render anywhere SVG renders: GitHub READMEs, docs sites, dashboards, emails that allow SVG. They follow one editorial design system (serif mastheads, hairline rules, slate ink on paper white, framed canvas stages, typed-edge graph diagrams) supplied to the agent as context — share a design guideline with your agent and the tool calls come out on-system.

Try it interactive

GitHub can't run scripts inside a README, so the interactive demos live in the editor — one click, no install. Each is a shipped template where the relation graph does all the state handling (tabs, accordions, menus — no event-handler code):

• Tabs from relations — on_click_fire + exclusive_group + on_enter_set_visibility

• Accordion from relations — disclosure pairs via on_event_toggle

• Solar system, 4-in-1 tabs — the state machine driving four scenes

• Menubar from relations — WAI-ARIA menubar semantics from the same graph

The same graph drives visuals, keyboard access, and screen-reader roles (WCAG 2.1 AA) — see pinepaper://docs/relations from your MCP client.

Run these yourself

The snippets above are MCP tool-call arguments — they execute when an AI agent invokes the tool. Three ways to make that happen:

1 · Ask your agent (any MCP client). With this server configured, paste a prompt like:

Create a blue circle and make it ride a diamond-shaped path with easeInOut, looping. Add an orange rotating square beside it. Then export the scene as animated SVG.

Your agent picks the tools (pinepaper_create_item, pinepaper_add_relation, pinepaper_export_svg) and runs them.

2 · Hand your agent a complete batch. This is a full, valid pinepaper_agent_batch_execute argument — an agent (or an MCP inspector) can execute it verbatim; $0/$1 reference the created items in order:

{
  "operations": [
    { "type": "create", "itemType": "circle",
      "properties": { "x": 300, "y": 260, "radius": 10, "fillColor": "#2e5e8f" } },
    { "type": "relation", "relationType": "moves_along_path", "sourceId": "$0",
      "relationOptions": { "path": [ { "x": 180, "y": 260 }, { "x": 300, "y": 180 },
                                     { "x": 420, "y": 260 }, { "x": 300, "y": 340 } ],
                           "duration": 6, "easing": "easeInOut", "loop": true } },
    { "type": "create", "itemType": "rectangle",
      "properties": { "x": 520, "y": 260, "width": 60, "height": 60, "fillColor": "#f0a030" } },
    { "type": "animate", "itemId": "$1", "animationType": "rotate" }
  ]
}

3 · No MCP, no agent — just a browser. Open pinepaper.studio/editor, open the browser console, and paste (verified working as-is):

const app = window.PinePaper;
const dot = app.create('circle', { x: 300, y: 260, radius: 10, fillColor: '#2e5e8f' });
app.addRelation(dot.data.id, null, 'moves_along_path', {
  path: [ {x:180,y:260}, {x:300,y:180}, {x:420,y:260}, {x:300,y:340} ],
  duration: 6, easing: 'easeInOut', loop: true,
});
const sq = app.create('rectangle', { x: 520, y: 260, width: 60, height: 60, fillColor: '#f0a030' });
app.animate(sq, { animationType: 'rotate' });

The same code an agent generates is the code you can paste — the canvas is yours either way, undo included.

What's new in 1.6.6

Dependency security, no new tools and no API changes:

• 10 vulnerable transitive pins cleared (21 advisories: 1 critical, 13 high, 6 moderate, 1 low) across basic-ftp, fast-uri, js-yaml, path-to-regexp, ws, ip-address, qs, flatted, body-parser and ajv. Each is pinned to a floor in overrides so neither resolver can drift back.

• Root cause was a stale committed bun.lock. It pinned the vulnerable versions while package-lock.json had already re-resolved most of them — and bun test/bun run build install from bun.lock, so that was the tree in use. Both lockfiles now agree.

• npm audit reported zero against all of this; its registry advisory feed lags GitHub's. Verified instead with an OSV.dev sweep of both lockfiles, red-tested against the previous commit.

• manifest.json version parity is now tested. It had silently sat at 1.6.4 through the 1.6.5 release.

Exposure note: puppeteer has been an optional peer since 1.6.5, so its chain (basic-ftp, ws, ip-address, js-yaml) never reached installs of this package. The @modelcontextprotocol/sdk chain (fast-uri, path-to-regexp, qs, body-parser, ajv) is the production surface.

What's new in 1.6.5

Security hardening, no new tools:

• Generated code is breakout-proof. Three emitters wrapped user text in hand-escaped quotes without escaping backslashes (CodeQL js/incomplete-sanitization, High ×3) — an input like x\'; evil() could land outside the string in emitted code. All string literals now emit via JSON.stringify; regression tests pin the class.

• Puppeteer is now an optional peer. The 4 browser tools lazy-load it and explain the one-line install (npm i puppeteer) when absent. The default dependency tree drops the headless-browser download, its install script, and its large transitive tree (tar-fs/bare-* — the usual "obfuscated code" scanner alerts). Default deps: @modelcontextprotocol/sdk + zod.

• Slimmer tarball. Compiled test fixtures no longer ship in dist/.

What's new in 1.6.4

Fourteen new tools (121 → 135) and new actions across the surface — the release that catches the agent surface up with the engine.

3D worlds. pinepaper_world3d — a real depth-buffered 3D world under the canvas: terrain presets (forest, snowMountain, field, jungle), sun shadows, an addressable actor stage and a directed camera (follow/fixed/orbit). add_actor with live: true puts a rigged canvas character INTO the world, performing — walk cycle, expressions and all. describe returns the engine's own parameter schema, so the docs cannot drift.

Motion capture & characters. pinepaper_rigging gains import_bvh (CMU/Mixamo mocap → a new rig, stick figure included), retarget_bvh (drive an existing rig by bone name — the result reports matched/unmatched bones) and import_spine (Spine JSON). New pinepaper_import_layered_character lands a layer-decomposed illustration as role-bound parts — blink and smile work with zero wiring (check rolesWired in the result).

Video editing. pinepaper_media gains set_time_remap (speed ramps, freeze frames, reverse), speed_ramp, match_cut (subject-aligned cuts via on-device detection), apply_track_matte (a headline filled with footage; live: true tracks an animating matte) and stop_live_matte.

Design systems. pinepaper_brand_kit (plan with WCAG contrast audit, then apply), pinepaper_component (master/instance with overrides that survive master updates), pinepaper_artboard (retarget a finished design to a new format), pinepaper_comment, pinepaper_provenance, pinepaper_scene_diff — plus pinepaper_transform fit (contain/cover).

Typography & imagery. pinepaper_text_style (stacked-layer display titles + variable-font weight/width/slant as animatable properties), pinepaper_shatter_image (raster → tile grid, inert until animated), pinepaper_compose (the collage patterns), and pinepaper_image_filter now documents the full GPU registry — grain, scanlines, duotone, bloom, halation, lightShafts, paletteMap, and the second-input set (displace, refract, trackMatte, datamosh) — plus analyze_palette/recolor_palette (read an image's palette, recolor another to match, shading preserved).

Games & data. pinepaper_game (deterministic A* pathfinding that feeds moves_along_path, tilemaps with merged collision rects), pinepaper_audio_beats (beat detection → animate_to_beat), pinepaper_template_params, and Figma import via pinepaper_import_asset.

Agent economics. pinepaper_agent_export gains estimateOnly — preflight an export's size without rendering it; GIF exports are capped at 15s with a clear message instead of an OOM.

• Image editing tools: pinepaper_crop_image (one-shot crop, keeps the item's id and relations) and pinepaper_chroma_key (green-screen background removal with auto-estimated thresholds)

• pinepaper_media gains set_clip — re-trim an already-uploaded video/audio clip

• Shader auras in pinepaper_apply_effect: heatmap, liquid_metal, gem_smoke (WebGL2, silhouette-clipped)

• pinepaper_image_filter fixed and expanded — routed to the real GPU filter engine

• README as an MCP resource — clients can read pinepaper://docs/readme (and per-language variants) without leaving the protocol

• This README, in 9 languages, with live animated examples

Toolkits & Token Budget

135 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):

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:

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.

Features

🤖 Agent Flow Mode (enforced by default)

• Auto-Connection: Browser connects automatically on first tool call (headless mode)

• Auto-Session: Agent sessions start automatically — just start creating

• Batch Operations: Execute multiple operations in one call (~10x faster)

• Smart Exports: Auto-detect optimal format for Instagram, TikTok, YouTube, etc.

"Create a red pulsing text that says HELLO"  # Browser auto-connects
"Create 5 items in batch, then export for TikTok"
"Analyze the scene and recommend export format"

No manual setup required — just start making tool calls.

🔄 Relations (Behavior-Driven Animation)

The key feature — describe HOW items should behave, and the engine solves the motion every frame. 39 relation types are available via pinepaper_add_relation. Relations are compositional: one item can carry several at once.

Spatial & motion

Structural layout

Static composition expressed as edges instead of hardcoded coordinates. Placement is derived from the target's bounds and re-derived each frame, so moving or resizing the target brings the dependent along — and the layout stays editable as graph data.

Structure & construction

Animation & camera

Deterministic binding (Expression IR)

With signal: true these compile to a pure f(t) Expression IR, making them scrub-, loop-, and replay-stable. Expressions using random() or unknown symbols fall back to per-frame evaluation.

Event-driven scene chains

Create channels with pinepaper_event (create → eventId, pulse → fire it). Chain beats with on_event_fire_after on the canvas timeline to author a long scene as a graph of timed beats instead of a keyframe track.

Extras: relations can target the live pointer via the reserved targetId 'cursor', and any relation can carry params.window = { start, end?, repeat? } to gate when it is active (repeat: once | loop | pingpong).

🎨 Item Creation & Geometry

"Create a blue circle at position 200, 300 with radius 50"
"Create text saying 'Welcome' with font size 72"
"Draw the perpendicular bisector of AB"

Beyond basic shapes, pinepaper_geometry provides construction primitives, pinepaper_group handles group/ungroup/break-apart, and pinepaper_arrange controls z-order (bring forward/back/front/back).

🎬 Simple Animations

For quick looping effects: pulse, rotate, bounce, fade, wobble, slide, typewriter. For timed work use pinepaper_keyframe_animate; query the valid targets with pinepaper_get_animatable_properties and pinepaper_get_available_easings.

🖼️ Background Generators

31 procedural generators via pinepaper_execute_generator (list them with pinepaper_list_generators):

drawBlobs, drawBokeh, drawCircuit, drawFluidFlow, drawFormulaArt, drawFunctionPlot, drawGeometricAbstract, drawGlobeWireframe, drawGradientMesh, drawGrid, drawHalftone, drawLowPoly, drawNoiseTexture, drawOrganicFlow, drawParametricCollection, drawParametricCurve, drawPattern, drawPeaks, drawRibbons, drawScatter, drawShaderArt, drawSimulation, drawSpectrumAnalyzer, drawStackedCircles, drawStackedWaves, drawSunburst, drawSunsetScene, drawTruchet, drawWaves, drawWindField, drawYeganehMountains

📐 Diagram Tools

Create flowcharts, UML diagrams, network diagrams, and more:

"Create a flowchart for user login process"
"Make a UML class diagram for the User class"
"Design a network topology with 3 servers connected to a cloud"

• Shape types — Flowchart: process, decision, terminal, data, document, database, preparation · UML: uml-class, uml-usecase, uml-actor · Network: cloud, server · Basic: rectangle, circle, triangle, star

• Connectors — smart routing (orthogonal, direct, curved), arrow styles (classic, stealth, diamond, circle, none), animated bolt effect, labels

• Auto-layout — hierarchical, force-directed, tree, radial, grid

• Mermaid — import existing diagrams with pinepaper_import_mermaid

🗺️ Maps

Choropleths, region styling, and data-driven map animation via pinepaper_map, pinepaper_map_regions, pinepaper_map_animation, and pinepaper_map_data.

🔤 Typography

pinepaper_font covers font loading and text-to-path work; pinepaper_create_letter_collage and pinepaper_animate_letter_collage build and animate letterform collages.

🔍 Asset Search & Import

Search and import free SVG assets from multiple repositories:

• SVGRepo: 500,000+ icons with various licenses

• OpenClipart: 150,000+ public domain clipart (CC0)

• Iconify: 200,000+ icons from multiple icon sets

• Font Awesome: 2,000+ free icons (CC BY 4.0)

🖼️ Image Processing & Object Detection

Import images, then use pinepaper_image_filter, pinepaper_lasso, and pinepaper_cutout_style to process them. pinepaper_detect_objects runs object detection (with text queries) and can composite results as nodes; pinepaper_extract_object pulls a single object out.

🧠 Ontology & Validation

The server keeps a design graph of the canvas, so an AI can inspect and critique its own work: pinepaper_get_canvas_ontology, pinepaper_query_ontology, pinepaper_analyze_design, pinepaper_validate_design, pinepaper_validate, and pinepaper_validate_scene.

📊 Performance Metrics

Built-in performance tracking helps AI assistants optimize workflows:

• Automatic timing for all tool operations

• Phase breakdown (validation, code generation, execution, screenshots)

• Export formats: summary, detailed JSON, CSV

• Self-optimization through pinepaper_get_performance_metrics

📊 Training Data Export

Generate instruction/code pairs for LLM fine-tuning:

{
  "instruction": "moon orbits earth at radius 100",
  "code": "app.addRelation('item_1', 'item_2', 'orbits', {radius: 100})"
}

Tools Reference

All 135 tools, grouped by the tag used for toolkit filtering.

Canvas (canvas)

Item Creation (core)

Batch (batch)

Import (import)

Assets (assets)

Relations (relations)

Animation (animation)

Masks (masks)

Camera (camera)

Scene & Events (scene)

Generators, Effects & Filters

Editing (selection, transform, history)

Image Processing (image_processing)

Composition (precomp, deform, sprite, interaction)

Data Visualization (dataviz)

Diagram (diagram)

Map (map)

Media (media)

Rigging (rigging)

Typography (font, letter_collage)

Simulation & Utilities (magic, physics, measurement, template)

Query (query)

Ontology (ontology)

Export (export)

Agent Flow (agent)

Browser (browser)

Guide & Diagnostics

Escape Hatches (custom_code, p5, register)

Examples

Solar System

1. Create a yellow circle as the sun (radius 60) at center
2. Create a blue circle as Earth (radius 20)
3. Create a gray circle as the Moon (radius 8)
4. Add relation: Earth orbits Sun at radius 150, speed 0.3
5. Add relation: Moon orbits Earth at radius 40, speed 0.8

Animated Logo

1. Create text "BRAND" with font size 96
2. Apply pulse animation with speed 0.5
3. Apply sparkle effect with gold color
4. Add sunburst background

Following Labels

1. Create a circle as "player"
2. Create text "Player 1" as the label
3. Add relation: label follows player with offset [0, -50]

Event-Driven Scene Chain

1. Create events e0, e1, e2 (one per beat)
2. Chain them: on_event_fire_after e0 → e1 (delay 2000, timeline: canvas)
3. Chain: on_event_fire_after e1 → e2 (delay 2000, timeline: canvas)
4. Give beat 1 a reaction: on_event_add_relation e1 → planet (type: orbits)
5. Give beat 2 a reaction: on_event_set_color e2 → planet (color: #ff3300)
6. Pulse e0 to start — the whole chain is scrub- and replay-stable

Flowchart Diagram

1. Create a terminal shape with label "Start"
2. Create a process shape with label "Get Input"
3. Create a decision shape with label "Valid?"
4. Create a terminal shape with label "End"
5. Connect Start → Get Input
6. Connect Get Input → Valid?
7. Connect Valid? → End (label: "Yes")
8. Connect Valid? → Get Input (label: "No", routing: curved)
9. Apply hierarchical auto-layout

Network Diagram

1. Create a cloud shape with label "Internet"
2. Create 3 server shapes with labels "Web", "API", "DB"
3. Connect Internet → Web (label: "HTTPS")
4. Connect Web → API (label: "REST")
5. Connect API → DB (label: "SQL")
6. Apply force-directed auto-layout

Architecture

The server does not draw anything itself. It validates a tool call, generates JavaScript that calls PinePaper Studio's app.* API, and executes it in the browser — so the studio app stays the single source of truth for behavior.

┌─────────────────────────────────────────────────────────────┐
│                 AI Client (Claude, etc.)                    │
│                          │                                  │
│                    MCP Protocol                             │
│                          │                                  │
│              ┌───────────▼───────────┐                      │
│              │  PinePaper MCP Server │                      │
│              │  ┌─────────────────┐  │                      │
│              │  │  Tool Handlers  │  │  validate + route    │
│              │  └────────┬────────┘  │                      │
│              │           │           │                      │
│              │  ┌────────▼────────┐  │                      │
│              │  │ Code Generator  │  │  emit app.* calls    │
│              │  └────────┬────────┘  │                      │
│              └───────────┼───────────┘                      │
│                          │                                  │
│              ┌───────────▼───────────┐                      │
│              │   PinePaper Studio    │  execute in browser  │
│              │   (Browser/App)       │                      │
│              └───────────────────────┘                      │
└─────────────────────────────────────────────────────────────┘

Development

Setup

git clone https://github.com/pinepaper/mcp-server.git
cd mcp-server

# Using npm
npm install
npm run build

# Using bun (recommended)
bun install
bun run build

Test with MCP Client (Local)

1. Build the server:

   bun run build

2. Add to your MCP client config (example for Claude Desktop on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

   {
     "mcpServers": {
       "pinepaper": {
         "command": "node",
         "args": ["/full/path/to/mcp-server/dist/cli.js"]
       }
     }
   }

3. Restart your MCP client

4. Test with: "What PinePaper tools do you have available?"

Run Tests

Tests run on the Bun test runner.

bun test

# With coverage
bun test --coverage

# Typecheck
bun run typecheck

Manifest Check

manifest.json's tools[] must stay in sync with the served tool surface. This is enforced on publish (prepublishOnly), and you can run it directly:

bun run check:manifest   # verify
bun run fix:manifest     # rewrite manifest to match source

Development Watch Mode

bun run dev

Internationalization (i18n)

PinePaper MCP Server supports 51 languages, providing localized tool descriptions and messages for AI agents.

Supported Languages

Setting Language

Set the PINEPAPER_LOCALE environment variable:

{
  "mcpServers": {
    "pinepaper": {
      "command": "npx",
      "args": ["-y", "@pinepaper.studio/mcp-server"],
      "env": {
        "PINEPAPER_LOCALE": "ja"
      }
    }
  }
}

Or programmatically:

import { setLocale, t } from '@pinepaper.studio/mcp-server';

setLocale('fr');
const description = t('tools.pinepaper_create_item.description');

Adding New Languages

1. Create a new locale file in src/i18n/locales/ (e.g., xx.ts)

2. Copy the structure from en.ts

3. Translate all strings

4. Export from src/i18n/locales/index.ts

5. Add to the localeMap

See CONTRIBUTING.md for detailed guidelines.

Configuration

Environment Variables

Performance Metrics

Key Features:

• ⚡ Automatic timing for all tool operations

• 📊 Phase breakdown (validation, code generation, browser execution, screenshots)

• 🎯 Real-time query via pinepaper_get_performance_metrics tool

• 📈 Export formats: summary, JSON, CSV

• 💾 In-memory storage (resets on restart)

• 🚀 Minimal overhead (~1ms per operation)

Quick Example:

AI: "Let me check if batch operations are faster"
→ pinepaper_get_performance_metrics(format: 'summary')

Result:
  - pinepaper_create_item: avg 145ms
  - pinepaper_batch_create (10 items): avg 298ms (~30ms per item)

AI: "I'll use batch_create for the next 20 items"

Configuration:

# Disable metrics if not needed
export PINEPAPER_METRICS_ENABLED=false

# Increase retention for long sessions
export PINEPAPER_METRICS_RETENTION=5000

Learn More: See docs/PERFORMANCE_METRICS.md for complete documentation.

Documentation

Guides

• Workflow Guide — Decision trees, multi-step patterns, performance optimization, and troubleshooting

• Performance Metrics — In-memory metrics system for AI self-optimization

• Testing Guide — Test layout and conventions

• PinePaper Reference — Complete PinePaper Studio API reference

External Documentation

• PinePaper API Docs

• MCP Tools Specification

• MCP Server Installation

• User Guide

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Workflow

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Run tests: bun test

5. Submit a pull request

License

MIT License - see LICENSE for details.

Links

• PinePaper Studio

• Documentation

• GitHub Issues

• MCP Specification

Support

• 📧 Email: support@pinepaper.studio

• 🐛 Issues: GitHub Issues

Made with ❤️ by the PinePaper team