@rafaylabs/animation-mcp 1.0.0 → 1.0.1

package/bin/cli.js

@@ -24,7 +24,7 @@ async function main() {
     if (!ok) process.exitCode = 1;
   } else if (command === '--help' || command === '-h' || command === 'help') {
     console.log(`
-RafayLabs Animation MCP v1.0.0
+RafayLabs Animation MCP v1.0.1
 AI-driven on-brand Lottie animations and framework code generator.
 
 Usage:

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

@@ -5,6 +5,7 @@ export interface CatalogSearchParams {
     loop?: boolean;
     max_size_kb?: number;
     limit?: number;
+    page?: number;
 }
 export interface CatalogSearchResultItem {
     id: string;
@@ -17,10 +18,17 @@ export interface CatalogSearchResultItem {
     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<CatalogSearchResultItem[]>;
+export declare function searchCatalog(params: CatalogSearchParams): Promise<CatalogSearchResult>;
 /**
  * Downloads and caches a Lottie JSON animation from the catalogue by ID
  */

package/dist/api/catalog-client.js

@@ -10,7 +10,8 @@ const CACHE_DIR = path.join(os.homedir(), '.animation-mcp', 'cache');
  */
 export async function searchCatalog(params) {
     const limit = Math.min(params.limit || 5, 20);
-    const qs = new URLSearchParams({ search: params.query, limit: String(limit) });
+    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()}`);
@@ -19,7 +20,7 @@ export async function searchCatalog(params) {
     }
     const data = (await res.json());
     const items = data.items || data.animations || [];
-    return items.map((item, idx) => {
+    const results = items.map((item, idx) => {
         const sizeBytes = item.file_size_bytes || item.size_bytes || 25000;
         return {
             id: String(item.id || item.slug),
@@ -29,10 +30,20 @@ export async function searchCatalog(params) {
             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`,
-            match_score: Number((1.0 - idx * 0.08).toFixed(2)),
+            // 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

package/dist/index.js

@@ -14,7 +14,7 @@ import { SearchAnimationsArgsSchema, GetAnimationArgsSchema, ApplyThemeArgsSchem
 export async function startMcpServer() {
     const server = new Server({
         name: 'rafaylabs-animation-mcp',
-        version: '1.0.0',
+        version: '1.0.1',
     }, {
         capabilities: {
             tools: {},
@@ -26,7 +26,7 @@ export async function startMcpServer() {
             tools: [
                 {
                     name: 'search_animations',
-                    description: 'Search the RafayLabs catalogue of 11,000+ production Lottie animations using plain language (e.g. "success checkmark with confetti", "pulsing order delivery truck", "loading skeleton shimmer"). Returns short structured JSON with preview URLs, style, size, and category. Never returns raw Lottie JSON to save context window.',
+                    description: 'Search the RafayLabs catalogue of 11,000+ production Lottie animations using plain language (e.g. "success checkmark with confetti", "pulsing order delivery truck", "loading skeleton shimmer"). Results are ranked by relevance (match_score 0-1, 1 = closest). Returns short structured JSON with preview URLs, size, category, totalMatches and has_more. If nothing fits, call again with the next page or with different keywords. Never returns raw Lottie JSON to save context window.',
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -52,9 +52,14 @@ export async function startMcpServer() {
                             },
                             limit: {
                                 type: 'number',
-                                description: 'Maximum number of results to return (default 5)',
+                                description: 'Results per page, 1-20 (default 5)',
                                 default: 5,
                             },
+                            page: {
+                                type: 'number',
+                                description: 'Page of results (default 1). Use the next page when has_more is true and nothing fits yet',
+                                default: 1,
+                            },
                         },
                         required: ['query'],
                     },

package/dist/tools/schemas.d.ts

@@ -6,8 +6,10 @@ export declare const SearchAnimationsArgsSchema: z.ZodObject<{
     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;
@@ -16,6 +18,7 @@ export declare const SearchAnimationsArgsSchema: z.ZodObject<{
 }, {
     query: string;
     limit?: number | undefined;
+    page?: number | undefined;
     category?: string | undefined;
     style?: string | undefined;
     loop?: boolean | undefined;

package/dist/tools/schemas.js

@@ -6,6 +6,7 @@ export const SearchAnimationsArgsSchema = z.object({
     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 _'),

package/dist/tools/search.d.ts

@@ -7,8 +7,10 @@ export declare const SearchAnimationsSchema: z.ZodObject<{
     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;
@@ -17,6 +19,7 @@ export declare const SearchAnimationsSchema: z.ZodObject<{
 }, {
     query: string;
     limit?: number | undefined;
+    page?: number | undefined;
     category?: string | undefined;
     style?: string | undefined;
     loop?: boolean | undefined;
@@ -26,4 +29,7 @@ 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

@@ -6,17 +6,25 @@ export const SearchAnimationsSchema = z.object({
     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('Maximum number of results to return (default 5)'),
+    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 results = await searchCatalog({
+    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, totalMatches: results.length };
+    return {
+        results: found.results,
+        totalMatches: found.total,
+        page: found.page,
+        totalPages: found.totalPages,
+        has_more: found.hasMore,
+    };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafaylabs/animation-mcp",
-  "version": "1.0.0",
+  "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",