@pinepaper.studio/mcp-server 1.3.1 → 1.3.3

package/dist/tools/definitions.js

@@ -149,6 +149,13 @@ export const PINEPAPER_TOOLS = [
     // ---------------------------------------------------------------------------
     {
         name: 'pinepaper_create_item',
+        annotations: {
+            title: 'Create Item',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `Create an item on the PinePaper canvas. Returns an itemId (e.g., "item_1") that you MUST save to reference this item later.
 
 USE WHEN:
@@ -231,6 +238,13 @@ For glossy 3D spheres, use pinepaper_create_glossy_sphere instead. For diagonal
     },
     {
         name: 'pinepaper_modify_item',
+        annotations: {
+            title: 'Modify Item',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Modify an existing item's properties.
 
 USE WHEN:
@@ -274,6 +288,13 @@ GRADIENT OBJECT FORMAT:
     },
     {
         name: 'pinepaper_delete_item',
+        annotations: {
+            title: 'Delete Item',
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Delete a single item from the canvas by its registry ID.
 
 USE WHEN:
@@ -309,6 +330,13 @@ Use pinepaper_clear_canvas instead of deleting items one by one.`,
     // ---------------------------------------------------------------------------
     {
         name: 'pinepaper_create_glossy_sphere',
+        annotations: {
+            title: 'Create Glossy Sphere',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `Create a 3D-looking glossy sphere with realistic lighting effects. This is a HIGH-LEVEL tool that creates a complete glossy sphere with radial gradient, specular highlights, and optional shadow - all in one operation.
 
 USE WHEN:
@@ -375,6 +403,13 @@ EXAMPLES:
     },
     {
         name: 'pinepaper_create_diagonal_stripes',
+        annotations: {
+            title: 'Create Diagonal Stripes',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `Create a diagonal stripe pattern. This is a HIGH-LEVEL tool that creates multiple stripes at an angle with automatic clipping to a rectangular area.
 
 USE WHEN:
@@ -437,11 +472,175 @@ EXAMPLES:
             required: ['width', 'height', 'colors'],
         },
     },
+    {
+        name: 'pinepaper_create_scene',
+        annotations: {
+            title: 'Create Scene',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: `Create a complete scene with multiple items, relations, and animations in a single operation. This is the MOST EFFICIENT way to create complex animated scenes.
+
+USE WHEN:
+- Creating a solar system, bouncing balls, or any multi-item animated scene
+- User describes a scene with multiple related elements
+- Performance is important (reduces 4+ tool calls to 1)
+- Setting up multiple items that will interact with each other
+
+ADVANTAGES:
+- 4-8x faster than calling individual tools
+- Single undo step for entire scene
+- Automatic name-to-ID mapping for relations
+- Cleaner, more atomic scene creation
+
+HOW IT WORKS:
+1. Define items with "name" references (e.g., "sun", "earth", "moon")
+2. Define relations using those names (e.g., source: "earth", target: "sun")
+3. Define animations using names (e.g., target: "sun", type: "pulse")
+4. The server creates all items, then establishes relations and animations
+
+EXAMPLE - Solar System:
+{
+  "backgroundColor": "#0a0a0a",
+  "items": [
+    { "name": "sun", "itemType": "circle", "position": {"x": 400, "y": 300}, "properties": {"radius": 50, "color": "#fbbf24"} },
+    { "name": "earth", "itemType": "circle", "position": {"x": 550, "y": 300}, "properties": {"radius": 20, "color": "#3b82f6"} },
+    { "name": "moon", "itemType": "circle", "position": {"x": 590, "y": 300}, "properties": {"radius": 8, "color": "#9ca3af"} }
+  ],
+  "relations": [
+    { "source": "earth", "target": "sun", "type": "orbits", "params": {"radius": 150, "speed": 0.5} },
+    { "source": "moon", "target": "earth", "type": "orbits", "params": {"radius": 40, "speed": 1.5} }
+  ],
+  "animations": [
+    { "target": "sun", "type": "pulse", "speed": 0.3 }
+  ]
+}
+
+EXAMPLE - Bouncing Balls:
+{
+  "backgroundColor": "#1e293b",
+  "items": [
+    { "name": "ball1", "itemType": "circle", "position": {"x": 200, "y": 300}, "properties": {"radius": 30, "color": "#ef4444"} },
+    { "name": "ball2", "itemType": "circle", "position": {"x": 400, "y": 300}, "properties": {"radius": 30, "color": "#22c55e"} },
+    { "name": "ball3", "itemType": "circle", "position": {"x": 600, "y": 300}, "properties": {"radius": 30, "color": "#3b82f6"} }
+  ],
+  "animations": [
+    { "target": "ball1", "type": "bounce", "speed": 1.0 },
+    { "target": "ball2", "type": "bounce", "speed": 0.8 },
+    { "target": "ball3", "type": "bounce", "speed": 1.2 }
+  ]
+}
+
+SUPPORTED ITEM TYPES: text, circle, star, rectangle, triangle, polygon, ellipse, path, line, arc
+SUPPORTED RELATIONS: orbits, follows, attached_to, maintains_distance, points_at, mirrors, parallax, bounds_to
+SUPPORTED ANIMATIONS: pulse, rotate, bounce, fade, wobble, slide, typewriter`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                items: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            name: {
+                                type: 'string',
+                                description: 'Reference name for this item (used in relations/animations)',
+                            },
+                            itemType: {
+                                type: 'string',
+                                enum: ['text', 'circle', 'star', 'rectangle', 'triangle', 'polygon', 'ellipse', 'path', 'line', 'arc'],
+                                description: 'Type of item to create',
+                            },
+                            position: {
+                                type: 'object',
+                                properties: {
+                                    x: { type: 'number' },
+                                    y: { type: 'number' },
+                                },
+                                description: 'Position on canvas',
+                            },
+                            properties: {
+                                type: 'object',
+                                description: 'Item-specific properties (color, radius, content, etc.)',
+                                additionalProperties: true,
+                            },
+                        },
+                        required: ['name', 'itemType'],
+                    },
+                    description: 'Array of items to create with reference names',
+                },
+                relations: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            source: { type: 'string', description: 'Name of source item' },
+                            target: { type: 'string', description: 'Name of target item' },
+                            type: {
+                                type: 'string',
+                                enum: ['orbits', 'follows', 'attached_to', 'maintains_distance', 'points_at', 'mirrors', 'parallax', 'bounds_to'],
+                            },
+                            params: {
+                                type: 'object',
+                                description: 'Relation parameters (radius, speed, distance, etc.)',
+                                additionalProperties: true,
+                            },
+                        },
+                        required: ['source', 'target', 'type'],
+                    },
+                    description: 'Relations between items',
+                },
+                animations: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            target: { type: 'string', description: 'Name of item to animate' },
+                            type: {
+                                type: 'string',
+                                enum: ['pulse', 'rotate', 'bounce', 'fade', 'wobble', 'slide', 'typewriter'],
+                            },
+                            speed: { type: 'number', description: 'Animation speed (default: 1.0)' },
+                            params: {
+                                type: 'object',
+                                description: 'Animation-specific parameters',
+                                additionalProperties: true,
+                            },
+                        },
+                        required: ['target', 'type'],
+                    },
+                    description: 'Animations to apply to items',
+                },
+                backgroundColor: {
+                    type: 'string',
+                    description: 'Background color for the scene (hex, rgb, or named)',
+                },
+                backgroundGenerator: {
+                    type: 'string',
+                    description: 'Name of generator to use for background (e.g., "drawSunburst")',
+                },
+                clearFirst: {
+                    type: 'boolean',
+                    description: 'Clear canvas before creating scene (default: true)',
+                },
+            },
+            required: ['items'],
+        },
+    },
     // ---------------------------------------------------------------------------
     // BATCH OPERATION TOOLS
     // ---------------------------------------------------------------------------
     {
         name: 'pinepaper_batch_create',
+        annotations: {
+            title: 'Batch Create Items',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `Create multiple items at once with a single history save. This is more efficient than creating items one by one.
 
 USE WHEN:
@@ -489,6 +688,13 @@ items: [
     },
     {
         name: 'pinepaper_batch_modify',
+        annotations: {
+            title: 'Batch Modify Items',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Modify multiple items at once with a single history save. This is more efficient than modifying items one by one.
 
 USE WHEN:
@@ -535,6 +741,13 @@ modifications: [
     },
     {
         name: 'pinepaper_create_grid',
+        annotations: {
+            title: 'Create Grid',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `Create a grid of lines on the canvas. This is a convenience method that handles all coordinate calculations automatically.
 
 USE WHEN:
@@ -592,6 +805,13 @@ EXAMPLE:
     // ---------------------------------------------------------------------------
     {
         name: 'pinepaper_add_relation',
+        annotations: {
+            title: 'Add Relation',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Create a behavior relationship between two items. Relations are the PRIMARY way to add animation in PinePaper - they describe HOW items should behave relative to each other.
 
 USE WHEN:
@@ -649,6 +869,13 @@ Relations are COMPOSITIONAL - an item can have multiple relations that work toge
     },
     {
         name: 'pinepaper_remove_relation',
+        annotations: {
+            title: 'Remove Relation',
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Remove a relationship between items.
 
 USE WHEN:
@@ -671,6 +898,13 @@ USE WHEN:
     },
     {
         name: 'pinepaper_query_relations',
+        annotations: {
+            title: 'Query Relations',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Query relationships for an item.
 
 USE WHEN:
@@ -700,6 +934,13 @@ USE WHEN:
     // ---------------------------------------------------------------------------
     {
         name: 'pinepaper_animate',
+        annotations: {
+            title: 'Animate Item',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Apply a simple LOOP animation to an item. These are continuous animations that repeat infinitely.
 
 USE WHEN:
@@ -743,6 +984,13 @@ ANIMATION TYPES:
     },
     {
         name: 'pinepaper_keyframe_animate',
+        annotations: {
+            title: 'Keyframe Animation',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Apply keyframe-based animation with precise timing and property control.
 
 USE WHEN:
@@ -808,6 +1056,13 @@ EASING OPTIONS:
     },
     {
         name: 'pinepaper_play_timeline',
+        annotations: {
+            title: 'Play Timeline',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `Control keyframe animation playback.
 
 USE WHEN:
@@ -843,6 +1098,13 @@ USE WHEN:
     // ---------------------------------------------------------------------------
     {
         name: 'pinepaper_execute_generator',
+        annotations: {
+            title: 'Execute Generator',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `Execute a background generator to create procedural patterns.
 
 USE WHEN:
@@ -879,6 +1141,13 @@ GENERATORS:
     },
     {
         name: 'pinepaper_list_generators',
+        annotations: {
+            title: 'List Generators',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Get a list of all available background generators with their parameters.
 
 USE WHEN:
@@ -895,6 +1164,13 @@ USE WHEN:
     // ---------------------------------------------------------------------------
     {
         name: 'pinepaper_apply_effect',
+        annotations: {
+            title: 'Apply Effect',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `Apply a visual effect to an item.
 
 USE WHEN:
@@ -928,6 +1204,13 @@ EFFECTS:
     // ---------------------------------------------------------------------------
     {
         name: 'pinepaper_get_items',
+        annotations: {
+            title: 'Get Items',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Get all or filtered items from the canvas.
 
 USE WHEN:
@@ -966,6 +1249,13 @@ USE WHEN:
     },
     {
         name: 'pinepaper_get_relation_stats',
+        annotations: {
+            title: 'Get Relation Stats',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Get statistics about active relations in the scene.
 
 USE WHEN:
@@ -982,6 +1272,13 @@ USE WHEN:
     // ---------------------------------------------------------------------------
     {
         name: 'pinepaper_set_background_color',
+        annotations: {
+            title: 'Set Background Color',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Set the canvas background color.
 
 USE WHEN:
@@ -1000,6 +1297,13 @@ USE WHEN:
     },
     {
         name: 'pinepaper_set_canvas_size',
+        annotations: {
+            title: 'Set Canvas Size',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Change the canvas dimensions.
 
 IMPORTANT: Call this BEFORE creating items if you need a specific canvas size. The default canvas is 800x600 which may be too small for complex designs.
@@ -1034,6 +1338,13 @@ For wedding invitations, event cards, or detailed designs, use at least 1080x108
     },
     {
         name: 'pinepaper_get_canvas_size',
+        annotations: {
+            title: 'Get Canvas Size',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Get the current canvas dimensions.
 
 USE WHEN:
@@ -1047,6 +1358,13 @@ USE WHEN:
     },
     {
         name: 'pinepaper_clear_canvas',
+        annotations: {
+            title: 'Clear Canvas',
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Clear all items from the canvas, removing everything including any welcome template items.
 
 USE WHEN:
@@ -1067,6 +1385,13 @@ IMPORTANT NOTES:
     },
     {
         name: 'pinepaper_refresh_page',
+        annotations: {
+            title: 'Refresh Page',
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         description: `Refresh the PinePaper Studio page in the browser. This is the most reliable way to get a completely clean canvas.
 
 USE WHEN:
@@ -1092,6 +1417,13 @@ IMPORTANT NOTES:
     // ---------------------------------------------------------------------------
     {
         name: 'pinepaper_import_svg',
+        annotations: {
+            title: 'Import SVG',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
         description: `Import an SVG string or SVG from URL onto the canvas. Returns an itemId for the imported graphic.
 
 USE WHEN:
@@ -1145,6 +1477,13 @@ Returns the itemId of the imported SVG group, which can be used with pinepaper_a
     // ---------------------------------------------------------------------------
     {
         name: 'pinepaper_add_filter',
+        annotations: {
+            title: 'Add Filter',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `Add a visual filter effect to the canvas. Filters are scene-wide effects that can be stacked.
 
 USE WHEN:
@@ -1197,6 +1536,13 @@ Filters can be stacked - call multiple times to combine effects.`,
     // ---------------------------------------------------------------------------
     {
         name: 'pinepaper_export_svg',
+        annotations: {
+            title: 'Export SVG',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Export the scene as animated SVG.
 
 USE WHEN:
@@ -1215,6 +1561,13 @@ USE WHEN:
     },
     {
         name: 'pinepaper_export_training_data',
+        annotations: {
+            title: 'Export Training Data',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Export relation data as training pairs for LLM fine-tuning. This generates instruction/code pairs from the current scene's relations.
 
 USE WHEN:
@@ -1245,6 +1598,13 @@ OUTPUT FORMAT:
     // ---------------------------------------------------------------------------
     {
         name: 'pinepaper_browser_connect',
+        annotations: {
+            title: 'Connect to Browser',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         description: `Connect to PinePaper Studio Editor in a browser. This launches a browser window and navigates to the PinePaper Editor.
 
 USE WHEN:
@@ -1271,6 +1631,13 @@ The browser will open and navigate to https://pinepaper.studio/editor where the
     },
     {
         name: 'pinepaper_browser_disconnect',
+        annotations: {
+            title: 'Disconnect from Browser',
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         description: `Disconnect from the browser and close PinePaper Studio.
 
 USE WHEN:
@@ -1284,6 +1651,13 @@ USE WHEN:
     },
     {
         name: 'pinepaper_browser_screenshot',
+        annotations: {
+            title: 'Take Screenshot',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         description: `Take a screenshot of the current PinePaper canvas.
 
 USE WHEN:
@@ -1308,6 +1682,13 @@ Returns a base64-encoded PNG image of the canvas.`,
     },
     {
         name: 'pinepaper_browser_status',
+        annotations: {
+            title: 'Browser Status',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         description: `Check the current browser connection status.
 
 USE WHEN:
@@ -1324,6 +1705,13 @@ USE WHEN:
     // ---------------------------------------------------------------------------
     {
         name: 'pinepaper_get_performance_metrics',
+        annotations: {
+            title: 'Get Performance Metrics',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
         description: `Get execution performance metrics to identify bottlenecks and optimize workflows.
 
 USE WHEN:
@@ -1415,6 +1803,13 @@ If you see significantly higher numbers, investigate:
     // ---------------------------------------------------------------------------
     {
         name: 'pinepaper_search_assets',
+        annotations: {
+            title: 'Search Assets',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
         description: `Search for free SVG assets from open repositories (SVGRepo, OpenClipart, Iconify, FontAwesome).
 
 USE WHEN:
@@ -1475,6 +1870,13 @@ PERFORMANCE:
     },
     {
         name: 'pinepaper_import_asset',
+        annotations: {
+            title: 'Import Asset',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
         description: `Import an SVG asset from search results or direct URL onto the canvas.
 
 USE WHEN:
@@ -1551,6 +1953,13 @@ RETURNS:
     // ---------------------------------------------------------------------------
     {
         name: 'pinepaper_p5_draw',
+        annotations: {
+            title: 'p5.js Draw',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
         description: `Execute p5.js-style drawing code on the PinePaper canvas.
 
 Claude can use familiar p5.js syntax - the code is translated to Paper.js automatically.