# Motion.dev MCP Server - Expected Output Specification
## Final Deliverable
A fully functional Model Context Protocol (MCP) server that provides comprehensive Motion.dev animation capabilities to AI assistants, enabling production-quality animation code generation across React, JavaScript, and Vue frameworks.
## Working MCP Server Requirements
### 1. Core Server Functionality
- **Executable MCP Server**: `npm start` launches a working server
- **Protocol Compliance**: Full MCP specification compliance with proper handshake
- **Client Integration**: Works seamlessly with Claude Code and other MCP clients
- **Error Handling**: Graceful error responses with helpful error messages
- **Logging**: Comprehensive logging for debugging and monitoring
### 2. Documentation Integration
- **Complete Coverage**: All Motion.dev documentation endpoints accessible
- **Real-time Fetching**: Live fetching from motion.dev with intelligent caching
- **Search Capabilities**: Full-text search across all documentation
- **Structured Data**: Parsed and structured documentation responses
- **Performance**: <2s response time for fresh fetches, <200ms for cached
### 3. MCP Tools Implementation
#### Documentation Tools (Must Work)
```typescript
// Tool: get_motion_docs
{
name: "get_motion_docs",
description: "Fetch Motion.dev documentation by URL or topic",
parameters: {
url: "/docs/react-animation",
format: "markdown", // markdown, json, raw
includeExamples: true,
includeApiRef: true
}
}
// Tool: search_motion_docs
{
name: "search_motion_docs",
description: "Search across all Motion.dev documentation",
parameters: {
query: "spring animations",
framework: "react", // optional: react, js, vue
category: "animations", // optional filter
limit: 10
}
}
// Tool: get_component_api
{
name: "get_component_api",
description: "Get API reference for Motion components",
parameters: {
component: "motion.div",
framework: "react",
includeProps: true,
includeExamples: true
}
}
// Tool: get_examples_by_category
{
name: "get_examples_by_category",
description: "Fetch code examples by animation category",
parameters: {
category: "scroll-animations",
framework: "react",
complexity: "intermediate", // basic, intermediate, advanced
format: "code-only" // code-only, with-explanation
}
}
```
#### Code Generation Tools (Must Work)
```typescript
// Tool: generate_motion_component
{
name: "generate_motion_component",
description: "Generate Motion component with animations",
parameters: {
framework: "react",
componentName: "FadeInButton",
animations: ["fadeIn", "hover", "tap"],
props: ["children", "onClick"],
typescript: true
}
}
// Tool: create_animation_sequence
{
name: "create_animation_sequence",
description: "Create complex animation timeline",
parameters: {
framework: "react",
sequence: [
{"element": "container", "animate": {"opacity": 1}, "delay": 0},
{"element": "title", "animate": {"y": 0}, "delay": 0.2}
],
stagger: true
}
}
// Tool: convert_between_frameworks
{
name: "convert_between_frameworks",
description: "Convert animations between frameworks",
parameters: {
from: "react",
to: "vue",
code: "<motion.div animate={{ x: 100 }} />",
preserveComments: true
}
}
// Tool: optimize_motion_code
{
name: "optimize_motion_code",
description: "Provide performance optimization suggestions",
parameters: {
code: "motion component code",
framework: "react",
focusAreas: ["performance", "accessibility", "bundle-size"]
}
}
// Tool: validate_motion_syntax
{
name: "validate_motion_syntax",
description: "Validate Motion code syntax and patterns",
parameters: {
code: "motion component code",
framework: "react",
strict: true
}
}
```
### 4. MCP Resources Implementation
#### Framework-Specific Resources (Must Work)
```typescript
// Resource: motion_react_docs
{
uri: "motion://docs/react",
name: "Motion React Documentation",
description: "Complete React Motion documentation and examples"
}
// Resource: motion_js_docs
{
uri: "motion://docs/js",
name: "Motion JavaScript Documentation",
description: "Vanilla JavaScript Motion documentation"
}
// Resource: motion_vue_docs
{
uri: "motion://docs/vue",
name: "Motion Vue Documentation",
description: "Vue Motion documentation and components"
}
// Resource: motion_examples
{
uri: "motion://examples",
name: "Motion Code Examples",
description: "Curated Motion code examples by category"
}
// Resource: motion_best_practices
{
uri: "motion://best-practices",
name: "Motion Best Practices",
description: "Performance and accessibility guidelines"
}
```
### 5. Expected File Structure (Final Output)
```
motion-dev-mcp/
├── README.md # Usage and setup guide
├── CLAUDE.md # Development guide
├── OUTPUT.md # This specification
├── package.json # All dependencies configured
├── tsconfig.json # TypeScript config
├── .gitignore # Proper ignore patterns
├── dist/ # Compiled JavaScript output
│ └── index.js # Main executable
├── src/
│ ├── index.ts # MCP server entry point ✅
│ ├── server.ts # FastMCP server setup ✅
│ ├── docs/
│ │ ├── fetcher.ts # Documentation fetcher ✅
│ │ ├── parser.ts # HTML/Markdown parser ✅
│ │ ├── cache.ts # Caching mechanism ✅
│ │ └── sitemap.ts # Sitemap processing ✅
│ ├── tools/
│ │ ├── docs-tools.ts # Documentation tools ✅
│ │ ├── generator-tools.ts # Code generation tools ✅
│ │ └── utility-tools.ts # Conversion and validation ✅
│ ├── resources/
│ │ ├── docs-resources.ts # Documentation resources ✅
│ │ └── examples-resources.ts # Example resources ✅
│ ├── types/
│ │ ├── motion.ts # Motion.dev type definitions ✅
│ │ ├── mcp.ts # MCP protocol types ✅
│ │ └── index.ts # Type exports ✅
│ └── utils/
│ ├── validators.ts # Input validation ✅
│ ├── formatters.ts # Response formatting ✅
│ └── errors.ts # Error handling ✅
├── docs/ # Cached documentation
│ ├── react/ # React docs cache
│ ├── js/ # JavaScript docs cache
│ ├── vue/ # Vue docs cache
│ └── examples/ # Examples cache
└── tests/ # Test suites
├── tools.test.ts # Tool tests
├── resources.test.ts # Resource tests
└── integration.test.ts # E2E tests
```
### 6. Functional Requirements
#### Server Startup
```bash
# Must work commands:
npm install # Install all dependencies
npm run build # Compile TypeScript
npm start # Start MCP server
npm test # Run test suite
npm run dev # Development mode with auto-reload
```
#### MCP Client Integration
```json
// Must work in Claude Code config:
{
"mcpServers": {
"motion-dev": {
"command": "node",
"args": ["./dist/index.js"],
"cwd": "/path/to/motion-dev-mcp"
}
}
}
```
#### Tool Response Examples
```typescript
// get_motion_docs response:
{
success: true,
data: {
title: "React Animation Guide",
content: "# Animation in React...", // Full markdown
examples: [...], // Code examples
apiReference: {...}, // API docs
lastUpdated: "2025-01-15"
}
}
// generate_motion_component response:
{
success: true,
data: {
component: `
import { motion } from "motion/react"
interface FadeInButtonProps {
children: React.ReactNode;
onClick: () => void;
}
export const FadeInButton: React.FC<FadeInButtonProps> = ({
children,
onClick
}) => {
return (
<motion.button
initial={{ opacity: 0 }}
animate={{ opacity: 1 }}
whileHover={{ scale: 1.05 }}
whileTap={{ scale: 0.95 }}
onClick={onClick}
className="px-4 py-2 rounded"
>
{children}
</motion.button>
)
}`,
imports: ["motion/react"],
dependencies: ["motion"],
typescript: true
}
}
```
### 7. Quality Standards
#### Code Quality
- **TypeScript**: 100% typed, no `any` types
- **Error Handling**: All edge cases handled gracefully
- **Performance**: Sub-second responses for common operations
- **Memory**: Efficient caching without memory leaks
- **Testing**: >90% code coverage
#### Documentation Quality
- **Accuracy**: All generated code must compile and run
- **Completeness**: Cover all Motion.dev features and APIs
- **Examples**: Production-ready examples, not demos
- **Framework Parity**: Equal quality across React/JS/Vue
#### MCP Compliance
- **Protocol**: Full MCP 1.0 specification compliance
- **Tools**: All tools properly registered and functional
- **Resources**: All resources accessible and performant
- **Errors**: Proper MCP error response format
### 8. Success Criteria
#### Functional Tests
- [ ] MCP server starts without errors
- [ ] All 9 tools respond correctly to valid inputs
- [ ] All 5 resources return proper data
- [ ] Documentation fetching works for all endpoints
- [ ] Code generation produces compilable code
- [ ] Framework conversion maintains functionality
- [ ] Caching improves performance as expected
#### Integration Tests
- [ ] Works with Claude Code client
- [ ] Handles concurrent requests properly
- [ ] Graceful failure on network issues
- [ ] Proper error messages for invalid inputs
- [ ] Session management works correctly
#### Performance Tests
- [ ] <200ms for cached documentation
- [ ] <2s for fresh documentation fetches
- [ ] <1s for code generation tools
- [ ] Handles 10+ concurrent requests
- [ ] Memory usage stable under load
### 9. Documentation Requirements
#### User Documentation
- **README.md**: Clear setup and usage instructions
- **API Reference**: Complete tool and resource documentation
- **Examples**: Working examples for each tool
- **Troubleshooting**: Common issues and solutions
#### Developer Documentation
- **Code Comments**: JSDoc for all public functions
- **Architecture**: System design documentation
- **Testing**: Test suite documentation
- **Contributing**: Development workflow guide
### 10. Deployment Ready
#### Package Configuration
```json
{
"name": "motion-dev-mcp",
"version": "1.0.0",
"description": "Motion.dev MCP Server",
"main": "dist/index.js",
"engines": {
"node": ">=18.0.0"
},
"scripts": {
"build": "tsc",
"start": "node dist/index.js",
"dev": "ts-node src/index.ts",
"test": "jest",
"lint": "eslint src/**/*.ts"
}
}
```
#### Production Readiness
- **Error Logging**: Comprehensive error tracking
- **Performance Monitoring**: Response time metrics
- **Health Checks**: Server health endpoints
- **Graceful Shutdown**: Proper cleanup on exit
- **Security**: Input validation and sanitization
---
## Validation Checklist
### ✅ Core Functionality
- [ ] MCP server executable via `npm start`
- [ ] All 9 tools implemented and working
- [ ] All 5 resources implemented and working
- [ ] Full Motion.dev documentation accessible
- [ ] Code generation produces valid, compilable code
### ✅ Quality Assurance
- [ ] TypeScript compilation with no errors
- [ ] Test suite passes with >90% coverage
- [ ] Performance benchmarks met
- [ ] Memory usage within acceptable limits
- [ ] Error handling comprehensive
### ✅ Integration
- [ ] Claude Code integration working
- [ ] MCP protocol compliance verified
- [ ] Documentation complete and accurate
- [ ] Examples functional and tested
**Final Success Metric**: An AI assistant using this MCP server can generate production-ready Motion animations for any React, JavaScript, or Vue project with proper documentation backing and framework-appropriate syntax.
