@rafaylabs/animation-mcp 0.0.0-stage → 1.0.1

package/dist/tools/schemas.d.ts

@@ -0,0 +1,140 @@
+import { z } from 'zod';
+export declare const SearchAnimationsArgsSchema: z.ZodObject<{
+    query: z.ZodString;
+    style: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    loop: z.ZodOptional<z.ZodBoolean>;
+    max_size_kb: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    page: number;
+    query: string;
+    category?: string | undefined;
+    style?: string | undefined;
+    loop?: boolean | undefined;
+    max_size_kb?: number | undefined;
+}, {
+    query: string;
+    limit?: number | undefined;
+    page?: number | undefined;
+    category?: string | undefined;
+    style?: string | undefined;
+    loop?: boolean | undefined;
+    max_size_kb?: number | undefined;
+}>;
+export declare const GetAnimationArgsSchema: z.ZodObject<{
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+}, {
+    id: string;
+}>;
+export declare const ApplyThemeArgsSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    file_path: z.ZodOptional<z.ZodString>;
+    lottie_json: z.ZodOptional<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodAny>, z.ZodString]>>;
+    output_path: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodEnum<["json", "lottie"]>>;
+    overwrite: z.ZodOptional<z.ZodBoolean>;
+    theme: z.ZodObject<{
+        primary: z.ZodString;
+        secondary: z.ZodOptional<z.ZodString>;
+        background: z.ZodOptional<z.ZodString>;
+        accent: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        primary: string;
+        secondary?: string | undefined;
+        background?: string | undefined;
+        accent?: string | undefined;
+    }, {
+        primary: string;
+        secondary?: string | undefined;
+        background?: string | undefined;
+        accent?: string | undefined;
+    }>;
+    mode: z.ZodOptional<z.ZodEnum<["light", "dark"]>>;
+}, "strip", z.ZodTypeAny, {
+    theme: {
+        primary: string;
+        secondary?: string | undefined;
+        background?: string | undefined;
+        accent?: string | undefined;
+    };
+    mode?: "light" | "dark" | undefined;
+    id?: string | undefined;
+    lottie_json?: string | Record<string, any> | undefined;
+    format?: "json" | "lottie" | undefined;
+    file_path?: string | undefined;
+    output_path?: string | undefined;
+    overwrite?: boolean | undefined;
+}, {
+    theme: {
+        primary: string;
+        secondary?: string | undefined;
+        background?: string | undefined;
+        accent?: string | undefined;
+    };
+    mode?: "light" | "dark" | undefined;
+    id?: string | undefined;
+    lottie_json?: string | Record<string, any> | undefined;
+    format?: "json" | "lottie" | undefined;
+    file_path?: string | undefined;
+    output_path?: string | undefined;
+    overwrite?: boolean | undefined;
+}>;
+export declare const SaveAnimationArgsSchema: z.ZodObject<{
+    themed_json: z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodAny>, z.ZodString]>;
+    path: z.ZodString;
+    format: z.ZodOptional<z.ZodEnum<["json", "lottie"]>>;
+    overwrite: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    themed_json: string | Record<string, any>;
+    format?: "json" | "lottie" | undefined;
+    overwrite?: boolean | undefined;
+}, {
+    path: string;
+    themed_json: string | Record<string, any>;
+    format?: "json" | "lottie" | undefined;
+    overwrite?: boolean | undefined;
+}>;
+export declare const GetCodeArgsSchema: z.ZodObject<{
+    framework: z.ZodEnum<["react", "react-native", "nextjs", "html"]>;
+    file_path: z.ZodString;
+    options: z.ZodOptional<z.ZodObject<{
+        loop: z.ZodOptional<z.ZodBoolean>;
+        autoplay: z.ZodOptional<z.ZodBoolean>;
+        size: z.ZodOptional<z.ZodNumber>;
+        componentName: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        loop?: boolean | undefined;
+        autoplay?: boolean | undefined;
+        size?: number | undefined;
+        componentName?: string | undefined;
+    }, {
+        loop?: boolean | undefined;
+        autoplay?: boolean | undefined;
+        size?: number | undefined;
+        componentName?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    file_path: string;
+    framework: "react" | "react-native" | "nextjs" | "html";
+    options?: {
+        loop?: boolean | undefined;
+        autoplay?: boolean | undefined;
+        size?: number | undefined;
+        componentName?: string | undefined;
+    } | undefined;
+}, {
+    file_path: string;
+    framework: "react" | "react-native" | "nextjs" | "html";
+    options?: {
+        loop?: boolean | undefined;
+        autoplay?: boolean | undefined;
+        size?: number | undefined;
+        componentName?: string | undefined;
+    } | undefined;
+}>;

package/dist/tools/schemas.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+export const SearchAnimationsArgsSchema = z.object({
+    query: z.string().min(1, 'Search query cannot be empty'),
+    style: z.string().optional(),
+    category: z.string().optional(),
+    loop: z.boolean().optional(),
+    max_size_kb: z.number().positive().optional(),
+    limit: z.number().int().min(1).max(20).optional().default(5),
+    page: z.number().int().min(1).max(50).optional().default(1),
+});
+export const GetAnimationArgsSchema = z.object({
+    id: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/, 'Animation ID may only contain letters, numbers, - and _'),
+});
+const HexColorRegex = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+export const ApplyThemeArgsSchema = z.object({
+    id: z.string().regex(/^[A-Za-z0-9_-]{1,128}$/, 'Animation ID may only contain letters, numbers, - and _').optional(),
+    file_path: z.string().optional(),
+    lottie_json: z.union([z.record(z.any()), z.string()]).optional(),
+    output_path: z.string().optional(),
+    format: z.enum(['json', 'lottie']).optional(),
+    overwrite: z.boolean().optional(),
+    theme: z.object({
+        primary: z.string().regex(HexColorRegex, 'Primary color must be a valid hex string (e.g. #0476FF)'),
+        secondary: z.string().regex(HexColorRegex, 'Secondary color must be a valid hex string').optional(),
+        background: z.string().regex(HexColorRegex, 'Background color must be a valid hex string').optional(),
+        accent: z.string().regex(HexColorRegex, 'Accent color must be a valid hex string').optional(),
+    }),
+    mode: z.enum(['light', 'dark']).optional(),
+});
+export const SaveAnimationArgsSchema = z.object({
+    themed_json: z.union([z.record(z.any()), z.string()], {
+        required_error: 'themed_json is required',
+    }),
+    path: z.string().min(1, 'Target file path is required'),
+    format: z.enum(['json', 'lottie']).optional(),
+    overwrite: z.boolean().optional(),
+});
+export const GetCodeArgsSchema = z.object({
+    framework: z.enum(['react', 'react-native', 'nextjs', 'html'], {
+        errorMap: () => ({ message: 'Framework must be one of: react, react-native, nextjs, html' }),
+    }),
+    file_path: z.string().min(1, 'file_path is required'),
+    options: z
+        .object({
+        loop: z.boolean().optional(),
+        autoplay: z.boolean().optional(),
+        size: z.number().positive().optional(),
+        componentName: z.string().optional(),
+    })
+        .optional(),
+});

