@eyejack-creator/mcp 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @eyejack-creator/mcp
 
-EyeJack Creator MCP server — connect **Claude Code / Codex / Cursor** to a live EyeJack editing session. Phase 3 of the agentic roadmap: **read-only** (scene inspection); writes, screenshots, and live sync arrive in later phases.
+EyeJack Creator MCP server — connect **Claude Code / Codex / Cursor** to a live EyeJack editing session. Your AI reads the scene, **edits it** (revision-checked writes land in the open editor live, with a human-readable action log) and **sees it** — the screenshot tool renders the editor's current view back to the model, closing the read → edit → inspect loop.
 
 ```
 Claude Code ──stdio──► @eyejack/mcp ──► @eyejack/creator-api ──► AppSync (agent session token)
@@ -19,16 +19,19 @@ claude mcp add eyejack \
 
 Other MCP clients consume the same `{command, args, env}` triple — Cursor (`.cursor/mcp.json` or Settings → MCP), Claude Desktop (`claude_desktop_config.json`), Codex (`~/.codex/config.toml` `mcp_servers`).
 
-2. Ask away: *"What's in my scene?" · "Which assets aren't placed yet?" · "How is the layout arranged?"*
+2. Ask away: *"What's in my scene?" · "Arrange the panels in a row" · "Duplicate the logo panel and place it on the left"* — edits appear in your open editor as they happen.
 
 The token lives as long as your editor tab (the tab heartbeats it; closing the tab lets it lapse within minutes). Pressing Connect AI anywhere supersedes the previous session — one active AI session per account.
 
-## Tools (v0)
+## Tools
 
-| Tool | Returns |
+| Tool | Does |
 |---|---|
 | `get_scene` | Full structured snapshot: metadata, parsed scene document (unity-space, degrees), `sceneRevision`, referenced files |
 | `list_assets` | The artwork's asset files with `usedInScene` resolution |
+| `update_scene` | Whole-document, revision-checked scene write — applied **live** in the open editor with your `ops` action log; conflicts return the current scene to rebase on |
+| `publish_artwork` | Publish the artwork to its public launch URL (draft/disabled → published) |
+| `screenshot` | JPEG of the editor's current view, rendered by the open tab and relayed over AppSync (auto-degraded under the transport cap) — the agent's eyes |
 | `get_session_status` | Session scope, active state, expiry |
 
 Tool descriptions embed the scene-format contract so models handle coordinates/conventions correctly without external docs.

package/dist/index.js

@@ -3,6 +3,7 @@
 // src/index.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { WebSocket as WsWebSocket } from "ws";
 
 // ../creator-api/dist/transport.js
 var GraphQLRequestError = class extends Error {
@@ -282,100 +283,6 @@ var STAGES = {
   }
 };
 
-// ../creator-api/dist/domains/agent.js
-var CREATE_AGENT_SESSION = `
-  mutation CreateAgentSession($artworkId: ID!) {
-    createAgentSession(artworkId: $artworkId) {
-      sessionId
-      token
-      artworkId
-      expiresAt
-    }
-  }
-`;
-var AGENT_SESSION_HEARTBEAT = `
-  mutation AgentSessionHeartbeat($sessionId: ID!) {
-    agentSessionHeartbeat(sessionId: $sessionId) {
-      sessionId
-      artworkId
-      status
-      expiresAt
-      lastHeartbeat
-    }
-  }
-`;
-var END_AGENT_SESSION = `
-  mutation EndAgentSession($sessionId: ID!) {
-    endAgentSession(sessionId: $sessionId) {
-      sessionId
-      artworkId
-      status
-      expiresAt
-    }
-  }
-`;
-var AGENT_GET_SESSION = `
-  query AgentGetSession {
-    agentGetSession {
-      sessionId
-      artworkId
-      userid
-      status
-      expiresAt
-      lastHeartbeat
-    }
-  }
-`;
-var AGENT_GET_SCENE = `
-  query AgentGetScene {
-    agentGetScene {
-      artworkId
-      name
-      status
-      sceneConfig
-      sceneRevision
-      modified
-      files {
-        type
-        path
-        checksum
-        fileID
-        size
-        width
-        height
-        pz
-      }
-    }
-  }
-`;
-var AgentApi = class {
-  constructor(client2) {
-    this.client = client2;
-  }
-  // --- Browser-side (Cognito) session lifecycle ---
-  async createSession(artworkId) {
-    const data = await this.client.execute(CREATE_AGENT_SESSION, { artworkId });
-    return data.createAgentSession;
-  }
-  async heartbeat(sessionId) {
-    const data = await this.client.execute(AGENT_SESSION_HEARTBEAT, { sessionId });
-    return data.agentSessionHeartbeat;
-  }
-  async endSession(sessionId) {
-    const data = await this.client.execute(END_AGENT_SESSION, { sessionId });
-    return data.endAgentSession;
-  }
-  // --- Agent-side (session token) scoped reads ---
-  async getSession() {
-    const data = await this.client.execute(AGENT_GET_SESSION);
-    return data.agentGetSession;
-  }
-  async getScene() {
-    const data = await this.client.execute(AGENT_GET_SCENE);
-    return data.agentGetScene;
-  }
-};
-
 // ../creator-api/dist/documents/artworks.js
 var ARTWORK_FIELDS = `
   id
