@impractical-ai/motion 0.1.4 → 0.1.6

package/README.md

@@ -1,22 +1,34 @@
 # Impractical Motion CLI
 
-Connect Claude Code to Impractical Motion through its MCP server.
+Connect Claude Code, Codex, Cursor, or OpenCode to Impractical Motion through
+its MCP server.
 
 ## Requirements
 
 - Node.js 22 or newer
-- Claude Code installed and signed in
+- At least one supported coding agent: Claude Code, Codex, Cursor, or OpenCode
 - Google Chrome or Chromium for frame inspection
 
 ## Setup
 
+```sh
+npx --yes @impractical-ai/motion setup --agent
+```
+
+Approve the device code in the browser, then restart the detected coding agents.
+Setup installs the global `impractical` MCP configuration for every detected
+Claude Code, Codex, Cursor, and OpenCode client, plus the shared skill for Claude
+Code and Codex. Re-running setup verifies and reuses a working credential,
+preserves unrelated client configuration, and does not require another browser
+authorization.
+
+For the full Claude Code plugin workflow, run:
+
 ```sh
 npx --yes @impractical-ai/motion setup --claude
 ```
 
-Approve the device code in the browser, then run `/reload-plugins` in Claude Code and type
-`continue`. Re-running setup verifies and reuses a working credential, refreshes the user-scoped
-plugin, and does not require another browser authorization.
+Then run `/reload-plugins` in Claude Code and type `continue`.
 
 Setup writes the API credential to `~/.impractical/config.json` with mode `0600`. Environment
 variables `IMPRACTICAL_API_KEY`, `IMPRACTICAL_SUPABASE_URL`, and `IMPRACTICAL_APP_URL` take
@@ -24,7 +36,7 @@ precedence over that file.
 
 ## MCP server
 