package/dist/tools/search.d.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { CatalogSearchResultItem } from '../api/catalog-client.js';
+export declare const SearchAnimationsSchema: z.ZodObject<{
+    query: z.ZodString;
+    style: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodString>;
+    loop: z.ZodOptional<z.ZodBoolean>;
+    max_size_kb: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    page: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    page: number;
+    query: string;
+    category?: string | undefined;
+    style?: string | undefined;
+    loop?: boolean | undefined;
+    max_size_kb?: number | undefined;
+}, {
+    query: string;
+    limit?: number | undefined;
+    page?: number | undefined;
+    category?: string | undefined;
+    style?: string | undefined;
+    loop?: boolean | undefined;
+    max_size_kb?: number | undefined;
+}>;
+export type SearchAnimationsInput = z.infer<typeof SearchAnimationsSchema>;
+export declare function handleSearchAnimations(input: SearchAnimationsInput): Promise<{
+    results: CatalogSearchResultItem[];
+    totalMatches: number;
+    page: number;
+    totalPages: number;
+    has_more: boolean;
+}>;

package/dist/tools/search.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { searchCatalog } from '../api/catalog-client.js';
+export const SearchAnimationsSchema = z.object({
+    query: z.string().min(1, 'Please provide search keywords, e.g. "checkmark", "loading spinner", or "successful payment"'),
+    style: z.string().optional().describe('Visual style: flat, 3d, minimal, gradient, outline'),
+    category: z.string().optional().describe('Animation category: success, loading, error, empty state, onboarding, ecommerce'),
+    loop: z.boolean().optional().describe('Whether the animation should continuously loop'),
+    max_size_kb: z.number().optional().describe('Maximum allowed file size in KB'),
+    limit: z.number().min(1).max(20).default(5).describe('Results per page, 1-20 (default 5)'),
+    page: z.number().int().min(1).max(50).default(1).describe('Page of results (default 1). Ask for the next page when has_more is true and nothing fits yet'),
+});
+export async function handleSearchAnimations(input) {
+    // Sign-in, plan and daily limits are enforced by the server; it answers 401/429 with a clear message.
+    const found = await searchCatalog({
+        query: input.query,
+        category: input.category,
+        style: input.style,
+        loop: input.loop,
+        max_size_kb: input.max_size_kb,
+        limit: input.limit,
+        page: input.page,
+    });
+    return {
+        results: found.results,
+        totalMatches: found.total,
+        page: found.page,
+        totalPages: found.totalPages,
+        has_more: found.hasMore,
+    };
+}

