realtime-avatar-mcp 0.4.0 → 0.5.0

package/README.md

@@ -1,27 +1,26 @@
 # realtime-avatar-mcp
 
-**Not published yet** — the package is marked `private: true`, so `npm publish` skips it rather than relying on nobody running the command. Build it and point your agent at the local path.
+Published on npm as [`realtime-avatar-mcp`](https://www.npmjs.com/package/realtime-avatar-mcp) — run it with `npx`, never installed into an app.
 
 An MCP server for Realtime Avatar. [`AGENTS.md`](../../AGENTS.md) tells a coding agent what
 the API is; this lets it *look* — at your avatars, your balance, your bill — instead of
 guessing ids and inventing shapes.
 
-```bash
-npm run build
-```
-
 ```jsonc
 {
   "mcpServers": {
     "realtime-avatar": {
-      "command": "node",
-      "args": ["/abs/path/to/realtime-avatar-sdk/libs/mcp/dist/bin.js"],
+      "command": "npx",
+      "args": ["-y", "realtime-avatar-mcp"],
       "env": { "REALTIME_AVATAR_API_KEY": "tic_test_…" }
     }
   }
 }
 ```
 
+Working on it in this repo? `npm run build`, then point `command` at `node` with
+`args: ["/abs/path/to/realtime-avatar-sdk/libs/mcp/dist/bin.js"]`.
+
 ## Tools
 
 | Tool | |

package/dist/server.d.ts

@@ -5,7 +5,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  * `test/server.test.ts` asserts the two stay equal; the equivalent constant in
  * `realtime-avatar` had that guard and this one did not, which is how it drifted.
  */
-export declare const MCP_VERSION = "0.4.0";
+export declare const MCP_VERSION = "0.5.0";
 /**
  * The Realtime Avatar MCP server.
  *

package/dist/server.js

@@ -10,7 +10,7 @@ import { RealtimeAvatar, isQueued } from "realtime-avatar";
  * `test/server.test.ts` asserts the two stay equal; the equivalent constant in
  * `realtime-avatar` had that guard and this one did not, which is how it drifted.
  */
-export const MCP_VERSION = "0.4.0";
+export const MCP_VERSION = "0.5.0";
 const MICROS_PER_CREDIT = 1_000_000;
 /** Extension -> asset kind, so a caller does not have to restate what the filename says. */
 const KIND_BY_EXT = {
@@ -109,6 +109,15 @@ export function createServer(options) {
             `total ${credits(total)}` +
             (page.nextCursor ? "\n(more pages available)" : ""));
     });
+    server.registerTool("list_clips", {
+        title: "List an avatar's clip library",
+        description: "The declared clip library: every non-retired clip with its render status, plus " +
+            "the library revision (pass it to set_clip_library as expectedRevision), the pose " +
+            "anchor and eligibility. status is the render JOB, not serveability — a clip " +
+            "re-rendering keeps serving its previous take.",
+        inputSchema: { avatarId: z.string() },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ avatarId }) => text(JSON.stringify(await rta.listClips(avatarId), null, 2)));
     if (!options.allowWrites)
         return server;
     // ── writes, opt-in only ────────────────────────────────────────────────────
@@ -153,9 +162,48 @@ export function createServer(options) {
             "Relay this payload to the browser byte-for-byte — the client SDK validates it " +
             "strictly and rejects a reshaped object.");
     });
+    server.registerTool("set_clip_library", {
+        title: "Declare an avatar's clip library",
+        description: "Declare the avatar's FULL desired clip library — a declaration, not a delta: " +
+            "unchanged clips are kept, new or changed ones are queued to render, omitted ones " +
+            "are retired. The 202 is acceptance, not readiness — poll list_clips until no row " +
+            "is queued or generating. Pass expectedRevision from list_clips so a concurrent " +
+            "writer surfaces as a 409 instead of a lost update. Does not spend credits.",
+        inputSchema: {
+            avatarId: z.string(),
+            clips: z.array(z.object({
+                clipId: z.string().describe("Stable id you choose; same id + same source = kept"),
+                role: z.enum(["idle", "listen", "gesture"]),
+                whenHint: z.string().optional().describe("Briefed to the character, like an actor"),
+                source: z.union([
+                    z.object({ motionPrompt: z.string() }),
+                    z.object({ assetId: z.string() }),
+                ]).describe("motionPrompt renders motion; assetId uploads a clip that must start AND end on the rest pose"),
+                durationSeconds: z.number().optional(),
+                reroll: z.boolean().optional().describe("Set true to force a re-render of the same prompt"),
+            })).max(12).describe("The COMPLETE library. Omitted clips are retired."),
+            expectedRevision: z.number().int().optional()
+                .describe("CAS: the revision you last read. Omit to declare unconditionally."),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ avatarId, clips, expectedRevision }) => {
+        const update = await rta.setClipLibrary(avatarId, { clips, expectedRevision });
+        const bucket = (label, ids) => `${label} (${ids.length})${ids.length ? `  ${ids.join(", ")}` : ""}`;
+        return text(`revision ${update.revision}\n` +
+            [
+                bucket("kept — still serving", update.plan.kept),
+                bucket("queued — rendering now", update.plan.queued),
+                bucket("retired — no longer live", update.plan.retired),
+            ].join("\n") +
+            (update.plan.queued.length
+                ? "\n\nQueued clips render in the background — poll list_clips until no row is queued or generating."
+                : ""));
+    });
     server.registerTool("sync_clips", {
         title: "Sync an avatar's clips",
-        description: "Prepare an avatar's clip set. Clips are prepared once and cached by URL hash, and " +
+        description: "DEPRECATED — this serves the sunsetting external-URL clip tier; declare the " +
+            "library with set_clip_library instead. Clips are prepared once and cached by URL " +
+            "hash, and " +
             "the serve path only LOADS that cache — so a clip you added but never synced does " +
             "nothing at all on the next call, silently. Idempotent: call it after every clip " +
             "change. Pass the complete set you want live; anything omitted is retired. This does " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtime-avatar-mcp",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "MCP server for Realtime Avatar — let a coding agent read your avatars, balance and bill directly.",
   "license": "MIT",
   "author": "The Influence Company",
@@ -55,7 +55,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "realtime-avatar": "0.4.0",
+    "realtime-avatar": "0.5.0",
     "zod": "^4.4.3"
   }
 }