instantclips-mcp 1.1.0 → 1.2.0

package/README.es.md

@@ -10,9 +10,10 @@ dirección creativa y renderizar el vídeo.
 
 **El servidor del producto permanece alojado.** Este repositorio contiene su guía de conexión, los
 metadatos de registro, un cliente HTTP de ejemplo y un pequeño adaptador stdio de código abierto
-para los clientes que no pueden conectarse directamente a un servidor remoto. El adaptador se
-limita a transportar mensajes MCP al endpoint alojado; las definiciones de las herramientas y la
-implementación del producto permanecen en un único lugar.
+para los clientes que no pueden conectarse directamente a un servidor remoto. El adaptador responde
+localmente a la inicialización, al ping y al descubrimiento de herramientas desde una instantánea
+generada, y envía al endpoint alojado únicamente las llamadas autenticadas. El servidor alojado
+sigue siendo la fuente de verdad; la implementación del producto no se duplica aquí.
 
 ## Endpoint
 
@@ -59,8 +60,9 @@ Para no guardar el token en el archivo, sustituye el encabezado por
 
 ### Clientes que solo admiten stdio y procesos sin interfaz
 
-El paquete npm `instantclips-mcp` es un adaptador ligero de stdio a HTTPS. Lee el token del entorno,
-fija InstantClips como endpoint de destino y reenvía el protocolo sin modificarlo:
+El paquete npm `instantclips-mcp` es un adaptador ligero de stdio a HTTPS. Sirve localmente la
+inicialización y el descubrimiento de herramientas para arrancar rápido y sin credenciales; después
+lee el token del entorno y envía las llamadas de herramientas a InstantClips:
 
 ```json
 {
@@ -84,7 +86,8 @@ INSTANTCLIPS_TOKEN="your-token" npx -y instantclips-mcp --check --json
 ```
 
 El token solo se acepta mediante `INSTANTCLIPS_TOKEN`, nunca como argumento de línea de comandos,
-por lo que no aparece en la lista de procesos. Se requiere Node.js 20 o posterior.
+por lo que no aparece en la lista de procesos. Es obligatorio para llamar a una herramienta, pero
+no para `initialize`, `ping` ni `tools/list`. Se requiere Node.js 20 o posterior.
 
 ### Cursor y VS Code
 
