appiq-solution 1.2.0 → 1.3.0

package/#Tools/claude-talk-to-figma-mcp/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.2] - 2025-01-19
+
+### Fixed
+- Fixed critical opacity handling bug in `set_stroke_color` where `a: 0` (transparent) was incorrectly converted to `a: 1` (opaque)
+- Fixed stroke weight handling where `strokeWeight: 0` (no border) was incorrectly converted to `strokeWeight: 1`
+- Resolved problematic `||` operator usage that affected falsy values in color and stroke operations
+
+### Added
+- Extended `applyDefault()` utility function to handle stroke weight defaults safely
+- Added `FIGMA_DEFAULTS.stroke.weight` constant for centralized stroke configuration
+- Comprehensive test suite for `set_stroke_color` covering edge cases and integration scenarios
+- Enhanced validation for RGB components in stroke operations
+
+### Changed
+- Improved architectural consistency by applying the same safe defaults pattern from `set_fill_color` to `set_stroke_color`
+- Enhanced separation of concerns between MCP layer (business logic) and Figma plugin (pure translator)
+- Renamed `weight` parameter to `strokeWeight` for better clarity and consistency
+- Updated Figma plugin to expect complete data from MCP layer instead of handling defaults internally
+
+### Technical Details
+- Replaced `strokeWeight: strokeWeight || 1` with `applyDefault(strokeWeight, FIGMA_DEFAULTS.stroke.weight)`
+- Enhanced type safety with proper `Color` and `ColorWithDefaults` interface usage
+- Improved error messages and validation for better debugging experience
+
+## [0.5.1] - 2025-06-15
+
+### Fixed
+- Fixed opacity handling in `set_fill_color` to properly respect alpha values
+- Added `applyColorDefaults` function to ensure appropriate default values for colors
+
+### Added
+- Added automated tests for color functions and node manipulation
+
+### Changed
+- Improved TypeScript typing for colors and related properties
+- General code cleanup and better utility organization
+
+## [0.5.0] - 2025-05-28
+
+### Changed
+- Implemented modular tool structure for better maintainability
+- Enhanced handling of complex operations with timeouts and chunking
+- Improved error handling and recovery for all tools
+- Improved TypeScript typing and standardized error handling
+
+### Fixed
+- Fixed channel connection issues with improved state management
+- Resolved timeout problems in `flatten_node`, `create_component_instance`, and `set_effect_style_id`
+- Enhanced remote component access with better error handling
+
+### Added
+- Comprehensive documentation of tool categories and capabilities
+
+## [0.4.0] - 2025-04-15
+
+### Added
+- New tools for creating advanced shapes:
+  - `create_ellipse`: Creation of ellipses and circles
+  - `create_polygon`: Creation of polygons with customizable sides
+  - `create_star`: Creation of stars with customizable points and inner radius
+  - `create_vector`: Creation of complex vector shapes
+  - `create_line`: Creation of straight lines
+- Advanced text and font manipulation capabilities
+- New commands for controlling typography: font styles, spacing, text case, and more
+- Support for accessing team library components
+- Improved error handling and timeout management
+- Enhanced text scanning capabilities
+
+### Changed
+- Improvements in documentation and usage examples
+
+## [0.3.0] - 2025-03-10
+
+### Added
+- Added `set_auto_layout` command to configure auto layout properties for frames and groups
+- Support for settings for layout direction, padding, item spacing, alignment and more
+
+## [0.2.0] - 2025-02-01
+
+### Added
+- Initial public release with Claude Desktop support

package/#Tools/claude-talk-to-figma-mcp/Dockerfile

@@ -0,0 +1,16 @@
+# Use the Bun image as the base image
+FROM oven/bun:latest
+
+# Set the working directory in the container
+WORKDIR /app
+
+# Copy the current directory contents into the container at /app
+COPY package*.json ./
+
+RUN bun install
+
+# Expose the port on which the API will listen
+EXPOSE 3055
+
+# Run the server when the container launches
+CMD ["bun", "src/talk_to_figma_mcp/server.ts"]

package/#Tools/claude-talk-to-figma-mcp/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Github User sonnylazuardi
+Copyright (c) 2025 Github User arinspunk (modification: Cursor to Claude)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/#Tools/claude-talk-to-figma-mcp/TESTING.md

