PinePaper MCP Server

Create animated graphics with AI using the Model Context Protocol

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.). Using natural language, you can:

• Create text, shapes, and complex graphics
• Animate items with behavior-driven relations
• Generate procedural backgrounds
• Export animated SVG and training data

Quick Start

1. Install

# Using npm
npm install -g @pinepaper.studio/mcp-server

# Using bun
bun add -g @pinepaper.studio/mcp-server

2. Configure Your AI Client

Add to your MCP client configuration. Examples:

Claude Desktop (claude_desktop_config.json):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Other MCP Clients: Refer to your AI client's MCP configuration documentation.

3. Start Using

Open your AI client and try:

"Create a red pulsing text that says HELLO"

"Create a sun and earth, make earth orbit the sun"

"Add a sunburst background with blue and purple colors"

Features

🤖 Agent Flow Mode (ENFORCED in v1.5.0)

Agent mode is now enforced by default for optimal performance:

• 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.

Tools:

• pinepaper_agent_start_job - Start a named job session (optional)
• pinepaper_agent_end_job - End job with summary and export recommendations
• pinepaper_agent_reset - Quick canvas reset
• pinepaper_agent_batch_execute - Execute multiple operations in batch
• pinepaper_agent_export - Smart export with platform auto-detection
• pinepaper_agent_analyze - Analyze content for export recommendations

🎯 Interactive Triggers (NEW in v1.5.0)

Add click, hover, and drag interactions to items:

"Make the button show a panel when clicked"
"Add a hover effect that plays an animation"
"Create a drag-and-drop quiz"

Event Types:

• click, hover_enter, hover_exit
• drag_start, drag_move, drag_end
• timeline, animation_end

Tools:

• pinepaper_add_trigger - Add event triggers with actions
• pinepaper_remove_trigger - Remove triggers from items
• pinepaper_query_triggers - List all triggers

📝 Quiz/LMS Integration (NEW in v1.5.0)

Create interactive quizzes with SCORM/xAPI support:

"Create a multiple choice quiz about planets"
"Add a drag-and-drop matching exercise"
"Track quiz score and progress"

Question Types:

• Multiple choice, Multiple select
• Drag-and-drop, Matching, Sequencing
• Hotspot, True/False, Fill-in-blank

Tools:

• pinepaper_create_quiz - Create interactive quizzes
• pinepaper_get_quiz_state - Get score, progress, answers
• pinepaper_reset_quiz - Reset quiz state

📐 Diagram Tools (NEW in v1.4.3)

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

Connector Features:

• Smart routing (orthogonal, direct, curved)
• Arrow styles (classic, stealth, diamond, circle, none)
• Animated bolt effect for data flow
• Labels on connectors

Auto-Layout Algorithms:

• Hierarchical (flowcharts, org charts)
• Force-directed (network diagrams)
• Tree (hierarchies)
• Radial (mind maps)
• Grid (component libraries)

Tools:

• pinepaper_create_diagram_shape - Create diagram shapes with ports
• pinepaper_connect - Connect items with smart connectors
• pinepaper_connect_ports - Connect specific ports
• pinepaper_add_ports - Add connection ports to items
• pinepaper_auto_layout - Automatically arrange items
• pinepaper_get_diagram_shapes - List available shapes
• pinepaper_update_connector - Update connector properties
• pinepaper_remove_connector - Remove a connector
• pinepaper_diagram_mode - Control diagram editing mode

🔍 Asset Search & Import (NEW in v1.3.0)

Search and import free SVG assets from multiple repositories:

"Search for a rocket icon"
"Import a cat illustration"
"Add a user avatar icon"

Supported 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)

Tools:

• pinepaper_search_assets - Search across all repositories
• pinepaper_import_asset - Import and place on canvas

📊 Performance Metrics (NEW in v1.3.0)

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

Example workflow:

1. Run your scene creation workflow
2. Call pinepaper_get_performance_metrics
3. Identify bottlenecks (e.g., individual creates vs batch)
4. Adjust approach and re-run

🐛 Enhanced Error Messages (NEW in v1.3.0)

