@thenavidm/creatomate-mcp-cli 0.0.0-stage → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 2.0.0 - 2026-10-03
+
+- Modernize the five-tool private MCP as the shared house TypeScript CLI, local stdio MCP and versioned desktop bundle.
+- Use current V2 template CRUD and single-object renders; retain documented V1 feed reads and explicit legacy tag/transcript submission.
+- Force free dry_run validation, preserve advisory errors/warnings, and require confirmation for six paid/template operations on both surfaces.
+- Add isolated private project profiles, exact reviewed one-to-ten render batches, bounded unique status reads, stop-on-failure receipts and no automatic replay/polling.
+- Remove undocumented render listing/page arguments and PDF format claims; document changed v2 payload/result shapes.
+- Preserve AGPL/private legacy history and maintain complete client/OS setup, current alternatives, version history, topics/keywords and quality evidence.
+
+## 1.0.0 - private legacy source
+
+Five MCP registrations on V1, no declared task CLI. Private history is retained; no earlier owned public npm release is assumed.
+
+| Component | Verified local version |
+| --- | --- |
+| Owned package / desktop | 2.0.0 |
+| Runtime | Node22+ |
+| API | V2 templates/renders, documented V1 feeds/tag compatibility |
+| @modelcontextprotocol/sdk | 1.32.0 |
+| ajv | 8.20.0 |
+| ajv-formats | 3.0.1 |
+| typescript | 7.0.2 |
+| vitest | 5.0.3 |
+| vite | 8.3.2 |
+| @anthropic-ai/mcpb | 2.1.2 |
+
+
+The private 1.0.0 package exposed five MCP tools and no CLI. Version2.0.0 preserves list_templates, get_template, create_render and get_render names while changing their native contract deliberately: rendering uses payload JSON on /v2/renders and returns one object; templates use current v2 sources/tag filters. list_renders and old page/per_page arguments are removed because current docs do not establish those endpoints/options. Do not send requests to guessed paths for compatibility. PDF is absent from the documented render formats; it is no longer advertised.
+
+Raw v2 RenderScript is top-level. Native legacy source/tags/transcripts require create_legacy_render and explicit approval; v1 results are arrays. All paid/template operations require confirmation and both read-only policy and private credential routing are enforced. Full client docs, package keywords, topics, dated changelog, annotated tags, public npm/desktop artifacts and complete guide are maintained together.
+
+Fifty-two behavior/shared-CLI tests, local build/typecheck and full/read-only stdio discovery passed with fixture-only credentials. The official SDK’s actual startRender comparison used injected HTTP. Public source/platform CI/npm/desktop/CMS checks must be recorded separately in release proof before claiming publication. Actual account outcomes, desktop GUI, fresh matched successful Codex task/token usage and private site deployment remain pending.

package/COMPARISON.md

