@lottiefiles/creator-mcp 0.1.1

package/README.md

@@ -0,0 +1,279 @@
+# @lottiefiles/creator-mcp
+
+[![npm version](https://img.shields.io/npm/v/@lottiefiles/creator-mcp.svg?style=flat-square)](https://www.npmjs.com/package/@lottiefiles/creator-mcp)
+
+Let AI control [LottieFiles Creator](https://creator.lottiefiles.com) — build and edit
+Lottie animations through natural language.
+
+<!-- TODO: Add demo GIF showing AI assistant controlling Creator -->
+
+[Getting Started](#getting-started) | [Example Prompts](#example-prompts)
+
+---
+
+## What It Does
+
+This MCP server connects AI assistants like Claude, Cursor, and Windsurf to the
+[LottieFiles Creator](https://creator.lottiefiles.com) animation editor. Your AI gets full
+access to the Creator API — it can read, modify, and create animations on your behalf.
+
+- **Read & modify animation properties** — colors, transforms, opacity, timing
+- **Create shapes, layers, and keyframes** programmatically
+- **Inspect animation structure** — list layers, examine keyframes, export data
+- **Full Creator API access** — anything Creator can do, your AI can do
+
+## Getting Started
+
+### Prerequisites
+
+- **Node.js** 18 or later
+- **LottieFiles Creator** open in your browser at
+  [creator.lottiefiles.com](https://creator.lottiefiles.com)
+
+### Install
+
+[![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&logo=visualstudiocode&logoColor=ffffff)](https://vscode.dev/redirect/mcp/install?name=%40lottiefiles%2Fcreator-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40lottiefiles%2Fcreator-mcp%22%5D%7D)
+[![Install in VS Code Insiders](https://img.shields.io/badge/Install_in-VS_Code_Insiders-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=ffffff)](https://insiders.vscode.dev/redirect/mcp/install?name=%40lottiefiles%2Fcreator-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40lottiefiles%2Fcreator-mcp%22%5D%7D&quality=insiders)
+[![Install in Cursor](https://img.shields.io/badge/Install_in-Cursor-000000?style=flat-square&logo=cursor&logoColor=ffffff)](https://cursor.com/install-mcp?name=lottiefiles-creator&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBsb3R0aWVmaWxlcy9jcmVhdG9yLW1jcCJdfQ==)
+
+Add the following config to your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "lottiefiles-creator": {
+      "command": "npx",
+      "args": ["-y", "@lottiefiles/creator-mcp@latest"]
+    }
+  }
+}
+```
+
+### MCP Client configuration
+
+<details>
+<summary><strong>Amp</strong></summary>
+
+```bash
+amp mcp add lottiefiles-creator -- npx -y @lottiefiles/creator-mcp@latest
+```
+
+</details>
+
+<details>
+<summary><strong>Antigravity</strong></summary>
+
+Follow Antigravity's MCP setup docs and use the config above.
+
+</details>
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+```bash
+claude mcp add lottiefiles-creator -- npx -y @lottiefiles/creator-mcp@latest
+```
+
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Use the config above in your `claude_desktop_config.json`.
+
+</details>
+
+<details>
+<summary><strong>Cline</strong></summary>
+
+Follow Cline's MCP setup docs and use the config above.
+
+</details>
+
+<details>
+<summary><strong>Codex</strong></summary>
+
+Follow the [configure MCP guide](https://github.com/openai/codex/blob/main/docs/config.md)
+using:
+
+```toml
+[mcp_servers.lottiefiles-creator]
+command = "npx"
+args = ["-y", "@lottiefiles/creator-mcp@latest"]
+```
+
+Or add via CLI:
+
+```bash
+codex mcp add lottiefiles-creator -- npx -y @lottiefiles/creator-mcp@latest
+```
+
+</details>
+
+<details>
+<summary><strong>Copilot CLI</strong></summary>
+
+1. Start `copilot`
+2. Run `/mcp add`
+3. Configure:
+
+- Server name: `lottiefiles-creator`
+- Server type: `Local`
+- Command: `npx -y @lottiefiles/creator-mcp@latest`
+
+</details>
+
+<details>
+<summary><strong>Copilot / VS Code</strong></summary>
+
+Follow VS Code MCP setup docs and use the config above.
+
+Or via CLI:
+
+```bash
+code --add-mcp '{"name":"lottiefiles-creator","command":"npx","args":["-y","@lottiefiles/creator-mcp@latest"]}'
+```
+
+</details>
+
+<details>
+<summary><strong>Copilot / GitHub CLI</strong></summary>
+
+```bash
+gh copilot mcp add lottiefiles-creator -- npx -y @lottiefiles/creator-mcp@latest
+```
+
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Click the install button above, or use the config above.
+
+</details>
+
+<details>
+<summary><strong>Factory CLI</strong></summary>
+
+```bash
+droid mcp add lottiefiles-creator "npx -y @lottiefiles/creator-mcp@latest"
+```
+
+</details>
+
+<details>
+<summary><strong>Gemini CLI</strong></summary>
+
+```bash
+gemini mcp add lottiefiles-creator npx -y @lottiefiles/creator-mcp@latest
+gemini mcp add -s user lottiefiles-creator npx -y @lottiefiles/creator-mcp@latest
+```
+
+</details>
+
+<details>
+<summary><strong>Gemini Code Assist</strong></summary>
+
+Follow Gemini Code Assist MCP setup docs and use the config above.
+
+</details>
+
+<details>
+<summary><strong>JetBrains AI Assistant & Junie</strong></summary>
+
+Follow JetBrains MCP setup docs and use the config above.
+
+</details>
+
+<details>
+<summary><strong>Kiro</strong></summary>
+
+Follow Kiro MCP setup docs and use the config above.
+
+</details>
+
+<details>
+<summary><strong>Qoder</strong></summary>
+
+Follow Qoder MCP setup docs and use the config above.
+
+</details>
+
+<details>
+<summary><strong>Visual Studio</strong></summary>
+
+Add a local MCP server with:
+
+- Name: `lottiefiles-creator`
+- Command: `npx`
+- Arguments: `-y @lottiefiles/creator-mcp@latest`
+
+</details>
+
+<details>
+<summary><strong>Warp</strong></summary>
+
+Follow Warp MCP setup docs and use the config above.
+
+</details>
+
+<details>
+<summary><strong>Windsurf</strong></summary>
+
+Follow Windsurf MCP setup docs and use the config above.
+
+</details>
+
+<details>
+<summary><strong>VS Code</strong></summary>
+
+If using `.vscode/mcp.json`, use:
+
+```json
+{
+  "servers": {
+    "lottiefiles-creator": {
+      "command": "npx",
+      "args": ["-y", "@lottiefiles/creator-mcp@latest"]
+    }
+  }
+}
+```
+
+</details>
+
+### Your first prompt
+
+1. Open [LottieFiles Creator](https://creator.lottiefiles.com).
+2. Enable MCP in Creator.
+3. Keep that tab open while using your AI assistant.
+
+Ask your assistant:
+
+```text
+Run a script that logs the active scene size in lottiefiles creator
+```
+
+If setup is correct, you should see a tool response with scene dimensions.
+
+## Example Prompts
+
+Once connected, try asking your AI assistant:
+
+| Prompt                                         | What it does                                     |
+| ---------------------------------------------- | ------------------------------------------------ |
+| "What layers are in this animation?"           | Lists all layers with their types and properties |
+| "Change the background color to blue"          | Modifies the background layer color              |
+| "List all keyframes on the first layer"        | Inspects keyframe data for a specific layer      |
+| "Make the animation loop smoothly"             | Adjusts timing and easing for seamless looping   |
+| "Center all selected layers in the scene"      | Aligns selected layers to scene center           |
+| "Change all fills to a neon cyan palette"      | Batch-updates colors across shapes               |
+| "Create a pulsing loading spinner"             | Builds a looped shape animation                  |
+| "Offset each layer by 3 frames"                | Staggers layer timing for motion rhythm          |
+| "Remove hidden layers from this scene"         | Cleans up invisible and unused layers            |
+| "Round all rectangle corners to 16"            | Applies consistent corner radius styling         |
+| "List every text layer and its content"        | Extracts text content for copy review            |
+| "Duplicate this scene and make a dark variant" | Creates an alternate themed scene                |
+| "Create a 2-second intro with logo fade-in"    | Generates timeline-based intro animation         |
+
+<!-- TODO: Add screenshot showing example prompt and Creator result side-by-side -->

package/dist/index.mjs

@@ -0,0 +1,492 @@
+#!/usr/bin/env node
+import { WebSocketServer } from "ws";
+import { randomUUID } from "crypto";
+import { z } from "zod";
+import { createRequire } from "module";
+import { Console } from "node:console";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { onExit } from "signal-exit";
+import eos from "end-of-stream";
+
+//#region ../creator-mcp-shared/src/constants.ts
+/** Default WebSocket port used by the MCP bridge. */
+const DEFAULT_WS_PORT = 3847;
+/** WebSocket host (localhost only for security). */
+const WS_HOST = "127.0.0.1";
+/** Full WebSocket URL for the MCP bridge. */
+const WS_URL = `ws://${WS_HOST}:${DEFAULT_WS_PORT}`;
+/** Custom close code: another tab is already connected. */
+const WS_CLOSE_ANOTHER_TAB = 4001;
+/** Canonical tool name for the run_script MCP tool. */
+const RUN_SCRIPT_TOOL_NAME = "run_script";
+/** Canonical tool description for the run_script MCP tool. */
+const RUN_SCRIPT_TOOL_DESCRIPTION = `Execute a JavaScript script in the LottieFiles Creator animation editor. The script runs in a sandboxed runtime with access to the \`creator\` global object (the Creator API) for reading and manipulating animations, layers, shapes, keyframes, colors, and more. Use console.log() to output results — all console output is captured and returned.
+
+IMPORTANT: Before calling this tool, you MUST call these tools (once per session):
+1. get_api_doc — The API type definitions (paginated, read ALL pages). The Creator API is unique and cannot be guessed.
+2. get_rules — Conventions like layer ordering that affect visual correctness.
+
+Skipping these tools will lead to TypeError and incorrect scripts. Call them first, then write your script.`;
+/** Canonical tool name for the get_api_doc MCP tool. */
+const GET_API_DOC_TOOL_NAME = "get_api_doc";
+/** Lines per page for paginated get_api_doc responses. */
+const API_DOC_PAGE_SIZE = 1e3;
+/** Canonical tool description for the get_api_doc MCP tool. */
+const GET_API_DOC_TOOL_DESCRIPTION = `Get the TypeScript type definitions for the Creator API. The API is large, so results are paginated (~1000 lines per page). Call with page=1 first, then continue calling with each subsequent page number until all pages are read.
+
+YOU MUST read ALL pages before writing any scripts with run_script. The Creator API is unique and cannot be guessed from common patterns. Skipping pages will cause TypeErrors and incorrect scripts.`;
+/** Canonical tool name for the get_rules MCP tool. */
+const GET_RULES_TOOL_NAME = "get_rules";
+/** Canonical tool description for the get_rules MCP tool. */
+const GET_RULES_TOOL_DESCRIPTION = "Get the rules and conventions for writing Creator scripts. YOU MUST call this tool before writing scripts to avoid common pitfalls like incorrect layer ordering.";
+/** Canonical MCP setup guide URL. */
+const MCP_GUIDE_URL = "https://lottiefiles.notion.site/lottie-creator-mcp";
+/** Message returned when a script produces no console output. */
+const NO_RETURN_VALUE_MESSAGE = "(Script executed successfully, no console output)";
+
+//#endregion
+//#region ../creator-mcp-shared/src/schemas.ts
+/** Zod schema for validating incoming ScriptRequest messages over WebSocket. */
+const scriptRequestSchema = z.object({
+	id: z.string(),
+	type: z.literal("run_script"),
+	script: z.string()
+});
+/** Zod schema for validating ScriptResponse messages over WebSocket. */
+const scriptResponseSchema = z.object({
+	type: z.literal("script_response"),
+	id: z.string(),
+	logs: z.array(z.string()),
+	error: z.string().optional()
+});
+
+//#endregion
+//#region ../creator-mcp-shared/src/resources.ts
+/** Path to the Creator API type definitions, relative to the Creator origin. */
+const TYPES_RESOURCE = { path: "/mcp-resources/types.d.ts" };
+/** Path to the Creator scripting rules, relative to the Creator origin. */
+const RULES_RESOURCE = { path: "/mcp-resources/rules.md" };
+
+//#endregion
+//#region ../creator-mcp-shared/src/format-tool-result.ts
+/** Format script execution logs and optional error into an MCP tool result. */
+function formatToolResult(logs, error) {
+	if (error) return {
+		content: [{
+			type: "text",
+			text: logs.length > 0 ? `${logs.join("\n")}\n\nError: ${error}` : `Error: ${error}`
+		}],
+		isError: true
+	};
+	return { content: [{
+		type: "text",
+		text: logs.length > 0 ? logs.join("\n") : NO_RETURN_VALUE_MESSAGE
+	}] };
+}
+/** Paginate a large text document and return a single page with navigation hints. */
+function paginateText(text, page, toolName, pageSize = API_DOC_PAGE_SIZE) {
+	const lines = text.split("\n");
+	const totalPages = Math.ceil(lines.length / pageSize);
+	if (page < 1 || page > totalPages) return { content: [{
+		type: "text",
+		text: `Invalid page ${page}. The document has ${totalPages} pages.`
+	}] };
+	const start = (page - 1) * pageSize;
+	const pageLines = lines.slice(start, start + pageSize);
+	const header = `[Page ${page} of ${totalPages}]`;
+	const footer = page < totalPages ? `\n\n[End of page ${page}/${totalPages} — IMPORTANT: You MUST call ${toolName} with page=${page + 1} to continue reading. Do NOT write scripts until you have read ALL pages.]` : `\n\n[End of page ${page}/${totalPages} — You have read the complete API documentation.]`;
+	return { content: [{
+		type: "text",
+		text: `${header}\n\n${pageLines.join("\n")}${footer}`
+	}] };
+}
+
+//#endregion
+//#region src/constants.ts
+const pkg = createRequire(import.meta.url)("../package.json");
+const PACKAGE_NAME = pkg.name;
+const PACKAGE_VERSION = pkg.version;
+const env = z.object({
+	CREATOR_URL: z.string().url().default("https://creator.lottiefiles.com"),
+	WS_PORT: z.coerce.number().int().min(1).max(65535).default(3847),
+	SCRIPT_TIMEOUT_MS: z.coerce.number().int().min(1e3).max(3e5).default(6e4)
+}).parse(process.env);
+const CREATOR_URL = env.CREATOR_URL;
+const WS_PORT = env.WS_PORT;
+const PING_INTERVAL_MS = 5e3;
+const SCRIPT_TIMEOUT_MS = env.SCRIPT_TIMEOUT_MS;
+const WEBSOCKET_SERVER_UNAVAILABLE_MESSAGE = "Creator MCP bridge is unavailable in this session. Another Creator MCP server may already be running in a different app or terminal. Stop other Creator MCP servers, then restart this one.";
+const NO_CREATOR_CONNECTED_MESSAGE = `No Creator tab is connected. Open LottieFiles Creator at ${CREATOR_URL} in your browser and enable MCP. If you need setup help, see ${MCP_GUIDE_URL}`;
+
+//#endregion
+//#region src/logger.ts
+const prefix = `[${PACKAGE_NAME.replace("@", "").replace("/", "-")}]`;
+/**
+* MCP-safe logger that follows the Console API.
+*
+* All output goes to stderr so it never conflicts with the MCP stdio
+* transport on stdout. Messages are automatically prefixed with the
+* package name.
+*/
+var Logger = class extends Console {
+	constructor() {
+		super({
+			stdout: process.stderr,
+			stderr: process.stderr
+		});
+	}
+	log(...args) {
+		super.log(prefix, ...args);
+	}
+	info(...args) {
+		super.info(prefix, ...args);
+	}
+	warn(...args) {
+		super.warn(prefix, ...args);
+	}
+	error(...args) {
+		super.error(prefix, ...args);
+	}
+	debug(...args) {
+		super.debug(prefix, ...args);
+	}
+};
+const logger = new Logger();
+
+//#endregion
+//#region src/websocket-server.ts
+const allowedOrigin = new URL(CREATOR_URL).origin;
+var ConnectionManager = class {
+	_wss = null;
+	_activeConnection = null;
+	_pendingRequests = /* @__PURE__ */ new Map();
+	_pingInterval = null;
+	_isWebSocketReady = false;
+	async start(port = DEFAULT_WS_PORT) {
+		return new Promise((resolve, reject) => {
+			this._wss = new WebSocketServer({
+				port,
+				host: WS_HOST,
+				maxPayload: 10 * 1024 * 1024
+			});
+			this._wss.on("listening", () => {
+				logger.info(`WebSocket server listening on ${WS_HOST}:${port}`);
+				this._isWebSocketReady = true;
+				this._startPingInterval();
+				resolve();
+			});
+			this._wss.on("error", (error) => {
+				this._isWebSocketReady = false;
+				if (error.code === "EADDRINUSE") logger.error(`Port ${port} is already in use`);
+				reject(error);
+			});
+			this._wss.on("close", () => {
+				this._isWebSocketReady = false;
+			});
+			this._wss.on("connection", (ws, req) => {
+				if (req.headers.origin !== allowedOrigin) {
+					logger.warn(`Rejected connection from origin: ${req.headers.origin}`);
+					ws.close(1008, "Origin not allowed");
+					return;
+				}
+				if (this._activeConnection) {
+					logger.warn("Rejected connection: another tab is already connected");
+					ws.close(WS_CLOSE_ANOTHER_TAB, "Another tab is already connected");
+					return;
+				}
+				const id = randomUUID();
+				this._activeConnection = {
+					id,
+					ws,
+					isAlive: true
+				};
+				logger.info(`Tab connected (id: ${id})`);
+				ws.on("pong", () => {
+					if (this._activeConnection?.id === id) this._activeConnection.isAlive = true;
+				});
+				ws.on("message", (data) => {
+					try {
+						const parsed = JSON.parse(data.toString());
+						const result = scriptResponseSchema.safeParse(parsed);
+						if (!result.success) {
+							logger.warn("Received message with unexpected shape:", JSON.stringify(parsed));
+							return;
+						}
+						this._handleMessage(result.data);
+					} catch (error) {
+						logger.error("Failed to parse message:", error);
+					}
+				});
+				ws.on("close", () => {
+					this._handleDisconnect();
+				});
+				ws.on("error", () => {
+					this._handleDisconnect();
+				});
+			});
+		});
+	}
+	_handleMessage(message) {
+		if (message.type !== "script_response") return;
+		const pending = this._pendingRequests.get(message.id);
+		if (!pending) {
+			logger.warn(`Received response for unknown request id: ${message.id}`);
+			return;
+		}
+		clearTimeout(pending.timer);
+		this._pendingRequests.delete(message.id);
+		pending.resolve(message);
+	}
+	_handleDisconnect() {
+		if (!this._activeConnection) return;
+		const { id } = this._activeConnection;
+		this._activeConnection = null;
+		for (const [reqId, pending] of this._pendingRequests) {
+			clearTimeout(pending.timer);
+			pending.reject(/* @__PURE__ */ new Error("Creator tab disconnected during script execution"));
+			this._pendingRequests.delete(reqId);
+		}
+		logger.info(`Tab disconnected (id: ${id})`);
+	}
+	_startPingInterval() {
+		this._pingInterval = setInterval(() => {
+			const conn = this._activeConnection;
+			if (!conn) return;
+			if (!conn.isAlive) {
+				logger.warn(`Tab unresponsive, terminating (id: ${conn.id})`);
+				conn.ws.terminate();
+				this._handleDisconnect();
+				return;
+			}
+			conn.isAlive = false;
+			conn.ws.ping();
+		}, PING_INTERVAL_MS);
+	}
+	get hasActiveConnection() {
+		return this._activeConnection !== null;
+	}
+	get isWebSocketReady() {
+		return this._isWebSocketReady;
+	}
+	async executeScript(script) {
+		if (!this._activeConnection) throw new Error(NO_CREATOR_CONNECTED_MESSAGE);
+		const conn = this._activeConnection;
+		const id = randomUUID();
+		const request = {
+			id,
+			type: "run_script",
+			script
+		};
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this._pendingRequests.delete(id);
+				reject(/* @__PURE__ */ new Error(`Script execution timed out after ${SCRIPT_TIMEOUT_MS / 1e3}s`));
+			}, SCRIPT_TIMEOUT_MS);
+			this._pendingRequests.set(id, {
+				resolve,
+				reject,
+				timer
+			});
+			try {
+				conn.ws.send(JSON.stringify(request));
+			} catch (error) {
+				clearTimeout(timer);
+				this._pendingRequests.delete(id);
+				reject(/* @__PURE__ */ new Error(`Failed to send script to Creator: ${error instanceof Error ? error.message : String(error)}`));
+			}
+		});
+	}
+	stop() {
+		if (this._pingInterval) {
+			clearInterval(this._pingInterval);
+			this._pingInterval = null;
+		}
+		for (const [, pending] of this._pendingRequests) {
+			clearTimeout(pending.timer);
+			pending.reject(/* @__PURE__ */ new Error("Server shutting down"));
+		}
+		this._pendingRequests.clear();
+		if (this._activeConnection) {
+			this._activeConnection.ws.close();
+			this._activeConnection = null;
+		}
+		this._wss?.close();
+		this._wss = null;
+		this._isWebSocketReady = false;
+	}
+};
+
+//#endregion
+//#region src/tools/run-script.ts
+async function handleRunScript(connectionManager, script) {
+	if (!connectionManager.isWebSocketReady) return {
+		content: [{
+			type: "text",
+			text: WEBSOCKET_SERVER_UNAVAILABLE_MESSAGE
+		}],
+		isError: true
+	};
+	if (!connectionManager.hasActiveConnection) return {
+		content: [{
+			type: "text",
+			text: NO_CREATOR_CONNECTED_MESSAGE
+		}],
+		isError: true
+	};
+	try {
+		const response = await connectionManager.executeScript(script);
+		return formatToolResult(response.logs, response.error);
+	} catch (error) {
+		return {
+			content: [{
+				type: "text",
+				text: error instanceof Error ? error.message : String(error)
+			}],
+			isError: true
+		};
+	}
+}
+
+//#endregion
+//#region src/mcp-server.ts
+async function fetchCreatorText(resourcePath) {
+	const url = `${CREATOR_URL}${resourcePath}`;
+	const response = await fetch(url);
+	if (!response.ok) throw new Error(`Failed to fetch ${url}: HTTP ${response.status}`);
+	return response.text();
+}
+function textResult(text) {
+	return { content: [{
+		type: "text",
+		text
+	}] };
+}
+async function startMcpServer(connectionManager) {
+	const server = new McpServer({
+		name: PACKAGE_NAME,
+		version: PACKAGE_VERSION
+	});
+	server.registerTool(RUN_SCRIPT_TOOL_NAME, {
+		title: "Run Script in Creator",
+		description: RUN_SCRIPT_TOOL_DESCRIPTION,
+		inputSchema: { script: z.string().describe("JavaScript code to execute. Use console.log() to output results.") },
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false,
+			openWorldHint: false
+		}
+	}, async ({ script }) => {
+		return handleRunScript(connectionManager, script);
+	});
+	server.registerTool(GET_API_DOC_TOOL_NAME, {
+		title: "Get Creator API Documentation",
+		description: GET_API_DOC_TOOL_DESCRIPTION,
+		inputSchema: { page: z.number().int().min(1).default(1).describe("Page number (1-indexed). Start with 1 and keep calling until all pages are read.") },
+		annotations: {
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async ({ page }) => {
+		try {
+			return paginateText(await fetchCreatorText(TYPES_RESOURCE.path), page, GET_API_DOC_TOOL_NAME);
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: error instanceof Error ? error.message : String(error)
+				}],
+				isError: true
+			};
+		}
+	});
+	server.registerTool(GET_RULES_TOOL_NAME, {
+		title: "Get Creator Script Rules",
+		description: GET_RULES_TOOL_DESCRIPTION,
+		annotations: {
+			readOnlyHint: true,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		}
+	}, async () => {
+		try {
+			return textResult(await fetchCreatorText(RULES_RESOURCE.path));
+		} catch (error) {
+			return {
+				content: [{
+					type: "text",
+					text: error instanceof Error ? error.message : String(error)
+				}],
+				isError: true
+			};
+		}
+	});
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	logger.info("MCP server started on stdio");
+}
+
+//#endregion
+//#region src/index.ts
+function setupShutdownHandlers(connectionManager) {
+	let isCleanedUp = false;
+	const cleanup = (reason) => {
+		if (isCleanedUp) return;
+		isCleanedUp = true;
+		logger.info(`Shutting down Creator MCP (${reason})`);
+		try {
+			connectionManager.stop();
+		} catch (error) {
+			logger.error("Failed during shutdown:", error);
+		}
+	};
+	onExit((code, signal) => {
+		cleanup(signal ?? `exit code ${code ?? 0}`);
+	});
+	eos(process.stdin, (error) => {
+		if (error) {
+			logger.error("stdin stream closed with error:", error);
+			cleanup("stdin error");
+			process.exit(1);
+		}
+		cleanup("stdin closed");
+		process.exit(0);
+	});
+	process.once("uncaughtException", (error) => {
+		logger.error("Uncaught exception:", error);
+		cleanup("uncaughtException");
+		process.exit(1);
+	});
+	process.once("unhandledRejection", (reason) => {
+		logger.error("Unhandled promise rejection:", reason);
+		cleanup("unhandledRejection");
+		process.exit(1);
+	});
+}
+async function main() {
+	const connectionManager = new ConnectionManager();
+	setupShutdownHandlers(connectionManager);
+	try {
+		await connectionManager.start(WS_PORT);
+	} catch (error) {
+		if (error.code === "EADDRINUSE") {
+			logger.error(`Port ${WS_PORT} is already in use. Another instance may be running.`);
+			logger.error("Starting in limited mode (MCP server only, no WebSocket).");
+		} else {
+			logger.error("Failed to start WebSocket server:", error);
+			process.exit(1);
+		}
+	}
+	await startMcpServer(connectionManager);
+}
+main().catch((error) => {
+	logger.error("Fatal error:", error);
+	process.exit(1);
+});
+
+//#endregion
+export {  };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@lottiefiles/creator-mcp",
+  "version": "0.1.1",
+  "description": "MCP server for LottieFiles Creator",
+  "license": "UNLICENSED",
+  "type": "module",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LottieFiles/creator.git"
+  },
+  "bin": {
+    "creator-mcp": "dist/index.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.27.1",
+    "end-of-stream": "1.4.5",
+    "signal-exit": "4.1.0",
+    "ws": "8.19.0",
+    "zod": "4.1.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.23.0",
+    "@types/end-of-stream": "1.4.4",
+    "@types/node": "22.9.0",
+    "@types/ws": "8.18.1",
+    "@vitest/eslint-plugin": "1.1.39",
+    "eslint": "9.16.0",
+    "tsdown": "0.20.3",
+    "tsx": "4.21.0",
+    "typescript": "5.8.3",
+    "typescript-eslint": "8.29.0",
+    "vitest": "4.0.18",
+    "@lottiefiles/creator-mcp-shared": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.mjs",
+    "lint": "pnpm lint:eslint",
+    "lint:check": "pnpm lint:eslint:check",
+    "lint:eslint": "eslint --fix .",
+    "lint:eslint:check": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit"
+  }
+}