faux-studio 0.3.2 → 0.3.4

package/dist/index.js

@@ -25355,10 +25355,99 @@ async function handleGetBlueprint(blueprintId, jwt2) {
   }
   return { content };
 }
+var TOOL_ANNOTATIONS = {
+  // --- Local tools ---
+  login: { readOnlyHint: true, openWorldHint: true },
+  setup_figma: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  // --- Read/Inspect ---
+  get_design_system: { readOnlyHint: true, openWorldHint: false },
+  get_screenshot: { readOnlyHint: true, openWorldHint: false },
+  get_node_details: { readOnlyHint: true, openWorldHint: false },
+  get_page_structure: { readOnlyHint: true, openWorldHint: false },
+  query_nodes: { readOnlyHint: true, openWorldHint: false },
+  get_components: { readOnlyHint: true, openWorldHint: false },
+  get_selection: { readOnlyHint: true, openWorldHint: false },
+  get_connections: { readOnlyHint: true, openWorldHint: false },
+  get_flow_starting_points: { readOnlyHint: true, openWorldHint: false },
+  get_blueprint: { readOnlyHint: true, openWorldHint: true },
+  search_icons: { readOnlyHint: true, openWorldHint: true },
+  // --- Create (not idempotent — creates new nodes each time) ---
+  create_from_schema: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  create_variable_collection: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  create_variables: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  create_text_styles: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  connect_nodes: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  add_variant_to_component_set: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  // --- Modify (idempotent — same params = same result) ---
+  modify_via_schema: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  update_variables: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  update_text_styles: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  update_connections: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  move_nodes: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  reorder_children: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  align_nodes: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  set_variable_mode: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  manage_component_properties: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  focus_viewport: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  // --- Destructive ---
+  delete_nodes: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+  delete_variable_collections: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+  delete_variables: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+  delete_text_styles: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+  disconnect_nodes: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+  detach_instance: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+  // --- Arbitrary execution (can't classify) ---
+  execute_figma_script: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  execute_workflow: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  // --- Signals (UI lifecycle, no canvas effect) ---
+  signal_work_start: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  signal_work_end: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+};
+function annotate(tool) {
+  const annotations = TOOL_ANNOTATIONS[tool.name];
+  if (!annotations) return tool;
+  return { ...tool, annotations };
+}
+var INSTRUCTIONS = `You are connected to Figma Desktop via faux-studio. You can create, modify, and inspect designs using the tools below.
+
+## Workflow
+1. Call \`setup_figma\` first to ensure Figma is running and connected.
+2. Call \`get_page_structure\` or \`get_screenshot\` to understand what's on the canvas.
+3. Use \`create_from_schema\` for all creation \u2014 it accepts declarative JSON schemas.
+4. Use \`modify_via_schema\` to change existing nodes.
+5. Use \`get_screenshot\` to verify your work visually.
+
+## Primary Tools
+- **create_from_schema** \u2014 The main creation tool. Pass a JSON schema describing frames, components, text, shapes, auto-layout, and variable bindings. Supports \`@Variable|fallback\` syntax for design tokens, \`$icon\` for icons, \`$image\` for images, \`$textStyle\` for typography, and ComponentSet matrix mode.
+- **modify_via_schema** \u2014 Modify existing nodes by ID. Same schema format as create_from_schema.
+- **execute_figma_script** \u2014 Run raw Figma Plugin API JavaScript when no other tool fits.
+
+## Design Tokens & Variables
+- Call \`get_design_system\` to read existing variables, styles, and tokens before designing.
+- Use \`create_variable_collection\` and \`create_variables\` to set up design tokens.
+- Bind variables in schemas with \`@CollectionName/VariableName|fallback\` syntax.
+
+## Reading the Canvas
+- \`get_page_structure\` \u2014 page/frame hierarchy
+- \`get_node_details\` \u2014 inspect specific nodes by ID
+- \`get_selection\` \u2014 what the user has selected
+- \`query_nodes\` \u2014 search nodes by type, name, or properties
+- \`get_components\` \u2014 list available components
+- \`get_screenshot\` \u2014 visual capture of the canvas
+
+## Best Practices
+- Always read the existing design system before creating new elements.
+- Use auto-layout (horizontal/vertical) for responsive layouts \u2014 avoid absolute positioning.
+- Bind colors, spacing, and typography to variables for maintainability.
+- Group related elements in frames with descriptive names.
+- Create components for reusable UI patterns.`;
 function createMcpServer(deps) {
   const server = new Server(
-    { name: "faux-studio", version: "0.3.2" },
-    { capabilities: { tools: { listChanged: true } } }
+    { name: "faux-studio", version: "0.3.4" },
+    {
+      capabilities: { tools: { listChanged: true } },
+      instructions: INSTRUCTIONS
+    }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => {
     const localTools = [
@@ -25382,7 +25471,8 @@ function createMcpServer(deps) {
         }
       }
     ];
-    return { tools: [...localTools, ...deps.tools] };
+    const allTools = [...localTools, ...deps.tools].map(annotate);
+    return { tools: allTools };
   });
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faux-studio",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "AI-powered Figma design via MCP — connect any AI client to Figma Desktop",
   "type": "module",
   "bin": {