@@ -124,10 +127,12 @@ Las marcas funcionan de la misma manera: `list_brands`, `create_brand`, `set_pro
 vídeo se prepara con la voz de una marca; por eso, si el escaparate de un producto importado no
 coincide con ninguna marca existente, el proceso se detiene y pregunta en lugar de adivinar.
 
-El propio servidor publica los parámetros exactos de cada herramienta. Este repositorio no los
-repite deliberadamente: ejecuta `python example.py tools`, como se indica abajo, para mostrar los
-esquemas actuales. Así, lo que construyas no puede quedar desfasado respecto a lo que acepta el
-servidor.
+El servidor alojado publica los parámetros exactos de cada herramienta. La instantánea generada
+[`manifest/instantclips-mcp.json`](manifest/instantclips-mcp.json) permite que clientes stdio y
+registros inspeccionen los mismos esquemas sin credenciales. Quienes mantienen el repositorio la
+actualizan con `INSTANTCLIPS_TOKEN="..." npm run sync:manifest`; `npm run check:manifest` falla si
+la copia incluida difiere del servidor en producción. Ejecuta `python example.py tools` cuando
+quieras imprimir específicamente los esquemas actuales mediante HTTP.
 
 ## Créditos
 
@@ -185,9 +190,12 @@ commit es una clave publicada.
 `glama.json` es el archivo independiente y específico de Glama que permite reclamar allí la ficha.
 Un servidor perteneciente a una organización, en lugar de una cuenta personal, solo puede
 reclamarse si ese archivo está presente.
-El archivo solo acredita la propiedad: configura `npm ci` como compilación en Glama, ejecuta
-`node bin/instantclips-mcp.js` y proporciona `INSTANTCLIPS_TOKEN` como secreto desde la interfaz de
-administración del servidor.
+El archivo solo acredita la propiedad. En el formulario Dockerfile de Glama, usa
+`["npm install --omit=dev"]` como pasos de compilación,
+`["node", "./bin/instantclips-mcp.js"]` como argumentos de CMD y cualquier valor ficticio para el
+marcador obligatorio `INSTANTCLIPS_TOKEN`. Las comprobaciones de inicialización y calidad de Glama
+usan el manifiesto incluido y nunca envían ese valor al servidor alojado. No introduzcas un token
+real de una cuenta en el entorno de compilación de un tercero.
 
 ## Licencia
 

package/README.md

@@ -9,8 +9,9 @@ does: import a product, draft the creative direction, and render the video.
 
 **The product server stays hosted.** This repository contains its connection guide, registry
 metadata, example HTTP client and a small open-source stdio adapter for clients that cannot connect
-to a remote server directly. The adapter only carries MCP messages to the hosted endpoint; the
-tool definitions and product implementation remain in one place.
+to a remote server directly. The adapter answers initialization, ping and tool discovery from a
+generated snapshot, then sends authenticated tool calls to the hosted endpoint. The hosted server
+remains the source of truth; the product implementation is not duplicated here.
 
 ## Endpoint
 
@@ -54,8 +55,9 @@ and export it in your shell instead.
 
 ### Stdio-only clients and headless runners
 
-The `instantclips-mcp` npm package is a thin stdio-to-HTTPS adapter. It reads the token from the
-environment, fixes the upstream endpoint to InstantClips and forwards the protocol unchanged:
+The `instantclips-mcp` npm package is a thin stdio-to-HTTPS adapter. It serves initialization and
+tool discovery locally for a fast, credential-free cold start, then reads the token from the
+environment and sends tool calls to InstantClips:
 
 ```json
 {
@@ -78,7 +80,8 @@ INSTANTCLIPS_TOKEN="your-token" npx -y instantclips-mcp --check --json
 ```
 
 The token is accepted only through `INSTANTCLIPS_TOKEN`, never as a command-line argument, so it
-does not appear in the process list. Node.js 20 or newer is required.
+does not appear in the process list. It is required for tool calls, but not for `initialize`,
+`ping`, or `tools/list`. Node.js 20 or newer is required.
 
 ### Cursor and VS Code
 
@@ -116,9 +119,12 @@ Brands work the same way: `list_brands`, `create_brand`, `set_product_brand`. Ev
 drafted in a brand's voice, so an import whose storefront matches no existing brand stops and asks
 rather than guessing.
 
-Each tool's exact parameters are published by the server itself. This repository deliberately does
-not restate them — run `python example.py tools` below to print the live schemas, so what you build
-against cannot drift from what the server accepts.
+Each tool's exact parameters are published by the hosted server. The generated
+[`manifest/instantclips-mcp.json`](manifest/instantclips-mcp.json) snapshot lets stdio clients and
+registries inspect those same schemas without a credential. Maintainers refresh it with
+`INSTANTCLIPS_TOKEN="..." npm run sync:manifest`; `npm run check:manifest` fails when the committed
+snapshot differs from the live server. Run `python example.py tools` below when you specifically
+want to print the live schemas over HTTP.
 
 ## Credits
 
@@ -170,8 +176,11 @@ of the repository — `.gitignore` covers `*.pem`, and a committed private key i
 
 `glama.json` is the separate, Glama-specific file that claims the listing there. A server under an
 organisation rather than a personal account can only be claimed with that file present.
-It carries ownership only: configure Glama's build as `npm ci`, run
-`node bin/instantclips-mcp.js`, and supply `INSTANTCLIPS_TOKEN` as a secret in the server admin UI.
+It carries ownership only. In Glama's Dockerfile form, use build steps
+`["npm install --omit=dev"]`, CMD arguments `["node", "./bin/instantclips-mcp.js"]`, and any dummy
+value for the required `INSTANTCLIPS_TOKEN` placeholder. Glama's initialization and tool-quality
+checks use the bundled manifest and never transmit that placeholder upstream. Do not put a real
+account token into a third-party build sandbox.
 
 ## License
 

package/README.zh-CN.md

@@ -8,8 +8,9 @@ VS Code、Claude 应用、ChatGPT 或其他任何 MCP 客户端都能完成网
 起草创意方向并渲染视频。
 
 **产品服务器仍以托管方式运行。** 本仓库包含连接指南、注册表元数据、示例 HTTP 客户端，以及一个
-面向无法直接连接远程服务器的客户端的小型开源 stdio 适配器。适配器只负责将 MCP 消息转发到托管
-端点；工具定义和产品实现仍然只保留在一个地方。
+面向无法直接连接远程服务器的客户端的小型开源 stdio 适配器。适配器通过生成的快照在本地响应
+初始化、ping 和工具发现，只有经过身份验证的工具调用才会发送到托管端点。托管服务器仍是唯一的
+事实来源；本仓库不会复制产品实现。
 
 ## 端点
 
@@ -52,8 +53,8 @@ http_headers = { Authorization = "Bearer YOUR_TOKEN" }
 
 ### 仅支持 stdio 的客户端和无界面自动化
 
-`instantclips-mcp` npm 软件包是一个轻量的 stdio 到 HTTPS 适配器。它从环境变量读取令牌，将上游
-端点固定为 InstantClips，并原样转发协议消息：
+`instantclips-mcp` npm 软件包是一个轻量的 stdio 到 HTTPS 适配器。它在本地提供初始化和工具发现，
+从而无需凭据即可快速启动；随后从环境变量读取令牌，并将工具调用发送到 InstantClips：
 
 ```json
 {
@@ -76,7 +77,7 @@ INSTANTCLIPS_TOKEN="your-token" npx -y instantclips-mcp --check --json
 ```
 
 令牌只能通过 `INSTANTCLIPS_TOKEN` 提供，不能作为命令行参数传入，因此不会出现在进程列表中。
-需要 Node.js 20 或更高版本。
+工具调用需要令牌，但 `initialize`、`ping` 和 `tools/list` 不需要。需要 Node.js 20 或更高版本。
 
 ### Cursor 和 VS Code
 
@@ -112,8 +113,12 @@ INSTANTCLIPS_TOKEN="your-token" npx -y instantclips-mcp --check --json
 的表达风格进行起草。因此，当导入商品的店铺与任何现有品牌都不匹配时，流程会暂停并询问，而不是
 自行猜测。
 
-每个工具的确切参数均由服务器自身发布。本仓库有意不重复列出这些参数；请运行下方的
-`python example.py tools` 来输出实时 schema，确保你构建的集成始终与服务器实际接受的参数一致。
+每个工具的确切参数均由托管服务器发布。生成的
+[`manifest/instantclips-mcp.json`](manifest/instantclips-mcp.json) 快照让 stdio 客户端和注册表无需
+凭据即可检查同一组 schema。维护者使用
+`INSTANTCLIPS_TOKEN="..." npm run sync:manifest` 更新快照；如果已提交的快照与线上服务器不同，
+`npm run check:manifest` 会失败。如需通过 HTTP 输出实时 schema，请运行下方的
+`python example.py tools`。
 
 ## 点数
 
@@ -163,8 +168,11 @@ npm 软件包中的 `mcpName` 必须与该注册表名称完全一致。仓库
 
 `glama.json` 是 Glama 专用的独立文件，用于认领该平台上的条目。归属于组织而非个人账户的服务器，
 只有在该文件存在时才能完成认领。
-该文件只用于证明所有权：在 Glama 中将构建命令设置为 `npm ci`，运行
-`node bin/instantclips-mcp.js`，并在服务器管理界面中将 `INSTANTCLIPS_TOKEN` 配置为密钥。
+该文件只用于证明所有权。在 Glama 的 Dockerfile 表单中，将构建步骤设为
+`["npm install --omit=dev"]`，将 CMD 参数设为
+`["node", "./bin/instantclips-mcp.js"]`，并为必填的 `INSTANTCLIPS_TOKEN` 占位参数填写任意虚拟值。
+Glama 的初始化与工具质量检查只读取随包提供的清单，不会将该占位值发送到托管服务器。请勿把真实
+账户令牌放入第三方构建沙箱。
 
 ## 许可证
 

package/bin/instantclips-mcp.js

@@ -7,6 +7,7 @@ import {
   StreamableHTTPClientTransport,
   UnauthorizedError,
 } from "@modelcontextprotocol/client";
+import { Server } from "@modelcontextprotocol/server";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 
 const DEFAULT_ENDPOINT = "https://app.instantclips.ai/mcp";
@@ -14,6 +15,12 @@ const SETTINGS_URL = "https://app.instantclips.ai/settings#ai-access";
 const packageJson = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8"),
 );
+const manifest = JSON.parse(
+  readFileSync(
+    new URL("../manifest/instantclips-mcp.json", import.meta.url),
+    "utf8",
+  ),
+);
 const VERSION = packageJson.version;
 
 function usage() {
@@ -28,15 +35,15 @@ Usage:
   instantclips-mcp --version
 
 Environment:
-  INSTANTCLIPS_TOKEN    Required bearer token. Create one at ${SETTINGS_URL}
+  INSTANTCLIPS_TOKEN    Bearer token required for tool calls. Create one at ${SETTINGS_URL}
 
-The upstream endpoint is ${DEFAULT_ENDPOINT}.
+Initialization and tool discovery work offline. Tool calls use ${DEFAULT_ENDPOINT}.
 `;
 }
 
-function configuration(env = process.env) {
+function configuration(env = process.env, { requireToken = true } = {}) {
   const token = env.INSTANTCLIPS_TOKEN?.trim();
-  if (!token) {
+  if (!token && requireToken) {
     throw new CliError(
       "missing_token",
       `INSTANTCLIPS_TOKEN is required. Create a token at ${SETTINGS_URL}.`,
@@ -72,37 +79,25 @@ function configuration(env = process.env) {
 }
 
 function remoteTransport({ endpoint, token }) {
+  if (!token) {
+    throw new CliError(
+      "missing_token",
+      `INSTANTCLIPS_TOKEN is required for tool calls. Create a token at ${SETTINGS_URL}.`,
+      78,
+    );
+  }
   return new StreamableHTTPClientTransport(endpoint, {
     authProvider: { token: async () => token },
   });
 }
 
-function isRequest(message) {
-  return Boolean(
-    message &&
-      !Array.isArray(message) &&
-      typeof message === "object" &&
-      typeof message.method === "string" &&
-      Object.hasOwn(message, "id"),
-  );
-}
-
-function isResponse(message) {
-  return Boolean(
-    message &&
-      !Array.isArray(message) &&
-      typeof message === "object" &&
-      Object.hasOwn(message, "id") &&
-      (Object.hasOwn(message, "result") || Object.hasOwn(message, "error")),
-  );
-}
-
 function safeFailure(error, token) {
+  if (error instanceof CliError) {
+    return { code: error.code, message: error.message };
+  }
   const status = error?.data?.status;
-  const text = String(error?.message || error || "Unknown error").replaceAll(
-    token,
-    "[redacted]",
-  );
+  const rawText = String(error?.message || error || "Unknown error");
+  const text = token ? rawText.replaceAll(token, "[redacted]") : rawText;
 
   if (
     error instanceof UnauthorizedError ||
@@ -136,10 +131,52 @@ function writeDiagnostic(failure) {
 
 async function startBridge(config) {
   const stdio = new StdioServerTransport();
-  const remote = remoteTransport(config);
-  const initializeRequestIds = new Set();
+  const server = new Server(manifest.serverInfo, {
+    capabilities: manifest.capabilities,
+    instructions: manifest.instructions,
+  });
+  let remoteClient;
+  let remoteClientPromise;
   let closing = false;
 
+  const connectRemote = () => {
+    if (!remoteClientPromise) {
+      remoteClientPromise = (async () => {
+        const client = new Client({
+          name: "instantclips-mcp-stdio-adapter",
+          version: VERSION,
+        });
+        try {
+          await client.connect(remoteTransport(config));
+          remoteClient = client;
+          return client;
+        } catch (error) {
+          await client.close().catch(() => {});
+          remoteClientPromise = undefined;
+          throw error;
+        }
+      })();
+    }
+    return remoteClientPromise;
+  };
+
+  server.setRequestHandler("tools/list", async () => ({
+    tools: manifest.tools,
+  }));
+
+  server.setRequestHandler("tools/call", async (request) => {
+    try {
+      const client = await connectRemote();
+      return await client.callTool(request.params);
+    } catch (error) {
+      const failure = safeFailure(error, config.token);
+      return {
+        content: [{ type: "text", text: failure.message }],
+        isError: true,
+      };
+    }
+  });
+
   const shutdown = async (exitCode = process.exitCode || 0) => {
     if (closing) return;
     closing = true;
@@ -148,68 +185,18 @@ async function startBridge(config) {
     process.stdin.off("close", onStdinEnd);
     process.off("SIGINT", onSigint);
     process.off("SIGTERM", onSigterm);
-    await Promise.allSettled([remote.close(), stdio.close()]);
+    await Promise.allSettled([remoteClient?.close(), server.close()]);
   };
 
   const onStdinEnd = () => void shutdown();
   const onSigint = () => void shutdown(130);
   const onSigterm = () => void shutdown(143);
-
-  stdio.onmessage = (message) => {
-    if (isRequest(message) && message.method === "initialize") {
-      initializeRequestIds.add(message.id);
-    }
-
-    void remote.send(message).catch(async (error) => {
-      if (isRequest(message)) {
-        initializeRequestIds.delete(message.id);
-        const failure = safeFailure(error, config.token);
-        await stdio
-          .send({
-            jsonrpc: "2.0",
-            id: message.id,
-            error: {
-              code: -32000,
-              message: failure.message,
-              data: { code: failure.code },
-            },
-          })
-          .catch((sendError) => {
-            writeDiagnostic(safeFailure(sendError, config.token));
-            void shutdown(74);
-          });
-      }
-    });
-  };
-
-  remote.onmessage = (message) => {
-    if (isResponse(message) && initializeRequestIds.delete(message.id)) {
-      const protocolVersion = message.result?.protocolVersion;
-      if (typeof protocolVersion === "string") {
-        remote.setProtocolVersion(protocolVersion);
-      }
-    }
-    void stdio.send(message).catch((error) => {
-      writeDiagnostic(safeFailure(error, config.token));
-      void shutdown(74);
-    });
-  };
-
-  remote.onerror = (error) => writeDiagnostic(safeFailure(error, config.token));
-  remote.onclose = () => void shutdown();
-  stdio.onerror = (error) => {
-    writeDiagnostic(safeFailure(error, config.token));
-    void shutdown(74);
-  };
-  stdio.onclose = () => void shutdown();
-
   process.stdin.once("end", onStdinEnd);
   process.stdin.once("close", onStdinEnd);
   process.once("SIGINT", onSigint);
   process.once("SIGTERM", onSigterm);
 
-  await remote.start();
-  await stdio.start();
+  await server.connect(stdio);
 }
 
 async function checkConnection(config, json) {
@@ -286,7 +273,7 @@ async function main(args) {
 
   let config;
   try {
-    config = configuration();
+    config = configuration(process.env, { requireToken: check });
   } catch (error) {
     if (check && json && error instanceof CliError) {
       process.stdout.write(

package/manifest/instantclips-mcp.json

@@ -0,0 +1,326 @@
+{
+  "schemaVersion": 1,
+  "source": "https://app.instantclips.ai/mcp",
+  "capabilities": {
+    "tools": {}
+  },
+  "serverInfo": {
+    "name": "instantclips",
+    "title": "InstantClips",
+    "version": "0.2.0",
+    "websiteUrl": "https://instantclips.ai"
+  },
+  "instructions": "InstantClips turns a product into a short vertical marketing video.\n\nEvery video is drafted against a BRAND — a voice, a target market and a\nset of keywords. Getting the brand right matters more than anything else\nhere: a product drafted under the wrong company's voice renders perfectly\nand is still unusable. Never assume a product belongs to whatever brand\nthe account already has.\n\nStart by asking the user for their store's URL if you do not already know\nthe brand, and call `list_brands` to see what the account has. Unlike the\nwebsite, which takes a product link and gets out of the way, you can\nsimply ask — a short question here is cheaper than a wrongly branded\nvideo.\n\nThe workflow, in order:\n\n1. `import_product_from_url` with the product's page URL (or\n   `create_product_from_images` with hosted image URLs). Both return\n   immediately and import in the background.\n2. Poll `get_product` until `import_status` is \"imported\".\n   - If it reports `brand_decision_required` with `drafting: false`, the\n     storefront does not match any brand on the account. Stop and put the\n     choice to the user: create a brand for it (`create_brand`) or attach\n     it to one they already have (`set_product_brand`). Do not choose for\n     them. No direction is drafted until this is settled.\n   - Otherwise the import also drafts a video direction — a six-section\n     creative plan (Hook / Content Focus / Format / Suggesting Visual\n     Aesthetic / Execution Guidelines /\n     Strict Guidelines & Restrictions) — so keep polling until\n     `video_direction.drafting` is false.\n3. Show the drafted direction to the user. Edit it with\n   `update_video_direction`, or roll a completely different angle with\n   `redraft_video_direction`. The direction is optional: an empty one is\n   valid and generation still works.\n4. `generate_video` — this SPENDS THE USER'S CREDITS. Get the user's\n   explicit go-ahead first, and tell them the credit cost that\n   `get_product` reports.\n5. Poll `get_video` until status is \"done\", then give the user\n   `output_url` (the finished MP4) and `share_url` (a public page).\n\nA render takes a few minutes. Poll every 20-30 seconds rather than in a\ntight loop, and tell the user what you are waiting on.\n",
+  "tools": [
+    {
+      "name": "list_brands",
+      "title": "List the account's brands",
+      "description": "List the brands on this account, with the plan's brand limit and whether\nanother brand can be created.\n\nA brand carries the identity every video is drafted against: its voice,\nits target market and its keywords. A product must belong to the brand it\nactually comes from — a product drafted under another company's voice is\nwrong even though it renders fine.\n\nCall this before answering a `brand_decision_required` from\n`get_product`, and whenever the user needs to choose or name a brand.\n\nThis does not spend credits.\n",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "properties": {},
+        "required": [],
+        "type": "object"
+      },
+      "annotations": {
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false,
+        "readOnlyHint": true
+      }
+    },
+    {
+      "name": "import_product_from_url",
+      "title": "Import a product from its page URL",
+      "description": "Start a new InstantClips product from a product page URL (a storefront\nlisting, e.g. a Shopify product page).\n\nReturns immediately with a product_id — the scrape, the image download\nand the first video-direction draft all run in the background. Poll\n`get_product` until `import_status` is \"imported\" and\n`video_direction.drafting` is false, which usually takes under a minute.\n\nPasting a URL that was already imported on this account returns that\nexisting product instead of creating a duplicate.\n\nIf the storefront name does not exactly match a brand this account has\nalready reviewed, the import stops on a brand decision instead of\nguessing: `get_product` will report `brand_decision_required`, and no\nvideo direction is drafted until it is resolved with `create_brand` or\n`set_product_brand`. Do not assume the account's existing brand — a\nproduct from a different company drafted under the wrong brand's voice\nis the failure this prevents. Pass `brand_id` only when the user has\ntold you which brand this product belongs to.\n\nThis does not spend credits. Only `generate_video` does.\n",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "properties": {
+          "url": {
+            "type": "string",
+            "description": "The product page URL, e.g. https://store.example.com/products/wool-runner"
+          },
+          "brand_id": {
+            "type": "string",
+            "description": "Optional, and only when the user has said which brand this is. Omit it to let the import match the storefront against the account's brands and ask when it cannot. Use `list_brands` to see what exists."
+          }
+        },
+        "required": [
+          "url"
+        ],
+        "type": "object"
+      },
+      "annotations": {
+        "destructiveHint": false,
+        "idempotentHint": false,
+        "openWorldHint": true,
+        "readOnlyHint": false
+      }
+    },
+    {
+      "name": "create_product_from_images",
+      "title": "Create a product from image URLs",
+      "description": "Start a new InstantClips product from hosted product photos, for a\nproduct that has no public page to scrape.\n\nImages must be publicly reachable URLs — this endpoint cannot read files\nfrom the caller's machine. Images larger than\n8MB are skipped; at most\n9 are used in a render.\n\nReturns immediately with a product_id; the downloads and the first\nvideo-direction draft run in the background. Poll `get_product` until\n`import_status` is \"imported\".\n\nPrefer `import_product_from_url` when a product page exists — the scrape\nalso collects the name, description, price and brand identity, which\nmake for a far better direction draft than images alone.\n\nThis does not spend credits. Only `generate_video` does.\n",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "properties": {
+          "image_urls": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Publicly reachable image URLs, most representative first.",
+            "minItems": 1
+          },
+          "name": {
+            "type": "string",
+            "description": "Product name."
+          },
+          "description": {
+            "type": "string",
+            "description": "Optional. What the product is, in a sentence or two — feeds the direction draft."
+          },
+          "creator_note": {
+            "type": "string",
+            "description": "Optional. A short free-text note to the director: the angle, occasion or message this video should carry."
+          },
+          "brand_id": {
+            "type": "string",
+            "description": "Which brand this product belongs to, from `list_brands`. There is no page to scrape here, so nothing can detect the brand for you: confirm it with the user rather than letting it fall through to the account's default brand."
+          }
+        },
+        "required": [
+          "image_urls",
+          "name"
+        ],
+        "type": "object"
+      },
+      "annotations": {
+        "destructiveHint": false,
+        "idempotentHint": false,
+        "openWorldHint": true,
+        "readOnlyHint": false
+      }
+    },
+    {
+      "name": "get_product",
+      "title": "Get a product and its video direction",
+      "description": "Read a product: what the import found, the current video direction and\nsettings, and every video generated from it.\n\nUse this to poll after `import_product_from_url` or\n`create_product_from_images`. The product is ready to work with when\n`import_status` is \"imported\" AND `video_direction.drafting` is false.\nPoll every 20-30 seconds; the whole thing normally settles inside a\nminute.\n\n`import_status` values: \"pending\" and \"importing\" mean keep polling;\n\"imported\" means done; \"failed\" means it did not work and\n`import_failed_reason` says why.\n\n`video_direction.credit_cost` is what `generate_video` will charge for\nthe current settings.\n",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "properties": {
+          "product_id": {
+            "type": "string",
+            "description": "The product's id."
+          }
+        },
+        "required": [
+          "product_id"
+        ],
+        "type": "object"
+      },
+      "annotations": {
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false,
+        "readOnlyHint": true
+      }
+    },
+    {
+      "name": "create_brand",
+      "title": "Create a brand for a product",
+      "description": "Create a new brand from the identity detected on a product that is\nwaiting on `brand_decision_required`, and attach the product to it.\n\nUse this when the product belongs to a company the account has no brand\nfor yet — the usual case when someone brings a new store. The brand's\nvoice, target market and keywords are taken from what the storefront\nscrape drafted; the user can rename it with `name`.\n\nAsk the user before calling this. It consumes one of the plan's brand\nslots, and on a plan that has run out this fails with a brand-limit\nerror — at which point the choices are to attach the product to an\nexisting brand with `set_product_brand`, to re-point an existing brand\nat this identity with `set_product_brand` and `replace_identity: true`,\nor to upgrade.\n\nOnce this returns, the video direction starts drafting: poll\n`get_product` until `video_direction.drafting` is false.\n\nThis does not spend credits.\n",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "properties": {
+          "product_id": {
+            "type": "string",
+            "description": "The product waiting on a brand decision."
+          },
+          "name": {
+            "type": "string",
+            "description": "Optional. Overrides the detected storefront name for the new brand."
+          }
+        },
+        "required": [
+          "product_id"
+        ],
+        "type": "object"
+      },
+      "annotations": {
+        "destructiveHint": false,
+        "idempotentHint": false,
+        "openWorldHint": false,
+        "readOnlyHint": false
+      }
+    },
+    {
+      "name": "set_product_brand",
+      "title": "Attach a product to an existing brand",
+      "description": "Attach a product waiting on `brand_decision_required` to one of the\naccount's existing brands. Use `list_brands` to see them.\n\nOnly do this when the user has confirmed the product really belongs to\nthat brand. Attaching a product to an unrelated brand is not a cosmetic\nmislabel: every video is drafted in that brand's voice, to its target\nmarket, with its keywords.\n\nBy default the brand's existing identity is left untouched. Pass\n`replace_identity: true` to instead overwrite that brand's voice, target\nmarket and keywords with the identity detected on this product — the\n\"re-point my brand at a different company\" move, for an account at its\nbrand limit. This rewrites a brand every other product on it shares, so\nconfirm it with the user explicitly first.\n\nOnce this returns, the video direction starts drafting: poll\n`get_product` until `video_direction.drafting` is false.\n\nThis does not spend credits.\n",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "properties": {
+          "product_id": {
+            "type": "string",
+            "description": "The product waiting on a brand decision."
+          },
+          "brand_id": {
+            "type": "string",
+            "description": "The brand to attach it to, from `list_brands`."
+          },
+          "replace_identity": {
+            "type": "boolean",
+            "description": "Optional, default false. Overwrite the brand's voice, target market and keywords with this product's detected identity. Affects every product on that brand — confirm with the user."
+          }
+        },
+        "required": [
+          "product_id",
+          "brand_id"
+        ],
+        "type": "object"
+      },
+      "annotations": {
+        "destructiveHint": true,
+        "idempotentHint": false,
+        "openWorldHint": false,
+        "readOnlyHint": false
+      }
+    },
+    {
+      "name": "update_video_direction",
+      "title": "Edit the video direction and render settings",
+      "description": "Edit the creative direction and render settings for a product's next\nvideo. Only the fields you pass are changed; everything else keeps its\ncurrent value.\n\n`creative_direction` is the plan the render is built from. It is free\ntext, but the drafts follow a six-section shape that works well and is\nworth preserving when editing:\n\n  Hook: ...\n  Content Focus: ...\n  Format: ...\n  Execution Guidelines: ...\n  Strict Guidelines & Restrictions: ...\n\nDo not invent a direction from nothing when one has not been drafted\nyet — call `redraft_video_direction` and edit what comes back. Leaving\nit empty is also valid: generation works without a direction.\n\n`creator_note` is different and smaller: the user's own short note to\nthe director (\"mention it is machine washable\", \"for Father's Day\"). It\nis carried through to the render verbatim, so put the user's words in\nit, not your paraphrase.\n\nOnly works before generation starts. This does not spend credits.\n",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "properties": {
+          "product_id": {
+            "type": "string",
+            "description": "The product's id."
+          },
+          "creative_direction": {
+            "type": "string",
+            "description": "The full creative plan, max 3000 characters. Pass an empty string to clear it."
+          },
+          "creator_note": {
+            "type": "string",
+            "description": "The user's short note to the director, max 1000 characters."
+          },
+          "ratio": {
+            "type": "string",
+            "enum": [
+              "9:16",
+              "3:4",
+              "16:9",
+              "1:1"
+            ],
+            "description": "Aspect ratio. 9:16 (vertical) is the default and what social feeds want."
+          },
+          "resolution": {
+            "type": "string",
+            "enum": [
+              "480P",
+              "720P",
+              "1080P"
+            ],
+            "description": "1080P needs a paid plan; a pick above the plan's ceiling quietly becomes that ceiling (the response reports what was actually saved)."
+          },
+          "enable_audio": {
+            "type": "boolean",
+            "description": "Whether the render has sound."
+          },
+          "target_market": {
+            "type": "string",
+            "description": "Free text, e.g. \"US/North America\" or \"Japan\". Drives the spoken language unless one is set explicitly. Saved on the brand, so it carries to later videos."
+          }
+        },
+        "required": [
+          "product_id"
+        ],
+        "type": "object"
+      },
+      "annotations": {
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false,
+        "readOnlyHint": false
+      }
+    },
+    {
+      "name": "redraft_video_direction",
+      "title": "Draft a new creative direction",
+      "description": "Ask InstantClips to draft a fresh creative direction for this product's\nnext video, using the product's facts, its images and the brand's\nidentity. Use it to get a first draft, or to try a different angle when\nthe user does not like the current one.\n\nThis OVERWRITES the current direction — including any edits. Confirm with\nthe user before re-rolling a direction they have already worked on.\n\nThe draft runs in the background: this returns with `drafting` true, and\nyou poll `get_product` until `video_direction.drafting` is false (a few\nseconds). Rolling a fresh angle is the point, so calling it twice gives\ntwo different drafts, not the same one.\n\nThis does not spend credits.\n",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "properties": {
+          "product_id": {
+            "type": "string",
+            "description": "The product's id."
+          },
+          "format": {
+            "type": "string",
+            "description": "Optional. Pin a specific video format instead of letting the drafter pick one — e.g. \"unboxing\", \"before_after\". Unknown values are ignored, so leave it out unless the user asked for a particular kind of video."
+          }
+        },
+        "required": [
+          "product_id"
+        ],
+        "type": "object"
+      },
+      "annotations": {
+        "destructiveHint": true,
+        "idempotentHint": false,
+        "openWorldHint": true,
+        "readOnlyHint": false
+      }
+    },
+    {
+      "name": "generate_video",
+      "title": "Generate the video (spends credits)",
+      "description": "Render the video. THIS SPENDS THE USER'S CREDITS.\n\nAsk the user before calling this, every time. Tell them the cost first —\n`get_product` reports it as `video_direction.credit_cost`, and the\nuser's balance as `credits_remaining`. Credits are charged at launch,\nnot on completion; a failed render is refunded automatically.\n\nShow the user the creative direction and let them approve or edit it\nbefore you call this. Do not call it to \"see what happens\", to retry a\nrender that is still in progress, or as part of a batch you decided on\nyour own.\n\nReturns as soon as the render is queued. Poll `get_video` with the\nreturned video_request_id every 20-30 seconds until its status is\n\"done\" (a few minutes), then give the user `output_url` and\n`share_url`.\n\nIf the account cannot afford it, nothing is charged and the response\nsays so — tell the user to top up at the credits page rather than\nretrying.\n",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "properties": {
+          "product_id": {
+            "type": "string",
+            "description": "The product to render. Its current direction and settings are used as-is."
+          }
+        },
+        "required": [
+          "product_id"
+        ],
+        "type": "object"
+      },
+      "annotations": {
+        "destructiveHint": false,
+        "idempotentHint": false,
+        "openWorldHint": true,
+        "readOnlyHint": false
+      }
+    },
+    {
+      "name": "get_video",
+      "title": "Check a video's render status",
+      "description": "Check one video's render.\n\n`status` values:\n  \"generating\" — still rendering, keep polling every 20-30 seconds.\n  \"done\" — finished; `output_url` is the MP4 and `share_url` is a\n           public page to send someone.\n  \"failed\" — `failed_reason` says why. The credits were refunded\n             automatically; the user can retry from the product page.\n  \"insufficient_credit\" — never launched; nothing was charged.\n  \"pending\" — not launched yet; call `generate_video`.\n\nA render normally takes a few minutes. Tell the user what you are\nwaiting on rather than polling silently in a tight loop.\n",
+      "inputSchema": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "properties": {
+          "video_request_id": {
+            "type": "string",
+            "description": "Returned by generate_video, and listed under `videos` in get_product."
+          }
+        },
+        "required": [
+          "video_request_id"
+        ],
+        "type": "object"
+      },
+      "annotations": {
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": false,
+        "readOnlyHint": true
+      }
+    }
+  ]
+}

package/package.json

@@ -1,18 +1,22 @@
 {
   "name": "instantclips-mcp",
   "mcpName": "ai.instantclips/instantclips",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Use the hosted InstantClips MCP server from stdio-only clients.",
   "type": "module",
   "bin": {
     "instantclips-mcp": "bin/instantclips-mcp.js"
   },
   "files": [
-    "bin/"
+    "bin/",
+    "manifest/",
+    "scripts/"
   ],
   "scripts": {
     "test": "node --test",
     "check:pack": "npm pack --dry-run",
+    "sync:manifest": "node scripts/sync-manifest.mjs",
+    "check:manifest": "node scripts/sync-manifest.mjs --check",
     "prepublishOnly": "npm test && npm run check:pack"
   },
   "repository": {

package/scripts/sync-manifest.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile } from "node:fs/promises";
+
+import {
+  Client,
+  StreamableHTTPClientTransport,
+} from "@modelcontextprotocol/client";
+
+const DEFAULT_ENDPOINT = "https://app.instantclips.ai/mcp";
+const manifestUrl = new URL("../manifest/instantclips-mcp.json", import.meta.url);
+const checkOnly = process.argv.slice(2).includes("--check");
+const token = process.env.INSTANTCLIPS_TOKEN?.trim();
+
+if (!token) {
+  throw new Error(
+    "INSTANTCLIPS_TOKEN is required to refresh the public tool manifest.",
+  );
+}
+
+const endpoint = new URL(
+  process.env.INSTANTCLIPS_MCP_URL || DEFAULT_ENDPOINT,
+);
+const transport = new StreamableHTTPClientTransport(endpoint, {
+  authProvider: { token: async () => token },
+});
+const client = new Client({
+  name: "instantclips-manifest-sync",
+  version: "1.0.0",
+});
+
+try {
+  await client.connect(transport);
+
+  const tools = [];
+  let cursor;
+  do {
+    const page = await client.listTools(cursor ? { cursor } : undefined);
+    tools.push(...page.tools);
+    cursor = page.nextCursor;
+  } while (cursor);
+
+  if (!tools.length) {
+    throw new Error("The hosted server returned an empty tool list.");
+  }
+
+  const manifest = {
+    schemaVersion: 1,
+    source: endpoint.href,
+    capabilities: client.getServerCapabilities(),
+    serverInfo: client.getServerVersion(),
+    instructions: client.getInstructions(),
+    tools,
+  };
+  const next = `${JSON.stringify(manifest, null, 2)}\n`;
+
+  if (checkOnly) {
+    const current = await readFile(manifestUrl, "utf8");
+    if (current !== next) {
+      process.stderr.write(
+        "The bundled manifest differs from the hosted InstantClips MCP server. Run npm run sync:manifest and commit the result.\n",
+      );
+      process.exitCode = 1;
+    } else {
+      process.stdout.write(
+        `Manifest is current: ${tools.length} tools from ${manifest.serverInfo?.name || endpoint.hostname}.\n`,
+      );
+    }
+  } else {
+    await writeFile(manifestUrl, next);
+    process.stdout.write(
+      `Updated ${manifestUrl.pathname}: ${tools.length} tools from ${manifest.serverInfo?.name || endpoint.hostname}.\n`,
+    );
+  }
+} finally {
+  await client.close().catch(() => {});
+}