package/dist/tools/theme.d.ts

@@ -0,0 +1,28 @@
+import { UserTheme, ThemingResult } from '../theming/engine.js';
+export interface ApplyThemeInput {
+    id?: string;
+    lottie_json?: Record<string, any> | string;
+    file_path?: string;
+    output_path?: string;
+    format?: 'json' | 'lottie';
+    overwrite?: boolean;
+    theme: UserTheme;
+    mode?: 'light' | 'dark';
+}
+export interface ApplyThemeSummaryResult {
+    success: boolean;
+    colorMap: ThemingResult['colorMap'];
+    themeableScore: number;
+    totalColorsCount: number;
+    hasRasterImages: boolean;
+    savedPath?: string;
+    absolutePath?: string;
+    sizeBytes?: number;
+    sizeKb?: string;
+    format?: 'json' | 'lottie';
+    note?: string;
+}
+/**
+ * Handles apply_theme tool execution
+ */
+export declare function executeApplyTheme(input: ApplyThemeInput, server?: any): Promise<ApplyThemeSummaryResult>;

package/dist/tools/theme.js

@@ -0,0 +1,66 @@
+import fs from 'fs';
+import { applyThemeToLottie } from '../theming/engine.js';
+import { fetchAnimationById } from '../api/catalog-client.js';
+import { resolveSafePath } from '../utils/workspace.js';
+import { saveAnimationToProject } from './save.js';
+import { readLottieFile } from '../utils/lottie-file.js';
+/**
+ * Handles apply_theme tool execution
+ */
+export async function executeApplyTheme(input, server) {
+    let lottieData = null;
+    // 1. From local file in user's workspace
+    if (input.file_path) {
+        const { absolutePath } = await resolveSafePath(input.file_path, { server });
+        if (!fs.existsSync(absolutePath)) {
+            throw new Error(`Animation file not found at path: ${input.file_path}`);
+        }
+        lottieData = readLottieFile(absolutePath);
+    }
+    // 2. From direct JSON input
+    if (!lottieData && input.lottie_json) {
+        lottieData =
+            typeof input.lottie_json === 'string'
+                ? JSON.parse(input.lottie_json)
+                : input.lottie_json;
+    }
+    // 3. From hosted catalogue ID
+    if (!lottieData && input.id) {
+        lottieData = await fetchAnimationById(input.id);
+    }
+    if (!lottieData) {
+        throw new Error('Please provide either `file_path`, `lottie_json`, or a catalogue `id`.');
+    }
+    // Apply theme
+    const themingResult = applyThemeToLottie(lottieData, input.theme, { mode: input.mode });
+    // If output_path is provided, save directly to project workspace
+    if (input.output_path) {
+        const saveResult = await saveAnimationToProject({
+            themed_json: themingResult.themedLottie,
+            path: input.output_path,
+            format: input.format,
+            overwrite: input.overwrite,
+        }, server);
+        return {
+            success: true,
+            colorMap: themingResult.colorMap,
+            themeableScore: themingResult.themeableScore,
+            totalColorsCount: themingResult.totalColorsCount,
+            hasRasterImages: themingResult.hasRasterImages,
+            savedPath: saveResult.savedPath,
+            absolutePath: saveResult.absolutePath,
+            sizeBytes: saveResult.sizeBytes,
+            sizeKb: saveResult.sizeKb,
+            format: saveResult.format,
+        };
+    }
+    // If output_path is omitted
+    return {
+        success: true,
+        colorMap: themingResult.colorMap,
+        themeableScore: themingResult.themeableScore,
+        totalColorsCount: themingResult.totalColorsCount,
+        hasRasterImages: themingResult.hasRasterImages,
+        note: 'Theming succeeded! Specify "output_path" (e.g. "assets/hero.json" or "assets/hero.lottie") to write directly to your project without filling AI context.',
+    };
+}

