Allyson MCP Server

npm version Node.js Version

Allyson MCP Server - AI-powered animation generator that transforms static files into animated SVG components using the Model Context Protocol (MCP).

🚀 Quick Start

Install MCP Server

Install and Run with npx

npx allyson-mcp --api-key YOUR_API_KEY

🔧 Configuration

Command Line Options

allyson-mcp [options]

Options:
  --api-key <key>     Your Allyson API key (required)
  --help              Show help message

Examples:
  allyson-mcp --api-key your-api-key-here
  API_KEY=your-key allyson-mcp

Environment Variables

You can also set your API key as an environment variable:

export API_KEY=your-api-key-here
allyson-mcp

🎯 Features

AI-Powered Animation Generation: Transform static images into animated SVG components
MCP Protocol Compatible: Works with any MCP-compatible AI assistant or tool
File Upload Support: Supports various image formats (PNG, JPG, SVG, etc.)
Custom Animation Prompts: Describe exactly what animation you want
Local File Processing: Reads files from your local filesystem
Automatic Output Generation: Saves animated components to specified paths

🛠 Available Tools

`generate_svg_animation`

Generates an animated SVG component from a source file and animation prompt.

Parameters:

prompt (string, required): Description of the animation to generate
- Example: "Make the character wave their hand"
- Example: "Add bouncing motion to the ball"
- Example: "Create a spinning effect for the logo"
svg_path (string, required): Absolute path to the source file
- Example: "/path/to/my-icon.svg"
output_path (string, required): Absolute path where to save the animated component
- Example: "/path/to/animated-component.tsx"

Example Usage in MCP Client:

{
  "tool": "generate_svg_animation",
  "arguments": {
    "prompt": "Make the logo glow and pulse gently",
    "svg_path": "/Users/john/Desktop/company-logo.svg",
    "output_path": "/Users/john/project/src/components/AnimatedLogo.tsx"
  }
}

🔌 Integration with AI Assistants

This MCP server is designed to work with AI assistants that support the Model Context Protocol, such as:

Claude Desktop (with MCP configuration)
Cursor IDE (with MCP integration)
Custom AI Applications (using MCP SDK)

MCP Configuration

{
  "mcpServers": {
    "allyson": {
      "command": "npx",
      "args": ["allyson-mcp", "--api-key", "YOUR_API_KEY"]
    }
  }
}

📝 Examples

Basic Animation Generation

# Start the server
allyson-mcp --api-key your-api-key

# The AI assistant can now use the tool:
# "Please animate this logo to have a subtle glow effect"
# File: /Users/john/logo.svg → /Users/john/animated-logo.tsx

🔐 Security

API Key Protection: Your API key is securely transmitted to the Allyson service
Local File Access: Only reads files you explicitly specify
No Data Storage: Files are processed and not stored on external servers
HTTPS Communication: All API communications use secure HTTPS

🐛 Troubleshooting

Common Issues

"API key is required" Error

# Solution: Provide API key via flag or environment variable
allyson-mcp --api-key YOUR_KEY
# or
export API_KEY=YOUR_KEY && allyson-mcp

"File not found" Error

# Make sure to use absolute paths
❌ Wrong: ./image.svg
✅ Correct: /Users/username/project/image.svg

"Cannot connect to animation API server" Error

Check your internet connection
Verify your API key is valid
Ensure the Allyson service is accessible

Permission Issues

# Make the file executable if needed
chmod +x node_modules/allyson-mcp/index.js

Debug Mode

For debugging, you can check the server logs which are output to stderr:

allyson-mcp --api-key YOUR_KEY 2> debug.log

📋 Requirements

Node.js: Version 18.0.0 or higher
API Key: Valid Allyson API key
Internet Connection: Required for API communication

🤝 Contributing

We welcome contributions! Please see our contributing guidelines for more details.