-The installed Claude plugin launches the server automatically. Other MCP clients can run:
+The installer configures supported clients to run:
 
 ```sh
 npx --yes @impractical-ai/motion@latest mcp

package/assets/engine.d.ts

@@ -598,12 +598,20 @@ export type AudioKit = {
 }
 
 export type Output = {
+  /** Delivery raster dimensions. They do not change scene layout. */
   width: number
   height: number
   fps: number
   render?: RenderConfig
 }
 
+/** Resolved renderer contract. `width`/`height` are always logical scene
+ * coordinates; only the exporter consumes `delivery` as raster dimensions. */
+export type StageConfig = Output & {
+  composition: { width: number; height: number }
+  delivery: { width: number; height: number }
+}
+
 export type Rect = { left: number; top: number; width: number; height: number }
 
 export type FramingTarget = string | Element | Rect | FramingTarget[]
@@ -642,6 +650,9 @@ export type TextStyleOverride = {
   color?: string
   x?: number
   y?: number
+  /** Wrapping width in scene px — the side bars reflow text instead of
+   * scale-squeezing it. Applied as inline-block + width. */
+  width?: number
   hidden?: boolean
 }
 
@@ -652,6 +663,14 @@ export type ObjectPositionOverride = {
   scaleY?: number
   rotation?: number
   hidden?: boolean
+  /** Plain CSS declarations the studio applies to the object's element —
+   * border-radius, background-color, box-shadow and friends. Applied at
+   * stage prepare, so they ride the structural rebuild route. */
+  styles?: Record<string, string>
+  /** Replacement source for the image or video the object carries (the
+   * element itself or its first img/video descendant), usually a data URI so
+   * renders never depend on the network. */
+  src?: string
 }
 
 export type AddedTextLayer = {
@@ -668,6 +687,11 @@ export type SceneOverrides = {
   textStyles?: Record<string, TextStyleOverride>
   addedText?: Record<string, AddedTextLayer>
   objects?: Record<string, ObjectPositionOverride> // stable UI wrapper id -> scene-pixel offset
+  /** Explicit paint order for editable siblings. Keys include the editable
+   * kind (`object:…` / `text:…`) so independently generated ids cannot
+   * collide. Values are normalized by the studio whenever an item moves in
+   * the stack. */
+  layerOrder?: Record<string, number>
 }
 
 export type TweenKind =
@@ -698,12 +722,16 @@ export type TweenInfo = {
   stagger?: number
   vars: Record<string, number | string>
   overridden: boolean
+  /** The editable layer this tween animates, when its first Element target
+   * sits inside one — lets the studio show a layer's choreography. */
+  targetObjectId?: string
+  targetTextId?: string
 }
 
 export type CameraSetInfo = Framing & { id: number; overridden: boolean }
 
 export type SceneInspection = {
-  config: Output
+  config: StageConfig
   duration: number
   tweens: TweenInfo[]
   cameraSets: CameraSetInfo[]
@@ -720,7 +748,7 @@ export type DirectionContext = {
   gsap: typeof gsap
   tl: gsap.core.Timeline // the master timeline (created paused)
   stage: HTMLElement // scene wrapper the camera transforms
-  config: Output
+  config: StageConfig
   q: <T extends HTMLElement>(selector: string) => T
   qa: (selector: string) => HTMLElement[]
   camera: {
@@ -897,6 +925,14 @@ export type DirectionContext = {
 
 export type Direction = (ctx: DirectionContext) => void | Promise<void>
 
+export type BuiltScene = {
+  timeline: gsap.core.Timeline
+  runtime: DeterministicStageRuntime
+  scene: SceneInspection
+  config: StageConfig
+  previewOverrides: (overrides: SceneOverrides) => boolean
+}
+
 // ─── Named eases ──────────────────────────────────────────────────────
 
 // ─── The promo easing set ─────────────────────────────────────────────────

package/assets/impractical/SKILL.md

@@ -13,13 +13,15 @@ source code lives in the cloud, never in the user's project directory.
 ## 0. Setup check (once per session)
 
 Call the `account_status` tool (`whoami` is its legacy alias). If the
-Impractical tools are not available, the Claude plugin is not connected. Tell
-the user to run:
+Impractical tools are not available, the current coding agent is not connected.
+Tell the user to run:
 
-    npx --yes @impractical-ai/motion setup --claude
+    npx --yes @impractical-ai/motion setup --agent
 
-Then ask them to run `/reload-plugins` and type `continue`. If the weekly quota
-is exhausted, call `upgrade` to give the user the authenticated billing page.
+Then ask them to restart or reload their coding agent and type `continue`.
+Claude Code users who specifically want the full plugin can run the same command
+with `--claude` instead. If the weekly quota is exhausted, call `upgrade` to give
+the user the authenticated billing page.
 
 ## 1. Read the engine before you write anything
 

package/dist/{api-64X3G4M2.js → api-C7KJDYN4.js}

@@ -2,6 +2,7 @@
 import {
   ApiContractError,
   ApiError,
+  ApiTransportError,
   admitMcpCall,
   delay,
   invoke,
@@ -12,11 +13,12 @@ import {
   waitForJobs,
   withAdmissionReceipt,
   withMeteredCall
-} from "./chunk-M77TS5RO.js";
-import "./chunk-EFP4P3WA.js";
+} from "./chunk-KITRCE33.js";
+import "./chunk-LJ4YH3YJ.js";
 export {
   ApiContractError,
   ApiError,
+  ApiTransportError,
   admitMcpCall,
   delay,
   invoke,

package/dist/{chunk-KC6BJJXH.js → chunk-BUHNO2W2.js}

@@ -6,17 +6,26 @@ import {
   loadConfig,
   recoverCorruptConfig,
   saveConfig
-} from "./chunk-M77TS5RO.js";
+} from "./chunk-KITRCE33.js";
 import {
   PACKAGE_COMMAND,
   PACKAGE_NAME,
   PACKAGE_VERSION,
   PRODUCTION_APP_URL,
   PRODUCTION_SUPABASE_URL
-} from "./chunk-EFP4P3WA.js";
+} from "./chunk-LJ4YH3YJ.js";
 
 // src/onboarding.ts
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync
+} from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -27,6 +36,10 @@ var CLAUDE_MARKETPLACE_NAME = "impractical";
 var AUTH_VERIFY_MIN_VERSION = "0.1.2";
 var CLAUDE_INSTALL_COMMAND = "npm install -g @anthropic-ai/claude-code";
 var CLAUDE_INSTALL_URL = "https://code.claude.com/docs/en/installation";
+var MCP_SERVER_NAME = "impractical";
+var MCP_COMMAND = ["npx", "--yes", `${PACKAGE_NAME}@latest`, "mcp"];
+var MCP_TOOL_TIMEOUT_MS = 6e5;
+var MCP_TOOL_TIMEOUT_SECONDS = MCP_TOOL_TIMEOUT_MS / 1e3;
 function parseSemver(value) {
   const match = value.trim().match(
     /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/
@@ -106,6 +119,300 @@ function marketplaceSourceLabel(record) {
 function commandResult(command, args) {
   return spawnSync(command, args, { encoding: "utf8", windowsHide: true });
 }
+function commandAvailable(command) {
+  const result = commandResult(command, ["--version"]);
+  return !result.error && result.status === 0;
+}
+function verifyAgentPrerequisites() {
+  const found = commandAvailable("claude") || commandAvailable("codex") || commandAvailable("cursor-agent") || commandAvailable("cursor") || commandAvailable("opencode");
+  if (!found) {
+    throw new Error(
+      "No supported coding agent was detected. Install Claude Code, Codex, Cursor, or OpenCode, then rerun setup."
+    );
+  }
+}
+function commandDetail(result) {
+  return `${result.stdout ?? ""}
+${result.stderr ?? ""}`.trim();
+}
+function runMcpCommand(command, args, harness) {
+  const result = commandResult(command, args);
+  if (!result.error && result.status === 0) return;
+  throw new Error(
+    `${harness} MCP setup failed: ${commandDetail(result) || result.error?.message || "unknown error"}`
+  );
+}
+function hasExpectedMcp(result) {
+  if (result.error || result.status !== 0) return false;
+  const detail = commandDetail(result);
+  return detail.includes("@impractical-ai/motion@latest") && /\bmcp\b/.test(detail);
+}
+function hasExpectedClaudeMcp(result) {
+  if (!hasExpectedMcp(result)) return false;
+  return new RegExp(`\\b${MCP_TOOL_TIMEOUT_MS}(?:ms)?\\b`).test(commandDetail(result));
+}
+function hasExpectedCodexMcp(result) {
+  if (!hasExpectedMcp(result)) return false;
+  return new RegExp(`\\btool_timeout_sec\\s*:\\s*${MCP_TOOL_TIMEOUT_SECONDS}\\b`).test(
+    commandDetail(result)
+  );
+}
+function codexConfigPath(home) {
+  const codexHome = process.env.CODEX_HOME?.trim();
+  return join(codexHome || join(home, ".codex"), "config.toml");
+}
+function atomicWrite(path, contents, mode) {
+  mkdirSync(dirname(path), { recursive: true, mode: 448 });
+  const temporary = join(dirname(path), `.${MCP_SERVER_NAME}-${process.pid}-${Date.now()}.tmp`);
+  try {
+    writeFileSync(temporary, contents, { mode });
+    chmodSync(temporary, mode);
+    renameSync(temporary, path);
+  } finally {
+    if (existsSync(temporary)) unlinkSync(temporary);
+  }
+}
+function upsertCodexToolTimeout(path) {
+  if (!existsSync(path)) throw new Error(`Codex MCP registration did not create ${path}.`);
+  const previous = readFileSync(path, "utf8");
+  const newline = previous.includes("\r\n") ? "\r\n" : "\n";
+  const lines = previous.split(/\r?\n/);
+  const section = /^\s*\[mcp_servers\.(?:impractical|"impractical")\]\s*(?:#.*)?$/;
+  const sectionStart = lines.findIndex((line) => section.test(line));
+  if (sectionStart === -1) {
+    throw new Error(`Codex MCP registration did not create [mcp_servers.${MCP_SERVER_NAME}].`);
+  }
+  let sectionEnd = lines.length;
+  for (let index = sectionStart + 1; index < lines.length; index++) {
+    if (/^\s*\[/.test(lines[index])) {
+      sectionEnd = index;
+      break;
+    }
+  }
+  const timeoutLine = /^\s*tool_timeout_sec\s*=/;
+  const timeoutIndex = lines.slice(sectionStart + 1, sectionEnd).findIndex((line) => timeoutLine.test(line));
+  if (timeoutIndex !== -1 && new RegExp(`^\\s*tool_timeout_sec\\s*=\\s*${MCP_TOOL_TIMEOUT_SECONDS}\\s*(?:#.*)?$`).test(
+    lines[sectionStart + 1 + timeoutIndex]
+  )) {
+    return;
+  }
+  if (timeoutIndex === -1) {
+    lines.splice(sectionEnd, 0, `tool_timeout_sec = ${MCP_TOOL_TIMEOUT_SECONDS}`);
+  } else {
+    lines[sectionStart + 1 + timeoutIndex] = `tool_timeout_sec = ${MCP_TOOL_TIMEOUT_SECONDS}`;
+  }
+  atomicWrite(path, lines.join(newline), statSync(path).mode & 511);
+}
+function restoreFile(path, existed, contents, mode) {
+  if (existed) atomicWrite(path, contents, mode);
+  else if (existsSync(path)) unlinkSync(path);
+}
+function installNativeMcp(command, harness, home) {
+  if (!commandAvailable(command)) return void 0;
+  const existing = commandResult(command, ["mcp", "get", MCP_SERVER_NAME]);
+  if (command === "claude") {
+    if (!hasExpectedClaudeMcp(existing)) {
+      const existingDetail = commandDetail(existing);
+      if (!existing.error && existing.status === 0 && !/No MCP server named\b/i.test(existingDetail)) {
+        runMcpCommand(command, ["mcp", "remove", MCP_SERVER_NAME, "-s", "user"], harness);
+      }
+      const definition = JSON.stringify({
+        type: "stdio",
+        command: MCP_COMMAND[0],
+        args: MCP_COMMAND.slice(1),
+        timeout: MCP_TOOL_TIMEOUT_MS
+      });
+      runMcpCommand(
+        command,
+        ["mcp", "add-json", "-s", "user", MCP_SERVER_NAME, definition],
+        harness
+      );
+      if (!hasExpectedClaudeMcp(commandResult(command, ["mcp", "get", MCP_SERVER_NAME]))) {
+        throw new Error(`${harness} MCP setup failed validation after registration.`);
+      }
+    }
+    return { harness };
+  }
+  const path = codexConfigPath(home);
+  mkdirSync(dirname(path), { recursive: true, mode: 448 });
+  const existed = existsSync(path);
+  const previous = existed ? readFileSync(path, "utf8") : "";
+  const mode = existed ? statSync(path).mode & 511 : 384;
+  try {
+    if (!hasExpectedMcp(existing)) {
+      runMcpCommand(command, ["mcp", "add", MCP_SERVER_NAME, "--", ...MCP_COMMAND], harness);
+    }
+    upsertCodexToolTimeout(path);
+    if (!hasExpectedCodexMcp(commandResult(command, ["mcp", "get", MCP_SERVER_NAME]))) {
+      throw new Error(`${harness} MCP setup failed validation after registration.`);
+    }
+  } catch (error) {
+    try {
+      restoreFile(path, existed, previous, mode);
+    } catch (rollbackError) {
+      throw new Error(
+        `${error instanceof Error ? error.message : String(error)} Rollback failed: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`
+      );
+    }
+    throw error;
+  }
+  return { harness, path };
+}
+function readJsonObject(path) {
+  if (!existsSync(path)) return {};
+  let value;
+  try {
+    value = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    throw new Error(`Cannot configure MCP because ${path} is not valid JSON.`);
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`Cannot configure MCP because ${path} must contain a JSON object.`);
+  }
+  return value;
+}
+function writeJsonObject(path, value) {
+  mkdirSync(dirname(path), { recursive: true, mode: 448 });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}
+`, { mode: 384 });
+}
+function hasRequiredFields(value, required) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value;
+  return Object.entries(required).every(
+    ([key, expected]) => JSON.stringify(record[key]) === JSON.stringify(expected)
+  );
+}
+function installCursorMcp(home) {
+  if (!commandAvailable("cursor-agent") && !commandAvailable("cursor")) return void 0;
+  const path = join(home, ".cursor", "mcp.json");
+  const config = readJsonObject(path);
+  const servers = config.mcpServers && typeof config.mcpServers === "object" && !Array.isArray(config.mcpServers) ? config.mcpServers : {};
+  const expected = {
+    command: MCP_COMMAND[0],
+    args: MCP_COMMAND.slice(1)
+  };
+  if (hasRequiredFields(servers[MCP_SERVER_NAME], expected)) {
+    return { harness: "Cursor", path };
+  }
+  const existing = servers[MCP_SERVER_NAME] && typeof servers[MCP_SERVER_NAME] === "object" && !Array.isArray(servers[MCP_SERVER_NAME]) ? servers[MCP_SERVER_NAME] : {};
+  config.mcpServers = {
+    ...servers,
+    [MCP_SERVER_NAME]: { ...existing, ...expected }
+  };
+  writeJsonObject(path, config);
+  return { harness: "Cursor", path };
+}
+function openCodeConfigHome(home) {
+  if (process.env.XDG_CONFIG_HOME?.trim()) return process.env.XDG_CONFIG_HOME.trim();
+  if (process.platform === "win32" && process.env.APPDATA?.trim()) return process.env.APPDATA.trim();
+  return join(home, ".config");
+}
+function verifyAgentConfigs(home = homedir()) {
+  const checks = [];
+  if (commandAvailable("cursor-agent") || commandAvailable("cursor")) {
+    checks.push({ harness: "Cursor", path: join(home, ".cursor", "mcp.json") });
+  }
+  if (commandAvailable("opencode")) {
+    checks.push({
+      harness: "OpenCode",
+      path: join(openCodeConfigHome(home), "opencode", "opencode.json")
+    });
+  }
+  const failures = [];
+  for (const check of checks) {
+    try {
+      readJsonObject(check.path);
+    } catch (error) {
+      failures.push({
+        harness: check.harness,
+        path: check.path,
+        message: error instanceof Error ? error.message : String(error),
+        remediation: agentMcpRemediation(check.harness, check.path)
+      });
+    }
+  }
+  if (failures.length > 0) {
+    const detail = failures.map(
+      (failure) => `${failure.harness}: ${failure.message}
+Remediation: ${failure.remediation}`
+    ).join("\n");
+    throw new Error(
+      `Device authorization was not started because ${failures.length} coding agent configuration${failures.length === 1 ? "" : "s"} must be repaired first.
+${detail}`
+    );
+  }
+}
+function installOpenCodeMcp(home) {
+  if (!commandAvailable("opencode")) return void 0;
+  const path = join(openCodeConfigHome(home), "opencode", "opencode.json");
+  const config = readJsonObject(path);
+  const servers = config.mcp && typeof config.mcp === "object" && !Array.isArray(config.mcp) ? config.mcp : {};
+  const expected = {
+    type: "local",
+    command: MCP_COMMAND,
+    timeout: MCP_TOOL_TIMEOUT_MS
+  };
+  if (hasRequiredFields(servers[MCP_SERVER_NAME], expected)) {
+    return { harness: "OpenCode", path };
+  }
+  const existing = servers[MCP_SERVER_NAME] && typeof servers[MCP_SERVER_NAME] === "object" && !Array.isArray(servers[MCP_SERVER_NAME]) ? servers[MCP_SERVER_NAME] : {};
+  config.mcp = {
+    ...servers,
+    [MCP_SERVER_NAME]: { ...existing, ...expected }
+  };
+  writeJsonObject(path, config);
+  return { harness: "OpenCode", path };
+}
+function agentMcpRemediation(harness, path) {
+  if (path) {
+    return `Repair ${path} so it contains a valid configuration object without deleting unrelated entries, then rerun \`${PACKAGE_COMMAND} setup --agent\`.`;
+  }
+  return `Inspect the ${harness} MCP configuration for \`${MCP_SERVER_NAME}\`, then rerun \`${PACKAGE_COMMAND} setup --agent\`.`;
+}
+function agentMcpFailureMessage(failures) {
+  const detail = failures.map((failure) => `${failure.harness}: ${failure.message}
+Remediation: ${failure.remediation}`).join("\n");
+  return `Could not configure ${failures.length} coding agent${failures.length === 1 ? "" : "s"}. Successful agent configurations were preserved.
+${detail}`;
+}
+function configureAgentMcps(home = homedir()) {
+  const configured = [];
+  const failures = [];
+  const installers = [
+    { harness: "Claude Code", install: () => installNativeMcp("claude", "Claude Code", home) },
+    {
+      harness: "Codex",
+      path: codexConfigPath(home),
+      install: () => installNativeMcp("codex", "Codex", home)
+    },
+    {
+      harness: "Cursor",
+      path: join(home, ".cursor", "mcp.json"),
+      install: () => installCursorMcp(home)
+    },
+    {
+      harness: "OpenCode",
+      path: join(openCodeConfigHome(home), "opencode", "opencode.json"),
+      install: () => installOpenCodeMcp(home)
+    }
+  ];
+  for (const installer of installers) {
+    try {
+      const result = installer.install();
+      if (result) configured.push(result);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      failures.push({
+        harness: installer.harness,
+        path: installer.path,
+        message,
+        remediation: agentMcpRemediation(installer.harness, installer.path)
+      });
+    }
+  }
+  return { configured, failures };
+}
 function requireCommand(command, label) {
   const result = commandResult(command, ["--version"]);
   if (result.error || result.status !== 0) {
@@ -288,7 +595,7 @@ function openBrowser(url) {
   });
   return !result.error && result.status === 0;
 }
