@rafaylabs/animation-mcp 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdul Rafay (RafayLabs)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# @rafaylabs/animation-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **AI-Assisted On-Brand Lottie Animations & Code Generator** for Cursor, Claude Code, Windsurf, VS Code, and any Model Context Protocol (MCP) client.
+
+Ask your AI coding assistant for an animation in plain English, and get back an **on-brand, recolored Lottie file plus ready-to-paste framework code** directly in your project.
+
+---
+
+## ⚡ Quick Start
+
+### 1. Connect to Cursor / Claude Code / Windsurf
+
+Add this one-liner to your MCP settings file:
+
+#### For Cursor (`~/.cursor/mcp.json` or project `.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "rafaylabs-animation": {
+      "command": "npx",
+      "args": ["-y", "@rafaylabs/animation-mcp"]
+    }
+  }
+}
+```
+
+#### For Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "rafaylabs-animation": {
+      "command": "npx",
+      "args": ["-y", "@rafaylabs/animation-mcp"]
+    }
+  }
+}
+```
+
+#### For VS Code (Cline / Roo / Copilot MCP):
+```json
+{
+  "name": "rafaylabs-animation",
+  "command": "npx",
+  "args": ["-y", "@rafaylabs/animation-mcp"]
+}
+```
+
+---
+
+## 🔑 Sign in, trial and licence
+
+Searching and downloading from the catalogue needs a free account (GitHub sign-in). Theming your own local files works without signing in.
+
+```bash
+npx @rafaylabs/animation-mcp login
+```
+
+1. Open the link shown in your terminal and **Continue with GitHub**. We read only your public profile.
+2. Your **7-day free trial** starts on first sign-in (up to 50 searches and 20 downloads a day).
+3. Have a Lifetime licence key? Answer **y** and paste it. It is linked to your GitHub account (up to 2 devices).
+
+| Plan | Searches / day | Downloads / day |
+|---|---|---|
+| Trial (7 days) | 50 | 20 |
+| Free | 10 | 3 |
+| Lifetime licence | Unlimited | 500 |
+
+Limits are applied by the server and reset at 00:00 UTC. Theming of local files is always unlimited. Pricing: https://getrafaylabs.com/pricing
+
+### Project folder
+Files are only read from / written to your project folder (reported by your editor via MCP roots). If your editor does not report one, set `ANIMATION_MCP_ROOT` to the project path in the MCP config `env`.
+
+Check status anytime:
+```bash
+npx @rafaylabs/animation-mcp status
+```
+
+Sign out (and free this device's licence slot):
+```bash
+npx @rafaylabs/animation-mcp logout
+```
+
+---
+
+## 🛠️ MCP Tools Exposed
+
+| Tool | Description |
+|---|---|
+| `search_animations` | Search the 11,000+ animation catalogue using natural phrases (e.g. *"payment successful confetti"*, *"loading car delivery"*). Returns compact JSON with match scores and preview URLs. |
+| `get_animation` | Fetch full Lottie JSON and metadata for a specific catalogue ID. |
+| `apply_theme` | Recolor any animation into your brand colors (`primary`, `secondary`, `background`, `accent`) in perceptual OKLCH color space, keeping shadows and highlights intact. Works on catalogue items **or any local `.json` file in your project**. |
+| `save_animation` | Save the themed animation directly into your project directory (e.g. `assets/animations/success.json`). |
+| `get_code` | Generate ready-to-paste component code for **React**, **React Native (Expo)**, **Next.js**, or **HTML**. |
+
+---
+
+## 💬 What It Feels Like
+
+In your AI chat (Cursor / Claude Code):
+> *"Add a celebratory success animation to our checkout confirmation screen. Our theme is #0476FF and white, and this is an Expo React Native app."*
+
+Your AI agent automatically:
+1. Calls `search_animations` → finds high-scoring celebratory checkmarks.
+2. Calls `apply_theme` → recolors it to `#0476FF`.
+3. Calls `save_animation` → saves to `assets/animations/checkout-success.json`.
+4. Calls `get_code` → generates the exact `<LottieView />` React Native component with imports.
+5. Injects the code directly into your screen. You never leave your editor!
+
+---
+
+## 📜 License
+MIT © [Abdul Rafay / RafayLabs](https://getrafaylabs.com)

package/bin/cli.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+/**
+ * RafayLabs Animation MCP CLI
+ * Supports:
+ * - default (no args): Starts MCP stdio server for AI coding tools (Cursor, Claude, VS Code, Windsurf)
+ * - `animation-mcp login`: GitHub sign-in (device flow) + licence activation
+ * - `animation-mcp status`: Check daily quota and license tier
+ * - `animation-mcp logout`: Clear local session
+ */
+
+import { startMcpServer } from '../dist/index.js';
+import { runCliLogin, runCliStatus, runCliLogout } from '../dist/auth/cli-login.js';
+
+const command = process.argv[2];
+
+async function main() {
+  if (command === 'login') {
+    await runCliLogin();
+  } else if (command === 'status') {
+    await runCliStatus();
+  } else if (command === 'logout') {
+    const ok = await runCliLogout(process.argv.includes('--force'));
+    if (!ok) process.exitCode = 1;
+  } else if (command === '--help' || command === '-h' || command === 'help') {
+    console.log(`
+RafayLabs Animation MCP v1.0.1
+AI-driven on-brand Lottie animations and framework code generator.
+
+Usage:
+  npx @rafaylabs/animation-mcp          Start MCP server (stdio mode for AI agents)
+  npx @rafaylabs/animation-mcp login    Sign in with GitHub (starts your 7-day trial)
+  npx @rafaylabs/animation-mcp status   Check account tier and daily quota
+  npx @rafaylabs/animation-mcp logout   Sign out, free this device's licence activation (--force: sign out even if offline)
+    `);
+  } else {
+    // Default: Start MCP Server over stdio
+    try {
+      await startMcpServer();
+    } catch (err) {
+      console.error('Fatal MCP Server error:', err);
+      process.exit(1);
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error('Command failed:', err);
+  process.exit(1);
+});

package/dist/api/catalog-client.d.ts

@@ -0,0 +1,35 @@
+export interface CatalogSearchParams {
+    query: string;
+    category?: string;
+    style?: string;
+    loop?: boolean;
+    max_size_kb?: number;
+    limit?: number;
+    page?: number;
+}
+export interface CatalogSearchResultItem {
+    id: string;
+    title: string;
+    description: string;
+    category: string;
+    preview_url: string | null;
+    duration_seconds: number;
+    size_kb: string;
+    match_score: number;
+    themeable_score: number;
+}
+export interface CatalogSearchResult {
+    results: CatalogSearchResultItem[];
+    total: number;
+    page: number;
+    totalPages: number;
+    hasMore: boolean;
+}
+/**
+ * Searches the 11K+ hosted Lottie animation catalogue
+ */
+export declare function searchCatalog(params: CatalogSearchParams): Promise<CatalogSearchResult>;
+/**
+ * Downloads and caches a Lottie JSON animation from the catalogue by ID
+ */
+export declare function fetchAnimationById(id: string): Promise<Record<string, any>>;

package/dist/api/catalog-client.js

@@ -0,0 +1,78 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { serverFetch } from './server.js';
+/** Catalogue ids are used in file names and URLs, so only allow a safe character set. */
+const SAFE_ID = /^[A-Za-z0-9_-]{1,128}$/;
+const CACHE_DIR = path.join(os.homedir(), '.animation-mcp', 'cache');
+/**
+ * Searches the 11K+ hosted Lottie animation catalogue
+ */
+export async function searchCatalog(params) {
+    const limit = Math.min(params.limit || 5, 20);
+    const page = Math.max(1, Math.floor(params.page || 1));
+    const qs = new URLSearchParams({ search: params.query, limit: String(limit), page: String(page) });
+    if (params.category)
+        qs.set('category', params.category);
+    const res = await serverFetch(`/api/mcp/search?${qs.toString()}`);
+    if (!res.ok) {
+        throw new Error(`Catalogue search failed with HTTP status ${res.status}. Please try again in a moment.`);
+    }
+    const data = (await res.json());
+    const items = data.items || data.animations || [];
+    const results = items.map((item, idx) => {
+        const sizeBytes = item.file_size_bytes || item.size_bytes || 25000;
+        return {
+            id: String(item.id || item.slug),
+            title: item.name || item.title || 'Animated Icon',
+            description: item.description || `High quality ${item.category || 'vector'} animation`,
+            category: item.category || 'general',
+            preview_url: item.thumbnail_webp_url || item.preview_url || null,
+            duration_seconds: Number(item.duration_seconds || item.duration || 2.0),
+            size_kb: `${(sizeBytes / 1024).toFixed(1)} KB`,
+            // Real relevance from the server (0..1); older servers do not send it, so fall back to rank order.
+            match_score: typeof item.match_score === 'number' ? item.match_score : Number(Math.max(0, 1.0 - idx * 0.08).toFixed(2)),
+            themeable_score: 0.95,
+        };
+    });
+    const total = Number(data.total ?? results.length);
+    const totalPages = Number(data.totalPages ?? 1);
+    return {
+        results,
+        total,
+        page: Number(data.page ?? page),
+        totalPages,
+        hasMore: typeof data.has_more === 'boolean' ? data.has_more : page < totalPages,
+    };
+}
+/**
+ * Downloads and caches a Lottie JSON animation from the catalogue by ID
+ */
+export async function fetchAnimationById(id) {
+    if (!SAFE_ID.test(id)) {
+        throw new Error(`Invalid animation id "${id}". Use an id returned by search_animations.`);
+    }
+    // Ensure local cache directory exists
+    if (!fs.existsSync(CACHE_DIR)) {
+        fs.mkdirSync(CACHE_DIR, { recursive: true });
+    }
+    const cacheFile = path.join(CACHE_DIR, `${id}.json`);
+    if (fs.existsSync(cacheFile)) {
+        try {
+            return JSON.parse(fs.readFileSync(cacheFile, 'utf-8'));
+        }
+        catch (e) {
+            // Invalid cache, continue to fetch
+        }
+    }
+    const res = await serverFetch(`/api/mcp/download/${encodeURIComponent(id)}`, { timeoutMs: 30_000 });
+    if (res.status === 404) {
+        throw new Error(`Animation "${id}" was not found in the catalogue.`);
+    }
+    if (!res.ok) {
+        throw new Error(`Downloading animation "${id}" failed with HTTP status ${res.status}.`);
+    }
+    const json = (await res.json());
+    fs.writeFileSync(cacheFile, JSON.stringify(json), 'utf-8');
+    return json;
+}

package/dist/api/server.d.ts

@@ -0,0 +1,29 @@
+export declare const SERVER_URL: string;
+export declare class ServerError extends Error {
+    status: number;
+    code?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined);
+}
+/** Calls the RafayLabs server as the signed-in user. Turns 401/429 into messages the AI client can show as they are. */
+export declare function serverFetch(path: string, init?: {
+    method?: string;
+    body?: unknown;
+    timeoutMs?: number;
+}): Promise<Response>;
+export interface MeResponse {
+    github_login: string;
+    plan: 'paid' | 'trial' | 'free';
+    trial_days_left: number;
+    usage: {
+        searches: {
+            used: number;
+            limit: number | null;
+        };
+        downloads: {
+            used: number;
+            limit: number | null;
+        };
+        resetsAt: string;
+    };
+}
+export declare function fetchMe(): Promise<MeResponse>;

package/dist/api/server.js

@@ -0,0 +1,55 @@
+import { loadConfig } from '../auth/config.js';
+export const SERVER_URL = (process.env.ANIMATION_MCP_SERVER_URL || 'https://getrafaylabs.com').replace(/\/+$/, '');
+export class ServerError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+/** Calls the RafayLabs server as the signed-in user. Turns 401/429 into messages the AI client can show as they are. */
+export async function serverFetch(path, init = {}) {
+    const token = loadConfig().serverToken;
+    if (!token) {
+        throw new ServerError('You are not signed in. Run `npx @rafaylabs/animation-mcp login` in a terminal (it takes about 30 seconds, and your 7-day trial starts on first sign-in).', 401, 'unauthorized');
+    }
+    let res;
+    try {
+        res = await fetch(`${SERVER_URL}${path}`, {
+            method: init.method ?? 'GET',
+            headers: {
+                Accept: 'application/json',
+                Authorization: `Bearer ${token}`,
+                'X-Client': 'animation-mcp',
+                ...(init.body ? { 'Content-Type': 'application/json' } : {}),
+            },
+            body: init.body ? JSON.stringify(init.body) : undefined,
+            signal: AbortSignal.timeout(init.timeoutMs ?? 20_000),
+        });
+    }
+    catch (err) {
+        throw new ServerError(`Could not reach RafayLabs (${err.message}). Check your internet connection and try again.`, 0, 'network');
+    }
+    if (res.status === 401 || res.status === 429) {
+        let message = '';
+        let code;
+        try {
+            const j = await res.json();
+            message = j?.message ?? '';
+            code = j?.error;
+        }
+        catch {
+            /* ignore */
+        }
+        throw new ServerError(message || (res.status === 401 ? 'Please run `animation-mcp login`.' : 'Daily limit reached.'), res.status, code);
+    }
+    return res;
+}
+export async function fetchMe() {
+    const res = await serverFetch('/api/mcp/me');
+    if (!res.ok)
+        throw new ServerError(`Could not load your account (HTTP ${res.status}).`, res.status);
+    return (await res.json());
+}

package/dist/auth/cli-login.d.ts

@@ -0,0 +1,3 @@
+export declare function runCliLogin(): Promise<void>;
+export declare function runCliStatus(): Promise<void>;
+export declare function runCliLogout(force?: boolean): Promise<boolean>;

package/dist/auth/cli-login.js

@@ -0,0 +1,121 @@
+import readline from 'readline';
+import { loadConfig, saveConfig } from './config.js';
+import { deactivateLicense } from './client.js';
+import { deviceLogin } from './device-login.js';
+import { serverFetch, fetchMe } from '../api/server.js';
+function ask(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+function describePlan(me) {
+    if (me.plan === 'paid')
+        return 'LIFETIME';
+    if (me.plan === 'trial')
+        return `TRIAL (${me.trial_days_left} day${me.trial_days_left === 1 ? '' : 's'} left)`;
+    return 'FREE';
+}
+function fmtLimit(used, limit) {
+    return `${used} / ${limit === null ? 'unlimited' : limit} today`;
+}
+export async function runCliLogin() {
+    console.log('\n=================================================');
+    console.log('RafayLabs Animation MCP - Sign in with GitHub');
+    console.log('=================================================');
+    let login;
+    try {
+        login = await deviceLogin();
+    }
+    catch (err) {
+        console.error(`\n❌ ${err.message}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`\n✅ Signed in as ${login}.`);
+    const answer = await ask('\nDo you have a Lifetime licence key to activate? (y/N): ');
+    if (answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes') {
+        const key = await ask('🔑 Paste your licence key: ');
+        if (key) {
+            console.log('⏳ Activating...');
+            try {
+                const res = await serverFetch('/api/mcp/license/activate', { method: 'POST', body: { license_key: key }, timeoutMs: 30_000 });
+                const json = await res.json().catch(() => ({}));
+                if (!res.ok)
+                    console.error(`\n❌ ${json.message || `Activation failed (HTTP ${res.status}).`}`);
+                else
+                    console.log('\n🎉 Lifetime licence activated on your GitHub account.');
+            }
+            catch (err) {
+                console.error(`\n❌ ${err.message}`);
+            }
+        }
+    }
+    try {
+        const me = await fetchMe();
+        console.log(`\nPlan: ${describePlan(me)}`);
+        console.log(`Searches:  ${fmtLimit(me.usage.searches.used, me.usage.searches.limit)}`);
+        console.log(`Downloads: ${fmtLimit(me.usage.downloads.used, me.usage.downloads.limit)}`);
+    }
+    catch {
+        /* status is optional here */
+    }
+    console.log('\nYour MCP client (Cursor, Claude Code, Windsurf) can now use the catalogue.\n');
+}
+export async function runCliStatus() {
+    const config = loadConfig();
+    console.log('\n=======================================');
+    console.log('RafayLabs Animation MCP Status');
+    console.log('=======================================');
+    if (!config.serverToken) {
+        console.log('Not signed in. Run `animation-mcp login`.');
+        console.log('Theming of local files works without signing in.');
+        console.log('=======================================\n');
+        return;
+    }
+    try {
+        const me = await fetchMe();
+        console.log(`GitHub:     ${me.github_login}`);
+        console.log(`Plan:       ${describePlan(me)}`);
+        console.log(`Searches:   ${fmtLimit(me.usage.searches.used, me.usage.searches.limit)}`);
+        console.log(`Downloads:  ${fmtLimit(me.usage.downloads.used, me.usage.downloads.limit)}`);
+        console.log('Theming:    UNLIMITED (local files)');
+    }
+    catch (err) {
+        console.log(err.message);
+    }
+    console.log('=======================================\n');
+}
+export async function runCliLogout(force = false) {
+    const config = loadConfig();
+    // Free the Lemon Squeezy activation first, otherwise every logout + login would use up one of the device slots.
+    if (config.licenseKey && config.instanceId) {
+        const result = await deactivateLicense(config.licenseKey, config.instanceId);
+        if (!result.ok && !force) {
+            console.error(`\n❌ Could not free this device's licence activation: ${result.error}`);
+            console.error('You are still signed in. Check your connection and try again,');
+            console.error('or run `animation-mcp logout --force` to sign out anyway (the activation stays used until you remove it in your Lemon Squeezy order page or contact info@getrafaylabs.com).\n');
+            return false;
+        }
+        if (result.ok)
+            console.log('✅ This device was removed from your licence (activation freed).');
+    }
+    config.email = undefined;
+    config.licenseKey = undefined;
+    config.instanceId = undefined;
+    config.sig = undefined;
+    config.tier = 'free';
+    config.token = undefined;
+    config.serverToken = undefined;
+    config.githubLogin = undefined;
+    config.cachedUntil = undefined;
+    saveConfig(config);
+    console.log('\n🚪 Logged out. Session credentials cleared from ~/.animation-mcp/config.json.\n');
+    return true;
+}

package/dist/auth/client.d.ts

@@ -0,0 +1,45 @@
+import { UserConfig } from './config.js';
+import { ProductBinding } from './product.js';
+export interface VerifyLicenseResult {
+    valid: boolean;
+    tier: 'free' | 'lifetime';
+    email?: string;
+    instanceId?: string;
+    error?: string;
+}
+/**
+ * Activates a Lemon Squeezy licence key on this machine.
+ * Fails closed: any problem (network, wrong product, not configured) means "not licensed".
+ */
+export declare function verifyLicenseKey(key: string, instanceName?: string, expected?: ProductBinding): Promise<VerifyLicenseResult>;
+/**
+ * Decides whether this run is a paid one. Used by every quota-limited tool.
+ *  - A verified, unexpired, untampered cached licence counts.
+ *  - ANIMATION_MCP_KEY is only a way to *supply* a key: it is always checked with Lemon Squeezy.
+ *  - Anything else is the free tier.
+ */
+export declare function resolveLicense(expected?: ProductBinding): Promise<boolean>;
+/**
+ * Frees this machine's activation on Lemon Squeezy so the key can be used on another device.
+ * Returns ok:true when the activation is gone (or was already gone).
+ */
+export declare function deactivateLicense(key: string, instanceId: string): Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+/**
+ * Email magic-code sign-in. Requires the server endpoint; fails closed when it is missing.
+ */
+export declare function requestEmailMagicCode(email: string): Promise<{
+    success: boolean;
+    message: string;
+}>;
+/**
+ * Verifies a magic code with the server. The paid tier is granted only from a server
+ * response that carries a token; there is no local fallback.
+ */
+export declare function verifyEmailMagicCode(email: string, code: string): Promise<{
+    success: boolean;
+    config?: UserConfig;
+    error?: string;
+}>;