mcp-server

@pinepaper/mcp-server

0 Stars 164 次浏览 pinepaper 更新于 2026-08-23

MCP 服务配置

复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用

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

服务介绍

PinePaper MCP Server

Create animated graphics with AI using the Model Context Protocol

Overview

PinePaper MCP Server enables AI assistants like Claude to create and animate graphics in PinePaper Studio. 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/mcp-server

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

2. Configure Claude Desktop

Add to your 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/mcp-server"]
    }
  }
}

3. Start Using

Open Claude Desktop 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

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

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

Query Tools

Tool	Description
`pinepaper_get_items`	Get canvas items
`pinepaper_get_relation_stats`	Relation statistics

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]

Architecture


                     Claude Desktop                          
                                                            
                    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 Claude Desktop (Local)

Build the server:

# Using npm
npm run build

# Using bun
bun run build

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Restart Claude Desktop
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 Claude Desktop config
{
  "mcpServers": {
    "pinepaper": {
      "command": "npx",
      "args": ["-y", "@pinepaper/mcp-server"],
      "env": {
        "PINEPAPER_LOCALE": "ja"
      }
    }
  }
}

Or programmatically:

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

// Set locale
setLocale('fr');

// Get translated string
const description = t('tools.pinepaper_create_item.description');

Adding New Languages

Create a new locale file in src/i18n/locales/ (e.g., xx.ts)
Copy the structure from en.ts
Translate all strings
Export from src/i18n/locales/index.ts
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`

API Documentation

Full API documentation available at:

Contributing

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

Development Workflow

Fork the repository
Create a feature branch
Make your changes
Run tests: npm test
Submit a pull request

License

MIT License - see LICENSE for details.

Support

Email: support@pinepaper.studio
Issues: GitHub Issues

Made with by the PinePaper team

查看源码项目主页