# MOTUS/MCP — Design System Reference Engine for Motion Graphics

> An interactive style guide, boilerplate library, and template assembler for AI agents building professional motion graphics with GSAP + SVG. Think of it as a specialized design system — not a magic prompt-to-video black box.

- **Website**: https://www.motusmcp.tools
- **Documentation**: https://www.motusmcp.tools/docs
- **Discord**: https://discord.gg/3qwXMAst
- **Status**: Phase 1 — Core Pipeline (In Development)

## What is MOTUS/MCP?

MOTUS/MCP is a **Design System Reference Engine** for motion graphics. It provides a proprietary, **layered knowledge base** and pre-built scene templates that AI agents use to assemble professional videos with GSAP + SVG.

**Core value:** The structured knowledge base — exact hex codes, GSAP easing functions, SVG filter definitions, layout rules, animation patterns, and gotchas. This is what makes MOTUS/MCP indispensable. The `generate_video_project` tool is a **fast-path template assembler** — it selects and stitches together relevant pre-built templates based on your prompt keywords. It is NOT a generative AI that creates original art from scratch.

**CRITICAL:** The MOTUS/MCP knowledge base is intentionally **fragmented across tools**. No single tool gives you a complete working video. Each tool provides one layer (structure, colors, animation code, styling, filters, transitions). You MUST call multiple tools in sequence to assemble a project. Attempting to build scenes from scratch will produce inferior results and violate the visual style system.

## How It Works

1. **Learn the System** — Call knowledge-base tools to get the exact design rules, colors, animation patterns, and gotchas.
2. **Assemble Scenes** — Use scene templates as blueprints. Each template gives you structure + animation code with placeholders.
3. **Fast Path (Optional)** — Call `generate_video_project(prompt)` to get a pre-assembled video using keyword-matched templates. This skips manual assembly but uses the same template library.
4. **Browser Rendering** — Preview and edit in your browser, then export as a video file.

## MCP Server Architecture (Interdependent Layers)

MOTUS/MCP exposes 13 tools that each provide **one layer** of the video production stack:

| Tool | Layer | Cost |
|------|-------|------|
| `get_color_palette` | **Colors** — Official hex values referenced as `{{palette.*}}` placeholders | 1 request |
| `list_transitions` | **Transition catalog** — List of available transitions | 1 request |
| `list_scene_templates` | **Template catalog** — List of scene templates with build complexity | 1 request |
| `validate_scene` | **Quality assurance** — Validates structure + GSAP + performance | 3 requests |
| `get_editing_rules` | **Principles** — Pacing, rhythm, gotchas (concepts, NOT code) | 5 requests |
| `get_animation_patterns` | **Animation engine** — Exact GSAP code for draw_in, scale_in, fade_in, camera | 5 requests |
| `get_scene_boilerplate` | **Scene skeleton** — HTML structure with color placeholders | 5 requests |
| `get_complete_boilerplate` | **Project skeleton** — Full index.html with NO scenes (infrastructure only) | 5 requests |
| `get_style_system` | **Design system** — Complete CSS, typography, spacing for a visual style | 5 requests |
| `get_transition_pattern` | **Transition implementation** — Exact GSAP code for scene changes | 15 requests |
| `get_scene_template` | **Scene blueprint** — Structure + animation code with placeholders (requires 3-6 other calls) | 25 requests |
| `get_dom_structure` | **Infrastructure** — HTML hierarchy, SVG filters, CSS classes (call per part) | 25 requests |
| `generate_video_project` | **Pre-assembled video** — Complete HTML with scenes pre-built (fast path) | 25 requests |

### Why the Knowledge Base is Fragmented

Each tool provides a **specialized layer**. Scene templates use `{{palette.*}}` placeholders that only `get_color_palette()` can resolve. Animation comments reference `get_animation_patterns()`. SVG filters are defined in `get_dom_structure(part="filters")`. This design ensures visual consistency — you cannot accidentally use wrong colors or broken animations because the system enforces dependencies.

**Building a single scene requires 4-6 tool calls minimum.**
**Building a full video requires 8-15 tool calls.**

### Quick Start for AI Agents (Mandatory Multi-Call Workflow)

1. Get an API key from https://www.motusmcp.tools/pricing or Discord.
2. Configure the MCP server: `MOTUSMCP_API_KEY=mk_your-key npx motusmcp`
3. Call `get_editing_rules(section="all")` for the proprietary style principles.
4. Call `get_color_palette()` to get hex values (templates reference these).
5. Call `get_dom_structure(part="css")` for base styling.
6. Call `get_dom_structure(part="filters")` for SVG effects.
7. Call `get_scene_template(template_id)` for each scene you need.
8. Replace all `{{palette.*}}` placeholders using the palette from step 4.
9. Call `get_animation_patterns(pattern_type)` for each animation type used.
10. Call `get_transition_pattern(transition_id)` for scene changes.
11. Assemble everything into the boilerplate from `get_complete_boilerplate()`.
12. Call `validate_scene(scene_html)` before finalizing.