@@ -546,79 +453,6 @@ var DELETE_ARTWORK = `
   }
 `;
 
-// ../creator-api/dist/domains/artworks.js
-var ArtworksApi = class {
-  constructor(client2, realtime) {
-    this.client = client2;
-    this.realtime = realtime;
-  }
-  /**
-   * Live artwork-record updates for a user (fattened onUpdateArtwork) over the
-   * SDK's realtime client. Payload fields are null for writers whose mutation
-   * selection didn't include them (e.g. creator-electron) — guard accordingly.
-   */
-  watchUser(userid, handlers) {
-    if (!this.realtime)
-      throw new Error("ArtworksApi.watchUser: realtime client not configured");
-    return this.realtime().subscribe(ON_UPDATE_ARTWORK, { userid }, {
-      next: (data) => {
-        if (data?.onUpdateArtwork)
-          handlers.next(data.onUpdateArtwork);
-      },
-      error: handlers.error
-    });
-  }
-  async get(id) {
-    const data = await this.client.execute(GET_ARTWORK, { id });
-    return data.getArtwork;
-  }
-  /** Batch fetch by ids (DynamoDB BatchGetItem under the hood). Missing ids are dropped. */
-  async getMany(ids) {
-    if (ids.length === 0)
-      return [];
-    const data = await this.client.execute(GET_ARTWORKS, {
-      ids
-    });
-    return (data.getArtworks || []).filter((a) => !!a);
-  }
-  async listByUser(userid, after) {
-    const data = await this.client.execute(GET_ARTWORKS_BY_USERID, { userid, after: after ?? null });
-    return data.getArtworksByUserid;
-  }
-  async create(input) {
-    const data = await this.client.execute(CREATE_ARTWORK, { input });
-    return data.createArtwork;
-  }
-  /**
-   * Legacy whole-record update — the same mutation the editor has always used.
-   * The server bumps sceneRevision whenever input contains a non-null
-   * sceneConfig. Fields absent from the input are left untouched; fields
-   * explicitly null are REMOVED from the record (VTL semantics) — mirror the
-   * legacy payload shape when swapping call sites.
-   */
-  async update(input) {
-    const data = await this.client.execute(UPDATE_ARTWORK, {
-      input
-    });
-    return data.updateArtwork;
-  }
-  async publish(id) {
-    const data = await this.client.execute(PUBLISH_ARTWORK, { id });
-    return data.publishArtwork;
-  }
-  async unpublish(id) {
-    const data = await this.client.execute(UNPUBLISH_ARTWORK, { id });
-    return data.unpublishArtwork;
-  }
-  /** Soft delete (status='deleted') via the backend's delete pipeline. */
-  async remove(id) {
-    const data = await this.client.execute(DELETE_ARTWORK, {
-      input: { id }
-    });
-    return data.deleteArtwork;
-  }
-};
-
 // ../creator-api/dist/domains/scene.js
 var MAX_DOC_BYTES = 3e5;
 function parseSceneConfig(raw) {
@@ -781,6 +615,326 @@ var SceneApi = class {
   }
 };
 