-async function waitForApproval(supabaseUrl, authorization, log) {
+async function waitForApproval(supabaseUrl, authorization, log, setupFlag) {
   const deadline = Date.parse(authorization.expiresAt);
   const intervalMs = Math.max(1, authorization.intervalSeconds) * 1e3;
   let announced = false;
@@ -304,16 +611,20 @@ async function waitForApproval(supabaseUrl, authorization, log) {
     }
     await delay(intervalMs);
   }
-  throw new Error(`Authorization expired. Run \`${PACKAGE_COMMAND} setup --claude\` again.`);
+  throw new Error(`Authorization expired. Run \`${PACKAGE_COMMAND} setup ${setupFlag}\` again.`);
 }
 async function setup(options) {
   if (options.installClaudePlugin) verifyClaudePrerequisites();
+  if (options.installAgentMcp) {
+    verifyAgentPrerequisites();
+  }
   const corruptConfigBackup = recoverCorruptConfig();
   if (corruptConfigBackup) {
     options.log(`Backed up invalid configuration to ${corruptConfigBackup}; starting clean.`);
   }
   const supabaseUrl = process.env.IMPRACTICAL_SUPABASE_URL?.trim() || PRODUCTION_SUPABASE_URL;
   const appUrl = process.env.IMPRACTICAL_APP_URL?.trim() || PRODUCTION_APP_URL;
+  const setupFlag = options.installAgentMcp ? "--agent" : "--claude";
   const existing = loadConfig();
   let apiKey = existing.supabaseUrl === supabaseUrl ? existing.apiKey : void 0;
   let verified;
@@ -327,6 +638,7 @@ async function setup(options) {
     }
   }
   if (!apiKey) {
+    if (options.installAgentMcp) verifyAgentConfigs();
     const authorization = await invokeAt(supabaseUrl, "cli-device-auth", {
       action: "start"
     });
@@ -340,10 +652,10 @@ async function setup(options) {
       options.log(opened ? "Opened your browser." : "Could not open a browser automatically; use the link above.");
     }
     try {
-      apiKey = await waitForApproval(supabaseUrl, authorization, options.log);
+      apiKey = await waitForApproval(supabaseUrl, authorization, options.log, setupFlag);
     } catch (error) {
       if (error instanceof ApiError && error.status === 410) {
-        throw new Error(`Authorization expired. Run \`${PACKAGE_COMMAND} setup --claude\` again.`);
+        throw new Error(`Authorization expired. Run \`${PACKAGE_COMMAND} setup ${setupFlag}\` again.`);
       }
       throw error;
     }
@@ -351,6 +663,7 @@ async function setup(options) {
     saveConfig({ apiKey, supabaseUrl, appUrl });
   }
   const claudePlugin = options.installClaudePlugin ? installClaudePlugin(options.log) : void 0;
+  const agentMcpSetup = options.installAgentMcp ? configureAgentMcps() : { configured: [], failures: [] };
   const installed = options.installAgentSkills ? installSkills() : [];
   const reconciled = reconcileLegacySkills();
   options.log("");
@@ -358,16 +671,30 @@ async function setup(options) {
   for (const skill of installed) {
     options.log(`Installed /impractical for ${skill.harness}.`);
   }
+  for (const mcp of agentMcpSetup.configured) {
+    options.log(`Configured Impractical MCP for ${mcp.harness}.`);
+  }
+  for (const failure of agentMcpSetup.failures) {
+    options.log(`Could not configure Impractical MCP for ${failure.harness}: ${failure.message}`);
+    options.log(`Remediation for ${failure.harness}: ${failure.remediation}`);
+  }
   for (const skill of reconciled) {
     options.log(`Refreshed legacy /impractical for ${skill.harness}; previous copy preserved at ${skill.backupPath}.`);
   }
   if (claudePlugin) options.log(pluginResultLine(claudePlugin));
   options.log(`Workspace: ${verified.orgId}${verified.plan ? ` \xB7 ${verified.plan}` : ""}`);
   options.log("");
-  options.log("Run /reload-plugins, then type continue.");
   if (options.installClaudePlugin) {
+    options.log("Run /reload-plugins, then type continue.");
+  } else if (options.installAgentMcp) {
+    options.log("Restart your coding agents, then ask them to use the Impractical MCP.");
+  }
+  if (options.installClaudePlugin || options.installAgentMcp) {
     for (const line of authenticatedWhoamiGuidance()) options.log(line);
   }
+  if (agentMcpSetup.failures.length > 0) {
+    throw new Error(agentMcpFailureMessage(agentMcpSetup.failures));
+  }
   return { installed, appUrl, supabaseUrl };
 }