@eyejack-creator/mcp 0.1.0

package/README.md

@@ -0,0 +1,42 @@
+# @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.
+
+```
+Claude Code ──stdio──► @eyejack/mcp ──► @eyejack/creator-api ──► AppSync (agent session token)
+```
+
+## Connect
+
+1. Open your artwork in the EyeJack Creator and press **Connect AI** — it mints a short-lived session token scoped to *that artwork only* and shows the exact command:
+
+```bash
+claude mcp add eyejack \
+  --env EYEJACK_SESSION_TOKEN=<token> \
+  --env EYEJACK_STAGE=dev \
+  -- npx -y @eyejack-creator/mcp
+```
+
+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?"*
+
+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)
+
+| Tool | Returns |
+|---|---|
+| `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 |
+| `get_session_status` | Session scope, active state, expiry |
+
+Tool descriptions embed the scene-format contract so models handle coordinates/conventions correctly without external docs.
+
+## Develop
+
+```bash
+pnpm --filter @eyejack-creator/mcp build
+# End-to-end smoke (spawns the server over stdio like a real client):
+EYEJACK_SESSION_TOKEN=<token> node examples/smoke-client.mjs
+```

package/dist/index.js

@@ -0,0 +1,962 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// ../creator-api/dist/transport.js
+var GraphQLRequestError = class extends Error {
+  constructor(message, errors, data) {
+    super(message);
+    this.errors = errors;
+    this.data = data;
+    this.name = "GraphQLRequestError";
+  }
+  /** First AppSync errorType, e.g. 'UnauthorizedException' or 'SceneRevisionConflict'. */
+  get errorType() {
+    return this.errors[0]?.errorType;
+  }
+  /** Payload attached via $util.error's data/errorInfo args (may be absent). */
+  get errorData() {
+    const first = this.errors[0];
+    return first?.data ?? first?.errorInfo ?? void 0;
+  }
+};
+var TransportError = class extends Error {
+  constructor(message, status, bodyText) {
+    super(message);
+    this.status = status;
+    this.bodyText = bodyText;
+    this.name = "TransportError";
+  }
+};
+var GraphQLClient = class {
+  constructor(options) {
+    this.endpoint = options.endpoint;
+    this.auth = options.auth;
+    const impl = options.fetchImpl ?? globalThis.fetch;
+    if (!impl) {
+      throw new Error("GraphQLClient: no fetch available \u2014 pass fetchImpl (Node < 18?)");
+    }
+    this.fetchImpl = impl.bind(globalThis);
+  }
+  /** Execute a query/mutation and return `data` (throws GraphQLRequestError / TransportError). */
+  async execute(query, variables) {
+    const body = JSON.stringify(variables === void 0 ? { query } : { query, variables });
+    const baseHeaders = { "Content-Type": "application/json" };
+    const authHeaders = await this.auth.authorize({
+      url: this.endpoint,
+      method: "POST",
+      headers: baseHeaders,
+      body
+    });
+    let response;
+    try {
+      response = await this.fetchImpl(this.endpoint, {
+        method: "POST",
+        headers: { ...baseHeaders, ...authHeaders },
+        body
+      });
+    } catch (err) {
+      throw new TransportError(`Network error calling ${this.endpoint}: ${err.message}`);
+    }
+    if (!response.ok) {
+      const text = await response.text().catch(() => "");
+      throw new TransportError(`HTTP ${response.status} from GraphQL endpoint`, response.status, text);
+    }
+    const json = await response.json();
+    if (json.errors && json.errors.length > 0) {
+      const first = json.errors[0];
+      throw new GraphQLRequestError(first?.message ?? "GraphQL request failed", json.errors, json.data);
+    }
+    if (json.data === void 0 || json.data === null) {
+      throw new GraphQLRequestError("GraphQL response contained no data", []);
+    }
+    return json.data;
+  }
+};
+
+// ../creator-api/dist/realtime.js
+var KA_GRACE_MS = 5 * 6e4;
+var RECONNECT_BASE_MS = 1e3;
+var RECONNECT_MAX_MS = 3e4;
+var AppSyncRealtimeClient = class {
+  constructor(options) {
+    this.ws = null;
+    this.connecting = null;
+    this.subs = /* @__PURE__ */ new Map();
+    this.nextId = 1;
+    this.kaTimeoutMs = KA_GRACE_MS;
+    this.kaTimer = null;
+    this.reconnectAttempt = 0;
+    this.closedByUser = false;
+    const url = new URL(options.graphqlEndpoint);
+    this.httpHost = url.host;
+    this.realtimeUrl = `wss://${url.host.replace("appsync-api", "appsync-realtime-api")}${url.pathname}`;
+    this.auth = options.auth;
+    const impl = options.WebSocketImpl ?? globalThis.WebSocket;
+    if (!impl)
+      throw new Error("AppSyncRealtimeClient: no WebSocket available \u2014 pass WebSocketImpl");
+    this.WebSocketImpl = impl;
+    this.onTransportEvent = options.onTransportEvent ?? (() => {
+    });
+  }
+  subscribe(query, variables, handlers) {
+    const id = String(this.nextId++);
+    const sub = { id, query, variables, handlers, started: false };
+    this.subs.set(id, sub);
+    this.ensureConnected().then(() => this.startSub(sub)).catch((err) => handlers.error?.(err));
+    return {
+      unsubscribe: () => {
+        this.subs.delete(id);
+        if (this.ws && this.ws.readyState === 1) {
+          this.ws.send(JSON.stringify({ id, type: "stop" }));
+        }
+        if (this.subs.size === 0)
+          this.teardown("idle");
+      }
+    };
+  }
+  /** Close the socket and stop reconnecting (subscriptions are NOT resumed). */
+  close() {
+    this.closedByUser = true;
+    this.teardown("closed-by-user");
+  }
+  async authHeader() {
+    const headers = await this.auth.authorize({
+      url: `https://${this.httpHost}/graphql`,
+      method: "WS",
+      headers: {},
+      body: "{}"
+    });
+    return { host: this.httpHost, ...headers };
+  }
+  b64(obj) {
+    const json = JSON.stringify(obj);
+    const btoaFn = globalThis.btoa;
+    if (btoaFn)
+      return btoaFn(unescape(encodeURIComponent(json)));
+    return Buffer.from(json, "utf8").toString("base64");
+  }
+  ensureConnected() {
+    if (this.ws && this.ws.readyState === 1)
+      return Promise.resolve();
+    if (this.connecting)
+      return this.connecting;
+    this.closedByUser = false;
+    this.connecting = new Promise((resolve, reject) => {
+      (async () => {
+        const auth = await this.authHeader();
+        const url = `${this.realtimeUrl}?header=${this.b64(auth)}&payload=${this.b64({})}`;
+        const ws = new this.WebSocketImpl(url, ["graphql-ws"]);
+        this.ws = ws;
+        const fail = (err) => {
+          this.connecting = null;
+          reject(err);
+        };
+        ws.onopen = () => ws.send(JSON.stringify({ type: "connection_init" }));
+        ws.onerror = (e) => {
+          this.onTransportEvent("socket-error", e);
+          fail(new Error("AppSync realtime socket error"));
+        };
+        ws.onclose = () => this.handleClose();
+        ws.onmessage = (event) => {
+          const msg = JSON.parse(String(event.data));
+          switch (msg.type) {
+            case "connection_ack": {
+              this.kaTimeoutMs = msg.payload?.connectionTimeoutMs ?? KA_GRACE_MS;
+              this.resetKaWatchdog();
+              this.reconnectAttempt = 0;
+              this.connecting = null;
+              resolve();
+              break;
+            }
+            case "ka":
+              this.resetKaWatchdog();
+              break;
+            case "start_ack":
+              break;
+            case "data": {
+              const sub = msg.id ? this.subs.get(msg.id) : void 0;
+              const data = msg.payload?.data;
+              if (sub && data !== void 0)
+                sub.handlers.next(data);
+              break;
+            }
+            case "error":
+            case "connection_error": {
+              const sub = msg.id ? this.subs.get(msg.id) : void 0;
+              this.onTransportEvent("protocol-error", msg.payload);
+              if (sub)
+                sub.handlers.error?.(msg.payload);
+              else
+                fail(new Error(`AppSync realtime error: ${JSON.stringify(msg.payload)}`));
+              break;
+            }
+            case "complete":
+              if (msg.id)
+                this.subs.delete(msg.id);
+              break;
+          }
+        };
+      })().catch((err) => {
+        this.connecting = null;
+        reject(err);
+      });
+    });
+    return this.connecting;
+  }
+  async startSub(sub) {
+    if (!this.ws || this.ws.readyState !== 1 || sub.started)
+      return;
+    const auth = await this.authHeader();
+    if (!this.subs.has(sub.id))
+      return;
+    sub.started = true;
+    this.ws.send(JSON.stringify({
+      id: sub.id,
+      type: "start",
+      payload: {
+        data: JSON.stringify({ query: sub.query, variables: sub.variables ?? {} }),
+        extensions: { authorization: auth }
+      }
+    }));
+  }
+  resetKaWatchdog() {
+    if (this.kaTimer)
+      clearTimeout(this.kaTimer);
+    this.kaTimer = setTimeout(() => {
+      this.onTransportEvent("ka-timeout");
+      try {
+        this.ws?.close();
+      } catch {
+      }
+    }, this.kaTimeoutMs);
+  }
+  handleClose() {
+    if (this.kaTimer)
+      clearTimeout(this.kaTimer);
+    this.kaTimer = null;
+    this.ws = null;
+    this.connecting = null;
+    for (const sub of this.subs.values())
+      sub.started = false;
+    if (this.closedByUser || this.subs.size === 0)
+      return;
+    const delay = Math.min(RECONNECT_BASE_MS * 2 ** this.reconnectAttempt, RECONNECT_MAX_MS);
+    this.reconnectAttempt += 1;
+    this.onTransportEvent("reconnecting", { attempt: this.reconnectAttempt, delayMs: delay });
+    setTimeout(() => {
+      if (this.subs.size === 0)
+        return;
+      this.ensureConnected().then(() => {
+        for (const sub of this.subs.values())
+          void this.startSub(sub);
+      }).catch((err) => this.onTransportEvent("reconnect-failed", err));
+    }, delay);
+  }
+  teardown(reason) {
+    this.onTransportEvent("teardown", reason);
+    if (this.kaTimer)
+      clearTimeout(this.kaTimer);
+    this.kaTimer = null;
+    const ws = this.ws;
+    this.ws = null;
+    this.connecting = null;
+    try {
+      ws?.close();
+    } catch {
+    }
+  }
+};
+
+// ../creator-api/dist/stages.js
+var STAGES = {
+  dev: {
+    graphqlEndpoint: "https://4mtyioftuncyll6x4xlsaafjt4.appsync-api.us-east-1.amazonaws.com/graphql",
+    region: "us-east-1"
+  },
+  prd: {
+    graphqlEndpoint: "https://xarmlusdjfdzjkab4ptvf5yqye.appsync-api.us-east-1.amazonaws.com/graphql",
+    region: "us-east-1"
+  }
+};
+
+// ../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
+  userid
+  artworkType
+  name
+  description
+  status
+  files {
+    type
+    path
+    checksum
+    fileID
+    size
+    width
+    height
+    pz
+  }
+  created
+  modified
+  downloadsCount
+  viewsCount
+  enabled
+  publishEnabled
+  redirectLaunchV3
+  ctaLinkUrl
+  ctaLinkText
+  creatorVersion
+  animationHasAlpha
+  animationVideoOrientation
+  sceneConfig
+  sceneRevision
+`;
+var GET_ARTWORK = `
+  query GetArtwork($id: ID!) {
+    getArtwork(id: $id) {
+      ${ARTWORK_FIELDS}
+    }
+  }
+`;
+var GET_ARTWORKS = `
+  query GetArtworks($ids: [ID]) {
+    getArtworks(ids: $ids) {
+      ${ARTWORK_FIELDS}
+    }
+  }
+`;
+var GET_ARTWORKS_BY_USERID = `
+  query GetArtworksByUserid($userid: ID!, $after: String) {
+    getArtworksByUserid(userid: $userid, after: $after) {
+      nextToken
+      items {
+        ${ARTWORK_FIELDS}
+      }
+    }
+  }
+`;
+var CREATE_ARTWORK = `
+  mutation CreateArtwork($input: CreateArtworkInput!) {
+    createArtwork(input: $input) {
+      id
+      status
+    }
+  }
+`;
+var UPDATE_ARTWORK = `
+  mutation UpdateArtwork($input: UpdateArtworkInput!) {
+    updateArtwork(input: $input) {
+      id
+      userid
+      name
+      description
+      status
+      creatorVersion
+      animationHasAlpha
+      animationVideoOrientation
+      redirectLaunchV3
+      modified
+      sceneRevision
+      sceneConfig
+      files {
+        type
+        path
+        checksum
+        fileID
+        size
+        width
+        height
+        pz
+      }
+    }
+  }
+`;
+var UPDATE_ARTWORK_SCENE = `
+  mutation UpdateArtworkScene($input: UpdateArtworkSceneInput!) {
+    updateArtworkScene(input: $input) {
+      id
+      userid
+      sceneConfig
+      sceneRevision
+      modified
+      ops
+      originId
+    }
+  }
+`;
+var ON_UPDATE_ARTWORK = `
+  subscription OnUpdateArtwork($userid: ID!) {
+    onUpdateArtwork(userid: $userid) {
+      id
+      userid
+      name
+      description
+      status
+      publishEnabled
+      viewsCount
+      downloadsCount
+      modified
+      sceneConfig
+      sceneRevision
+      files {
+        type
+        path
+        checksum
+        fileID
+        size
+        width
+        height
+        pz
+      }
+    }
+  }
+`;
+var ON_ARTWORK_SCENE = `
+  subscription OnArtworkScene($id: ID!) {
+    onArtworkScene(id: $id) {
+      id
+      userid
+      sceneConfig
+      sceneRevision
+      modified
+      ops
+      originId
+    }
+  }
+`;
+var PUBLISH_ARTWORK = `
+  mutation PublishArtwork($id: ID!) {
+    publishArtwork(id: $id) {
+      id
+      status
+    }
+  }
+`;
+var UNPUBLISH_ARTWORK = `
+  mutation UnpublishArtwork($id: ID!) {
+    unpublishArtwork(id: $id) {
+      id
+      status
+    }
+  }
+`;
+var DELETE_ARTWORK = `
+  mutation DeleteArtwork($input: DeleteArtworkInput!) {
+    deleteArtwork(input: $input) {
+      id
+    }
+  }
+`;
+
+// ../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) {
+  if (!raw)
+    return null;
+  let parsed;
+  try {
+    parsed = typeof raw === "string" ? JSON.parse(raw) : raw;
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null)
+    return null;
+  const doc = parsed;
+  if (typeof doc.version !== "number")
+    return null;
+  if (!Array.isArray(doc.assets) || !Array.isArray(doc.scenes))
+    return null;
+  return parsed;
+}
+function stringifySceneDocument(doc) {
+  return JSON.stringify(doc);
+}
+function validateSceneDocument(doc, files) {
+  const issues = [];
+  if (typeof doc.version !== "number") {
+    issues.push({ level: "error", message: "version must be a number" });
+  }
+  if (!Array.isArray(doc.scenes) || doc.scenes.length === 0) {
+    issues.push({ level: "error", message: "scenes must be a non-empty array (only scenes[0] renders)" });
+  }
+  if (!Array.isArray(doc.assets)) {
+    issues.push({ level: "error", message: "assets must be an array" });
+  }
+  const root = doc.scenes?.[0];
+  if (root) {
+    if (!Array.isArray(root.children)) {
+      issues.push({ level: "error", message: "scenes[0].children must be an array" });
+    } else {
+      const fileIds = new Set((files ?? []).map((f) => f.fileID).filter(Boolean));
+      const assetIds = new Set((doc.assets ?? []).map((a) => a.assetID));
+      root.children.forEach((child, i) => {
+        for (const key of ["position", "rotation", "scale"]) {
+          const v = child[key];
+          if (!Array.isArray(v) || v.length !== 3 || v.some((n) => typeof n !== "number" || !Number.isFinite(n))) {
+            issues.push({ level: "error", message: `children[${i}].${key} must be [x,y,z] finite numbers` });
+          }
+        }
+        if (!child.sceneID) {
+          issues.push({ level: "error", message: `children[${i}].sceneID missing` });
+        }
+        if (!child.assetID) {
+          issues.push({ level: "error", message: `children[${i}].assetID missing` });
+        } else if (files && !fileIds.has(child.assetID) && !assetIds.has(child.assetID)) {
+          issues.push({
+            level: "warning",
+            message: `children[${i}].assetID "${child.assetID}" matches no files[].fileID or assets[].assetID \u2014 the viewer will skip it`
+          });
+        }
+      });
+    }
+  }
+  const bytes = new TextEncoder().encode(stringifySceneDocument(doc)).length;
+  if (bytes > MAX_DOC_BYTES) {
+    issues.push({
+      level: "error",
+      message: `document is ${bytes} bytes; max ${MAX_DOC_BYTES} (DynamoDB item headroom)`
+    });
+  }
+  return issues;
+}
+var SceneApi = class {
+  constructor(client2, artworks, realtime) {
+    this.client = client2;
+    this.artworks = artworks;
+    this.realtime = realtime;
+  }
+  /** Live scene channel for one artwork (fat onArtworkScene) over the SDK's realtime client. */
+  watch(artworkId, handlers) {
+    if (!this.realtime)
+      throw new Error("SceneApi.watch: realtime client not configured");
+    return this.realtime().subscribe(ON_ARTWORK_SCENE, { id: artworkId }, {
+      next: (data) => {
+        if (data?.onArtworkScene)
+          handlers.next(data.onArtworkScene);
+      },
+      error: handlers.error
+    });
+  }
+  /** Read the structured snapshot (doc + revision + files) for an artwork. */
+  async get(artworkId) {
+    const artwork = await this.artworks.get(artworkId);
+    if (!artwork)
+      return null;
+    return {
+      artworkId: artwork.id,
+      name: artwork.name ?? null,
+      doc: parseSceneConfig(artwork.sceneConfig),
+      raw: artwork.sceneConfig ?? null,
+      revision: artwork.sceneRevision ?? 0,
+      files: artwork.files ?? [],
+      artwork
+    };
+  }
+  /**
+   * Revision-checked save (updateArtworkScene). The write is atomic: it lands
+   * only if the caller owns the artwork AND the stored revision equals
+   * expectedRevision; otherwise the SDK re-reads and returns a typed conflict
+   * for the caller to rebase on. Fans out to onArtworkScene subscribers.
+   */
+  async save(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.artworks.get(params.artworkId).catch(() => null);
+        if (!current)
+          return { conflict: true, exists: false, currentRevision: null };
+        return { conflict: true, exists: true, currentRevision: current.sceneRevision ?? 0 };
+      }
+      throw err;
+    }
+  }
+  /**
+   * Save a scene document through the LEGACY path (updateArtwork — no conflict
+   * check; the server still bumps sceneRevision). Kept for un-migrated flows;
+   * prefer save() everywhere new.
+   */
+  async saveLegacy(artworkId, doc, options) {
+    const raw = typeof doc === "string" ? doc : stringifySceneDocument(doc);
+    if (typeof doc !== "string") {
+      const issues = validateSceneDocument(doc, options?.validateAgainstFiles).filter((i) => i.level === "error");
+      if (issues.length > 0) {
+        throw new Error(`Refusing to save invalid scene document: ${issues.map((i) => i.message).join("; ")}`);
+      }
+    }
+    return this.artworks.update({ id: artworkId, sceneConfig: raw });
+  }
+};
+
+// ../creator-api/dist/client.js
+function createCreatorClient(options) {
+  const endpoint = options.endpoint ?? (options.stage ? STAGES[options.stage].graphqlEndpoint : void 0);
+  if (!endpoint) {
+    throw new Error("createCreatorClient: provide either `stage` or `endpoint`");
+  }
+  const graphql = new GraphQLClient({ endpoint, auth: options.auth, fetchImpl: options.fetchImpl });
+  let realtimeInstance = null;
+  const getRealtime = () => {
+    if (!realtimeInstance) {
+      realtimeInstance = new AppSyncRealtimeClient({
+        graphqlEndpoint: endpoint,
+        auth: options.auth,
+        WebSocketImpl: options.WebSocketImpl,
+        onTransportEvent: options.onRealtimeEvent
+      });
+    }
+    return realtimeInstance;
+  };
+  const agent = new AgentApi(graphql);
+  const artworks = new ArtworksApi(graphql, getRealtime);
+  const scene = new SceneApi(graphql, artworks, getRealtime);
+  return {
+    agent,
+    artworks,
+    scene,
+    graphql,
+    endpoint,
+    get realtime() {
+      return getRealtime();
+    }
+  };
+}
+
+// ../creator-api/dist/auth.js
+var StaticTokenProvider = class {
+  constructor(token, headerName = "Authorization") {
+    this.token = token;
+    this.headerName = headerName;
+  }
+  async authorize() {
+    return { [this.headerName]: this.token };
+  }
+};
+
+// src/config.ts
+function loadConfig() {
+  const token = process.env.EYEJACK_SESSION_TOKEN?.trim();
+  if (!token) {
+    console.error(
+      'EYEJACK_SESSION_TOKEN is not set.\nOpen your artwork in the EyeJack Creator, press "Connect AI", and use the command it shows.'
+    );
+    process.exit(1);
+  }
+  const stage = process.env.EYEJACK_STAGE?.trim() || "dev";
+  const endpoint = process.env.EYEJACK_GRAPHQL_ENDPOINT?.trim() || (STAGES[stage] ? STAGES[stage].graphqlEndpoint : void 0);
+  if (!endpoint) {
+    console.error(`Unknown EYEJACK_STAGE "${stage}" and no EYEJACK_GRAPHQL_ENDPOINT set.`);
+    process.exit(1);
+  }
+  return { token, endpoint, stage };
+}
+
+// src/tools.ts
+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.
+- Each child: { sceneID (stable uuid), assetID, position [x,y,z], rotation [x,y,z], scale [x,y,z] }.
+- 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).`;
+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)) {
+    return REJECTED_HINT;
+  }
+  if (err instanceof GraphQLRequestError) {
+    if ((err.errorType || "").includes("Unauthorized")) {
+      return REJECTED_HINT;
+    }
+    return `EyeJack API error: ${err.errorType || err.message}`;
+  }
+  return `Error: ${err.message}`;
+}
+var asText = (value) => ({
+  content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }]
+});
+var asError = (err) => ({
+  content: [{ type: "text", text: errorText(err) }],
+  isError: true
+});
+function registerTools(server2, client2) {
+  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}`,
+    async () => {
+      try {
+        const record = await client2.agent.getScene();
+        const doc = parseSceneConfig(record.sceneConfig);
+        return asText({
+          artworkId: record.artworkId,
+          name: record.name,
+          status: record.status,
+          sceneRevision: record.sceneRevision ?? 0,
+          modified: record.modified,
+          scene: doc,
+          sceneIsEmpty: !doc || !doc.scenes?.[0]?.children?.length,
+          files: (record.files || []).map((f) => ({
+            fileID: f.fileID,
+            type: f.type,
+            path: f.path,
+            width: f.width,
+            height: f.height
+          }))
+        });
+      } catch (err) {
+        return asError(err);
+      }
+    }
+  );
+  server2.tool(
+    "list_assets",
+    "List the asset files (images, videos, 3D models) available on the connected artwork \u2014 the palette the scene's panels can reference via assetID == fileID. Read-only.",
+    async () => {
+      try {
+        const record = await client2.agent.getScene();
+        const doc = parseSceneConfig(record.sceneConfig);
+        const usedIds = new Set((doc?.scenes?.[0]?.children || []).map((c) => c.assetID));
+        return asText(
+          (record.files || []).map((f) => ({
+            fileID: f.fileID,
+            type: f.type,
+            width: f.width,
+            height: f.height,
+            path: f.path,
+            usedInScene: f.fileID ? usedIds.has(f.fileID) : false
+          }))
+        );
+      } 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).",
+    async () => {
+      try {
+        const session = await client2.agent.getSession();
+        const now = Math.floor(Date.now() / 1e3);
+        return asText({
+          artworkId: session.artworkId,
+          status: session.status,
+          expiresAt: session.expiresAt,
+          expiresInSeconds: session.expiresAt ? session.expiresAt - now : null,
+          lastHeartbeat: session.lastHeartbeat
+        });
+      } catch (err) {
+        return asError(err);
+      }
+    }
+  );
+}
+
+// src/index.ts
+var config = loadConfig();
+var client = createCreatorClient({
+  endpoint: config.endpoint,
+  auth: new StaticTokenProvider(config.token)
+});
+var server = new McpServer({
+  name: "eyejack-creator",
+  version: "0.1.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.`);

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@eyejack-creator/mcp",
+  "version": "0.1.0",
+  "description": "EyeJack Creator MCP server — connect Claude Code / Codex / Cursor to a live EyeJack editing session.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "eyejack-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.0",
+    "typescript": "^5.4.0",
+    "@eyejack/creator-api": "0.1.0"
+  },
+  "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\"",
+    "smoke": "node examples/smoke-client.mjs"
+  }
+}