+// ../creator-api/dist/domains/agent.js
+var CREATE_AGENT_SESSION = `
+  mutation CreateAgentSession($artworkId: ID!) {
+    createAgentSession(artworkId: $artworkId) {
+      sessionId
+      token
+      artworkId
+      expiresAt
+    }
+  }
+`;
+var AGENT_SESSION_HEARTBEAT = `
+  mutation AgentSessionHeartbeat($sessionId: ID!) {
+    agentSessionHeartbeat(sessionId: $sessionId) {
+      sessionId
+      artworkId
+      status
+      expiresAt
+      lastHeartbeat
+    }
+  }
+`;
+var END_AGENT_SESSION = `
+  mutation EndAgentSession($sessionId: ID!) {
+    endAgentSession(sessionId: $sessionId) {
+      sessionId
+      artworkId
+      status
+      expiresAt
+    }
+  }
+`;
+var AGENT_GET_SESSION = `
+  query AgentGetSession {
+    agentGetSession {
+      sessionId
+      artworkId
+      userid
+      status
+      expiresAt
+      lastHeartbeat
+    }
+  }
+`;
+var GET_ARTWORK_SCENE_BACKUP = `
+  query GetArtworkSceneBackup($artworkId: ID!) {
+    getArtworkSceneBackup(artworkId: $artworkId) {
+      artworkId
+      sessionId
+      sceneConfig
+      sceneRevision
+      createdAt
+    }
+  }
+`;
+var REQUEST_AGENT_ACTION = `
+  mutation RequestAgentAction($sessionId: ID!, $requestId: ID!, $actionType: String!, $payload: String) {
+    requestAgentAction(sessionId: $sessionId, requestId: $requestId, actionType: $actionType, payload: $payload) {
+      sessionId
+      requestId
+      actionType
+      payload
+    }
+  }
+`;
+var POST_AGENT_ACTION_RESULT = `
+  mutation PostAgentActionResult($sessionId: ID!, $requestId: ID!, $ok: Boolean!, $resultType: String, $payload: String, $error: String) {
+    postAgentActionResult(sessionId: $sessionId, requestId: $requestId, ok: $ok, resultType: $resultType, payload: $payload, error: $error) {
+      sessionId
+      requestId
+      ok
+      resultType
+      payload
+      error
+    }
+  }
+`;
+var ON_AGENT_ACTION = `
+  subscription OnAgentAction($sessionId: ID!) {
+    onAgentAction(sessionId: $sessionId) {
+      sessionId
+      requestId
+      actionType
+      payload
+    }
+  }
+`;
+var ON_AGENT_ACTION_RESULT = `
+  subscription OnAgentActionResult($sessionId: ID!) {
+    onAgentActionResult(sessionId: $sessionId) {
+      sessionId
+      requestId
+      ok
+      resultType
+      payload
+      error
+    }
+  }
+`;
+var AGENT_GET_SCENE = `
+  query AgentGetScene {
+    agentGetScene {
+      artworkId
+      name
+      status
+      sceneConfig
+      sceneRevision
+      modified
+      files {
+        type
+        path
+        checksum
+        fileID
+        size
+        width
+        height
+        pz
+      }
+    }
+  }
+`;
+var AgentApi = class {
+  constructor(client2, realtime) {
+    this.client = client2;
+    this.realtime = realtime;
+  }
+  // --- Browser-side (Cognito) session lifecycle ---
+  async createSession(artworkId) {
+    const data = await this.client.execute(CREATE_AGENT_SESSION, { artworkId });
+    return data.createAgentSession;
+  }
+  async heartbeat(sessionId) {
+    const data = await this.client.execute(AGENT_SESSION_HEARTBEAT, { sessionId });
+    return data.agentSessionHeartbeat;
+  }
+  async endSession(sessionId) {
+    const data = await this.client.execute(END_AGENT_SESSION, { sessionId });
+    return data.endAgentSession;
+  }
+  /**
+   * The scene snapshot createAgentSession took before the (most recent)
+   * session started — what "Revert AI changes" restores. Browser-side
+   * (Cognito, owner-checked); null when no session ever ran or the 7-day
+   * TTL reaped it.
+   */
+  async getSceneBackup(artworkId) {
+    const data = await this.client.execute(GET_ARTWORK_SCENE_BACKUP, { artworkId });
+    return data.getArtworkSceneBackup;
+  }
+  // --- Agent-side (session token) scoped reads ---
+  async getSession() {
+    const data = await this.client.execute(AGENT_GET_SESSION);
+    return data.agentGetSession;
+  }
+  async getScene() {
+    const data = await this.client.execute(AGENT_GET_SCENE);
+    return data.agentGetScene;
+  }
+  // --- Agent-side (session token) writes (P4) ---
+  /**
+   * Revision-checked scene write with a session token. Same mutation and
+   * fan-out as SceneApi.save, but the conflict re-read uses agentGetScene
+   * (a session token cannot call getArtwork) and hands back the fresh record
+   * so the agent can rebase in one round trip. The backend hard-scopes the
+   * write to the session's artwork regardless of artworkId.
+   */
+  async saveScene(params) {
+    const raw = typeof params.doc === "string" ? params.doc : stringifySceneDocument(params.doc);
+    if (typeof params.doc !== "string") {
+      const errors = validateSceneDocument(params.doc, params.validateAgainstFiles).filter((i) => i.level === "error");
+      if (errors.length > 0) {
+        throw new Error(`Refusing to save invalid scene document: ${errors.map((i) => i.message).join("; ")}`);
+      }
+    }
+    try {
+      const data = await this.client.execute(UPDATE_ARTWORK_SCENE, {
+        input: {
+          id: params.artworkId,
+          expectedRevision: params.expectedRevision,
+          sceneConfig: raw,
+          ops: params.ops ?? null,
+          originId: params.originId ?? null
+        }
+      });
+      const payload = data.updateArtworkScene;
+      return { conflict: false, revision: payload.sceneRevision, modified: payload.modified ?? null, payload };
+    } catch (err) {
+      if (err instanceof GraphQLRequestError && err.errorType === "SceneRevisionConflict") {
+        const current = await this.getScene().catch(() => null);
+        return { conflict: true, currentRevision: current?.sceneRevision ?? null, current };
+      }
+      throw err;
+    }
+  }
+  /**
+   * Publish the session's artwork (guarded server-side: a session token can
+   * publish ONLY its own artwork; publish transitions draft/disabled →
+   * published — an already-published artwork rejects with a condition error).
+   */
+  async publish(artworkId) {
+    const data = await this.client.execute(PUBLISH_ARTWORK, {
+      id: artworkId
+    });
+    return data.publishArtwork;
+  }
+  // --- Runtime action channel (P5) ---
+  /** AGENT side: fire an action request into the session's channel. */
+  async requestAction(params) {
+    const data = await this.client.execute(REQUEST_AGENT_ACTION, { ...params, payload: params.payload ?? null });
+    return data.requestAgentAction;
+  }
+  /** BROWSER side: answer an action request (session-owner-checked server-side). */
+  async postActionResult(params) {
+    const data = await this.client.execute(POST_AGENT_ACTION_RESULT, {
+      ...params,
+      resultType: params.resultType ?? null,
+      payload: params.payload ?? null,
+      error: params.error ?? null
+    });
+    return data.postAgentActionResult;
+  }
+  /** BROWSER side: listen for the agent's action requests (subscribe-time owner check). */
+  watchActions(sessionId, handlers) {
+    if (!this.realtime)
+      throw new Error("AgentApi.watchActions: realtime client not configured");
+    return this.realtime().subscribe(ON_AGENT_ACTION, { sessionId }, {
+      next: (data) => {
+        if (data?.onAgentAction)
+          handlers.next(data.onAgentAction);
+      },
+      error: handlers.error
+    });
+  }
+  /** AGENT side: listen for the browser's results (subscribe-time session pin). */
+  watchActionResults(sessionId, handlers) {
+    if (!this.realtime)
+      throw new Error("AgentApi.watchActionResults: realtime client not configured");
+    return this.realtime().subscribe(ON_AGENT_ACTION_RESULT, { sessionId }, {
+      next: (data) => {
+        if (data?.onAgentActionResult)
+          handlers.next(data.onAgentActionResult);
+      },
+      error: handlers.error
+    });
+  }
+};
+
+// ../creator-api/dist/domains/artworks.js
+var ArtworksApi = class {
+  constructor(client2, realtime) {
+    this.client = client2;
+    this.realtime = realtime;
+  }
+  /**
+   * Live artwork-record updates for a user (fattened onUpdateArtwork) over the
+   * SDK's realtime client. Payload fields are null for writers whose mutation
+   * selection didn't include them (e.g. creator-electron) — guard accordingly.
+   */
+  watchUser(userid, handlers) {
+    if (!this.realtime)
+      throw new Error("ArtworksApi.watchUser: realtime client not configured");
+    return this.realtime().subscribe(ON_UPDATE_ARTWORK, { userid }, {
+      next: (data) => {
+        if (data?.onUpdateArtwork)
+          handlers.next(data.onUpdateArtwork);
+      },
+      error: handlers.error
+    });
+  }
+  async get(id) {
+    const data = await this.client.execute(GET_ARTWORK, { id });
+    return data.getArtwork;
+  }
+  /** Batch fetch by ids (DynamoDB BatchGetItem under the hood). Missing ids are dropped. */
+  async getMany(ids) {
+    if (ids.length === 0)
+      return [];
+    const data = await this.client.execute(GET_ARTWORKS, {
+      ids
+    });
+    return (data.getArtworks || []).filter((a) => !!a);
+  }
+  async listByUser(userid, after) {
+    const data = await this.client.execute(GET_ARTWORKS_BY_USERID, { userid, after: after ?? null });
+    return data.getArtworksByUserid;
+  }
+  async create(input) {
+    const data = await this.client.execute(CREATE_ARTWORK, { input });
+    return data.createArtwork;
+  }
+  /**
+   * Legacy whole-record update — the same mutation the editor has always used.
+   * The server bumps sceneRevision whenever input contains a non-null
+   * sceneConfig. Fields absent from the input are left untouched; fields
+   * explicitly null are REMOVED from the record (VTL semantics) — mirror the
+   * legacy payload shape when swapping call sites.
+   */
+  async update(input) {
+    const data = await this.client.execute(UPDATE_ARTWORK, {
+      input
+    });
+    return data.updateArtwork;
+  }
+  async publish(id) {
+    const data = await this.client.execute(PUBLISH_ARTWORK, { id });
+    return data.publishArtwork;
+  }
+  async unpublish(id) {
+    const data = await this.client.execute(UNPUBLISH_ARTWORK, { id });
+    return data.unpublishArtwork;
+  }
+  /** Soft delete (status='deleted') via the backend's delete pipeline. */
+  async remove(id) {
+    const data = await this.client.execute(DELETE_ARTWORK, {
+      input: { id }
+    });
+    return data.deleteArtwork;
+  }
+};
+
 // ../creator-api/dist/client.js
 function createCreatorClient(options) {
   const endpoint = options.endpoint ?? (options.stage ? STAGES[options.stage].graphqlEndpoint : void 0);
@@ -800,7 +954,7 @@ function createCreatorClient(options) {
     }
     return realtimeInstance;
   };
