keyframe-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keyframe.it
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# 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.
+
+## Install
+
+**Claude Code**
+
+```bash
+claude mcp add keyframe -- npx -y keyframe-mcp
+```
+
+**Claude Desktop / Cursor / any MCP client** — add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "keyframe": {
+      "command": "npx",
+      "args": ["-y", "keyframe-mcp"]
+    }
+  }
+}
+```
+
+Requires **Node 18+** and **Google Chrome** installed. It drives your existing Chrome — no
+browser download.
+
+## Usage
+
+Ask your assistant something like:
+
+> 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.
+
+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.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `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_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.
+
+## Docs
+
+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).
+
+## License
+
+MIT — see [LICENSE](./LICENSE). This covers the connector; the Keyframe.it editor is a separate
+hosted application.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "keyframe-mcp",
+  "version": "0.1.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" },
+  "main": "server.mjs",
+  "files": ["server.mjs", "README.md"],
+  "engines": { "node": ">=18" },
+  "homepage": "https://www.keyframe.it.com/",
+  "bugs": { "url": "https://www.keyframe.it.com/" },
+  "author": "Keyframe.it",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "modelcontextprotocol",
+    "mcp-server",
+    "claude",
+    "animation",
+    "2d-animation",
+    "skeletal-animation",
+    "spine",
+    "pixi-spine",
+    "game-development",
+    "gamedev",
+    "sprite",
+    "slot-symbols",
+    "keyframe"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "playwright-core": "^1.49.0"
+  }
+}

package/server.mjs

@@ -0,0 +1,131 @@
+#!/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 { 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)
+}
+
+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 }
+  }
+})
+
+process.on('SIGINT', async () => {
+  await browser?.close().catch(() => {})
+  process.exit(0)
+})
+
+await server.connect(new StdioServerTransport())