**Fast path:** Call `generate_video_project(prompt="your idea", style="parchment|dark")` to get a pre-assembled video using keyword-matched templates. This analyzes your prompt for keywords (space, documentary, finance, tech, etc.) and assembles the best-fitting templates into a complete HTML file. It is NOT generative AI — it is a smart template selector + assembler.

### Authentication

All access to MOTUS/MCP requires an API key. Buy one at https://www.motusmcp.tools/pricing or get free keys in Discord.

### MCP Server (for AI clients)

```bash
MOTUSMCP_API_KEY=mk_your-key npx motusmcp
```

Claude Desktop / Cursor / Windsurf / OpenCode config:

```json
{
  "mcpServers": {
    "motusmcp": {
      "command": "npx",
      "args": ["-y", "motusmcp"],
      "env": {
        "MOTUSMCP_API_KEY": "mk_your-api-key"
      }
    }
  }
}
```

### SDK (for developers)

```bash
npm install motusmcp gsap
```

```javascript
import { createMotusMCP, Renderer } from 'motusmcp';

const mcp = createMotusMCP({ apiKey: 'mk_your-api-key' });

const rules = await mcp.getEditingRules();
const templates = await mcp.listSceneTemplates();
const palette = await mcp.getColorPalette();

const renderer = new Renderer({
  container: '#video-container',
  width: 1920,
  height: 1080,
  fps: 60,
});

renderer
  .addScene({ id: 'scene-1', html: '<div>...</div>', duration: 5 })
  .addTransition({ type: 'smash-cut' });

await renderer.build();
await renderer.downloadVideo('my-video.webm');
```

## Scene Templates

All templates are **fragmented blueprints** that require multiple tool calls to resolve:

- `title-scene` — Cinematic title card with subtitle (requires: palette + css + fade_in) = **3 calls**
- `orbit-scene` — Orbital rings with nodes (requires: palette + css + draw_in + stagger) = **4 calls**
- `narration-scene` — Documentary quote/narration text (requires: palette + css + fade_in) = **3 calls**
- `graph-scene` — Bar chart (requires: palette + css + filters + 3 animation patterns) = **6 calls**
- `anatomy-scene` — Exploded view diagram (requires: palette + css + 2 animation patterns) = **4 calls**
- `phone-scroll-scene` — Mobile UI scroll (requires: palette + css + draw_in + gotchas) = **4 calls**
- `car-anatomy-scene` — Vehicle breakdown (requires: palette + css + draw_in + gotchas) = **4 calls**
- `globe-scene` — Rotating globe (requires: palette + css + scale_in + stagger) = **4 calls**
- `quantum-scene` — Abstract physics (requires: palette + css + stagger + mindset) = **4 calls**
- `counter-scene` — Animated counter (requires: palette + css + scale_in) = **3 calls**

## Transitions

- `smash-cut` — Dramatic hard cut with text reveal
- `pan-smooth` — Gentle horizontal camera pan between scenes
- `jump-cut` — Quick rhythmic cuts for high energy

## Color Palette

- **Ink**: #000000 — Background, shadows
- **Paper**: #F4F1EA — Text, highlights
- **Blueprint**: #1E3A8A — Accents, data lines
- **Crimson**: #DC2626 — Alerts, emphasis
- **Gold**: #F59E0B — Premium elements

## Style Systems

- `parchment-blueprint` — Vintage technical drawing aesthetic
- `dark-minimal` — Modern dark mode with red accents
- `neon-cyber` — Cyberpunk neon glow aesthetic
- `swiss-modern` — Clean Swiss typography grid

## Pricing

| Pack | Requests | Price |
|------|----------|-------|
| Starter | 3,000 | $10 |
| Pro | 30,000 | $29 |
| Mega | 100,000 | $79 |

Free API keys (100-500 requests) are dropped regularly in Discord.

## Architecture

```
User/Client
    |
    v
[motusmcp SDK]  (npm package, TypeScript)
    |
    |  Authorization: Bearer mk_...
    v
[mcp_proxy]  (Appwrite Function — auth, rate limiting, cost tracking)
    |
    |  X-Appwrite-Key + X-Appwrite-Project
    v
[ai_video_editor_mcp]  (Appwrite Function — MCP server)
    |
    |  Fetches fragmented KB from private Appwrite Storage at runtime
    v
[motusmcp-kb bucket]  (private encrypted storage — rules, DOM, templates, transitions, CSS)
```

## Technology Stack

- **Frontend**: React, Tailwind CSS, GSAP
- **Backend**: Appwrite Cloud Functions
- **Protocol**: Model Context Protocol (MCP) via JSON-RPC 2.0
- **Rendering**: Browser-based (MediaRecorder API for video export)
- **Target Output**: 4K at 60fps

## Roadmap

- **Phase 1** (Now): Core Pipeline — Prompt → Scene Planning → Animation Code → Rendered Video
- **Phase 2** (Next): Design Intelligence — Style generation, asset creation, premium effects
- **Phase 3** (After): Editorial Brain — Pacing, rhythm, story structure
- **Phase 4** (Future): Pro Layer — DaVinci Resolve export, layered project handoff
- **Phase 5** (Future): Data Layer — CSV to Cinematic

## License

MIT

## Contact

- Discord: https://discord.gg/3qwXMAst
- Website: https://www.motusmcp.tools