package/dist/utils/lottie-file.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Reads a local animation file. Accepts plain Lottie JSON and dotLottie (.lottie)
+ * containers (v1 `animations/<id>.json` and v2 `a/<id>.json` layouts).
+ */
+export declare function readLottieFile(absolutePath: string): Record<string, any>;

package/dist/utils/lottie-file.js

@@ -0,0 +1,47 @@
+import fs from 'fs';
+import { unzipSync, strFromU8 } from 'fflate';
+/**
+ * Reads a local animation file. Accepts plain Lottie JSON and dotLottie (.lottie)
+ * containers (v1 `animations/<id>.json` and v2 `a/<id>.json` layouts).
+ */
+export function readLottieFile(absolutePath) {
+    const buf = fs.readFileSync(absolutePath);
+    // ZIP magic number "PK" -> dotLottie container
+    if (buf.length > 4 && buf[0] === 0x50 && buf[1] === 0x4b) {
+        let files;
+        try {
+            files = unzipSync(new Uint8Array(buf));
+        }
+        catch (err) {
+            throw new Error(`Failed to unzip .lottie file: ${err.message}`);
+        }
+        let entry;
+        if (files['manifest.json']) {
+            try {
+                const manifest = JSON.parse(strFromU8(files['manifest.json']));
+                const id = manifest?.animations?.[0]?.id;
+                if (id) {
+                    entry = [`animations/${id}.json`, `a/${id}.json`].find((p) => files[p]);
+                }
+            }
+            catch {
+                // fall through to scan
+            }
+        }
+        entry ??= Object.keys(files).find((p) => /^(animations|a)\/[^/]+\.json$/.test(p));
+        if (!entry)
+            throw new Error('No animation found inside the .lottie file.');
+        try {
+            return JSON.parse(strFromU8(files[entry]));
+        }
+        catch (err) {
+            throw new Error(`Failed to parse animation inside .lottie file: ${err.message}`);
+        }
+    }
+    try {
+        return JSON.parse(buf.toString('utf-8'));
+    }
+    catch (err) {
+        throw new Error(`Failed to parse local JSON file: ${err.message}`);
+    }
+}

package/dist/utils/workspace.d.ts

@@ -0,0 +1,20 @@
+export declare function setProjectRoot(root: string | null): void;
+export declare function getProjectRoot(): string | null;
+/** Returns every root the client reports (empty if unsupported). */
+export declare function getClientRoots(server?: any): Promise<string[]>;
+/** Kept for backwards compatibility: first client root, or null. */
+export declare function getClientProjectRoot(server?: any): Promise<string | null>;
+export interface ResolvePathOptions {
+    server?: any;
+    projectRoot?: string | null;
+}
+/** True when `child` is `parent` itself or inside it (no `..` escape). */
+export declare function isInside(parent: string, child: string): boolean;
+/**
+ * Resolves a user/AI supplied path to an absolute path that is guaranteed to stay
+ * inside the project root (symlinks included).
+ */
+export declare function resolveSafePath(targetPath: string, options?: ResolvePathOptions): Promise<{
+    absolutePath: string;
+    projectRoot: string | null;
+}>;

package/dist/utils/workspace.js

