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

# 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:

    # Global installation
    npm install -g mcp-artisan

    # Or local project installation
    npm install mcp-artisan

1. 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`):

    {
      "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

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

# 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

# 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.