keyframe-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,80 +1,78 @@
 # keyframe-mcp
 
-An [MCP](https://modelcontextprotocol.io) server that lets Claude — or any MCP client —
-**rig, animate and export 2D skeletal animations** by driving
-[Keyframe.it](https://www.keyframe.it.com), a free browser-based animation editor for game
-sprites.
-
-It opens the editor in your own Chrome and exposes Keyframe.it's `window.keyframe` scripting
-API (150+ methods) as tools. Rendered frames, clips and assets come back as **real images**, so
-the model sees the art it's working on — and the finished rig is sitting in your browser,
-ready to keep editing.
-
-Exports are Spine-compatible bundles (3.8 / 4.2 — `.json` or binary `.skel` + `.atlas` + `.png`)
-that load in pixi-spine and other Spine runtimes. Free, no account, nothing uploaded.
+Create, inspect and export 2D skeletal animations in [Keyframe.it](https://www.keyframe.it.com/) from any MCP client.
 
 ## Install
 
-**Claude Code**
+Requires Node 18+ and Google Chrome. No browser download or Keyframe account is needed.
 
-```bash
+```sh
 claude mcp add keyframe -- npx -y keyframe-mcp
 ```
 
-**Claude Desktop / Cursor / any MCP client** — add to your MCP config:
+Other clients:
 
 ```json
-{
-  "mcpServers": {
-    "keyframe": {
-      "command": "npx",
-      "args": ["-y", "keyframe-mcp"]
-    }
-  }
-}
+{"mcpServers":{"keyframe":{"command":"npx","args":["-y","keyframe-mcp"]}}}
 ```
 
-Requires **Node 18+** and **Google Chrome** installed. It drives your existing Chrome — no
-browser download.
+Version 0.2.0 adds persistent projects, named tools with validated schemas, complete clip creation, animation checks, editable image layers and file exports. Restart the MCP client after updating. For a local checkout, run `npm ci` in `mcp/`, then configure `node` with the absolute path to `mcp/server.mjs`.
 
-## Usage
+## Workflow
 
-Ask your assistant something like:
+1. `keyframe_open` resumes a dedicated Chrome profile and waits for saved projects to restore.
+2. Read `keyframe_methods`, `keyframe_call {method:"recipes"}` and the current document with `keyframe_call {method:"getState"}`.
+3. Build a complete clip with `keyframe_build_animation`. All poses are validated before the document changes. Partial transform values carry forward from setup. `loop:true` copies the first pose to the end; `replace:true` replaces all tracks in an existing clip. FPS applies to the entire project.
+4. Review `keyframe_contact_sheet` and `keyframe_check_animation`. Inspect motion with `keyframe_call {method:"renderClip",args:["idle"]}`. Warnings can be intentional; contact-sheet framing is fitted to the clip, and loop transform checks exclude springs.
+5. `keyframe_export {format:"project"}` writes an editable JSON file. Use `gif` for a preview or `spine` for a ZIP with skeleton, atlas, textures and test.html. Files return as MCP resource links plus local paths; supporting clients can read them with resources/read.
+6. `keyframe_open_result` saves and opens visible Chrome so the user can continue editing. The window lasts while the connector is running; saved projects persist after shutdown.
 
-> Open Keyframe.it, load the noir example, and make a 2-second idle animation where she
-> breathes and her hair sways. Show me the result.
+Example clip tool arguments (use real bone names from the project):
+
+```json
+{"spec":{"name":"idle","duration":2,"fps":24,"loop":true,"poses":[{"time":0,"bones":{"root":{"y":0,"scaleY":1}}},{"time":1,"bones":{"root":{"y":-6,"scaleY":1.03}}}]}}
+```
 
-The assistant calls `keyframe_open`, reads the API with `keyframe_methods`, then works through
-`keyframe_call`. For multi-step jobs it should read the built-in recipes first
-(`keyframe_call {method: "recipes"}`) — they encode the right order of operations for slicing
-sheets, rigging, meshing and weights, idle loops, walk cycles and win FX.
+Read `keyframe_session` and pass its `projectId` and `revision` in `expected` to build/configure/layer edits to reject stale commands. Requests run sequentially. Changes are saved before the tool responds. If saving fails after a mutation, the error says `applied:true`; retry `keyframe_save` before closing.
 
 ## Tools
 
-| Tool | What it does |
+| Tool | Purpose |
 | --- | --- |
-| `keyframe_open` `{url?}` | Open the editor (launches Chrome on first use, reuses the tab after). Returns an overview. **Call first.** |
-| `keyframe_methods` | List every scripting method with a one-line description. |
-| `keyframe_call` `{method, args?}` | Call any `window.keyframe` method. Image results (`renderFrame`, `renderClip`, `getAssetPng`) return as actual images. |
-| `keyframe_screenshot` | Screenshot the whole editor UI (rarely needed). |
-
-## Environment
-
-| Variable | Default | Meaning |
+| `keyframe_open` | Open/resume the editor, optional URL |
+| `keyframe_methods` | Discover all scripting methods |
+| `keyframe_call` | Call a method with positional JSON arguments; image results appear inline |
+| `keyframe_session` | Active project and revision |
+| `keyframe_list_projects` / `keyframe_open_project` | Find and reopen saved projects |
+| `keyframe_save` | Wait for browser storage to commit |
+| `keyframe_build_animation` | Create a complete validated clip in one undo step |
+| `keyframe_configure_animation` | Duration and project FPS |
+| `keyframe_apply_pose` | Batch named bone transforms in the active clip |
+| `keyframe_contact_sheet` | Timestamped pose grid, empty/edge-frame checks |
+| `keyframe_check_animation` | Loop, visibility and rig diagnostics |
+| `keyframe_image_layers` / `keyframe_image_layer_png` | Inspect editable layers and pixels |
+| `keyframe_edit_image_layers` | Atomic layer add/update/reorder/delete, including editable text |
+| `keyframe_export` | Project JSON, GIF or Spine ZIP as files |
+| `keyframe_open_result` | Save and show the editable result |
+| `keyframe_screenshot` | Whole editor UI |
+
+Every named tool advertises its JSON Schema. Errors use MCP `isError:true` and `{ok:false,error}`. The generic call tool remains available for rigging, slicing, meshes, physics and other advanced methods.
+
+## Storage and handoff
+
+The connector uses **its own Chrome profile**, not existing personal Chrome tabs. Projects belong to that profile and site origin. Export project JSON and import it in your usual browser to transfer work. Existing projects from version 0.1.0's temporary browser profile cannot be recovered unless previously exported.
+
+| Variable | Default | Purpose |
 | --- | --- | --- |
-| `KEYFRAME_URL` | `https://www.keyframe.it.com/` | Editor URL — set `http://localhost:5173` to drive a local dev build |
-| `KEYFRAME_HEADLESS` | `1` | Set `0` to watch the work happen in a visible Chrome window |
-
-Tip: `KEYFRAME_HEADLESS=0` is genuinely fun the first time — you watch bones and keyframes
-appear as the model works.
+| `KEYFRAME_URL` | `https://www.keyframe.it.com/` | Editor URL; HTTP allowed for localhost development |
+| `KEYFRAME_PROFILE_DIR` | `~/.keyframe-mcp/profile` | Persistent browser storage; use separate directories for concurrent instances |
+| `KEYFRAME_HEADLESS` | `1` | Set `0` to watch work; open_result switches to visible Chrome |
+| `KEYFRAME_EXPORT_DIR` | `~/.keyframe-mcp/exports` | Downloaded artifacts; files remain after shutdown |
 
-## Docs
+Close or Apply the human image editor before agent layer edits. Layers retain text, visibility, opacity, blend modes and locks. The composite stays compatible with existing rig/export tools. See the [full API reference](https://www.keyframe.it.com/llms.txt) for operation examples and limits.
 
-The scripting surface is documented in the editor (`window.keyframe.help()`) and at
-[keyframe.it.com/llms.txt](https://www.keyframe.it.com/llms.txt). For the whole product in one
-fetch, see [llms-full.txt](https://www.keyframe.it.com/llms-full.txt).
+## Development
 
-## License
+`npm test` runs schema, protocol, persistence, serialization, error and file-resource tests with a fake browser. `../e2e/agent-workflow.html` exercises the real editor API, canvas renders, layer compositing, exports and save/reload through a Vite dev server.
 
-MIT — see [LICENSE](./LICENSE). This covers the connector; the Keyframe.it editor is a separate
-hosted application.
+MIT — see LICENSE. This license covers the connector; the editor is a separate hosted application.

package/package.json

@@ -1,14 +1,27 @@
 {
   "name": "keyframe-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for Keyframe.it — let Claude (or any MCP client) rig, animate and export 2D skeletal animations by driving the free Keyframe.it editor in your browser.",
   "type": "module",
-  "bin": { "keyframe-mcp": "server.mjs" },
+  "bin": {
+    "keyframe-mcp": "server.mjs"
+  },
   "main": "server.mjs",
-  "files": ["server.mjs", "README.md"],
-  "engines": { "node": ">=18" },
+  "files": [
+    "server.mjs",
+    "session.mjs",
+    "runner.mjs",
+    "tools.mjs",
+    "README.md"
+  ],
+  "scripts": { "test": "node --test runner.test.mjs", "prepublishOnly": "npm test" },
+  "engines": {
+    "node": ">=18"
+  },
   "homepage": "https://www.keyframe.it.com/",
-  "bugs": { "url": "https://www.keyframe.it.com/" },
+  "bugs": {
+    "url": "https://www.keyframe.it.com/"
+  },
   "author": "Keyframe.it",
   "license": "MIT",
   "keywords": [
@@ -30,6 +43,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
+    "ajv": "^8.20.0",
     "playwright-core": "^1.49.0"
   }
 }

package/runner.mjs

@@ -0,0 +1,70 @@
+import Ajv from 'ajv'
+import { mkdir, writeFile, readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { randomUUID } from 'node:crypto'
+import { definitions } from './tools.mjs'
+const ajv = new Ajv({ allErrors: true, strict: false })
+const registered = new Map(definitions.map(d => [d.name, { ...d, validate: ajv.compile(d.inputSchema) }]))
+export function toContent(result) {
+  const image = result?.dataUrl?.match(/^data:(image\/[a-z+]+);base64,(.*)$/s)
+  if (image) {
+    const { dataUrl, ...metadata } = result
+    return { content: [{ type: 'image', mimeType: image[1], data: image[2] }, { type: 'text', text: JSON.stringify(metadata) }], structuredContent: metadata, ...(result.ok === false ? { isError: true } : {}) }
+  }
+  return { content: [{ type: 'text', text: JSON.stringify(result) ?? 'null' }], ...(result && typeof result === 'object' && !Array.isArray(result) ? { structuredContent: result } : {}), ...(result?.ok === false ? { isError: true } : {}) }
+}
+export class ToolRunner {
+  constructor(session, outputDir = process.env.KEYFRAME_EXPORT_DIR || join(homedir(), '.keyframe-mcp', 'exports')) {
+    this.session = session
+    this.outputDir = resolve(outputDir)
+    this.artifacts = new Map()
+    this.pending = Promise.resolve()
+  }
+  call(name, args) {
+    // Serialize requests so a second command cannot switch projects mid-edit.
+    const task = this.pending.then(() => this.dispatch(name, args)).catch(e => toContent({ ok: false, error: String(e?.message ?? e) }))
+    this.pending = task.then(() => {})
+    return task
+  }
+  async dispatch(name, args) {
+    const definition = registered.get(name)
+    if (!definition) throw new Error(`Unknown tool: ${name}`)
+    if (!definition.validate(args)) throw new Error(`Invalid arguments: ${ajv.errorsText(definition.validate.errors)}`)
+    const page = await this.session.open(name === 'keyframe_open' ? args.url : undefined)
+    if (name === 'keyframe_open_result') return toContent(await this.session.handoff())
+    if (name === 'keyframe_screenshot') return { content: [{ type: 'image', mimeType: 'image/png', data: (await page.screenshot({ type: 'png' })).toString('base64') }] }
+    if (name === 'keyframe_open') return toContent({ ...await this.session.invoke('describe'), profile: this.session.profile, visible: !this.session.headless, handoffTool: 'keyframe_open_result' })
+    const before = await this.session.invoke('sessionInfo')
+    const result = await this.session.invoke(name === 'keyframe_call' ? args.method : definition.method, name === 'keyframe_call' ? args.args ?? [] : definition.args(args))
+    const after = await this.session.invoke('sessionInfo')
+    if (before.revision !== after.revision || before.projectId !== after.projectId) {
+      try { await this.session.save() }
+      catch (e) { return toContent({ ok: false, error: `The command changed the project, but saving failed: ${e.message}. Retry keyframe_save before closing the editor.`, applied: true }) }
+    }
+    if (result?.artifact && result.ok !== false) return this.writeArtifact(result)
+    return toContent(result)
+  }
+  async writeArtifact(result) {
+    const artifact = result.artifact
+    const match = artifact.dataUrl?.match(/^data:([^;,]*)(?:;[^,]*)?;base64,(.*)$/s)
+    if (!match) throw new Error('Export did not return an embedded file')
+    const safeName = artifact.name.replace(/[^a-z0-9_.-]/gi, '_').replace(/^\.+/, '') || 'export'
+    await mkdir(this.outputDir, { recursive: true })
+    const path = join(this.outputDir, `${randomUUID()}-${safeName}`)
+    const bytes = Buffer.from(match[2], 'base64')
+    await writeFile(path, bytes, { flag: 'wx' })
+    const resource = { uri: pathToFileURL(path).href, name: safeName, mimeType: artifact.mimeType || match[1], size: bytes.length }
+    this.artifacts.set(resource.uri, { resource, path })
+    const metadata = { ok: true, projectId: result.projectId, path, ...resource }
+    return { content: [{ type: 'text', text: JSON.stringify(metadata) }, { type: 'resource_link', ...resource }], structuredContent: metadata }
+  }
+  resources() { return [...this.artifacts.values()].map(a => a.resource) }
+  async readResource(uri) {
+    const artifact = this.artifacts.get(uri)
+    if (!artifact) throw new Error('Unknown export resource; only files exported in this session can be read')
+    const bytes = await readFile(artifact.path)
+    return { contents: [{ uri, mimeType: artifact.resource.mimeType, blob: bytes.toString('base64') }] }
+  }
+}

package/server.mjs

@@ -1,131 +1,35 @@
 #!/usr/bin/env node
-// keyframe-mcp — MCP server that drives the Keyframe.it editor through its window.keyframe
-// scripting API. Launches the user's installed Chrome (playwright-core `channel: 'chrome'`,
-// no browser download) and proxies API calls as tools. Results carrying an image data URL
-// (renderFrame, renderClip, getAssetPng) come back as real MCP image content, so the model
-// SEES the art, not a base64 wall.
-//
-// Env: KEYFRAME_URL (default https://www.keyframe.it.com/), KEYFRAME_HEADLESS=0 to watch.
 import { Server } from '@modelcontextprotocol/sdk/server/index.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js'
 import { chromium } from 'playwright-core'
-
-const DEFAULT_URL = process.env.KEYFRAME_URL || 'https://www.keyframe.it.com/'
-let browser = null
-let page = null
-
-async function ensurePage(url) {
-  if (page && !page.isClosed()) return page
-  if (!browser || !browser.isConnected()) {
-    browser = await chromium.launch({
-      channel: 'chrome',
-      headless: process.env.KEYFRAME_HEADLESS !== '0',
-    })
-  }
-  page = await browser.newPage({ viewport: { width: 1440, height: 900 } })
-  await page.goto(url || DEFAULT_URL, { waitUntil: 'domcontentloaded' })
-  await page.waitForFunction(() => !!globalThis.keyframe, undefined, { timeout: 30000 })
-  return page
-}
-
-const text = (s) => ({ content: [{ type: 'text', text: typeof s === 'string' ? s : JSON.stringify(s, null, 1) }] })
-
-/** JSON result → MCP content; a data-URL image field becomes real image content. */
-function toContent(result) {
-  if (result && typeof result === 'object' && typeof result.dataUrl === 'string' && result.dataUrl.startsWith('data:image/')) {
-    const m = result.dataUrl.match(/^data:(image\/[a-z+]+);base64,(.*)$/s)
-    if (m) {
-      const { dataUrl, ...rest } = result
-      return {
-        content: [
-          { type: 'image', mimeType: m[1], data: m[2] },
-          { type: 'text', text: JSON.stringify({ ...rest, dataUrl: `(shown above, ${Math.round(m[2].length / 1366)}kB)` }, null, 1) },
-        ],
-      }
-    }
-  }
-  return text(result)
+import { pathToFileURL } from 'node:url'
+import { EditorSession } from './session.mjs'
+import { ToolRunner } from './runner.mjs'
+import { advertisedTools } from './tools.mjs'
+
+export function createServer(session = new EditorSession(chromium)) {
+  const runner = new ToolRunner(session)
+  const server = new Server({ name: 'keyframe-mcp', version: '0.2.0' }, { capabilities: { tools: {}, resources: {} } })
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: advertisedTools }))
+  server.setRequestHandler(CallToolRequestSchema, req => runner.call(req.params.name, req.params.arguments ?? {}))
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: runner.resources() }))
+  server.setRequestHandler(ReadResourceRequestSchema, req => runner.readResource(req.params.uri))
+  return { server, runner, session }
 }
 
-const TOOLS = [
-  {
-    name: 'keyframe_open',
-    description:
-      'Open the Keyframe.it editor (launches Chrome on first use; reuses the tab afterwards). Optional url overrides the default (e.g. a local dev server). Returns the editor overview. Call this first.',
-    inputSchema: { type: 'object', properties: { url: { type: 'string', description: 'editor URL (default: keyframe.it.com or $KEYFRAME_URL)' } } },
-  },
-  {
-    name: 'keyframe_methods',
-    description: 'List every window.keyframe API method with a one-line description. Call once after keyframe_open, before other calls.',
-    inputSchema: { type: 'object', properties: {} },
-  },
-  {
-    name: 'keyframe_call',
-    description:
-      "Call a window.keyframe API method by name, e.g. {method: 'getState'} or {method: 'poseBone', args: ['armL', {rotation: 20}]}. Results that contain an image (renderFrame, renderClip, getAssetPng) are returned as an actual image. Read keyframe_methods (and the matching recipes() entry for multi-step tasks) first.",
-    inputSchema: {
-      type: 'object',
-      properties: {
-        method: { type: 'string', description: 'API method name, e.g. getState, applyPose, renderFrame' },
-        args: { type: 'array', description: 'positional arguments for the method (JSON values)' },
-      },
-      required: ['method'],
-    },
-  },
-  {
-    name: 'keyframe_screenshot',
-    description: 'Screenshot the whole editor UI (rarely needed — prefer keyframe_call renderFrame/getAssetPng for art, getState for data).',
-    inputSchema: { type: 'object', properties: {} },
-  },
-]
-
-const server = new Server({ name: 'keyframe-mcp', version: '0.1.0' }, { capabilities: { tools: {} } })
-
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
-
-server.setRequestHandler(CallToolRequestSchema, async (req) => {
-  const { name, arguments: args = {} } = req.params
-  try {
-    if (name === 'keyframe_open') {
-      const p = await ensurePage(args.url)
-      const overview = await p.evaluate(() => globalThis.keyframe.describe())
-      return text(overview)
-    }
-    if (name === 'keyframe_methods') {
-      const p = await ensurePage()
-      return text(await p.evaluate(() => globalThis.keyframe.help()))
-    }
-    if (name === 'keyframe_call') {
-      const p = await ensurePage()
-      const result = await p.evaluate(async ({ method, callArgs }) => {
-        const fn = globalThis.keyframe?.[method]
-        if (typeof fn !== 'function') {
-          return { ok: false, error: `no method "${method}" — see keyframe_methods` }
-        }
-        try {
-          const r = await fn.apply(globalThis.keyframe, callArgs)
-          return r === undefined ? { ok: true } : r
-        } catch (e) {
-          return { ok: false, error: String(e?.message ?? e) }
-        }
-      }, { method: args.method, callArgs: Array.isArray(args.args) ? args.args : [] })
-      return toContent(result)
-    }
-    if (name === 'keyframe_screenshot') {
-      const p = await ensurePage()
-      const buf = await p.screenshot({ type: 'png' })
-      return { content: [{ type: 'image', mimeType: 'image/png', data: buf.toString('base64') }] }
-    }
-    return { ...text(`unknown tool "${name}"`), isError: true }
-  } catch (e) {
-    return { ...text(`error: ${String(e?.message ?? e)}`), isError: true }
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const { server, runner, session } = createServer()
+  let closing = false
+  const shutdown = async () => {
+    if (closing) return
+    closing = true
+    try { await runner.pending; await session.close() }
+    catch (e) { console.error(`Could not save/close Keyframe: ${e.message}`) }
+    finally { await server.close(); process.exit(0) }
   }
-})
-
-process.on('SIGINT', async () => {
-  await browser?.close().catch(() => {})
-  process.exit(0)
-})
-
-await server.connect(new StdioServerTransport())
+  process.on('SIGINT', shutdown)
+  process.on('SIGTERM', shutdown)
+  process.stdin.on('end', shutdown)
+  await server.connect(new StdioServerTransport())
+}

package/session.mjs

@@ -0,0 +1,55 @@
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+export function editorUrl(value) {
+  const url = new URL(value)
+  if (url.username || url.password || !(url.protocol === 'https:' || (url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)))) throw new Error('Use HTTPS, or HTTP on localhost, for the editor URL')
+  return url.href
+}
+export class EditorSession {
+  constructor(chromium, env = process.env) {
+    this.chromium = chromium
+    this.url = editorUrl(env.KEYFRAME_URL || 'https://www.keyframe.it.com/')
+    this.profile = resolve(env.KEYFRAME_PROFILE_DIR || join(homedir(), '.keyframe-mcp', 'profile'))
+    this.headless = env.KEYFRAME_HEADLESS !== '0'
+    this.context = null
+    this.page = null
+  }
+  async open(url) {
+    const target = url ? editorUrl(url) : this.url
+    if (this.page && !this.page.isClosed() && this.page.url() !== target) await this.save()
+    if (!this.context) {
+      this.context = await this.chromium.launchPersistentContext(this.profile, { channel: 'chrome', headless: this.headless, viewport: { width: 1440, height: 900 } })
+      this.context.on('close', () => { this.context = null; this.page = null })
+    }
+    if (!this.page || this.page.isClosed()) this.page = this.context.pages().find(p => p.url() === target) ?? await this.context.newPage()
+    if (this.page.url() !== target) await this.page.goto(target, { waitUntil: 'domcontentloaded' })
+    this.url = target
+    await this.page.waitForFunction(() => !!globalThis.keyframe, undefined, { timeout: 30000 })
+    const status = await this.invoke('ready')
+    if (status?.ok === false) throw new Error(status.error)
+    this.url = this.page.url()
+    return this.page
+  }
+  async invoke(method, args = []) {
+    return this.page.evaluate(async ({ method, args }) => {
+      const api = globalThis.keyframe
+      if (!api || !Object.prototype.hasOwnProperty.call(api, method) || typeof api[method] !== 'function') return { ok: false, error: `Unknown API method ${method}; check keyframe_methods and update the editor if needed` }
+      try { return (await api[method](...args)) ?? { ok: true } }
+      catch (e) { return { ok: false, error: String(e?.message ?? e) } }
+    }, { method, args })
+  }
+  async save() {
+    if (!this.page || this.page.isClosed()) return
+    const saved = await this.invoke('saveProject')
+    if (saved?.ok === false) throw new Error(saved.error)
+    return saved
+  }
+  async handoff() {
+    await this.open()
+    const saved = await this.save()
+    if (this.headless) { await this.context.close(); this.headless = false; await this.open() }
+    await this.page.bringToFront()
+    return { ok: true, ...saved, url: this.url, visible: true, profile: this.profile, note: 'Continue editing in the opened Chrome window. This dedicated profile is separate from your usual browser. Export project JSON to transfer it.' }
+  }
+  async close() { try { await this.save() } finally { await this.context?.close() } }
+}

package/tools.mjs

@@ -0,0 +1,45 @@
+// Schemas are advertised to clients and validated before dispatch.
+const str = { type: 'string', minLength: 1 }
+const bool = { type: 'boolean' }
+const number = (minimum, maximum) => ({ type: 'number', minimum, maximum })
+const integer = (minimum, maximum) => ({ type: 'integer', minimum, maximum })
+const object = (properties = {}, required = []) => ({ type: 'object', properties, required, additionalProperties: false })
+const transform = { ...object(Object.fromEntries(['x', 'y', 'rotation', 'scaleX', 'scaleY', 'shearX', 'shearY'].map(k => [k, { type: 'number' }]))), minProperties: 1 }
+const bones = { type: 'object', minProperties: 1, additionalProperties: transform }
+const expected = object({ projectId: str, revision: integer(0, Number.MAX_SAFE_INTEGER) })
+const textProperties = {
+  str, font: str, size: number(1, 1024), bold: bool, italic: bool, outline: number(0, 100), fill: str, stroke: str,
+  x: number(-16384, 16384), y: number(-16384, 16384), vertical: bool, distH: number(-100, 100), distV: number(-100, 100),
+  warp: object({ kind: { enum: ['arc', 'arch', 'bulge', 'shellL', 'shellU', 'flag', 'wave', 'fish', 'rise', 'fisheye', 'inflate', 'squeeze', 'twist'] }, bend: number(-100, 100) }, ['kind', 'bend']),
+}
+const text = object(textProperties, ['str', 'font', 'size', 'bold', 'italic', 'outline', 'fill', 'stroke', 'x', 'y'])
+const layerChange = { oneOf: [
+  { ...object({ action: { const: 'add' }, name: str, src: str, text }, ['action', 'name']), oneOf: [{ required: ['src'], not: { required: ['text'] } }, { required: ['text'], not: { required: ['src'] } }] },
+  object({ action: { const: 'update' }, id: str, patch: { ...object({ name: str, visible: bool, locked: bool, opacity: number(0, 1), mode: { enum: ['source-over', 'multiply', 'screen', 'overlay', 'darken', 'lighten', 'color-dodge', 'color-burn', 'hard-light', 'soft-light', 'difference', 'hue', 'saturation', 'color', 'luminosity', 'lighter'] }, text: object(textProperties) }), minProperties: 1 } }, ['action', 'id', 'patch']),
+  object({ action: { const: 'move' }, id: str, targetId: str, above: bool }, ['action', 'id', 'targetId', 'above']),
+  object({ action: { const: 'delete' }, id: str }, ['action', 'id']),
+] }
+const tool = (name, description, inputSchema = object(), method, args = () => []) => ({ name, description, inputSchema, method, args })
+export const definitions = [
+  tool('keyframe_open', 'Open or resume a saved editor session in a dedicated Chrome profile. Call first; waits for project restoration.', object({ url: str })),
+  tool('keyframe_methods', 'List scripting methods; read recipes through keyframe_call for rigging workflows.', object(), 'help'),
+  tool('keyframe_call', 'Call a scripting method using positional arguments. Read keyframe_methods first. Mutations are saved; image results appear inline.', object({ method: str, args: { type: 'array' } }, ['method'])),
+  tool('keyframe_screenshot', 'Show the editor UI. Prefer contact sheets to assess animation.'),
+  tool('keyframe_session', 'Read active project, readiness and revision. Supply expected to edit tools to reject stale edits.', object(), 'sessionInfo'),
+  tool('keyframe_list_projects', 'List projects saved in this connector profile.', object(), 'listProjects'),
+  tool('keyframe_open_project', 'Save the active project and open a saved project by ID.', object({ projectId: str }, ['projectId']), 'openProject', a => [a.projectId]),
+  tool('keyframe_save', 'Wait for the active project to commit to browser storage.', object(), 'saveProject'),
+  tool('keyframe_build_animation', 'Build a complete clip atomically. Partial transforms carry forward from setup. loop:true copies the first pose to the end. replace:true replaces a clip and all its tracks. FPS is project-wide.', object({ spec: object({ name: str, duration: number(.05, 120), fps: integer(1, 60), loop: bool, replace: bool,
+    poses: { type: 'array', minItems: 1, maxItems: 2048, items: object({ time: number(0, 120), bones, easing: { enum: ['linear', 'step', 'easeIn', 'easeOut', 'easeInOut', 'bezier'] }, bezier: { type: 'array', items: { type: 'number' }, minItems: 4, maxItems: 4 } }, ['time', 'bones']) },
+  }, ['name', 'duration', 'poses']), expected }, ['spec']), 'buildAnimation', a => [a.spec, a.expected]),
+  tool('keyframe_configure_animation', 'Set clip duration and project FPS. Rejects shortening past keys/events.', object({ animation: str, duration: number(.05, 120), fps: integer(1, 60), expected }, ['animation']), 'configureAnimation', a => [a.animation, { duration: a.duration, fps: a.fps }, a.expected]),
+  tool('keyframe_apply_pose', 'Apply bone transforms at a time in the active clip. Validates all names and values before editing. Use build_animation for a whole clip.', object({ bones, time: number(0, 120) }, ['bones']), 'applyPose', a => [a.bones, a.time === undefined ? {} : { time: a.time }]),
+  tool('keyframe_contact_sheet', 'Show sampled frames with timestamps, empty frames and edge-touch warnings. Uses a fixed camera fitted to the clip; warnings indicate possible clipping.', object({ animation: str, samples: integer(2, 24), size: integer(64, 512) }), 'renderContactSheet', a => [a.animation, { samples: a.samples, size: a.size }]),
+  tool('keyframe_check_animation', 'Check endpoint discontinuities, sampled invisible parts and rig problems. Warnings can be intentional; also review rendered frames.', object({ animation: str, samples: integer(2, 60) }), 'inspectAnimation', a => [a.animation, { samples: a.samples }]),
+  tool('keyframe_export', 'Write an editable project JSON, animated GIF or Spine ZIP to disk. Returns an MCP resource and local path. Spine ZIP includes atlas, textures and a preview.', object({ format: { enum: ['project', 'gif', 'spine'] }, animation: str, version: { enum: ['3.8', '4.2'] }, binary: bool, size: integer(64, 1024), fps: integer(1, 60) }, ['format']), 'exportArtifact', a => [a]),
+  tool('keyframe_image_layers', 'List editable image layers and stable IDs in bottom-to-top order.', object({ asset: str }, ['asset']), 'getImageLayers', a => [a.asset]),
+  tool('keyframe_image_layer_png', 'Show one image layer as a PNG.', object({ asset: str, id: str }, ['asset', 'id']), 'getImageLayerPng', a => [a.asset, a.id]),
+  tool('keyframe_edit_image_layers', 'Atomically add text or embedded image layers, edit properties/text, reorder or delete layers. Updates composite and editable layers. Close the human image editor first.', object({ asset: str, operations: { type: 'array', minItems: 1, maxItems: 100, items: layerChange }, expected }, ['asset', 'operations']), 'editImageLayers', a => [a.asset, a.operations, a.expected]),
+  tool('keyframe_open_result', 'Save the project and show it in visible Chrome with the connector profile. Export project JSON to transfer to your usual browser.'),
+]
+export const advertisedTools = definitions.map(({ method, args, ...definition }) => definition)