instantclips-mcp 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Instant Studio, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,195 @@
+# MCP de InstantClips
+
+[English](README.md) · **Español** · [简体中文](README.zh-CN.md)
+
+[InstantClips](https://instantclips.ai) convierte un producto de comercio electrónico en vídeos
+verticales cortos para TikTok, Instagram Reels y Stories. Funciona como un **servidor MCP alojado**,
+por lo que Claude Code, Codex, Cursor, VS Code, la aplicación de Claude, ChatGPT o cualquier otro
+cliente MCP pueden hacer lo mismo que la aplicación web: importar un producto, preparar la
+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.
+
+## Endpoint
+
+|            |                                            |
+| ---------- | ------------------------------------------ |
+| Endpoint   | `https://app.instantclips.ai/mcp`          |
+| Transporte | Streamable HTTP, sin estado                |
+| Método     | `POST`, JSON-RPC 2.0                       |
+| Auth       | `Authorization: Bearer <token>`            |
+
+Genera un token en **[app.instantclips.ai/settings#ai-access](https://app.instantclips.ai/settings#ai-access)**.
+El token da acceso a tu propia cuenta: las mismas marcas, productos, créditos y límites del plan
+que en la aplicación web. Al iniciar sesión se crea una cuenta si todavía no tienes una, con
+créditos gratuitos para empezar.
+
+Al abrir el endpoint en un navegador, aparece la página de configuración en lugar de un error de
+protocolo, con botones de instalación de un clic que introducen el token por ti.
+
+## Instalación
+
+Conéctate directamente al endpoint alojado siempre que tu cliente admita Streamable HTTP. Usa el
+adaptador stdio descrito abajo solo para clientes y procesos automatizados que requieran un comando
+local.
+
+### Claude Code
+
+```bash
+claude mcp add --transport http instantclips https://app.instantclips.ai/mcp --header "Authorization: Bearer YOUR_TOKEN"
+```
+
+### Codex
+
+Añade lo siguiente a `~/.codex/config.toml`; la configuración se aplica a la CLI, la aplicación y
+la extensión del IDE:
+
+```toml
+[mcp_servers.instantclips]
+url = "https://app.instantclips.ai/mcp"
+http_headers = { Authorization = "Bearer YOUR_TOKEN" }
+```
+
+Para no guardar el token en el archivo, sustituye el encabezado por
+`bearer_token_env_var = "INSTANTCLIPS_TOKEN"` y expórtalo como variable de entorno en tu shell.
+
+### 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:
+
+```json
+{
+  "mcpServers": {
+    "instantclips": {
+      "command": "npx",
+      "args": ["-y", "instantclips-mcp"],
+      "env": {
+        "INSTANTCLIPS_TOKEN": "YOUR_TOKEN"
+      }
+    }
+  }
+}
+```
+
+Para comprobar la conexión de forma automatizada, incluidos los nombres actuales de las
+herramientas:
+
+```bash
+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.
+
+### Cursor y VS Code
+
+La [página de configuración](https://app.instantclips.ai/settings#ai-access) incluye botones de
+instalación de un clic. Una vez generado el token, los botones lo introducen por ti.
+
+### Aplicación de Claude y ChatGPT
+
+Estos clientes se conectan mediante su propia configuración de conectores, no mediante un archivo.
+Apunta el conector a `https://app.instantclips.ai/mcp` y autentícate con el mismo token: como
+encabezado de solicitud en Claude y como clave de API en ChatGPT. Los encabezados de solicitud de
+Claude siguen en beta y ChatGPT requiere el modo de desarrollador; su disponibilidad depende de tu
+cuenta y de las políticas de tu espacio de trabajo.
+
+### Cualquier otro cliente
+
+OpenClaw, Hermes o un agente que hayas creado: conéctalo a la URL mediante Streamable HTTP con un
+encabezado `Authorization: Bearer`. El protocolo no contiene nada específico de InstantClips, por
+lo que cualquier cliente compatible con MCP ya puede comunicarse con el servidor.
+
+## Herramientas
+
+El flujo de trabajo, en orden:
+
+1. **Importar** — usa `import_product_from_url` para una página de tienda o
+   `create_product_from_images` cuando no haya una página que leer.
+2. **Esperar el borrador** — consulta `get_product` periódicamente hasta que terminen la importación
+   y la preparación de la dirección creativa.
+3. **Revisarlo y orientarlo** — la dirección se devuelve como texto: gancho, enfoque del contenido,
+   formato, pautas de ejecución y restricciones. `update_video_direction` permite editarla y
+   `redraft_video_direction` propone otro enfoque.
+4. **Renderizar** — usa `generate_video`.
+5. **Recoger el resultado** — consulta `get_video` periódicamente para obtener el MP4 terminado y
+   un enlace público para compartirlo.
+
+Las marcas funcionan de la misma manera: `list_brands`, `create_brand`, `set_product_brand`. Cada
+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.
+
+## Créditos
+
+Importar un producto, preparar la dirección creativa y editarla es **gratis**. `generate_video` es
+la única herramienta que consume créditos y requiere tu autorización explícita; las herramientas
+indican antes el coste. Un agente no puede acumular cargos sin avisarte. Consulta los
+[precios](https://instantclips.ai/#pricing).
+
+## example.py
+
+Un cliente MCP sin dependencias: solo requiere Python 3.9 o posterior y la biblioteca estándar; no
+hace falta ejecutar `pip install`.
+
+```bash
+export INSTANTCLIPS_TOKEN="your-token"
+
+python example.py tools                 # todas las herramientas, con su esquema de entrada actual
+python example.py call list_brands '{}' # llama a una herramienta con argumentos JSON
+```
+
+Ejecuta primero `tools`: muestra los nombres y tipos de parámetros reales de cada herramienta, que
+es lo que necesitas antes de automatizar el flujo de trabajo descrito arriba.
+
+## Enlaces
+
+- [instantclips.ai/automate](https://instantclips.ai/automate/) — qué es la automatización y para
+  qué sirve. No repite la configuración; esa información está en este archivo y en la página de
+  configuración de la aplicación.
+- [app.instantclips.ai/llms.txt](https://app.instantclips.ai/llms.txt) — descripción del producto y
+  de la secuencia de herramientas en un formato legible por máquinas.
+- [Términos](https://app.instantclips.ai/terms) · [Privacidad](https://app.instantclips.ai/privacy)
+
+## Registro
+
+`server.json` es la entrada de este servidor en el
+[registro oficial de MCP](https://registry.modelcontextprotocol.io), del que se alimentan los demás
+directorios. Una sola entrada, `ai.instantclips/instantclips`, contiene tanto el endpoint alojado en
+`remotes` como el adaptador stdio en `packages`. Así, cada cliente puede elegir el transporte que
+admita sin crear dos identidades para el mismo conjunto de herramientas.
+
+El valor `mcpName` del paquete npm debe coincidir exactamente con ese nombre del registro. El enlace
+al repositorio apunta al adaptador de código abierto; la implementación alojada del producto no se
+encuentra en este repositorio.
+
+El espacio de nombres `ai.instantclips` es el DNS inverso del dominio, por lo que debe publicarse
+mediante autenticación del dominio por DNS o HTTP, no mediante GitHub. Autenticarse con GitHub
+obligaría a usar `io.github.instantstudioai/...` y a renunciar al espacio de nombres de la marca.
+
+Publica primero el paquete npm y, después de incrementar `version`, vuelve a publicar esta misma
+entrada del registro con `mcp-publisher publish`. La autenticación del dominio conserva el espacio
+de nombres de marca `ai.instantclips`; no lo sustituyas por un nombre `io.github.*`. La clave de
+firma no se guarda en el repositorio: `.gitignore` cubre `*.pem`, y una clave privada incluida en un
+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.
+
+## Licencia
+
+MIT — consulta [LICENSE](LICENSE). La licencia cubre el contenido de este repositorio; el uso del
+servicio alojado se rige por los [Términos de servicio](https://app.instantclips.ai/terms).

package/README.md

@@ -0,0 +1,179 @@
+# InstantClips MCP
+
+**English** · [Español](README.es.md) · [简体中文](README.zh-CN.md)
+
+[InstantClips](https://instantclips.ai) turns an e-commerce product into short-form vertical
+video for TikTok, Instagram Reels and Stories. It runs a hosted **MCP server**, so Claude Code,
+Codex, Cursor, VS Code, the Claude app, ChatGPT or any other MCP client can do what the web app
+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.
+
+## Endpoint
+
+|            |                                            |
+| ---------- | ------------------------------------------ |
+| Endpoint   | `https://app.instantclips.ai/mcp`          |
+| Transport  | Streamable HTTP, stateless                 |
+| Method     | `POST`, JSON-RPC 2.0                       |
+| Auth       | `Authorization: Bearer <token>`            |
+
+Mint a token at **[app.instantclips.ai/settings#ai-access](https://app.instantclips.ai/settings#ai-access)**.
+The token is a handle on your own account: same brands, products, credits and plan limits as the
+web app. Signing in creates an account if you do not have one, with free credits to start.
+
+Opening the endpoint in a browser returns the setup page rather than a protocol error, with
+one-click install buttons that fill your token in for you.
+
+## Install
+
+Connect to the hosted endpoint directly whenever your client supports Streamable HTTP. Use the
+stdio adapter below only for clients and automated runners that require a local command.
+
+### Claude Code
+
+```bash
+claude mcp add --transport http instantclips https://app.instantclips.ai/mcp --header "Authorization: Bearer YOUR_TOKEN"
+```
+
+### Codex
+
+Add to `~/.codex/config.toml`, which covers the CLI, the app and the IDE extension together:
+
+```toml
+[mcp_servers.instantclips]
+url = "https://app.instantclips.ai/mcp"
+http_headers = { Authorization = "Bearer YOUR_TOKEN" }
+```
+
+To keep the token out of the file, swap the header for `bearer_token_env_var = "INSTANTCLIPS_TOKEN"`
+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:
+
+```json
+{
+  "mcpServers": {
+    "instantclips": {
+      "command": "npx",
+      "args": ["-y", "instantclips-mcp"],
+      "env": {
+        "INSTANTCLIPS_TOKEN": "YOUR_TOKEN"
+      }
+    }
+  }
+}
+```
+
+For an automated connectivity check, including the live tool names:
+
+```bash
+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.
+
+### Cursor and VS Code
+
+One-click install buttons are on the [setup page](https://app.instantclips.ai/settings#ai-access).
+They fill in your token once you have minted one.
+
+### Claude app and ChatGPT
+
+These connect through their own connector settings rather than a file. Point one at
+`https://app.instantclips.ai/mcp` and authenticate with the same token — a request header in
+Claude, an API key in ChatGPT. Claude's request headers are still in beta, and ChatGPT requires
+developer mode; availability there depends on your account and workspace policy.
+
+### Anything else
+
+OpenClaw, Hermes, or an agent you wrote yourself: point it at the URL over streamable HTTP with an
+`Authorization: Bearer` header. Nothing on the wire is InstantClips-specific, so a client that
+speaks MCP already speaks this.
+
+## Tools
+
+The workflow, in order:
+
+1. **Import** — `import_product_from_url` for a store page, or `create_product_from_images` when
+   there is no page to read.
+2. **Wait for the draft** — poll `get_product` until the import and the creative direction have
+   finished.
+3. **Read and steer it** — the direction comes back as text: hook, content focus, format,
+   execution guidelines, restrictions. `update_video_direction` edits it, `redraft_video_direction`
+   asks for another angle.
+4. **Render** — `generate_video`.
+5. **Collect** — poll `get_video` for the finished MP4 and a public share link.
+
+Brands work the same way: `list_brands`, `create_brand`, `set_product_brand`. Every video is
+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.
+
+## Credits
+
+Importing a product, drafting the creative direction and editing it are all **free**.
+`generate_video` is the only tool that spends credits, and it requires your explicit go-ahead — the
+tools report the cost first. An agent cannot quietly run up a bill. See
+[pricing](https://instantclips.ai/#pricing).
+
+## example.py
+
+A dependency-free MCP client — Python 3.9+, standard library only, no `pip install`.
+
+```bash
+export INSTANTCLIPS_TOKEN="your-token"
+
+python example.py tools                 # every tool, with its live input schema
+python example.py call list_brands '{}' # call one tool with JSON arguments
+```
+
+`tools` is the one to run first: it prints the real parameter names and types for every tool, which
+is what you need before scripting the workflow above.
+
+## Links
+
+- [instantclips.ai/automate](https://instantclips.ai/automate/) — what the automation is and what
+  it is for. It does not repeat the setup; this file and the app's setup page are where that lives.
+- [app.instantclips.ai/llms.txt](https://app.instantclips.ai/llms.txt) — machine-readable
+  description of the product and the tool sequence
+- [Terms](https://app.instantclips.ai/terms) · [Privacy](https://app.instantclips.ai/privacy)
+
+## Registry
+
+`server.json` is this server's entry in the [official MCP registry](https://registry.modelcontextprotocol.io),
+which the other directories ingest from. One `ai.instantclips/instantclips` entry carries both the
+hosted endpoint in `remotes` and the stdio adapter in `packages`, so a host can choose the transport
+it supports without creating two identities for the same tool surface.
+
+The npm package's `mcpName` must exactly match that registry name. The repository link points to the
+open-source adapter; the hosted product implementation is not in this repository.
+
+The `ai.instantclips` namespace is the reverse-DNS of the domain, which requires publishing under
+DNS or HTTP domain auth rather than GitHub auth. Authenticating with GitHub instead would force the
+entry into `io.github.instantstudioai/...` and give up the branded namespace.
+
+Publish the npm package first, then re-publish this same registry entry with
+`mcp-publisher publish` after bumping its `version`. Domain authentication keeps the branded
+`ai.instantclips` namespace; do not replace it with an `io.github.*` name. The signing key stays out
+of the repository — `.gitignore` covers `*.pem`, and a committed private key is a published one.
+
+`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.
+
+## License
+
+MIT — see [LICENSE](LICENSE). The license covers this repository's contents; use of the hosted
+service is governed by the [Terms of Service](https://app.instantclips.ai/terms).

package/README.zh-CN.md

@@ -0,0 +1,172 @@
+# InstantClips MCP
+
+[English](README.md) · [Español](README.es.md) · **简体中文**
+
+[InstantClips](https://instantclips.ai) 可将电商商品转化为适用于 TikTok、Instagram Reels 和
+Stories 的竖屏短视频。它提供托管的 **MCP 服务器**，因此 Claude Code、Codex、Cursor、
+VS Code、Claude 应用、ChatGPT 或其他任何 MCP 客户端都能完成网页应用中的工作：导入商品、
+起草创意方向并渲染视频。
+
+**产品服务器仍以托管方式运行。** 本仓库包含连接指南、注册表元数据、示例 HTTP 客户端，以及一个
+面向无法直接连接远程服务器的客户端的小型开源 stdio 适配器。适配器只负责将 MCP 消息转发到托管
+端点；工具定义和产品实现仍然只保留在一个地方。
+
+## 端点
+
+|          |                                            |
+| -------- | ------------------------------------------ |
+| 端点     | `https://app.instantclips.ai/mcp`          |
+| 传输方式 | Streamable HTTP，无状态                    |
+| 方法     | `POST`，JSON-RPC 2.0                       |
+| 身份验证 | `Authorization: Bearer <token>`            |
+
+前往 **[app.instantclips.ai/settings#ai-access](https://app.instantclips.ai/settings#ai-access)**
+生成令牌。该令牌关联你自己的账户，可访问与网页应用相同的品牌、商品、点数和方案限额。如果你还没有
+账户，登录时会自动创建账户，并赠送可用于开始体验的免费点数。
+
+在浏览器中打开端点时会显示设置页面，而不是协议错误；页面上的一键安装按钮会自动为你填入令牌。
+
+## 安装
+
+如果客户端支持 Streamable HTTP，请优先直接连接托管端点。只有在客户端或自动化运行环境必须执行
+本地命令时，才使用下方的 stdio 适配器。
+
+### Claude Code
+
+```bash
+claude mcp add --transport http instantclips https://app.instantclips.ai/mcp --header "Authorization: Bearer YOUR_TOKEN"
+```
+
+### Codex
+
+将以下配置添加到 `~/.codex/config.toml`。该配置同时适用于 CLI、应用和 IDE 扩展：
+
+```toml
+[mcp_servers.instantclips]
+url = "https://app.instantclips.ai/mcp"
+http_headers = { Authorization = "Bearer YOUR_TOKEN" }
+```
+
+如果不想将令牌写入文件，请将请求头配置替换为
+`bearer_token_env_var = "INSTANTCLIPS_TOKEN"`，然后在 shell 中导出该环境变量。
+
+### 仅支持 stdio 的客户端和无界面自动化
+
+`instantclips-mcp` npm 软件包是一个轻量的 stdio 到 HTTPS 适配器。它从环境变量读取令牌，将上游
+端点固定为 InstantClips，并原样转发协议消息：
+
+```json
+{
+  "mcpServers": {
+    "instantclips": {
+      "command": "npx",
+      "args": ["-y", "instantclips-mcp"],
+      "env": {
+        "INSTANTCLIPS_TOKEN": "YOUR_TOKEN"
+      }
+    }
+  }
+}
+```
+
+如需自动检查连接并获取实时工具名称，请运行：
+
+```bash
+INSTANTCLIPS_TOKEN="your-token" npx -y instantclips-mcp --check --json
+```
+
+令牌只能通过 `INSTANTCLIPS_TOKEN` 提供，不能作为命令行参数传入，因此不会出现在进程列表中。
+需要 Node.js 20 或更高版本。
+
+### Cursor 和 VS Code
+
+[设置页面](https://app.instantclips.ai/settings#ai-access)提供一键安装按钮。生成令牌后，按钮会自动
+为你填入令牌。
+
+### Claude 应用和 ChatGPT
+
+这些客户端通过各自的连接器设置进行连接，而不是读取配置文件。将连接地址设为
+`https://app.instantclips.ai/mcp`，并使用同一个令牌进行身份验证：Claude 使用请求头，ChatGPT
+使用 API 密钥。Claude 的自定义请求头功能仍处于测试阶段，而 ChatGPT 需要开启开发者模式；具体
+是否可用取决于你的账户和工作区政策。
+
+### 其他客户端
+
+无论是 OpenClaw、Hermes，还是你自己编写的智能体，只需通过 Streamable HTTP 连接该 URL，并
+添加 `Authorization: Bearer` 请求头。传输协议中没有 InstantClips 专用内容，因此任何支持 MCP
+的客户端都能与该服务器通信。
+
+## 工具
+
+工作流程如下：
+
+1. **导入** — 如果有店铺商品页面，使用 `import_product_from_url`；如果没有可读取的页面，则使用
+   `create_product_from_images`。
+2. **等待草稿** — 轮询 `get_product`，直到商品导入和创意方向起草完成。
+3. **查看并调整** — 创意方向以文本返回，包含开场钩子、内容重点、形式、执行指南和限制条件。
+   使用 `update_video_direction` 进行编辑，或使用 `redraft_video_direction` 获取另一个方向。
+4. **渲染** — 使用 `generate_video`。
+5. **获取结果** — 轮询 `get_video`，获取完成的 MP4 文件和公开分享链接。
+
+品牌的操作方式相同：`list_brands`、`create_brand`、`set_product_brand`。每个视频都会采用对应品牌
+的表达风格进行起草。因此，当导入商品的店铺与任何现有品牌都不匹配时，流程会暂停并询问，而不是
+自行猜测。
+
+每个工具的确切参数均由服务器自身发布。本仓库有意不重复列出这些参数；请运行下方的
+`python example.py tools` 来输出实时 schema，确保你构建的集成始终与服务器实际接受的参数一致。
+
+## 点数
+
+导入商品、起草创意方向和编辑方向均为**免费**。只有 `generate_video` 会消耗点数，而且必须获得你
+的明确许可；工具会事先报告费用。智能体无法在你不知情的情况下产生费用。详见
+[价格](https://instantclips.ai/#pricing)。
+
+## example.py
+
+这是一个无第三方依赖的 MCP 客户端，仅需 Python 3.9 或更高版本和标准库，无需运行
+`pip install`。
+
+```bash
+export INSTANTCLIPS_TOKEN="your-token"
+
+python example.py tools                 # 所有工具及其实时输入 schema
+python example.py call list_brands '{}' # 使用 JSON 参数调用一个工具
+```
+
+请先运行 `tools`：它会输出每个工具真实的参数名称和类型，这是自动化上述工作流程前所需的信息。
+
+## 链接
+
+- [instantclips.ai/automate](https://instantclips.ai/automate/) — 介绍自动化功能及其用途。该页面不会
+  重复设置说明；设置方法请参阅本文档和应用中的设置页面。
+- [app.instantclips.ai/llms.txt](https://app.instantclips.ai/llms.txt) — 适合机器读取的产品说明和工具
+  调用顺序。
+- [服务条款](https://app.instantclips.ai/terms) · [隐私政策](https://app.instantclips.ai/privacy)
+
+## 注册表
+
+`server.json` 是该服务器在 [MCP 官方注册表](https://registry.modelcontextprotocol.io)中的条目，其他
+目录会从中获取信息。同一个 `ai.instantclips/instantclips` 条目既通过 `remotes` 提供托管端点，
+也通过 `packages` 提供 stdio 适配器。客户端可根据自身支持情况选择传输方式，无需为同一组工具创建
+两个身份。
+
+npm 软件包中的 `mcpName` 必须与该注册表名称完全一致。仓库链接指向开源适配器；托管产品的实现
+不在本仓库中。
+
+`ai.instantclips` 命名空间是域名的反向 DNS，因此发布时必须使用 DNS 或 HTTP 域名验证，而不能
+使用 GitHub 身份验证。改用 GitHub 身份验证会强制使用 `io.github.instantstudioai/...`，从而失去
+品牌命名空间。
+
+请先发布 npm 软件包，再增加 `version`，并运行 `mcp-publisher publish` 重新发布同一个注册表条目。
+域名身份验证会保留品牌命名空间 `ai.instantclips`；请勿将其替换为 `io.github.*` 名称。签名密钥不
+存放在仓库中：`.gitignore` 已忽略 `*.pem`，因为一旦提交私钥，就等于公开了私钥。
+
+`glama.json` 是 Glama 专用的独立文件，用于认领该平台上的条目。归属于组织而非个人账户的服务器，
+只有在该文件存在时才能完成认领。
+该文件只用于证明所有权：在 Glama 中将构建命令设置为 `npm ci`，运行
+`node bin/instantclips-mcp.js`，并在服务器管理界面中将 `INSTANTCLIPS_TOKEN` 配置为密钥。
+
+## 许可证
+
+MIT — 参见 [LICENSE](LICENSE)。该许可证适用于本仓库中的内容；托管服务的使用受
+[服务条款](https://app.instantclips.ai/terms)约束。

package/bin/instantclips-mcp.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+
+import {
+  Client,
+  StreamableHTTPClientTransport,
+  UnauthorizedError,
+} from "@modelcontextprotocol/client";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+
+const DEFAULT_ENDPOINT = "https://app.instantclips.ai/mcp";
+const SETTINGS_URL = "https://app.instantclips.ai/settings#ai-access";
+const packageJson = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+const VERSION = packageJson.version;
+
+function usage() {
+  return `InstantClips MCP ${VERSION}
+
+Use the hosted InstantClips MCP server from a client that requires stdio.
+
+Usage:
+  instantclips-mcp
+  instantclips-mcp --check [--json]
+  instantclips-mcp --help
+  instantclips-mcp --version
+
+Environment:
+  INSTANTCLIPS_TOKEN    Required bearer token. Create one at ${SETTINGS_URL}
+
+The upstream endpoint is ${DEFAULT_ENDPOINT}.
+`;
+}
+
+function configuration(env = process.env) {
+  const token = env.INSTANTCLIPS_TOKEN?.trim();
+  if (!token) {
+    throw new CliError(
+      "missing_token",
+      `INSTANTCLIPS_TOKEN is required. Create a token at ${SETTINGS_URL}.`,
+      78,
+    );
+  }
+
+  let endpoint;
+  try {
+    endpoint = new URL(env.INSTANTCLIPS_MCP_URL || DEFAULT_ENDPOINT);
+  } catch {
+    throw new CliError(
+      "invalid_endpoint",
+      "The InstantClips MCP endpoint URL is invalid.",
+      78,
+    );
+  }
+  const isLoopback = ["localhost", "127.0.0.1", "[::1]"].includes(
+    endpoint.hostname,
+  );
+  if (
+    endpoint.protocol !== "https:" &&
+    !(endpoint.protocol === "http:" && isLoopback)
+  ) {
+    throw new CliError(
+      "insecure_endpoint",
+      "The InstantClips MCP endpoint must use HTTPS (HTTP is allowed only for loopback tests).",
+      78,
+    );
+  }
+
+  return { endpoint, token };
+}
+
+function remoteTransport({ endpoint, token }) {
+  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) {
+  const status = error?.data?.status;
+  const text = String(error?.message || error || "Unknown error").replaceAll(
+    token,
+    "[redacted]",
+  );
+
+  if (
+    error instanceof UnauthorizedError ||
+    status === 401 ||
+    /\b401\b/.test(text)
+  ) {
+    return {
+      code: "authentication_failed",
+      message: `InstantClips authentication failed. Replace INSTANTCLIPS_TOKEN with a token from ${SETTINGS_URL}.`,
+    };
+  }
+
+  if (
+    /fetch failed|ECONNREFUSED|ENOTFOUND|ETIMEDOUT|network|socket|connect/i.test(text)
+  ) {
+    return {
+      code: "upstream_unavailable",
+      message: "The hosted InstantClips MCP endpoint is unavailable.",
+    };
+  }
+
+  return {
+    code: "upstream_error",
+    message: `The hosted InstantClips MCP endpoint returned an error: ${text}`,
+  };
+}
+
+function writeDiagnostic(failure) {
+  process.stderr.write(`instantclips-mcp: ${failure.message}\n`);
+}
+
+async function startBridge(config) {
+  const stdio = new StdioServerTransport();
+  const remote = remoteTransport(config);
+  const initializeRequestIds = new Set();
+  let closing = false;
+
+  const shutdown = async (exitCode = process.exitCode || 0) => {
+    if (closing) return;
+    closing = true;
+    process.exitCode = exitCode;
+    process.stdin.off("end", onStdinEnd);
+    process.stdin.off("close", onStdinEnd);
+    process.off("SIGINT", onSigint);
+    process.off("SIGTERM", onSigterm);
+    await Promise.allSettled([remote.close(), stdio.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();
+}
+
+async function checkConnection(config, json) {
+  const transport = remoteTransport(config);
+  const client = new Client({ name: "instantclips-mcp-check", version: VERSION });
+
+  try {
+    await client.connect(transport);
+    const tools = [];
+    let cursor;
+    do {
+      const page = await client.listTools(cursor ? { cursor } : undefined);
+      tools.push(...page.tools.map((tool) => tool.name));
+      cursor = page.nextCursor;
+    } while (cursor);
+
+    const server = client.getServerVersion();
+    const result = {
+      ok: true,
+      endpoint: config.endpoint.href,
+      protocolVersion: client.getNegotiatedProtocolVersion(),
+      server,
+      toolCount: tools.length,
+      tools,
+    };
+
+    if (json) {
+      process.stdout.write(`${JSON.stringify(result)}\n`);
+    } else {
+      process.stdout.write(
+        `InstantClips MCP is reachable: ${tools.length} tools from ${server?.name || "the hosted server"}.\n`,
+      );
+    }
+    return 0;
+  } catch (error) {
+    const failure = safeFailure(error, config.token);
+    if (json) {
+      process.stdout.write(`${JSON.stringify({ ok: false, ...failure })}\n`);
+    } else {
+      writeDiagnostic(failure);
+    }
+    return failure.code === "authentication_failed" ? 77 : 69;
+  } finally {
+    await client.close().catch(() => {});
+  }
+}
+
+class CliError extends Error {
+  constructor(code, message, exitCode) {
+    super(message);
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}
+
+async function main(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    if (args.length !== 1) throw new CliError("usage", usage(), 64);
+    process.stdout.write(usage());
+    return 0;
+  }
+  if (args.includes("--version") || args.includes("-v")) {
+    if (args.length !== 1) throw new CliError("usage", usage(), 64);
+    process.stdout.write(`${VERSION}\n`);
+    return 0;
+  }
+
+  const check = args.includes("--check");
+  const json = args.includes("--json");
+  const accepted = new Set(["--check", "--json"]);
+  if (args.some((arg) => !accepted.has(arg)) || (json && !check)) {
+    throw new CliError("usage", usage(), 64);
+  }
+
+  let config;
+  try {
+    config = configuration();
+  } catch (error) {
+    if (check && json && error instanceof CliError) {
+      process.stdout.write(
+        `${JSON.stringify({ ok: false, code: error.code, message: error.message })}\n`,
+      );
+      return error.exitCode;
+    }
+    throw error;
+  }
+  if (check) return checkConnection(config, json);
+  await startBridge(config);
+  return 0;
+}
+
+try {
+  process.exitCode = await main(process.argv.slice(2));
+} catch (error) {
+  if (error instanceof CliError) {
+    process.stderr.write(
+      error.code === "usage"
+        ? `${error.message}\n`
+        : `instantclips-mcp: ${error.message}\n`,
+    );
+    process.exitCode = error.exitCode;
+  } else {
+    process.stderr.write(`instantclips-mcp: ${error?.message || error}\n`);
+    process.exitCode = 70;
+  }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "instantclips-mcp",
+  "mcpName": "ai.instantclips/instantclips",
+  "version": "1.1.0",
+  "description": "Use the hosted InstantClips MCP server from stdio-only clients.",
+  "type": "module",
+  "bin": {
+    "instantclips-mcp": "bin/instantclips-mcp.js"
+  },
+  "files": [
+    "bin/"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check:pack": "npm pack --dry-run",
+    "prepublishOnly": "npm test && npm run check:pack"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/InstantStudioAI/instantclips-mcp.git"
+  },
+  "homepage": "https://instantclips.ai/automate/",
+  "bugs": {
+    "url": "https://github.com/InstantStudioAI/instantclips-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "video-generation",
+    "video-ads",
+    "ecommerce",
+    "ai-agents"
+  ],
+  "author": "InstantStudioAI",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/client": "2.0.0",
+    "@modelcontextprotocol/server": "2.0.0"
+  }
+}