@@ -0,0 +1,216 @@
+# Testing Guide for Claude Talk to Figma MCP
+
+This document provides a detailed guide for testing the Claude Talk to Figma MCP project, including both automated tests and manual integration tests.
+
+## Testing Approaches
+
+The project uses two complementary testing approaches:
+
+1. **Automated Tests**: Unit and component integration tests using Jest
+2. **Manual Integration Tests**: End-to-end tests for the complete Claude-MCP-Figma workflow
+
+## Prerequisites
+
+Before starting the tests, make sure you have:
+
+- Claude Desktop installed
+- Figma account with plugin creation access
+- Bun installed (v1.0.0 or higher)
+- Permissions to install plugins in Figma
+
+## Automated Tests
+
+### Running Automated Tests
+
+```bash
+# Run all automated tests
+bun run test
+
+# Run in watch mode (re-runs on file changes)
+bun run test:watch
+
+# Run with coverage report
+bun run test:coverage
+```
+
+### Test Categories
+
+1. **Unit Tests** (`tests/unit/`):
+   - Test individual functions and utilities in isolation
+   - Verify edge cases and error handling
+   - Example: `defaults.test.ts` - Tests the proper handling of falsy values
+
+2. **Integration Tests** (`tests/integration/`):
+   - Test interactions between multiple components
+   - Verify that components work together correctly
+   - Example: `set-fill-color.test.ts` - Tests the opacity handling in fill colors
+
+### Adding New Tests
+
+1. For unit tests:
+   - Create a file in the appropriate directory under `tests/unit/`
+   - Name the file `*.test.ts` to be detected by Jest
+
+2. For integration tests:
+   - Create a file in the `tests/integration/` directory
+   - Use the test fixtures in `tests/fixtures/` for test data
+
+## Manual Integration Tests
+
+These tests verify the complete end-to-end workflow between Claude Desktop, the MCP server, and Figma.
+
+### Running Integration Tests
+
+```bash
+bun run test:integration
+```
+
+This script will guide you through the complete testing process.
+
+## Test Cases
+
+### 1. Environment Setup
+
+| Test case | Steps | Expected result |
+| -------------- | ----- | ------------------ |
+| Dependencies installation | Run `bun install` | All dependencies are installed without errors |
+| Claude configuration | Run `bun run configure-claude` | Script executed correctly, successful configuration message |
+| Verify configuration | Check `claude_desktop_config.json` file | Contains configuration for "ClaudeTalkToFigma" |
+
+### 2. WebSocket Server Configuration
+
+| Test case | Steps | Expected result |
+| -------------- | ----- | ------------------ |
+| Start WebSocket server | Run `bun socket` | Server starts on port 3055, shows confirmation message |
+| Verify server status | Access `http://localhost:3055/status` | Returns JSON with "running" status and statistics |
+| Test reconnection | Stop and restart the server | Client reconnects automatically |
+
+### 3. Figma Plugin Setup
+
+#### Install the Figma Plugin
+
+1. Open Figma and go to **Menu > Plugins > Development > New Plugin**
+2. Select "Link existing plugin"
+3. Navigate to and select the folder `src/claude_mcp_plugin` from this repository
+
+#### Connect Plugin to WebSocket Server
+
+1. The plugin will ask for a port number (default: 3055)
+2. Enter the port number where your WebSocket server is running
+3. Click "Connect"
+4. You should see a "Connected to Claude MCP server" message
+
+#### Integration Test
+
+To test if the Figma plugin is correctly communicating with the Claude MCP server:
+
+1. Start the WebSocket server
+2. Open Figma and run the Claude MCP Plugin from your Development plugins
+3. Connect to the WebSocket server 
+4. Open Claude Desktop and select the "ClaudeTalkToFigma" MCP
+5. Test a simple command in Claude like: "Can you show me information about my current Figma document?"
+
+Claude should be able to communicate with Figma and return information about the document.
+
+### 4. Claude-MCP-Figma Integration Tests
+
+| Test case | Steps | Expected result |
+| -------------- | ----- | ------------------ |
+| Get document info | Ask Claude about the open document | Claude returns information about the document |
+| Get selection | Select element in Figma and ask Claude | Claude returns details of the selected element |
+| Create element | Ask Claude to create a rectangle | Rectangle created in Figma document |
+| Modify element | Ask Claude to change color of an element | Element color changed correctly |
+| Complex operation | Ask Claude to find text and modify it | Text correctly modified in multiple nodes |
+
+## Common Problems and Solutions
+
+### Connection Problems
+
+| Problem | Possible cause | Solution |
+| -------- | ------------- | -------- |
+| "Cannot connect to WebSocket server" | Server is not running | Run `bun socket` in terminal |
+| "Connection error: port in use" | Port 3055 is occupied | Free the port or change port configuration |
+| "Cannot connect from plugin" | CORS restrictions | Verify that the plugin uses the correct domain |
+| "Connection rejected" | Firewall blocking connection | Allow connections to port 3055 in firewall |
+
+### Problems with Claude Desktop
+
+| Problem | Possible cause | Solution |
+| -------- | ------------- | -------- |
+| "MCP does not appear in Claude Desktop" | Incorrect configuration | Verify configuration file and run `bun run configure-claude` |
+| "Claude does not respond to Figma commands" | MCP not selected | Select "ClaudeTalkToFigma" in the MCPs menu |
+| "Error executing MCP command" | Missing dependencies | Reinstall with `bun install` |
+| "Claude cannot execute commands in Figma" | Channel not joined | Verify that `join_channel` was executed |
+
+### Problems with Figma
+
+| Problem | Possible cause | Solution |
+| -------- | ------------- | -------- |
+| "Plugin does not appear in Figma" | Incorrect import | Verify path and reimport the plugin |
+| "Error executing commands in Figma" | Insufficient permissions | Verify permissions in manifest.json |
+| "Cannot modify elements" | Document in read-only mode | Open document in edit mode |
+| "Error creating elements" | Incorrect selection | Verify that the target page or frame is selected |
+
+## Diagnostics and Debugging
+
+### Diagnostic Tools
+
+1. **WebSocket Server Logs**:
+   - Detailed logs are shown in the terminal where you run `bun socket`
+   - Look for ERROR or WARN messages to identify problems
+
+2. **Status Endpoint**:
+   - Access `http://localhost:3055/status` to verify statistics
+   - Check active connections and accumulated errors
+
+3. **Figma Console**:
+   - Open the development console in Figma (F12 or Cmd+Option+I)
+   - Review error messages related to the plugin
+
+4. **Configuration Verification**:
+   - Examine `claude_desktop_config.json` to confirm correct configuration
+
+### Systematic Debugging Steps
+
+1. **Verify Individual Components**:
+   - Confirm that the WebSocket server is running
+   - Verify that the Figma plugin can be opened
+   - Check that Claude Desktop recognizes the MCP
+
+2. **Test Communication in Parts**:
+   - Test the plugin's connection to the WebSocket directly
+   - Verify that Claude can execute basic MCP commands
+   - Confirm that commands reach the Figma plugin
+
+3. **Restart Components in Order**:
+   - Restart the WebSocket server
+   - Reload the plugin in Figma
+   - Restart Claude Desktop
+
+4. **Update Versions**:
+   - Make sure you have the latest versions of all dependencies
+   - Verify compatibility with the current version of Figma
+
+## Comprehensive Testing Checklist
+
+- [ ] Claude Desktop configuration completed
+- [ ] WebSocket server started and running
+- [ ] Figma plugin installed and connected
+- [ ] Claude Desktop can get document information
+- [ ] Claude Desktop can get current selection
+- [ ] Claude Desktop can create new elements
+- [ ] Claude Desktop can modify existing elements
+- [ ] Claude Desktop can scan and modify text
+- [ ] The system recovers correctly from disconnections
+- [ ] Errors are handled and reported correctly
+- [ ] Automated tests pass successfully
+- [ ] Set fill color handles transparency correctly
+
+## Troubleshooting Automated Tests
+
+| Problem | Possible cause | Solution |
+| -------- | ------------- | -------- |
+| Jest tests fail to run | Missing dependencies | Run `bun install` to install all dependencies |
+| Test timeouts | Slow machine or heavy CPU load | Increase timeout in Jest configuration |
+| Mocks not working | Incorrect import paths | Verify mock paths match actual module paths |
+| Type errors in tests | TypeScript configuration issue | Check `tsconfig.json` and Jest TypeScript settings |