@@ -0,0 +1,116 @@
+import { fileURLToPath } from 'url';
+import fs from 'fs';
+import path from 'path';
+/**
+ * Project-root resolution and path safety for every tool that reads or writes files.
+ *
+ * Root sources, in order of priority:
+ *   1. ANIMATION_MCP_ROOT env var (explicit override, for clients without `roots/list`)
+ *   2. The roots the MCP client reports through `roots/list` (re-read on every call,
+ *      so switching workspaces in the editor is picked up)
+ *   3. Nothing -> relative paths are refused; absolute paths are only allowed
+ *      inside the server's current working directory.
+ */
+let rootsUnsupported = false;
+let manualRoot = null;
+export function setProjectRoot(root) {
+    manualRoot = root;
+}
+export function getProjectRoot() {
+    return manualRoot;
+}
+function uriToPath(uri) {
+    try {
+        if (uri.startsWith('file://'))
+            return fileURLToPath(uri);
+    }
+    catch {
+        return null;
+    }
+    return path.isAbsolute(uri) ? uri : null;
+}
+/** Returns every root the client reports (empty if unsupported). */
+export async function getClientRoots(server) {
+    if (rootsUnsupported || !server || typeof server.listRoots !== 'function')
+        return [];
+    try {
+        const response = await server.listRoots();
+        return (response?.roots ?? [])
+            .map((r) => uriToPath(r.uri))
+            .filter((p) => !!p);
+    }
+    catch {
+        // Client does not implement the roots capability: do not ask again.
+        rootsUnsupported = true;
+        return [];
+    }
+}
+/** Kept for backwards compatibility: first client root, or null. */
+export async function getClientProjectRoot(server) {
+    const roots = await getClientRoots(server);
+    return roots[0] ?? null;
+}
+/** True when `child` is `parent` itself or inside it (no `..` escape). */
+export function isInside(parent, child) {
+    const rel = path.relative(parent, child);
+    return rel === '' || (!rel.startsWith('..' + path.sep) && rel !== '..' && !path.isAbsolute(rel));
+}
+/** realpath of the deepest existing ancestor + the not-yet-existing remainder. */
+function realpathLoose(p) {
+    const missing = [];
+    let current = p;
+    for (;;) {
+        try {
+            const real = fs.realpathSync(current);
+            return missing.length ? path.join(real, ...missing.reverse()) : real;
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                return p;
+            missing.push(path.basename(current));
+            current = parent;
+        }
+    }
+}
+/**
+ * Resolves a user/AI supplied path to an absolute path that is guaranteed to stay
+ * inside the project root (symlinks included).
+ */
+export async function resolveSafePath(targetPath, options) {
+    const trimmed = targetPath.trim();
+    if (!trimmed)
+        throw new Error('Path cannot be empty.');
+    if (trimmed.includes('\0'))
+        throw new Error('Path contains an invalid character.');
+    let roots = [];
+    if (options?.projectRoot)
+        roots = [options.projectRoot];
+    else if (process.env.ANIMATION_MCP_ROOT)
+        roots = [path.resolve(process.env.ANIMATION_MCP_ROOT)];
+    else if (manualRoot)
+        roots = [manualRoot];
+    else
+        roots = await getClientRoots(options?.server);
+    const isAbs = path.isAbsolute(trimmed);
+    if (roots.length === 0) {
+        if (!isAbs) {
+            throw new Error(`Relative path "${trimmed}" provided, but no project root was detected from your MCP client. ` +
+                `Provide an absolute path inside your project, or set the ANIMATION_MCP_ROOT environment variable in your MCP config.`);
+        }
+        // No root known: only allow absolute paths inside the folder the server was started in.
+        roots = [process.cwd()];
+    }
+    const candidate = isAbs ? path.normalize(trimmed) : null;
+    // For absolute paths pick the root that contains it; for relative ones use the first root.
+    const root = candidate
+        ? roots.find((r) => isInside(realpathLoose(r), realpathLoose(candidate))) ?? roots[0]
+        : roots[0];
+    const resolved = candidate ?? path.resolve(root, trimmed);
+    const realRoot = realpathLoose(root);
+    const realTarget = realpathLoose(resolved);
+    if (!isInside(realRoot, realTarget)) {
+        throw new Error(`Access denied: path "${trimmed}" resolves outside project root "${root}".`);
+    }
+    return { absolutePath: resolved, projectRoot: root };
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@rafaylabs/animation-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "type": "module",
+  "description": "On-brand Lottie animations and framework code inside your AI coding assistant (Cursor, Claude Code, Windsurf, VS Code)",
+  "main": "dist/index.js",
+  "bin": {
+    "animation-mcp": "./bin/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "start": "node bin/cli.js",
+    "test": "tsc && node --test",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "lottie",
+    "animation",
+    "ai",
+    "cursor",
+    "claude-code",
+    "react",
+    "react-native",
+    "nextjs",
+    "theming"
+  ],
+  "author": "Abdul Rafay <info@getrafaylabs.com> (https://getrafaylabs.com)",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "commander": "^12.1.0",
+    "fflate": "^0.8.3",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://getrafaylabs.com/animation-mcp",
+  "bugs": {
+    "email": "info@getrafaylabs.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}