appiq-solution 1.2.0 → 1.3.0

package/#Tools/claude-talk-to-figma-mcp/src/talk_to_figma_mcp/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "talk-to-figma-mcp",
+  "version": "0.5.1",
+  "description": "MCP server for Figma integration",
+  "main": "server.ts",
+  "type": "module",
+  "scripts": {
+    "start": "node --loader ts-node/esm server.ts",
+    "build": "tsc",
+    "dev": "node --loader ts-node/esm --watch server.ts"
+  },
+  "keywords": [
+    "figma",
+    "mcp",
+    "claude",
+    "ai"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.4.0",
+    "uuid": "^9.0.1",
+    "ws": "^8.16.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.5",
+    "@types/uuid": "^9.0.7",
+    "@types/ws": "^8.5.10",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  }
+}

package/#Tools/claude-talk-to-figma-mcp/src/talk_to_figma_mcp/prompts/index.ts

@@ -0,0 +1,297 @@
+/**
+ * This module contains all the prompts used by the Figma MCP server.
+ * Prompts provide guidance to Claude on how to work with Figma designs effectively.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+/**
+ * Register all prompts with the MCP server
+ * @param server - The MCP server instance
+ */
+export function registerPrompts(server: McpServer): void {
+  // Design Strategy Prompt
+  server.prompt(
+    "design_strategy",
+    "Best practices for working with Figma designs",
+    (extra) => {
+      return {
+        messages: [
+          {
+            role: "assistant",
+            content: {
+              type: "text",
+              text: `When working with Figma designs, follow these best practices:
+
+1. Start with Document Structure:
+   - First use get_document_info() to understand the current document
+   - Plan your layout hierarchy before creating elements
+   - Create a main container frame for each screen/section
+
+2. Naming Conventions:
+   - Use descriptive, semantic names for all elements
+   - Follow a consistent naming pattern (e.g., "Login Screen", "Logo Container", "Email Input")
+   - Group related elements with meaningful names
+
+3. Layout Hierarchy:
+   - Create parent frames first, then add child elements
+   - For forms/login screens:
+     * Start with the main screen container frame
+     * Create a logo container at the top
+     * Group input fields in their own containers
+     * Place action buttons (login, submit) after inputs
+     * Add secondary elements (forgot password, signup links) last
+
+4. Input Fields Structure:
+   - Create a container frame for each input field
+   - Include a label text above or inside the input
+   - Group related inputs (e.g., username/password) together
+
+5. Element Creation:
+   - Use create_frame() for containers and input fields
+   - Use create_text() for labels, buttons text, and links
+   - Set appropriate colors and styles:
+     * Use fillColor for backgrounds
+     * Use strokeColor for borders
+     * Set proper fontWeight for different text elements
+
+6. Mofifying existing elements:
+  - use set_text_content() to modify text content.
+
+7. Visual Hierarchy:
+   - Position elements in logical reading order (top to bottom)
+   - Maintain consistent spacing between elements
+   - Use appropriate font sizes for different text types:
+     * Larger for headings/welcome text
+     * Medium for input labels
+     * Standard for button text
+     * Smaller for helper text/links
+
+8. Best Practices:
+   - Verify each creation with get_node_info()
+   - Use parentId to maintain proper hierarchy
+   - Group related elements together in frames
+   - Keep consistent spacing and alignment
+
+Example Login Screen Structure:
+- Login Screen (main frame)
+  - Logo Container (frame)
+    - Logo (image/text)
+  - Welcome Text (text)
+  - Input Container (frame)
+    - Email Input (frame)
+      - Email Label (text)
+      - Email Field (frame)
+    - Password Input (frame)
+      - Password Label (text)
+      - Password Field (frame)
+  - Login Button (frame)
+    - Button Text (text)
+  - Helper Links (frame)
+    - Forgot Password (text)
+    - Don't have account (text)`,
+            },
+          },
+        ],
+        description: "Best practices for working with Figma designs",
+      };
+    }
+  );
+
+  // Read Design Strategy Prompt
+  server.prompt(
+    "read_design_strategy",
+    "Best practices for reading Figma designs",
+    (extra) => {
+      return {
+        messages: [
+          {
+            role: "assistant",
+            content: {
+              type: "text",
+              text: `When reading Figma designs, follow these best practices:
+
+1. Start with selection:
+   - First use get_selection() to understand the current selection
+   - If no selection ask user to select single or multiple nodes
+
+2. Get node infos of the selected nodes:
+   - Use get_nodes_info() to get the information of the selected nodes
+   - If no selection ask user to select single or multiple nodes
+`,
+            },
+          },
+        ],
+        description: "Best practices for reading Figma designs",
+      };
+    }
+  );
+
+  // Text Replacement Strategy Prompt
+  server.prompt(
+    "text_replacement_strategy",
+    "Systematic approach for replacing text in Figma designs",
+    (extra) => {
+      return {
+        messages: [
+          {
+            role: "assistant",
+            content: {
+              type: "text",
+              text: `# Intelligent Text Replacement Strategy
+
+## 1. Analyze Design & Identify Structure
+- Scan text nodes to understand the overall structure of the design
+- Use AI pattern recognition to identify logical groupings:
+  * Tables (rows, columns, headers, cells)
+  * Lists (items, headers, nested lists)
+  * Card groups (similar cards with recurring text fields)
+  * Forms (labels, input fields, validation text)
+  * Navigation (menu items, breadcrumbs)
+\`\`\`
+scan_text_nodes(nodeId: "node-id")
+get_node_info(nodeId: "node-id")  // optional
+\`\`\`
+
+## 2. Strategic Chunking for Complex Designs
+- Divide replacement tasks into logical content chunks based on design structure
+- Use one of these chunking strategies that best fits the design:
+  * **Structural Chunking**: Table rows/columns, list sections, card groups
+  * **Spatial Chunking**: Top-to-bottom, left-to-right in screen areas
+  * **Semantic Chunking**: Content related to the same topic or functionality
+  * **Component-Based Chunking**: Process similar component instances together
+
+## 3. Progressive Replacement with Verification
+- Create a safe copy of the node for text replacement
+- Replace text chunk by chunk with continuous progress updates
+- After each chunk is processed:
+  * Export that section as a small, manageable image
+  * Verify text fits properly and maintain design integrity
+  * Fix issues before proceeding to the next chunk
+
+\`\`\`
+// Clone the node to create a safe copy
+clone_node(nodeId: "selected-node-id", x: [new-x], y: [new-y])
+
+// Replace text chunk by chunk
+set_multiple_text_contents(
+  nodeId: "parent-node-id", 
+  text: [
+    { nodeId: "node-id-1", text: "New text 1" },
+    // More nodes in this chunk...
+  ]
+)
+
+// Verify chunk with small, targeted image exports
+export_node_as_image(nodeId: "chunk-node-id", format: "PNG", scale: 0.5)
+\`\`\`
+
+## 4. Intelligent Handling for Table Data
+- For tabular content:
+  * Process one row or column at a time
+  * Maintain alignment and spacing between cells
+  * Consider conditional formatting based on cell content
+  * Preserve header/data relationships
+
+## 5. Smart Text Adaptation
+- Adaptively handle text based on container constraints:
+  * Auto-detect space constraints and adjust text length
+  * Apply line breaks at appropriate linguistic points
+  * Maintain text hierarchy and emphasis
+  * Consider font scaling for critical content that must fit
+
+## 6. Progressive Feedback Loop
+- Establish a continuous feedback loop during replacement:
+  * Real-time progress updates (0-100%)
+  * Small image exports after each chunk for verification
+  * Issues identified early and resolved incrementally
+  * Quick adjustments applied to subsequent chunks
+
+## 7. Final Verification & Context-Aware QA
+- After all chunks are processed:
+  * Export the entire design at reduced scale for final verification
+  * Check for cross-chunk consistency issues
+  * Verify proper text flow between different sections
+  * Ensure design harmony across the full composition
+
+## 8. Chunk-Specific Export Scale Guidelines
+- Scale exports appropriately based on chunk size:
+  * Small chunks (1-5 elements): scale 1.0
+  * Medium chunks (6-20 elements): scale 0.7
+  * Large chunks (21-50 elements): scale 0.5
+  * Very large chunks (50+ elements): scale 0.3
+  * Full design verification: scale 0.2
+
+## Sample Chunking Strategy for Common Design Types
+
+### Tables
+- Process by logical rows (5-10 rows per chunk)
+- Alternative: Process by column for columnar analysis
+- Tip: Always include header row in first chunk for reference
+
+### Card Lists
+- Group 3-5 similar cards per chunk
+- Process entire cards to maintain internal consistency
+- Verify text-to-image ratio within cards after each chunk
+
+### Forms
+- Group related fields (e.g., "Personal Information", "Payment Details")
+- Process labels and input fields together
+- Ensure validation messages and hints are updated with their fields
+
+### Navigation & Menus
+- Process hierarchical levels together (main menu, submenu)
+- Respect information architecture relationships
+- Verify menu fit and alignment after replacement
+
+## Best Practices
+- **Preserve Design Intent**: Always prioritize design integrity
+- **Structural Consistency**: Maintain alignment, spacing, and hierarchy
+- **Visual Feedback**: Verify each chunk visually before proceeding
+- **Incremental Improvement**: Learn from each chunk to improve subsequent ones
+- **Balance Automation & Control**: Let AI handle repetitive replacements but maintain oversight
+- **Respect Content Relationships**: Keep related content consistent across chunks
+
+Remember that text is never just text—it's a core design element that must work harmoniously with the overall composition. This chunk-based strategy allows you to methodically transform text while maintaining design integrity.`,
+            },
+          },
+        ],
+        description: "Systematic approach for replacing text in Figma designs",
+      };
+    }
+  );
+}
+
+// Export individual prompt registration functions
+export function registerDesignStrategyPrompt(server: McpServer): void {
+  server.prompt(
+    "design_strategy",
+    "Best practices for working with Figma designs",
+    (extra) => {
+      // Implementation is the same as above
+      // This function is exported for individual usage if needed
+    }
+  );
+}
+
+export function registerReadDesignStrategyPrompt(server: McpServer): void {
+  server.prompt(
+    "read_design_strategy",
+    "Best practices for reading Figma designs",
+    (extra) => {
+      // Implementation is the same as above
+      // This function is exported for individual usage if needed
+    }
+  );
+}
+
+export function registerTextReplacementStrategyPrompt(server: McpServer): void {
+  server.prompt(
+    "text_replacement_strategy",
+    "Systematic approach for replacing text in Figma designs",
+    (extra) => {
+      // Implementation is the same as above
+      // This function is exported for individual usage if needed
+    }
+  );
+}