Errors now include canvas context for easier debugging:

• Total item count and types
• Active relations
• Recent items created
• Canvas state at time of error

Makes troubleshooting much faster and more precise.

🎨 Item Creation

Create text, shapes, and custom graphics:

"Create a blue circle at position 200, 300 with radius 50"
"Add a gold star in the center"
"Create text saying 'Welcome' with font size 72"

🔄 Relations (Behavior-Driven Animation)

The key feature - describe HOW items should behave:

Relation	Description	Example
orbits	Circular motion	"Moon orbits Earth"
follows	Move toward target	"Label follows player"
attached_to	Fixed offset	"Hat attached to character"
maintains_distance	Stay at distance	"Satellite 200px from station"
points_at	Face target	"Arrow points at target"
mirrors	Mirror position	"Reflection mirrors original"
parallax	Depth movement	"Background parallax scroll"
bounds_to	Stay within area	"Player stays in arena"

🎬 Simple Animations

For quick looping effects:

• pulse - Scale up/down
• rotate - Continuous spin
• bounce - Vertical bounce
• fade - Opacity cycle
• wobble - Side-to-side
• slide - Horizontal slide
• typewriter - Character reveal

🖼️ Background Generators

Procedural patterns:

• drawSunburst - Radial rays
• drawSunsetScene - Animated sunset
• drawGrid - Lines, dots, squares
• drawWaves - Layered waves
• drawCircuit - Tech circuit board

📊 Training Data Export

Generate instruction/code pairs for LLM fine-tuning:

"Export training data from this scene"

Outputs pairs like:

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

Tools Reference

Item Tools

Tool	Description
pinepaper_create_item	Create text, shapes, graphics
pinepaper_modify_item	Change item properties
pinepaper_delete_item	Remove an item
pinepaper_batch_create	Create multiple items at once
pinepaper_batch_modify	Modify multiple items at once
pinepaper_create_grid	Create items in a grid layout
pinepaper_create_glossy_sphere	Create 3D glossy sphere effect
pinepaper_create_diagonal_stripes	Create diagonal stripe pattern

Relation Tools

Tool	Description
pinepaper_add_relation	Create behavioral relationship
pinepaper_remove_relation	Remove relationship
pinepaper_query_relations	Find existing relations

Animation Tools

Tool	Description
pinepaper_animate	Apply simple loop animation
pinepaper_keyframe_animate	Timed keyframe animation
pinepaper_play_timeline	Control playback

Generator Tools

Tool	Description
pinepaper_execute_generator	Run background generator
pinepaper_list_generators	List available generators

Effect Tools

Tool	Description
pinepaper_apply_effect	Apply sparkle, blast effects

Asset Tools (NEW)

Tool	Description
pinepaper_search_assets	Search for SVG assets across repositories
pinepaper_import_asset	Import asset from search results

Query Tools

Tool	Description
pinepaper_get_items	Get canvas items
pinepaper_get_relation_stats	Relation statistics
pinepaper_get_performance_metrics	Get execution timing metrics

Diagram Tools (NEW in v1.4.3)

Tool	Description
pinepaper_create_diagram_shape	Create flowchart/UML/network shapes with ports
pinepaper_connect	Connect items with smart connectors
pinepaper_connect_ports	Connect specific ports on items
pinepaper_add_ports	Add connection ports to items
pinepaper_auto_layout	Auto-arrange items using layout algorithms
pinepaper_get_diagram_shapes	List available diagram shapes
pinepaper_update_connector	Update connector style/label
pinepaper_remove_connector	Remove a connector
pinepaper_diagram_mode	Control diagram editing mode

Agent Flow Mode Tools (NEW in v1.5.0)

Tool	Description
pinepaper_agent_start_job	Start content creation job session
pinepaper_agent_end_job	End job with summary and recommendations
pinepaper_agent_reset	Quick canvas reset without page refresh
pinepaper_agent_batch_execute	Execute multiple operations in batch
pinepaper_agent_export	Smart export with platform auto-detection
pinepaper_agent_analyze	Analyze content for export recommendations

Interactive Trigger Tools (NEW in v1.5.0)

