@eyejack-creator/mcp 0.1.0 → 0.2.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 **and edits it**: revision-checked writes land in the open editor live, with a human-readable action log. Screenshots arrive in a later phase.
 
 ```
 Claude Code ──stdio──► @eyejack/mcp ──► @eyejack/creator-api ──► AppSync (agent session token)
@@ -19,16 +19,18 @@ 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) |
 | `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

@@ -282,100 +282,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 +452,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 +614,241 @@ 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 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;
+  }
+  /**
+   * 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;
+  }
+};
+
+// ../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);
@@ -841,10 +909,12 @@ 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 { 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 +922,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 +943,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 +1002,69 @@ 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);
+      }
+    }
+  );
   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).",
@@ -954,9 +1094,9 @@ var client = createCreatorClient({
 });
 var server = new McpServer({
   name: "eyejack-creator",
-  version: "0.1.0"
+  version: "0.2.0"
 });
-registerTools(server, client);
+registerTools(server, client, { launchBaseUrl: config.launchBaseUrl });
 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 tools ready.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eyejack-creator/mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "EyeJack Creator MCP server — connect Claude Code / Codex / Cursor to a live EyeJack editing session.",
   "license": "UNLICENSED",
   "type": "module",
@@ -20,7 +20,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "zod": "^3.23.0"
+    "zod": "3.24.2"
   },
   "devDependencies": {
     "esbuild": "^0.24.0",