-  const agent = new AgentApi(graphql);
+  const agent = new AgentApi(graphql, getRealtime);
   const artworks = new ArtworksApi(graphql, getRealtime);
   const scene = new SceneApi(graphql, artworks, getRealtime);
   return {
@@ -841,10 +995,13 @@ function loadConfig() {
     console.error(`Unknown EYEJACK_STAGE "${stage}" and no EYEJACK_GRAPHQL_ENDPOINT set.`);
     process.exit(1);
   }
-  return { token, endpoint, stage };
+  const launchBaseUrl = stage === "prd" ? "https://launch.eyejack.io" : "https://launch.eyejack.dev";
+  return { token, endpoint, stage, launchBaseUrl };
 }
 
 // src/tools.ts
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
 var SCENE_CONTRACT = `Scene document conventions (the stored EyeJack format):
 - Coordinate space is unity-style left-handed; rotations are in DEGREES.
 - Only scenes[0] is rendered ("root"); its children[] are the panels/models.
@@ -852,7 +1009,7 @@ var SCENE_CONTRACT = `Scene document conventions (the stored EyeJack format):
 - A child's assetID must equal a files[].fileID (the asset it displays).
 - files[] entries carry type (image | video | video-alpha | glb | image-target | cover), path (CDN url), width, height.
 - Assets are provisioned by the human in the browser for now \u2014 there is no upload tool yet.
