Allyson MCP Server
Allyson MCP Server - AI-powered animation generator that transforms static files into animated SVG components using the Model Context Protocol (MCP).
🚀 Quick Start
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.
📄 License
Apache-2.0 License - see LICENSE file for details.
🔗 Links
📞 Support
- Documentation: Check this README and inline help (
--help) - Issues: Report bugs on our GitHub Issues