@@ -0,0 +1,25 @@
+# Creatomate comparisons
+
+| Offering | Reviewed surface | Strengths and limits |
+| --- | --- | --- |
+| [Official hosted MCP](https://creatomate.com/docs/fundamentals/getting-started/mcp-integration) | Provider URL https://api.creatomate.com/mcp or project-specific /mcp/PROJECT-ID | Eight documented tools: get_guide, list_templates, get_template, create_template, update_template, delete_template, create_render and get_render. OAuth or project API-key Bearer, one project per connection, provider-maintained current guide and template/render workflows. Client approvals are explicitly documented. No authenticated hosted discovery is claimed here. |
+| [Official SDK](https://github.com/Creatomate/creatomate-node) | Published creatomate 1.2.1, npm source/fixture | Node application SDK, not a task CLI. Source still uses v1 and exposes startRender plus an optional polling render helper. Actual exported startRender with injected HTTP submitted once without a confirmation argument. No missing hosted-MCP approval claim follows from an SDK call. |
+| [Official preview SDK](https://github.com/Creatomate/creatomate-preview) | @creatomate/preview 1.6.1 package metadata | Browser preview/editor integration, useful for visual design; not an agent task CLI and not recreated by this package. |
+| [Official n8n integration](https://github.com/Creatomate/n8n-nodes-creatomate) | @creatomate/n8n-nodes-creatomate 1.0.1 metadata | Workflow-node integration, a separate surface from local CLI/MCP. No live installation or task comparison claimed. |
+| [Community MCP](https://github.com/WAR10CK222/creatomate-mcp-server) | Source c48577bc95de4ce8e77ed7e12d902dcd7766fdca, package version 1.0.0 / server string 2.0.0 | One render_video tool, animation resource and social-ad prompt, with guided style/TTS/caption inputs and SDK polling. Inspected source has no task CLI binary, named project routing or shared confirmation guard. Source inspection is not a runtime or visual-quality benchmark. |
+| This owned package | Shared task CLI, local stdio MCP and versioned desktop bundle | Seventeen tools, eleven reads/helpers and six confirmed operations; current v2 template CRUD and single-object renders, documented v1 feeds/tag compatibility, forced free dry-run validation and exact bounded paid/status workflows. Isolated projects and direct-call read-only controls. No hosted OAuth, guide tool, visual editor, media downloader or automatic publishing. |
+
+Checked October 3, 2026. The current account inventory contains no newer owned Creatomate repository. The old five-tool MCP uses v1 and has no declared task CLI. The official npm SDK fixture uses a fake key and injected HTTP; no provider request or credits were spent. Our equivalent confirmed render fixture refuses before fetch without explicit approval, and the exact batch hash refuses changes to profile label, order or payloads before the first submission. On first failure it reports known earlier submissions and leaves subsequent work unattempted. These are useful local execution and review differences, not universal superiority or measured token savings.
+
+The official hosted product already has project-specific connections, template creation/editing/deletion, raw-source renders, guide fetching, free dry runs and client approvals. None are presented as invented official gaps. The owned shared MCP offers the same local task workflows as the CLI for stdio users. Native v1 tag batches already exist; our ordered one-to-ten exact payload review serves a different task from rendering every tagged template. Native v1 feeds are documented and absent from the reviewed hosted eight-tool list, not claimed absent from every provider client.
+
+No dedicated official task CLI was found in the reviewed provider docs, ten official GitHub repositories or current Creatomate npm search results; this is a checked-search finding, not proof that no CLI exists anywhere. More names, SEO and a logo are not build qualification. Provider account outcomes, authenticated hosted discovery, actual desktop GUI installation and matched successful Codex task/token measurements remain unverified.
+
+
+| Route | What the agent receives | Evidence |
+| --- | --- | --- |
+| Local MCP | Client-loaded tool schemas and requested JSON results | Actual shared discovery and policy fixtures |
+| Task CLI | Discovered help/schema and command output; optional --select | Same handlers and guard through the house SDK bridge |
+| Official hosted MCP | Provider tools, current guide and account workflow | Current provider docs; authenticated behavior unmeasured |
+
+There are no fresh matched successful Codex task/token measurements for this refresh. Schema/tool counts, character division and another client’s results are not token savings. --select reduces returned fields locally, not upstream body size, network calls, render credits or guaranteed client context use. Record Codex/model/package versions, date, loading mode, equivalent completed task, actual API/usage and latency before publishing an efficiency winner. Claude Code benchmarking remains deferred at Navid’s instruction.

package/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+Thanks for looking. Here is what helps and what does not.
+
+## Issues, yes
+
+Bug reports are genuinely useful, and the more concrete the better: the command
+you ran, what you expected, what happened instead. If it involves a specific
+post, account or file, say which.
+
+Feature requests are welcome too. Keep the tool surface focused: compare the
+workflow and context cost before adding another tool. Some clients defer tool
+schemas, while others load the whole catalogue. Report the client and task
+when proposing a context or efficiency improvement.
+
+## Pull requests, no
+
+This is one of a family of servers that are deliberately identical to each
+other: the same section order, the same safety model, the same shape of tool
+description, the same voice. A change usually has to land the same way in
+several of them, so reviewing a patch into that takes longer than writing it.
+
+That is a property of how these are maintained, not a judgement on the patch.
+If something is broken, an issue gets it fixed faster than a pull request will.
+
+## Security
+
+Please do not open a public issue for a vulnerability. Use the private
+reporting path in [SECURITY.md](SECURITY.md), which also sets out what the
+server can reach and what it holds.

package/INSTALL.md

@@ -0,0 +1,321 @@
+# Install Creatomate MCP Server & CLI
+
+One npm package includes both binaries and all **17 tools**. Requires Node.js 22 or newer for CLI/manual MCP installs. Discovery works before account authentication. Account operations need eligible Creatomate project REST API access; provider project plans, key permissions and API quota apply.
+
+| Route | Program | Use |
+| --- | --- | --- |
+| Terminal | creatomate-cli | Scripts and agents with a shell |
+| Local MCP | creatomate-mcp | AI clients supporting stdio |
+| Desktop archive | creatomate-2.0.0.mcpb | Compatible Claude Desktop custom extensions |
+| Creatomate-hosted alternative | https://api.creatomate.com/mcp | Official remote provider-hosted access |
+
+## Contents
+
+[Requirements](#requirements) · [CLI](#cli) · [Private account setup](#private-account-setup) · [Claude Code](#claude-code) · [Codex](#codex) · [Claude Desktop](#claude-desktop) · [Cursor](#cursor) · [VS Code and Copilot](#vs-code-and-copilot) · [Windsurf](#windsurf) · [Zed](#zed) · [Gemini CLI](#gemini-cli) · [Docker](#docker) · [Verify](#verify) · [Multiple accounts](#multiple-accounts) · [Updates and removal](#updates-and-removal) · [Troubleshooting](#troubleshooting) · [Development](#development)
+
+## Requirements
+
+Install Node from [nodejs.org](https://nodejs.org/en/download). Open a new terminal and check `node --version` and `npm --version`. The desktop host needs a compatible Node runtime; dependencies are bundled. A GUI app may not inherit your terminal's environment. Check your account's current API access and quota with Creatomate instead of assuming npm installation provides it.
+
+## CLI
+
+On macOS/Linux, use Terminal. On Windows, use PowerShell or Command Prompt:
+
+```bash
+npm install -g @thenavidm/creatomate-mcp-cli@latest
+creatomate-cli --version
+creatomate-cli
+creatomate-cli list-templates --help
+creatomate-cli schema create-render
+creatomate-cli login
+```
+
+If PowerShell blocks npm.ps1, use npm.cmd or Command Prompt according to your policy. If a binary is missing, check `npm prefix -g`, ensure its executable directory is on PATH and open a new terminal. Avoid sudo as a workaround for PATH problems.
+
+For one command without a global install:
+
+```bash
+npx -y --package @thenavidm/creatomate-mcp-cli@latest creatomate-cli tools
+```
+
+Make [SKILL.md](./SKILL.md) available in your agent's supported skill location. The installed file is `<npm root -g>/@thenavidm/creatomate-mcp-cli/SKILL.md`. npm does not automatically register client skills. Your agent should read the actual schema and use --agent/--select for compact output.
+
+## Private account setup
+
+### Private project API keys
+
+1. Open the intended project in [Creatomate](https://creatomate.com), then Project Settings → API Integration. The editor’s Use Template → Integrate with API also shows the template ID and integration examples.
+2. Save that project’s API key outside repositories. Set CREATOMATE_TOKEN_FILE to an absolute owner-private token-only file, or set CREATOMATE_API_KEY in private client settings. A profile is a project, not an account-wide unrestricted connection.
+3. Run creatomate-cli doctor for local settings. Deliberately run doctor --network for one GET /v2/templates: it reports count, not full template data. Success proves that request, not account ownership, every endpoint or rendering quality.
+4. Read the intended template’s source and the current [provider guide](https://creatomate.com/llms.txt). Prepare the exact requested design; use validate_render before paid submission. A free provider dry run returns effective source, errors and warnings.
+5. Approve only the requested paid render or template mutation. Do not submit a render just to test installation.
+
+Keys are project-specific and sent only to api.creatomate.com in Authorization: Bearer. Named {name,api_key,token_file} profiles never fall back to a global key or another profile. The exact selected label and requested IDs matter. login prints setup instructions only; it does not store credentials, start OAuth, load .env or reuse official MCP sessions. The hosted official MCP supports OAuth or project-key Bearer access separately, and reaches one project per connection.
+
+Token files override the selected profile’s environment key and are cached until restart. Use a canonical private directory (0700) and regular absolute non-symlink file (0600), at most 64 KiB, on macOS/Linux. Windows users must restrict ACLs to themselves; POSIX mode checks do not prove Windows ACL protection. GUI and remote clients have their own environment and filesystem.
+
+### Credits, plans and limits
+
+This AGPL wrapper is free; provider access, credits, media rights and external generation services remain separate. Check [current pricing](https://creatomate.com/pricing), your project and API Log before approving spending. A provider dry run with dry_run:true uses no credits and queues nothing. Our validate_render forces that flag; preview_render_batch is local only and does not validate through the provider.
+
+Current credit documentation states one credit per image. Video credits depend on width × height × frame_rate × duration / 100000000, rounded up, with subtitle/provider rules and actual plan behavior still relevant. A half-scale draft is approximately one quarter of full-resolution video credits, not free. Current free-plan output is clamped so both dimensions are at most 480 pixels. Wrapper limits are not a spending cap or reliable quote; inspect the provider estimate under Single Export and actual API Log usage.
+
+The current API rate limit is 30 requests per ten seconds per account, across projects. Every request counts; X-RateLimit-Remaining and Retry-After report provider guidance. Default 350 ms process-wide spacing serializes starts across this client’s project profiles. Other processes/apps still share the provider limit. There is no automatic retry, including 429/402, redirects, network timeouts and 5xx. Respect Retry-After before an intentional repeat; do not replay an unknown paid submission.
+
+JSON request bodies are capped at 1 MiB, API responses at 5 MiB. Local exact batches contain one to ten separate v2 submissions; status batches contain one to twenty unique IDs. Native v1 tag rendering can select any number of matching templates and is explicitly not covered by the exact-batch count bound. Provider render concurrency is separate from accepted request rate; a planned job can remain queued. Webhooks are preferred over repeatedly polling large batches.
+
+### Rotation, disconnection and retention
+
+Rotate/revoke the intended project key through provider settings, update private files/config and restart every process using it. Removing npm or a client entry does not revoke a key or undo submissions. Official OAuth connections can be revoked through Account Settings → MCP Connections; removing a client-side connector alone does not revoke the provider grant.
+
+Generated renders, status records, snapshots and download URLs expire after 30 days. Template input media is a different retention scope. Save requested finished files to your own storage through an explicitly approved external workflow; this wrapper never automatically fetches media or uploads files. Current v2 template deletion is soft deletion, recoverable for 30 days; no undocumented wrapper restore endpoint is added. Keep keys, project profiles, source/media URLs and private render metadata out of public issues.
+
+
+```bash
+export CREATOMATE_TOKEN_FILE='/absolute/private/creatomate.txt'
+creatomate-cli doctor --network
+```
+
+```powershell
+$env:CREATOMATE_TOKEN_FILE = 'C:\Users\YOUR_USER\Private\creatomate.txt'
+creatomate-cli doctor --network
+```
+
+### Agent-guided installation
+
+> Help me install Creatomate MCP Server & CLI with INSTALL.md. Check Node and the binary, let me configure my account credentials privately, then run discovery and doctor --network. Do not change or mutate accounts during setup.
+
+## Codex
+
+Codex is the current validation priority. Private token paths must exist in the process or remote environment where the server runs.
+
+~~~bash
+codex mcp add creatomate -- npx -y @thenavidm/creatomate-mcp-cli@latest
+codex mcp list
+~~~
+
+Account credentials must reach the server through private environment settings. `codex mcp add --env NAME=value` stores values in your local config, so never commit that config or put secrets in a shared command. In TOML, the equivalent server is:
+
+~~~toml
+[mcp_servers.creatomate]
+command = "npx"
+args = ["-y", "@thenavidm/creatomate-mcp-cli@latest"]
+env_vars = ["CREATOMATE_API_KEY", "CREATOMATE_TOKEN_FILE", "CREATOMATE_ACCOUNTS", "CREATOMATE_DEFAULT_ACCOUNT", "CREATOMATE_READ_ONLY", "CREATOMATE_ALLOW_DESTRUCTIVE"]
+~~~
+
+`env_vars` forwards those names from the environment available to Codex. If that environment does not contain them, configure private env settings locally. Codex can also call the CLI directly with SKILL.md and `--agent` output.
+
+## Claude Code
+
+For a user-scoped connection, after privately configuring credentials:
+
+~~~bash
+claude mcp add --scope user creatomate -- npx -y @thenavidm/creatomate-mcp-cli@latest
+claude mcp list
+~~~
+
+Use the client's private local environment settings for the account variable if they are not inherited. Claude's `-e NAME=value` registration option writes values into its config; only use it locally through your secret manager, with no shared command transcript. Never place credentials in a project .mcp.json. Reconnect and ask Claude to verify credentials.
+
+Alternatively install the CLI, make SKILL.md available to Claude, and use shell commands. Registering both surfaces is optional.
+
+## Claude Desktop
+
+### Install the .mcpb extension
+
+1. Download `creatomate-2.0.0.mcpb` from [GitHub Releases](https://github.com/thenavidm/creatomate-mcp-cli/releases/latest).
+2. In a supported Claude Desktop build, open **Settings > Extensions > Advanced settings > Install Extension…** and select it.
+3. Enter a private API key in the sensitive setting, or an absolute private token-file path. Leave the unused credential method empty. Requests use Authorization: Bearer at the fixed Creatomate endpoint. Use the intended project API key; named profiles are configured separately in private client environments.
+4. Enable read-only if you want only the 11 read operations. Reconnect and ask for account verification.
+
+The bundle includes production dependencies and no credentials. Use a regular private token-only file if you prefer file-based credentials. The manifest requires Node 22 or newer from a compatible host. Organization policy may restrict custom extensions. Manual bundle updates require installing the new version; no automatic directory updates are promised. GUI installation remains unverified separately from archive/protocol checks.
+
+### Manual config
+
+Open **Settings > Developer > Edit Config**, or use your platform's config file:
+
+| OS | Typical config path |
+| --- | --- |
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json`; confirm the location through Edit Config in your installed build |
+
+~~~json
+{
+  "mcpServers": {
+    "creatomate": {
+      "command": "npx",
+      "args": ["-y", "@thenavidm/creatomate-mcp-cli@latest"],
+      "env": {
+        "CREATOMATE_API_KEY": "YOUR_PRIVATE_API_KEY",
+        "CREATOMATE_TOKEN_FILE": ""
+      }
+    }
+  }
+}
+~~~
+
+Replace the placeholders only in your private file. Merge the server entry into an existing mcpServers object instead of replacing other integrations. Fully quit and reopen Claude Desktop. Do not enable an extension and a manual entry with the same name; choose one route.
+
+If a Windows launcher cannot execute npx directly, use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "@thenavidm/creatomate-mcp-cli@latest"]`. An absolute node executable and installed `dist/index.js` path also avoids launcher/PATH problems.
+
+## Cursor
+
+Use private user settings at `~/.cursor/mcp.json`, or **Settings > Tools & MCP**. [Cursor documents environment interpolation and envFile support](https://cursor.com/docs/mcp).
+
+~~~json
+{
+  "mcpServers": {
+    "creatomate": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@thenavidm/creatomate-mcp-cli@latest"],
+      "env": {
+        "CREATOMATE_API_KEY": "${env:CREATOMATE_API_KEY}",
+        "CREATOMATE_TOKEN_FILE": "${env:CREATOMATE_TOKEN_FILE}"
+      }
+    }
+  }
+}
+~~~
+
+The environment values must exist for the Cursor process. If you use envFile, keep that file private and outside version control. A project's .cursor/mcp.json must not contain actual credentials. Reconnect the server after saving.
+
+## VS Code and Copilot
+
+Use **MCP: Open User Configuration**. [VS Code uses servers and secure inputs](https://code.visualstudio.com/docs/agent-customization/mcp-servers), rather than a mcpServers root:
+
+~~~json
+{
+  "inputs": [
+    {"type": "promptString", "id": "creatomate-api-token", "description": "Creatomate API key (leave empty for a private token file)", "password": true},
+    {"type": "promptString", "id": "creatomate-token-file", "description": "Optional private token-file path (leave empty for API key)"}
+  ],
+  "servers": {
+    "creatomate": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@thenavidm/creatomate-mcp-cli@latest"],
+      "env": {
+        "CREATOMATE_API_KEY": "${input:creatomate-api-token}",
+        "CREATOMATE_TOKEN_FILE": "${input:creatomate-token-file}"
+      }
+    }
+  }
+}
+~~~
+
+Start Creatomate through the MCP controls, approve trust if prompted, and enter credentials in the private input prompts. Workspace .vscode/mcp.json may contain this placeholder-only structure, but never resolved secret values. Remote development runs the server in the selected remote environment, so local file paths refer to that environment.
+
+## Windsurf
+
+Open Cascade's MCP settings or edit the private user file `~/.codeium/windsurf/mcp_config.json`. Use the Claude Desktop manual mcpServers block above with your locally configured env values. See [Windsurf's current MCP documentation](https://docs.devin.ai/desktop/cascade/mcp). Restart or reconnect Creatomate in Cascade; project files must not contain secrets.
+
+## Zed
+
+Open **Settings > AI > MCP Servers > Add Server > Add Local Server**, or your user settings file. [Zed uses context_servers](https://zed.dev/docs/ai/mcp):
+
+~~~json
+{
+  "context_servers": {
+    "creatomate": {
+      "command": "npx",
+      "args": ["-y", "@thenavidm/creatomate-mcp-cli@latest"],
+      "env": {
+        "CREATOMATE_API_KEY": "YOUR_PRIVATE_API_KEY",
+        "CREATOMATE_TOKEN_FILE": ""
+      }
+    }
+  }
+}
+~~~
+
+Enter actual values only in private user settings. Check the active-server indicator before prompting. Do not wrap command and args inside a nested command object from older Zed examples.
+
+## Gemini CLI
+
+Merge the Claude Desktop manual mcpServers block into your private `~/.gemini/settings.json`. Configure the private credential values locally, then restart Gemini CLI and inspect `/mcp`. See [Gemini CLI's MCP configuration](https://geminicli.com/docs/tools/mcp-server/). Its project settings must not contain real credentials. You can instead use the CLI from an agent shell.
+
+Other local stdio clients use the same command and arguments, adapted to their config format. A client that only accepts a remote MCP URL cannot connect directly: this package does not ship a public HTTP listener. ChatGPT's remote connector setup is not a substitute for local stdio installation.
+
+## Docker
+
+Build locally from the reviewed source; no prebuilt registry image is claimed:
+
+```bash
+git clone https://github.com/thenavidm/creatomate-mcp-cli.git
+cd creatomate-mcp-cli
+docker build -t creatomate-mcp-cli .
+docker run --rm -i -e CREATOMATE_API_KEY creatomate-mcp-cli
+```
+
+
+## Cline and other local MCP clients
+
+Use the client's **Add MCP server** flow with command `npx`, arguments `-y` and `@thenavidm/creatomate-mcp-cli@latest`, stdio transport, and private local CREATOMATE_API_KEY or CREATOMATE_TOKEN_FILE settings. UI names depend on the installed client. Reconnect and discover tools before an account call. Browser-only clients need a remote HTTPS connector; use Creatomate's official server rather than this local stdio command.
+
+## Verify
+
+```bash
+creatomate-cli doctor
+creatomate-cli doctor --network
+creatomate-cli list-accounts --agent
+creatomate-cli list-templates --agent
+creatomate-cli get-template --template-id YOUR_TEMPLATE_ID --agent
+```
+
+Local doctor verifies presence/settings, not authentication. Network doctor deliberately reads compact template metadata and prints its count. It does not verify account ownership or submit a render. Read-only discovery leaves eleven tools and refuses hidden confirmed mutations.
+
+## Multiple accounts
+
+Set CREATOMATE_ACCOUNTS privately to unique {name,api_key,token_file} project profiles. CREATOMATE_DEFAULT_ACCOUNT selects the exact label and defaults to the first configured profile. --account selects one project for that operation; no wildcard/all-accounts expansion occurs.
+
+Missing selected credentials fail rather than inheriting CREATOMATE_API_KEY or another profile. A token_file overrides only that profile’s key. Restart after rotation because loaded credentials are cached. list_accounts reports labels/default/auth-method availability without keys or file paths; it does not prove which provider project a key reaches.
+
+The official hosted MCP already supports one project per connection and project-specific URLs for multiple connections. These are acknowledged useful official controls. The owned profile routing serves local scripts/shared MCP workflows and does not claim provider project isolation is unique.
+
+## Updates and removal
+
+```bash
+npm install -g @thenavidm/creatomate-mcp-cli@latest
+creatomate-cli --version
+npm uninstall -g @thenavidm/creatomate-mcp-cli
+codex mcp remove creatomate
+```
+
+npx @latest resolves when a process starts; restart/reconnect for a released update. Global npm and desktop bundles require explicit updates. Install the new versioned .mcpb and verify its reported version. Remove client entries and revoke provider key/OAuth grants separately. Uninstalling does not undo renders/template edits, revoke keys or copy expiring output into permanent storage.
+
+## Troubleshooting
+
+| Symptom | Check / next action |
+| --- | --- |
+| Exit10 | Exact profile’s key/file, owner permissions and GUI environment; no global fallback |
+| 401/403 | Intended project key and provider permissions; hosted OAuth is a different credential |
+| 402/429 | Balance/request limit, Retry-After and concurrent clients; no automatic paid replay |
+| 400 with hint | Inspect provider hint/docs; basic local acceptance is not RenderScript validation |
+| valid:false | Correct dry-run errors; no render was queued |
+| valid:true but bad design | Inspect source, media availability, external keys and actual visual output |
+| 202 with warnings/errors | Job may still be queued/spend credits; inspect status, not a silent retry |
+| Low resolution | Current free-plan 480-pixel clamp, render_scale and max dimensions |
+| Render URL not ready | Wait for succeeded through an intentional read or webhook |
+| URL/status expired | Provider retention is 30 days; retrieve permanent copies separately |
+| Review hash mismatch | Same profile label, exact payloads and order; re-review changed work |
+| Partial paid batch | Inspect known IDs and uncertain failed request; later items are unattempted |
+| list_renders / page rejected | No current documented render-list or paging contract was carried forward |
+| Source object rejected in v2 | Use raw top-level elements; legacy v1 source is a separate tool |
+| Desktop rejected | Host/runtime/custom-extension policy; protocol and GUI installation differ |
+
+
+## Development
+
+```bash
+git clone https://github.com/thenavidm/creatomate-mcp-cli.git
+cd creatomate-mcp-cli
+npm ci
+npm run typecheck
+npm run build
+npm test
+npm run check:counts
+npm run build:mcpb
+```
+
+Source mode: configure private env, then register `node /absolute/path/creatomate-mcp-cli/dist/index.js` as the MCP command. Build before registration and after source changes. No local credentials are packaged. [CONTRIBUTING.md](./CONTRIBUTING.md), [SECURITY.md](./SECURITY.md) and [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) cover contributions, disclosures and licensing.

package/LICENSE

@@ -0,0 +1,17 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2026 Navid Moazzez (https://navid.me) | CreatorSchool.ai (https://creatorschool.ai)
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.