package/#Tools/claude-talk-to-figma-mcp/src/talk_to_figma_mcp/server.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+/**
+ * Main entry point for the Figma MCP Server
+ * This file initializes the server, connects to Figma,
+ * and registers all tools and prompts.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// Import configuration
+import { SERVER_CONFIG } from "./config/config";
+
+// Import utilities
+import { logger } from "./utils/logger";
+import { connectToFigma } from "./utils/websocket";
+
+// Import tools registration function from tools/index.ts
+import { registerTools } from "./tools";
+
+// Import prompts registration function from prompts/index.ts
+import { registerPrompts } from "./prompts";
+
+/**
+ * Initialize and start the MCP server
+ */
+async function main() {
+  try {
+    // Create MCP server instance with configuration
+    const server = new McpServer(SERVER_CONFIG);
+    
+    // Register all tools with the server
+    registerTools(server);
+    
+    // Register all prompts with the server
+    registerPrompts(server);
+    
+    // Try to connect to Figma socket server
+    try {
+      connectToFigma();
+    } catch (error) {
+      logger.warn(`Could not connect to Figma initially: ${error instanceof Error ? error.message : String(error)}`);
+      logger.warn('Will try to connect when the first command is sent');
+    }
+
+    // Start the MCP server with stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info('FigmaMCP server running on stdio');
+  } catch (error) {
+    logger.error(`Error starting FigmaMCP server: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+}
+
+// Run the server
+main().catch(error => {
+  logger.error(`Error starting FigmaMCP server: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+});
+

package/#Tools/claude-talk-to-figma-mcp/src/talk_to_figma_mcp/tools/component-tools.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { sendCommandToFigma } from "../utils/websocket";
+
+/**
+ * Register component-related tools to the MCP server
+ * This module contains tools for working with components in Figma
+ * @param server - The MCP server instance
+ */
+export function registerComponentTools(server: McpServer): void {
+  // Create Component Instance Tool
+  server.tool(
+    "create_component_instance",
+    "Create an instance of a component in Figma",
+    {
+      componentKey: z.string().describe("Key of the component to instantiate"),
+      x: z.number().describe("X position"),
+      y: z.number().describe("Y position"),
+    },
+    async ({ componentKey, x, y }) => {
+      try {
+        const result = await sendCommandToFigma("create_component_instance", {
+          componentKey,
+          x,
+          y,
+        });
+        const typedResult = result as any;
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(typedResult),
+            }
+          ]
+        }
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error creating component instance: ${error instanceof Error ? error.message : String(error)}`,
+            },
+          ],
+        };
+      }
+    }
+  );
+}