@eyejack-creator/mcp 0.2.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. Your AI reads the scene **and edits it**: revision-checked writes land in the open editor live, with a human-readable action log. Screenshots arrive in a later phase.
+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)
@@ -31,6 +31,7 @@ The token lives as long as your editor tab (the tab heartbeats it; closing the t
 | `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 {
@@ -669,6 +670,50 @@ var GET_ARTWORK_SCENE_BACKUP = `
     }
   }
 `;
+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 {
@@ -692,8 +737,9 @@ var AGENT_GET_SCENE = `
   }
 `;
 var AgentApi = class {
-  constructor(client2) {
+  constructor(client2, realtime) {
     this.client = client2;
+    this.realtime = realtime;
   }
   // --- Browser-side (Cognito) session lifecycle ---
   async createSession(artworkId) {
@@ -774,6 +820,46 @@ var AgentApi = class {
     });
     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
@@ -868,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 {
@@ -914,6 +1000,7 @@ function loadConfig() {
 }
 
 // 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.
@@ -1065,6 +1152,83 @@ function registerTools(server2, client2, options) {
       }
     }
   );
+  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).",
@@ -1090,13 +1254,20 @@ function registerTools(server2, client2, options) {
 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.2.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, { launchBaseUrl: config.launchBaseUrl });
 var transport = new StdioServerTransport();
 await server.connect(transport);
-console.error(`eyejack-mcp connected (stage: ${config.stage}) \u2014 scene read/write 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.2.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,6 +20,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "ws": "^8.18.0",
     "zod": "3.24.2"
   },
   "devDependencies": {
@@ -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"
   }
 }