{"_id":"@a-company/atelier-mcp","_rev":"3-58ab32d62a8b36d533bdef339c179617","name":"@a-company/atelier-mcp","dist-tags":{"latest":"0.27.2"},"versions":{"0.25.1":{"name":"@a-company/atelier-mcp","version":"0.25.1","_id":"@a-company/atelier-mcp@0.25.1","maintainers":[{"name":"ascend42","email":"ascend@a-company.org"}],"bin":{"atelier-mcp":"dist/index.js"},"dist":{"shasum":"eb157f97e2d3ccedc906b8f34ea597b584e2bb12","tarball":"https://registry.npmjs.org/@a-company/atelier-mcp/-/atelier-mcp-0.25.1.tgz","fileCount":8,"integrity":"sha512-ZxkWyibqvsZcspTpuF4aG8+91AVgD8sp1IXEDkhszfTEvEd4s6bh0mMSHr8/vla1U6jrK96VdgNZetSSia1HJw==","signatures":[{"sig":"MEUCIQD/Msui2Y9tWGBrYEgUtM870q8BPqcMZ5EhtyUJVBru3gIga1+DklYdmvEMj15Oqi+inqI6Nn5oHfs1Q9XRXVhMTbM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":561837},"main":"./dist/index.cjs","type":"module","_from":"file:a-company-atelier-mcp-0.25.1.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"test":"vitest run","build":"tsup","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"ascend42","email":"ascend@a-company.org"},"_resolved":"/private/var/folders/gq/nt2kdpsj39dc8vpq6cfzx8gw0000gn/T/47186a91b10b00fb9f4641ea5c45a4d0/a-company-atelier-mcp-0.25.1.tgz","_integrity":"sha512-ZxkWyibqvsZcspTpuF4aG8+91AVgD8sp1IXEDkhszfTEvEd4s6bh0mMSHr8/vla1U6jrK96VdgNZetSSia1HJw==","_npmVersion":"11.7.0","description":"MCP server — AI authoring interface for animations","directories":{},"_nodeVersion":"24.12.0","dependencies":{"zod":"^3.25.0","@a-company/atelier-svg":"0.25.1","@a-company/atelier-core":"0.25.1","@a-company/atelier-types":"0.25.1","@a-company/atelier-canvas":"0.25.1","@a-company/atelier-lottie":"0.25.1","@a-company/atelier-schema":"0.25.1","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/atelier-mcp_0.25.1_1771887828813_0.7526119423060869","host":"s3://npm-registry-packages-npm-production"}},"0.27.1":{"name":"@a-company/atelier-mcp","version":"0.27.1","_id":"@a-company/atelier-mcp@0.27.1","maintainers":[{"name":"ascend42","email":"ascend@a-company.org"}],"bin":{"atelier-mcp":"dist/index.js"},"dist":{"shasum":"b5446bb22073f23ced9ca9f0956df6c1e665d5da","tarball":"https://registry.npmjs.org/@a-company/atelier-mcp/-/atelier-mcp-0.27.1.tgz","fileCount":8,"integrity":"sha512-0Kr0gEhcFRnySCUKBhc6MENe5hE+8vug2zxdsIx4TJH/cEn6pywGko72alNCEULiiXhNlNw7itA3C7I1PJrqOQ==","signatures":[{"sig":"MEYCIQCKf5rY7Oz3BsanZu8fYKCdPCrw57Os/zBRp5G0bBQXPwIhAKnyucgYrDbJWsckCMT45hz0BcjyLsNvOMNG6iGk8LcP","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":769908},"main":"./dist/index.cjs","type":"module","_from":"file:a-company-atelier-mcp-0.27.1.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"test":"vitest run","build":"tsup","clean":"rm -rf dist","typecheck":"tsc --noEmit"},"_npmUser":{"name":"ascend42","email":"ascend@a-company.org"},"_resolved":"/private/var/folders/gq/nt2kdpsj39dc8vpq6cfzx8gw0000gn/T/f367f362c3fa1f70491406a53aadda1d/a-company-atelier-mcp-0.27.1.tgz","_integrity":"sha512-0Kr0gEhcFRnySCUKBhc6MENe5hE+8vug2zxdsIx4TJH/cEn6pywGko72alNCEULiiXhNlNw7itA3C7I1PJrqOQ==","_npmVersion":"11.7.0","description":"MCP server — AI authoring interface for animations","directories":{},"_nodeVersion":"24.12.0","dependencies":{"ws":"^8.20.1","zod":"^3.25.0","yaml":"^2.7.0","@a-company/atelier-svg":"0.25.1","@a-company/atelier-core":"0.26.0","@a-company/atelier-types":"0.31.0","@a-company/atelier-canvas":"0.26.0","@a-company/atelier-lottie":"0.25.1","@a-company/atelier-schema":"0.28.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.4.0","vitest":"^3.0.0","@types/ws":"^8.18.1","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/atelier-mcp_0.27.1_1779253715044_0.6696971425946054","host":"s3://npm-registry-packages-npm-production"}},"0.27.2":{"name":"@a-company/atelier-mcp","version":"0.27.2","publishConfig":{"access":"public"},"description":"MCP server — AI authoring interface for animations","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"bin":{"atelier-mcp":"dist/index.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","ws":"^8.20.1","yaml":"^2.7.0","zod":"^3.25.0","@a-company/atelier-schema":"0.28.0","@a-company/atelier-core":"0.26.0","@a-company/atelier-canvas":"0.26.0","@a-company/atelier-lottie":"0.25.1","@a-company/atelier-svg":"0.25.1","@a-company/atelier-types":"0.31.0"},"devDependencies":{"@types/node":"^22.0.0","@types/ws":"^8.18.1","tsup":"^8.4.0","typescript":"^5.7.0","vitest":"^3.0.0"},"scripts":{"build":"tsup","typecheck":"tsc --noEmit","test":"vitest run","clean":"rm -rf dist"},"_id":"@a-company/atelier-mcp@0.27.2","_integrity":"sha512-NHKnrYcttMgEZU1YTlNPzuVc5mUEXvK/62Z6spvhMHhC94RFIRaPRFuPitASPxRQG1tX1e+P7NHf6wVJJWqCgw==","_resolved":"/private/var/folders/gq/nt2kdpsj39dc8vpq6cfzx8gw0000gn/T/204e06f5686aef9888cbc624069e17e5/a-company-atelier-mcp-0.27.2.tgz","_from":"file:a-company-atelier-mcp-0.27.2.tgz","_nodeVersion":"24.12.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-NHKnrYcttMgEZU1YTlNPzuVc5mUEXvK/62Z6spvhMHhC94RFIRaPRFuPitASPxRQG1tX1e+P7NHf6wVJJWqCgw==","shasum":"b8f84818af7e86cf08c713c9736699a300b9e3cc","tarball":"https://registry.npmjs.org/@a-company/atelier-mcp/-/atelier-mcp-0.27.2.tgz","fileCount":8,"unpackedSize":769952,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCZqT5XP0nA8kelXMwcTL8mJWgn6p8kInENbbHYPnIepwIgYGQZxKeXIZman5arHemCxg0Aivck4nPW6bROGOYFgpY="}]},"_npmUser":{"name":"ascend42","email":"ascend@a-company.org"},"directories":{},"maintainers":[{"name":"ascend42","email":"ascend@a-company.org"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/atelier-mcp_0.27.2_1779256160683_0.4316771859612867"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-23T23:03:48.720Z","modified":"2026-05-20T05:49:20.999Z","0.25.1":"2026-02-23T23:03:48.982Z","0.27.1":"2026-05-20T05:08:35.218Z","0.27.2":"2026-05-20T05:49:20.877Z"},"description":"MCP server — AI authoring interface for animations","maintainers":[{"name":"ascend42","email":"ascend@a-company.org"}],"readme":"---\ntitle: \"@atelier/mcp\"\nscope: MCP server with 27 tools for AI animation authoring\npackages: [\"@atelier/mcp\"]\nrelated: [\"docs/mcp-reference.md\", \"docs/ai-agent-guide.md\", \"docs/architecture.md\"]\n---\n\n# @atelier/mcp\n\nMCP server -- AI authoring interface for animations.\n\nExposes 27 tools across 8 categories that let an AI agent create, edit, animate, validate, and export Atelier animation documents through the [Model Context Protocol](https://modelcontextprotocol.io/).\n\n## Package Info\n\n| Field | Value |\n|-------|-------|\n| Name | `@atelier/mcp` |\n| Version | `0.1.0` |\n| Description | MCP server -- AI authoring interface for animations |\n| Binary | `atelier-mcp` -> `./dist/index.js` |\n| Build | tsup (ESM + CJS + DTS) |\n| Source | `packages/mcp/src/` |\n\n### Dependencies\n\n| Package | Version |\n|---------|---------|\n| `@atelier/types` | `workspace:*` |\n| `@atelier/schema` | `workspace:*` |\n| `@atelier/core` | `workspace:*` |\n| `@atelier/canvas` | `workspace:*` |\n| `@modelcontextprotocol/sdk` | `^1.0.0` |\n| `zod` | `^3.25.0` |\n\n## Setup\n\n### Claude Desktop\n\nAdd to your Claude Desktop configuration (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"atelier\": {\n      \"command\": \"atelier-mcp\"\n    }\n  }\n}\n```\n\nWhen run directly, the server connects via the stdio transport automatically.\n\n### Programmatic\n\n```typescript\nimport { createServer } from \"@atelier/mcp\";\n\nconst { server, store } = createServer();\n// server: McpServer (fully configured with all 27 tools)\n// store:  DocumentStore (in-memory backing store)\n```\n\n## Exports\n\nAll public exports from `packages/mcp/src/index.ts`:\n\n```typescript\nexport { DocumentStore } from \"./store.js\";\nexport { createServer } from \"./index.js\";\n\nexport { register as registerDocumentTools } from \"./tools/document.js\";\nexport { register as registerLayerTools } from \"./tools/layers.js\";\nexport { register as registerShapeTools } from \"./tools/shapes.js\";\nexport { register as registerStateTools } from \"./tools/states.js\";\nexport { register as registerDeltaTools } from \"./tools/deltas.js\";\nexport { register as registerPresetTools } from \"./tools/presets.js\";\nexport { register as registerPreviewTools } from \"./tools/preview.js\";\nexport { register as registerTemplateTools } from \"./tools/templates.js\";\n```\n\n`createServer()` returns `{ server: McpServer, store: DocumentStore }`. The server is pre-wired with all tool registrations. Individual `register*` functions are exported for selective tool registration on a custom server instance.\n\n## DocumentStore\n\n`packages/mcp/src/store.ts`\n\nIn-memory `Map`-based document storage. Each document is keyed by a string ID (auto-generated as `doc_{timestamp}_{counter}` if not provided).\n\n```typescript\nclass DocumentStore {\n  create(doc: AtelierDocument, id?: string): string;  // auto-generates ID if omitted\n  get(id: string): AtelierDocument | undefined;\n  set(id: string, doc: AtelierDocument): void;\n  delete(id: string): boolean;\n  has(id: string): boolean;\n  list(): Array<{ id: string; name: string; canvas: Canvas }>;\n  clear(): void;\n}\n```\n\n- `create` throws if a document with the given ID already exists.\n- `list` returns the ID, name, and canvas dimensions for each document.\n- `clear` removes all documents (useful for testing).\n\n## All 27 Tools by Category\n\n### Document Tools (5) -- `src/tools/document.ts`\n\n| Tool | Description | Key Params |\n|------|-------------|------------|\n| `atelier_create` | Create a new animation document with canvas settings | `name`, `width`, `height`, `fps`, `background?`, `description?`, `tags?` |\n| `atelier_info` | Get document summary (layers, states, duration, presets) | `id` |\n| `atelier_load` | Load a document from a YAML string | `yaml`, `id?` |\n| `atelier_export` | Export a document as a YAML string | `id` |\n| `atelier_list` | List all documents in the store | _(none)_ |\n\n### Layer Tools (5) -- `src/tools/layers.ts`\n\n| Tool | Description | Key Params |\n|------|-------------|------------|\n| `atelier_add_layer` | Add a new layer to a document | `id`, `layerId`, `visual`, `x`, `y`, `width`, `height`, `opacity?`, `rotation?`, `parentId?`, `anchorPoint?`, `scale?`, `visible?`, `description?`, `tags?` |\n| `atelier_edit_layer` | Edit layer properties | `id`, `layerId`, plus any property to update |\n| `atelier_remove_layer` | Remove a layer (warns about referencing deltas and child layers) | `id`, `layerId` |\n| `atelier_list_layers` | List all layers with index, type, frame, bounds | `id` |\n| `atelier_reorder` | Move a layer to a new position in the stack | `id`, `layerId`, `position` (0-based index) |\n\nThe `visual` parameter accepts a structured object with a required `type` field (`\"shape\"`, `\"text\"`, `\"image\"`, `\"group\"`, or `\"ref\"`) and type-specific fields:\n\n- **shape**: `shape` (type + cornerRadius/points/closed), `fill`, `stroke`\n- **text**: `content`, `style`\n- **image**: `assetId`\n- **ref**: `src`\n\nPosition and size values (`x`, `y`, `width`, `height`) accept either a number (pixels) or a string (percentage, e.g. `\"50%\"`).\n\n### Shape Tools (3) -- `src/tools/shapes.ts`\n\n| Tool | Description | Key Params |\n|------|-------------|------------|\n| `atelier_set_shape` | Set shape geometry on a shape-type layer | `id`, `layerId`, `shape` (`type`: rect/ellipse/path, `cornerRadius?`, `points?`, `closed?`) |\n| `atelier_set_fill` | Set fill on a shape-type layer | `id`, `layerId`, `fill` (`type`: solid/linear-gradient/radial-gradient, `color?`, `angle?`, `center?`, `radius?`, `stops?`) |\n| `atelier_set_stroke` | Set stroke on a shape-type layer | `id`, `layerId`, `stroke` (`color`, `width`, `dash?`, `lineCap?`, `lineJoin?`) |\n\nAll three tools validate that the target layer has `visual.type === \"shape\"` and return an error otherwise.\n\n### State Tools (4) -- `src/tools/states.ts`\n\n| Tool | Description | Key Params |\n|------|-------------|------------|\n| `atelier_add_state` | Add a named animation state | `id`, `stateName`, `duration` (in frames), `description?`, `tags?` |\n| `atelier_edit_state` | Edit state metadata | `id`, `stateName`, `duration?`, `description?`, `tags?` |\n| `atelier_remove_state` | Remove a state and all its deltas | `id`, `stateName` |\n| `atelier_list_states` | List all states with duration, description, delta count | `id` |\n\n### Delta Tools (4) -- `src/tools/deltas.ts`\n\n| Tool | Description | Key Params |\n|------|-------------|------------|\n| `atelier_add_delta` | Add an animation delta (keyframe transition) to a state | `id`, `stateName`, `layer`, `property`, `range` [start, end], `from`, `to`, `easing?`, `description?`, `tags?`, `deltaId?` |\n| `atelier_edit_delta` | Edit an existing delta by index | `id`, `stateName`, `deltaIndex`, plus any field to update |\n| `atelier_remove_delta` | Remove a delta by index | `id`, `stateName`, `deltaIndex` |\n| `atelier_apply_preset` | Apply a named preset to a layer, expanding into concrete deltas | `id`, `stateName`, `presetName`, `layerId`, `startFrame?`, `duration?` |\n\n**Animatable properties** (the `property` enum):\n\n```\nframe.x, frame.y, bounds.width, bounds.height,\nopacity, rotation, scale.x, scale.y,\nanchorPoint.x, anchorPoint.y,\nvisual.shape.cornerRadius, visual.fill.color,\nvisual.stroke.color, visual.stroke.width,\nvisual.style.fontSize, visual.style.color\n```\n\n**Easing options** (the `easing` parameter):\n\n| Type | Params |\n|------|--------|\n| Shorthand | `\"ease-in\"`, `\"ease-out\"`, `\"ease-in-out\"` |\n| Linear | `{ type: \"linear\" }` |\n| Cubic Bezier | `{ type: \"cubic-bezier\", x1, y1, x2, y2 }` |\n| Spring | `{ type: \"spring\", mass?, stiffness?, damping?, velocity? }` |\n| Step | `{ type: \"step\", steps, position?: \"start\" \\| \"end\" }` |\n\nBoth `atelier_add_delta` and `atelier_edit_delta` run overlap validation (via `@atelier/core` `validateNoOverlap`) and reject conflicting deltas on the same layer+property+range.\n\n### Preset Tools (2) -- `src/tools/presets.ts`\n\n| Tool | Description | Key Params |\n|------|-------------|------------|\n| `atelier_define_preset` | Define a reusable animation preset on a document | `id`, `presetName`, `deltas` (array of `{ property, offset?, from, to, easing? }`), `description?`, `tags?` |\n| `atelier_list_presets` | List all presets with descriptions and properties | `id` |\n\nPresets are stored on the document object under `doc.presets`. Each preset contains an array of delta definitions with relative offsets. Use `atelier_apply_preset` (in Delta Tools) to expand a preset into concrete deltas on a specific layer and state.\n\n### Preview Tools (2) -- `src/tools/preview.ts`\n\n| Tool | Description | Key Params |\n|------|-------------|------------|\n| `atelier_validate` | Validate schema correctness and check for delta overlaps across all states | `id` |\n| `atelier_preview` | Preview the resolved state of all layers at a specific frame | `id`, `stateName`, `frame` |\n\n- `atelier_validate` runs both `@atelier/schema` `validateDocument` and `@atelier/core` `validateAllDeltas` per state.\n- `atelier_preview` calls `@atelier/core` `resolveFrame` to compute interpolated property values at the given frame number.\n\n### Template Tools (2) -- `src/tools/templates.ts`\n\n| Tool | Description | Key Params |\n|------|-------------|------------|\n| `atelier_instantiate_template` | Instantiate a template document with variable bindings, creating a new document in the store | `id` (template doc), `bindings` (`{ variableName: value }`) |\n| `atelier_find_variables` | Scan a document for `{{variableName}}` patterns | `id` |\n\n- `atelier_find_variables` returns `variables` (all found), `declared` (in `doc.variables`), `undeclared` (found but not declared), and `unused` (declared but not found).\n- `atelier_instantiate_template` calls `@atelier/core` `instantiateTemplate` and stores the resulting document under a new auto-generated ID.\n\n## Error Handling\n\nAll tools return structured JSON in a `text` content block:\n\n**Success:**\n```json\n{ \"success\": true, \"id\": \"doc_1234_1\", \"name\": \"My Animation\" }\n```\n\n**Error:**\n```json\n{ \"error\": \"Document \\\"doc_abc\\\" not found\" }\n```\n\nError responses also set `isError: true` on the MCP result object. Zod validation errors are flattened to `\"path: message\"` format for AI readability.\n\n## Typical AI Workflow\n\n```\n1. atelier_create           -> get document ID\n2. atelier_add_layer        -> (repeat for each layer)\n3. atelier_set_shape/fill   -> configure shape visuals\n4. atelier_add_state        -> name state, set duration in frames\n5. atelier_add_delta        -> (repeat for each animation keyframe)\n6. atelier_validate         -> check for schema/overlap errors\n7. atelier_preview          -> inspect resolved frame data\n8. atelier_export           -> get YAML output\n```\n\nOptional steps:\n\n- `atelier_define_preset` + `atelier_apply_preset` to reuse animation patterns across layers\n- `atelier_find_variables` + `atelier_instantiate_template` for template-based workflows\n- `atelier_load` to import existing YAML documents into the store\n\n## Building\n\n```bash\n# From the monorepo root\npnpm --filter @atelier/mcp build\n\n# Or from this package directory\npnpm build\n```\n\nBuild output goes to `dist/` with ESM (`index.js`), CJS (`index.cjs`), declaration files (`index.d.ts`), and sourcemaps.\n\n## Testing\n\n```bash\npnpm --filter @atelier/mcp test\n```\n\n## Project Structure\n\n```\npackages/mcp/\n  src/\n    index.ts              # Server creation, stdio entry point, re-exports\n    store.ts              # DocumentStore (in-memory Map-based storage)\n    tools/\n      document.ts         # 5 tools: create, info, load, export, list\n      layers.ts           # 5 tools: add, edit, remove, list, reorder\n      shapes.ts           # 3 tools: set_shape, set_fill, set_stroke\n      states.ts           # 4 tools: add, edit, remove, list\n      deltas.ts           # 4 tools: add, edit, remove, apply_preset\n      presets.ts           # 2 tools: define, list\n      preview.ts           # 2 tools: validate, preview\n      templates.ts         # 2 tools: instantiate_template, find_variables\n  tsup.config.ts          # Build configuration\n  package.json\n```\n","readmeFilename":"README.md"}