mcp-artisan

# MCP-Artisan v2.0.0 A **secure** Model Context Protocol (MCP) tool with workspace sandbox for AI Agents to find prompts, save HTML, and render HTML to images. ## 🚨 Breaking Changes in v2.0.0 This is a **major version update** with breaking changes. All API parameters have been redesigned for enhanced security and usability. ### Key Changes: - **Workspace Sandbox**: All operations are now restricted to a specified workspace directory - **Simplified APIs**: Removed complex path parameters, added intelligent file discovery - **Enhanced Security**: Built-in path validation prevents directory traversal attacks - **Smart Organization**: Automatic file organization in `output/` subdirectories ## Installation & Usage ```bash # Install and run with workspace npx mcp-artisan /path/to/your/workspace # Example npx mcp-artisan ./my-project ``` **Required**: You must specify a workspace directory when starting the server. ## Configuration for AI Environments (Cursor, etc.) To use MCP-Artisan with AI development environments like Cursor, you need to configure the MCP server command. 1. **Install MCP-Artisan globally or within your project:** ```bash # Global installation npm install -g mcp-artisan # Or local project installation npm install mcp-artisan ``` 2. In your environment's MCP server settings (e.g., in `.cursor-agent/mcp.json` or a similar configuration file), set up the server command as follows: * **Command**: `npx` * **Arguments**: `["mcp-artisan", "/path/to/your/project/workspace"]` Replace `/path/to/your/project/workspace` with the **absolute path** to the folder you want the AI to work in. This folder will be used to find prompts and save output files. **Example Configuration (`.cursor-agent/mcp.json`):** ```json { "mcpServers": { "my-artisan-tool": { "command": "npx", "args": [ "-y", "mcp-artisan", "/Users/username/my-ai-project" ] } } } ``` ## New API Reference ### listPrompts Lists available prompt files automatically. - **Parameters**: None - **Behavior**: Searches in `workspace/prompts/` first, falls back to workspace root - **Returns**: Array of prompt filenames ### getPromptContent Reads prompt file content by filename. - **Parameters**: - `promptFileName` (string): Just the filename, no path needed - **Behavior**: Automatically searches in prompts directory and workspace root ### saveHtml Saves HTML with automatic organization. - **Parameters**: - `htmlContent` (string): Complete HTML content - `subfolderName` (string, max 20 chars): Descriptive folder name - `fileName` (string): Filename without .html extension - **Output**: Saves to `workspace/output/{subfolderName}/{fileName}.html` ### renderImageFromHtml Renders HTML to image using relative paths. - **Parameters**: - `htmlPath` (string): Relative path from workspace (e.g., "output/my-card/index.html") - `imageType` (optional): 'png' or 'jpeg' - **Output**: Image saved alongside HTML file ## Migration from v1.x | v1.x Parameter | v2.x Parameter | Notes | |---|---|---| | `promptsPath` | *(removed)* | Auto-discovery in workspace | | `promptPath` | `promptFileName` | Just filename, no path | | `outputPath` | `subfolderName` | Auto-organized in output/ | | `htmlPath` (absolute) | `htmlPath` (relative) | Relative to workspace | ## Security Features - **Workspace Sandbox**: All file operations restricted to workspace - **Path Validation**: Prevents directory traversal (../) attacks - **Input Sanitization**: Validates filenames and folder names - **Symlink Protection**: Resolves real paths to prevent escapes ## Example Workflow ```bash # Start server with workspace npx mcp-artisan ./my-project # Directory structure will be: # my-project/ # ├── prompts/ # Your prompt files # │ ├── card.txt # │ └── banner.md # └── output/ # Generated files # └── my-cards/ # Organized by subfolder # ├── card.html # └── card.png ``` ## Development ```bash # Clone and install git clone <repo> cd mcp-artisan npm install # Build npm run build # Development with workspace npm run dev -- ./test-workspace ``` ## License MIT ## Contributing Issues and pull requests are welcome. Please ensure all tests pass before submitting. ```