Tool	Description
pinepaper_add_trigger	Add event triggers (click, hover, drag)
pinepaper_remove_trigger	Remove triggers from items
pinepaper_query_triggers	List all triggers on canvas

Quiz/LMS Tools (NEW in v1.5.0)

Tool	Description
pinepaper_create_quiz	Create interactive quizzes
pinepaper_get_quiz_state	Get quiz score, progress, answers
pinepaper_reset_quiz	Reset quiz to initial state

Canvas Tools

Tool	Description
pinepaper_set_background_color	Set background
pinepaper_set_canvas_size	Set dimensions

Export Tools

Tool	Description
pinepaper_export_svg	Export animated SVG
pinepaper_export_training_data	Export LLM training pairs

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]

Flowchart Diagram (NEW)

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 (NEW)

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

┌─────────────────────────────────────────────────────────────┐
│                 AI Client (Claude, etc.)                    │
│                          │                                  │
│                    MCP Protocol                             │
│                          │                                  │
│              ┌───────────▼───────────┐                     │
│              │  PinePaper MCP Server │                     │
│              │  ┌─────────────────┐  │                     │
│              │  │  Tool Handlers  │  │                     │
│              │  └────────┬────────┘  │                     │
│              │           │           │                     │
│              │  ┌────────▼────────┐  │                     │
│              │  │ Code Generator  │  │                     │
│              │  └────────┬────────┘  │                     │
│              └───────────┼───────────┘                     │
│                          │                                  │
│              ┌───────────▼───────────┐                     │
│              │   PinePaper Studio    │                     │
│              │   (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:

   # Using npm
   npm run build
   
   # Using bun
   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

# Using npm
npm test

# Using bun
bun test

# Run with coverage
bun test --coverage

Development Watch Mode

# Using npm
npm run dev

# Using bun
bun run dev

Internationalization (i18n)

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

Supported Languages

Category	Languages
European	English, Spanish, French, German, Italian, Portuguese (+ Brazilian), Dutch, Polish, Russian, Ukrainian, Swedish, Danish, Norwegian, Finnish, Czech, Greek, Hungarian, Romanian, Turkish, Icelandic
East Asian	Chinese (Simplified & Traditional), Japanese, Korean
Southeast Asian	Thai, Vietnamese, Indonesian, Malay, Tagalog, Filipino
South Asian	Hindi, Bengali, Tamil, Telugu, Marathi, Gujarati, Kannada, Malayalam, Punjabi, Urdu
Middle Eastern	Arabic, Hebrew, Persian (RTL support)
Indigenous (Canada)	Chipewyan, Cree, Michif, Inuktitut, Mi'kmaq, Mohawk, Ojibwe

How It Works

The i18n system provides localized:

• Tool names and descriptions
• Error messages
• Success messages
• UI labels for item types, relations, animations, and generators

Setting Language

Set the PINEPAPER_LOCALE environment variable:

# In MCP client config (example for Claude Desktop)
{
  "mcpServers": {
    "pinepaper": {
      "command": "npx",
      "args": ["-y", "@pinepaper.studio/mcp-server"],
      "env": {
        "PINEPAPER_LOCALE": "ja"
      }
    }
  }
}

Or programmatically:

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

// Set locale
setLocale('fr');

// Get translated string
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

Variable	Description	Default
PINEPAPER_DEBUG	Enable debug logging	false
PINEPAPER_LOG_LEVEL	Log level (error/warn/info/debug)	info
PINEPAPER_LOCALE	Language locale code	en
PINEPAPER_METRICS_ENABLED	Enable performance metrics tracking	true
PINEPAPER_METRICS_RETENTION	Max metrics to retain in memory	1000
PINEPAPER_SCREENSHOT_MODE	Screenshot mode (on_request/always/never)	on_request

Performance Metrics

PinePaper MCP Server includes built-in performance tracking to help AI assistants optimize workflows by identifying bottlenecks and choosing faster alternatives.

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
• PinePaper Reference - Complete PinePaper Studio API reference

External Documentation

• PinePaper API Docs
• MCP Tools Specification

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: npm 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