-- sceneRevision is the concurrency counter; every write bumps it (writes arrive in a later phase).`;
+- sceneRevision is the optimistic-concurrency counter: pass your latest read's revision as expectedRevision when writing; every successful write bumps it by 1.`;
 var REJECTED_HINT = 'Session token rejected (expired, ended, or superseded). Ask the user to press "Connect AI" in the EyeJack editor again and update EYEJACK_SESSION_TOKEN.';
 function errorText(err) {
   if (err instanceof TransportError && (err.status === 401 || err.status === 403)) {
@@ -873,7 +1030,14 @@ var asError = (err) => ({
   content: [{ type: "text", text: errorText(err) }],
   isError: true
 });
-function registerTools(server2, client2) {
+function registerTools(server2, client2, options) {
+  let cachedArtworkId = null;
+  const artworkId = async () => {
+    if (!cachedArtworkId) {
+      cachedArtworkId = (await client2.agent.getSession()).artworkId;
+    }
+    return cachedArtworkId;
+  };
   server2.tool(
     "get_scene",
     `Read the full structured snapshot of the connected EyeJack artwork: metadata, the parsed scene document, the current sceneRevision, and the asset files it references. This session's token is scoped to exactly one artwork \u2014 there is nothing to select. ${SCENE_CONTRACT}`,
@@ -925,6 +1089,146 @@ function registerTools(server2, client2) {
       }
     }
   );
+  const updateSceneParams = {
+    expectedRevision: z.number().int().min(0).describe("The sceneRevision your edit is based on, from your latest read."),
+    scene: z.record(z.any()).describe(
+      "The complete scene document to store: { version, settings?, assets, scenes }. Top-level keys are frozen to these; per-child additive keys are allowed."
+    ),
+    ops: z.array(z.string().min(1).max(200)).min(1).max(10).describe(
+      'Short human-readable summaries of what changed (e.g. "Moved the logo panel 0.5 left"). Shown live to the user in their editor.'
+    )
+  };
+  server2.tool(
+    "update_scene",
+    `Write the connected artwork's scene (whole-document, revision-checked). The user's open editor applies the change LIVE and shows your ops descriptions, so keep ops honest and human-readable. Rules: send the COMPLETE document (this is not a patch \u2014 anything you omit is deleted); preserve any unknown keys you read; base expectedRevision on your latest get_scene (or the revision returned by your last successful update_scene). On a revision conflict nothing is written \u2014 the response includes the current scene so you can rebase and retry. ${SCENE_CONTRACT}`,
+    updateSceneParams,
+    async (args) => {
+      const { expectedRevision, scene, ops } = args;
+      try {
+        const result = await client2.agent.saveScene({
+          artworkId: await artworkId(),
+          doc: scene,
+          expectedRevision,
+          ops,
+          originId: "agent:mcp"
+        });
+        if (result.conflict) {
+          return asText({
+            conflict: true,
+            message: "Not written: the scene changed since your read (the human may have edited it). Rebase your change onto the current scene below and retry with its revision.",
+            currentRevision: result.currentRevision,
+            currentScene: result.current ? parseSceneConfig(result.current.sceneConfig) : null
+          });
+        }
+        return asText({
+          conflict: false,
+          revision: result.revision,
+          message: `Saved (revision ${result.revision}). The user's editor has applied your change live.`
+        });
+      } catch (err) {
+        return asError(err);
+      }
+    }
+  );
+  server2.tool(
+    "publish_artwork",
+    `Publish the connected artwork so it is publicly viewable at its launch URL (${options.launchBaseUrl}/<artworkId>). Only works when the artwork is in draft or disabled state \u2014 already-published artworks reject (their live page already reflects saved scene changes). Ask the user before publishing unless they already told you to.`,
+    async () => {
+      try {
+        const id = await artworkId();
+        const artwork = await client2.agent.publish(id);
+        return asText({
+          id: artwork.id,
+          status: artwork.status,
+          url: `${options.launchBaseUrl}/${artwork.id}`
+        });
+      } catch (err) {
+        if (err instanceof GraphQLRequestError && `${err.errorType} ${err.message}`.includes("ConditionalCheckFailed")) {
+          return asText(
+            "Nothing to do: the artwork is already published (publish only transitions draft/disabled \u2192 published). Saved scene changes are already live on its launch URL."
+          );
+        }
+        return asError(err);
+      }
+    }
+  );
+  let resultSub = null;
+  const pendingResults = /* @__PURE__ */ new Map();
+  const ensureResultListener = async () => {
+    if (resultSub) return;
+    resultSub = client2.agent.watchActionResults(options.sessionId, {
+      next: (result) => {
+        const resolve = pendingResults.get(result.requestId);
+        if (resolve) {
+          pendingResults.delete(result.requestId);
+          resolve(result);
+        }
+      },
+      error: (err) => {
+        console.error("[eyejack-mcp] action result channel error:", err);
+      }
+    });
+    await new Promise((resolve) => setTimeout(resolve, 800));
+  };
+  const requestOnce = async (payload, timeoutMs) => {
+    const requestId = randomUUID();
+    const waiter = new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        pendingResults.delete(requestId);
+        resolve(null);
+      }, timeoutMs);
+      pendingResults.set(requestId, (result) => {
+        clearTimeout(timer);
+        resolve(result);
+      });
+    });
+    await client2.agent.requestAction({
+      sessionId: options.sessionId,
+      requestId,
+      actionType: "SCREENSHOT",
+      payload
+    });
+    return waiter;
+  };
+  const screenshotParams = {
+    width: z.number().int().min(64).max(2048).optional().describe("Image width in px (default 1280; height follows the editor aspect)."),
+    quality: z.number().min(0.1).max(1).optional().describe("JPEG quality 0.1\u20131 (default 0.8; auto-degraded if the image exceeds the transport cap).")
+  };
+  server2.tool(
+    "screenshot",
+    "See the scene: capture a rendered JPEG of the connected artwork exactly as the user's open editor shows it. Use it to visually verify your update_scene edits (read \u2192 edit \u2192 screenshot \u2192 correct). Requires the editor tab open in a desktop browser; if nobody answers, the tab is closed, hidden, or on a touch device.",
+    screenshotParams,
+    async (args) => {
+      const { width, quality } = args;
+      try {
+        await ensureResultListener();
+        const payload = JSON.stringify({ width: width ?? 1280, quality: quality ?? 0.8 });
+        let result = await requestOnce(payload, 2e4);
+        if (!result) {
+          result = await requestOnce(payload, 2e4);
+        }
+        if (!result) {
+          return asText(
+            "No response from the editor tab (timed out twice). Ask the user to check the EyeJack editor tab is open, visible, and showing this artwork, then try again."
+          );
+        }
+        if (!result.ok || !result.payload) {
+          return asText(`The editor could not capture a screenshot: ${result.error || "unknown error"}`);
+        }
+        return {
+          content: [
+            {
+              type: "image",
+              data: result.payload,
+              mimeType: result.resultType || "image/jpeg"
+            }
+          ]
+        };
+      } catch (err) {
+        return asError(err);
+      }
+    }
+  );
   server2.tool(
     "get_session_status",
     "Inspect the agent session itself: which artwork it is scoped to, whether it is active, and when it expires (the editor tab heartbeats it while open; closing the tab lets it lapse).",
@@ -950,13 +1254,20 @@ function registerTools(server2, client2) {
 var config = loadConfig();
 var client = createCreatorClient({
   endpoint: config.endpoint,
-  auth: new StaticTokenProvider(config.token)
+  auth: new StaticTokenProvider(config.token),
+  // Node ≥22 ships a global WebSocket; older runtimes use `ws`. Needed for
+  // the screenshot tool's result subscription.
+  WebSocketImpl: globalThis.WebSocket ?? WsWebSocket
 });
 var server = new McpServer({
   name: "eyejack-creator",
-  version: "0.1.0"
+  version: "0.3.0"
+});
+registerTools(server, client, {
+  launchBaseUrl: config.launchBaseUrl,
+  // The token is "<sessionId>.<secret>" — the channel tools need the id.
+  sessionId: config.token.split(".")[0]
 });
-registerTools(server, client);
 var transport = new StdioServerTransport();
 await server.connect(transport);
-console.error(`eyejack-mcp connected (stage: ${config.stage}) \u2014 read-only tools ready.`);
+console.error(`eyejack-mcp connected (stage: ${config.stage}) \u2014 scene read/write + screenshot tools ready.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eyejack-creator/mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "EyeJack Creator MCP server — connect Claude Code / Codex / Cursor to a live EyeJack editing session.",
   "license": "UNLICENSED",
   "type": "module",
@@ -20,7 +20,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "zod": "^3.23.0"
+    "ws": "^8.18.0",
+    "zod": "3.24.2"
   },
   "devDependencies": {
     "esbuild": "^0.24.0",
@@ -29,7 +30,7 @@
   },
   "scripts": {
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "build": "npm run typecheck && rm -rf dist && esbuild src/index.ts --bundle --platform=node --format=esm --target=node18 --outfile=dist/index.js --external:@modelcontextprotocol/sdk --external:zod --banner:js=\"#!/usr/bin/env node\"",
+    "build": "npm run typecheck && rm -rf dist && esbuild src/index.ts --bundle --platform=node --format=esm --target=node18 --outfile=dist/index.js --external:@modelcontextprotocol/sdk --external:zod --external:ws --banner:js=\"#!/usr/bin/env node\"",
     "smoke": "node examples/smoke-client.mjs"
   }
 }