realtime-avatar-mcp 0.9.0 → 0.10.0

package/README.md

@@ -41,7 +41,6 @@ With `REALTIME_AVATAR_ALLOW_WRITES=1`:
 | --- | --- | --- |
 | `set_loop` | Re-direct her resting loop from a new description | no |
 | `set_clip_library` | Declare an avatar's full clip set as JSON — the platform renders it | no |
-| `sync_clips` | **Deprecated.** The external-URL tier. Use `set_clip_library` | no |
 | `upload_asset` | Upload a file **from this machine's disk**, get a public URL | no |
 | `create_remote_asset` | Register a file already on the internet — no local copy | no |
 | `create_avatar_from_image` | Build an avatar from ONE still — the loop is generated | no |
@@ -54,7 +53,7 @@ The five tools above are **read-only**, and each carries `readOnlyHint` so a hos
 the annotation rather than on a name it has to recognise. Pointed at a production key, this
 server is no more dangerous than a dashboard you left open.
 
-`REALTIME_AVATAR_ALLOW_WRITES=1` adds the eight write tools. Only `start_call` costs credits,
+`REALTIME_AVATAR_ALLOW_WRITES=1` enables the write tools. Only `start_call` costs credits,
 and it **refuses a `tic_live_` key outright** — an operator who armed writes against a test
 key and later swapped in a production one should not discover it by being billed. Two
 independent gates, because one is a single mistake away from being none.
@@ -64,12 +63,11 @@ Two things to understand before arming writes:
 - **`upload_asset` reads local disk.** It opens whatever absolute path the agent names, on the
   machine running the server. Relative paths are refused rather than resolved against
   whatever directory the host spawned it in.
-- **The clip tools retire by omission.** Both `set_clip_library` and `sync_clips` take the
-  COMPLETE set you want live; anything missing from it stops being served. Each reports all
-  three buckets — kept/queued/retired — because "queued: 1" alone reads like nothing else
-  changed. Declare with `set_clip_library`: clips are JSON (`motionPrompt` or an uploaded
-  `assetId`) and the platform renders and hosts them. `sync_clips` is the deprecated tier
-  that takes URLs on your own storage.
+- **The clip declaration retires by omission.** `set_clip_library` takes the COMPLETE set;
+  anything missing from it stops being served. Its plan reports kept/queued/retired clips.
+  Declare `source.motionPrompt` or `source.assetId`; the platform hosts and prepares media.
+  The avatar's stored source is the implicit rest state — never declared, so the id
+  `primary` is reserved.
 
 ## Why an MCP server at all
 

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.9.0";
+export declare const MCP_VERSION = "0.10.0";
 /**
  * The Realtime Avatar MCP server.
  *

package/dist/server.js

@@ -3,14 +3,15 @@ import { stat } from "node:fs/promises";
 import { basename, extname, isAbsolute, resolve } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { RealtimeAvatar, isQueued } from "realtime-avatar";
+import { RealtimeAvatar, isQueued, clipLibraryDeclarationSchema, } from "realtime-avatar";
 /**
  * Mirrors this package's `version`. It reaches the wire twice — as the MCP server's own
  * identity, and inside the `User-Agent` — so a stale value misattributes real traffic.
  * `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.9.0";
+export const MCP_VERSION = "0.10.0";
+const clipLibraryInputSchema = clipLibraryDeclarationSchema.safeExtend({ avatarId: z.string() });
 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 = {
@@ -120,7 +121,7 @@ export function createServer(options) {
         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 " +
+            "anchor, default source, idle and event behavior, 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 },
@@ -175,26 +176,19 @@ export function createServer(options) {
             "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(20).describe("The COMPLETE library (≤20 clips, ≤8 idle, ≤2 listen). Omitted clips are retired."),
-            expectedRevision: z.number().int().optional()
-                .describe("CAS: the revision you last read. Omit to declare unconditionally."),
-        },
+            "writer surfaces as a 409 instead of a lost update. clips maps stable ids to sources; " +
+            "'primary' is reserved — the avatar's stored source is the implicit rest state, " +
+            "weight 1, and the one clip that may repeat. idle.clips are variations on resting, " +
+            "drawn uniformly and never twice running; idle.weight says how often a variation " +
+            "plays instead of resting. on.userSpeechStarted plays one listening reaction per " +
+            "speech episode; actions are requestable by description, never automatic. Clip " +
+            "references are checked before sending. New or changed sources can incur generation " +
+            "or pose-validation charges; behavior-only edits reuse media. Do not submit " +
+            "speculative declarations.",
+        inputSchema: clipLibraryInputSchema,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ avatarId, clips, expectedRevision }) => {
-        const update = await rta.setClipLibrary(avatarId, { clips, expectedRevision });
+    }, async ({ avatarId, ...declaration }) => {
+        const update = await rta.setClipLibrary(avatarId, declaration);
         const bucket = (label, ids) => `${label} (${ids.length})${ids.length ? `  ${ids.join(", ")}` : ""}`;
         return text(`revision ${update.revision}\n` +
             [
@@ -209,8 +203,8 @@ export function createServer(options) {
     server.registerTool("set_loop", {
         title: "Re-direct the resting loop",
         description: "Re-generate the RESTING LOOP — the video she plays when nothing else is happening — " +
-            "from a new one-sentence description. NOT a clip: a clip with role 'idle' is a " +
-            "variant spliced over the loop, and declaring one never changes what she rests in. " +
+            "from a new one-sentence description. This replaces the avatar's stored source, " +
+            "which is the implicit rest state her declared idle variations are weighted against. " +
             "Accepted immediately (202) and rendered over minutes; she stays ready and keeps " +
             "serving her previous loop the whole time, and the clip library is untouched. Bills " +
             "one video generation per call, so do not send it speculatively.",
@@ -228,33 +222,6 @@ export function createServer(options) {
             `She is still playing the previous loop until the new one is ready:\n  ${result.servingUrl ?? "—"}\n\n` +
             "Poll get_avatar; the swap publishes in one step. Her clips are unaffected.");
     });
-    server.registerTool("sync_clips", {
-        title: "Sync an avatar's clips",
-        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 " +
-            "not spend credits.",
-        inputSchema: {
-            avatarId: z.string(),
-            clipUrls: z.array(z.string().url()).max(64)
-                .describe("The COMPLETE set that should be live. Omitted clips are retired."),
-        },
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ avatarId, clipUrls }) => {
-        const result = await rta.syncClips(avatarId, clipUrls);
-        const line = (label, urls) => urls.length ? `${label} (${urls.length})\n  ${urls.join("\n  ")}` : `${label} (0)`;
-        return text([
-            line("queued — preparing now", result.queued),
-            line("ready — already cached", result.ready),
-            line("retired — no longer live", result.retired),
-        ].join("\n") +
-            (result.queued.length
-                ? "\n\nQueued clips are not usable until they finish preparing."
-                : ""));
-    });
     server.registerTool("upload_asset", {
         title: "Upload a local file",
         description: "Upload a file FROM THIS MACHINE'S DISK and get back a public URL usable as a clip " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "realtime-avatar-mcp",
-  "version": "0.9.0",
+  "version": "0.10.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.9.0",
+    "realtime-avatar": "0.10.0",
     "zod": "^4.4.3"
   }
 }