@clipform/mcp-server 1.38.0 → 1.40.0

package/README.md

@@ -1,4 +1,5 @@
-# @clipform/mcp-server
+<!-- GENERATED from README.template.md by scripts/sync-mcp-server-readme.mjs - do not edit directly. -->
+# @clipform/mcp-server
 
 MCP server for [Clipform](https://clipform.io) - build and manage video-style forms from any MCP client (Claude, ChatGPT, Cursor, Windsurf, etc.).
 
@@ -10,9 +11,9 @@ There are two ways to connect: **remote** (recommended, uses your Clipform accou
 
 Use this if you have a Clipform account. Forms are created directly in your workspace and your plan tier applies (no 3-node cap on Pro).
 
-**Claude (claude.ai):** Settings → Connectors → Add custom connector → enter `https://mcp.clipform.io`
+**Claude (claude.ai):** Settings → Connectors → Add custom connector → enter `https://mcp.clipform.io`
 
-**ChatGPT:** Settings → Connectors → Advanced → enable Developer Mode → Create connector → enter `https://mcp.clipform.io` (requires Pro/Team/Enterprise)
+**ChatGPT:** Settings → Connectors → Advanced → enable Developer Mode → Create connector → enter `https://mcp.clipform.io` (requires Pro/Team/Enterprise)
 
 **Any MCP client with OAuth:** Point it at `https://mcp.clipform.io` - discovery, registration, and auth are handled automatically via OAuth 2.1 + Dynamic Client Registration (RFC 7591).
 
@@ -58,42 +59,36 @@ You can also pass the key as a CLI flag: `npx -y @clipform/mcp-server --api-key=
 
 ## Tools
 
-### Form & node management
+Your MCP client lists these automatically on connect (via `tools/list`). Full reference - arguments, schemas, and examples - is in the [docs](https://clipform.io/docs/guides/mcp).
 
 | Tool | Description |
 |------|-------------|
-| `clipform_create_form` | Create a new form with nodes, theming, and tags in one call. Returns the created node IDs (structured output) so media steps need no follow-up lookup |
-| `clipform_list_forms` | List forms in your workspace with filtering and pagination |
-| `clipform_get_form` | View a form and all its nodes |
-| `clipform_update_form` | Change title, publish status, or settings |
-| `clipform_delete_form` | Delete a form and its nodes (asks the user to confirm) |
-| `clipform_add_node` | Add a node to an existing form |
-| `clipform_update_node` | Update node text, type, config, or options |
-| `clipform_delete_node` | Remove a node (logic chain auto-relinks; asks the user to confirm) |
-
-### Media & logic
-
-| Tool | Description |
-|------|-------------|
-| `clipform_upload_node_media` | Attach video or image to one or more nodes (batch, max 10); set `fit_media: true` for generated renders |
-| `clipform_get_node_media` | View a node's media details |
-| `clipform_delete_node_media` | Remove media from a node (asks the user to confirm) |
-| `clipform_attach_audio` | Attach audio to a still-image node |
-
-### Creative
-
-| Tool | Description |
-|------|-------------|
-| `clipform_render_composition` | Render a video composition to MP4 or PNG - flag reveals, emoji puzzles, grids, timelines, map motion and more. Pass `wait: false` to fire renders in parallel and poll for results |
-| `clipform_generate_tts` | Generate narration audio with word-level captions |
-| `clipform_generate_slideshow` | Create slideshow videos from images + audio (waits, returns URL) |
-| `clipform_generate_video` | Generate video from images, clips, or both synced to audio. Supports a looping background-audio bed (crowd noise, ambience) and print-style texture overlays. Pass `wait: false` to fire renders in parallel and poll for results |
-| `clipform_check_render` | Check status of a render started with `wait: false` |
-| `clipform_search_media` | Search royalty-free images and videos, with orientation filter and alt-text descriptions |
-| `clipform_search_music` | Search royalty-free music and ambient sounds |
-| `clipform_list_compositions` | List available video compositions and prop schemas |
-| `clipform_list_assets` | List available sound effects, animations, and fonts |
-| `clipform_fetch_boundary` | Fetch a GeoJSON boundary polygon for a country, city, or region |
+| `clipform_create_form` | Create a new Clipform (interactive video-style form). |
+| `clipform_list_forms` | List forms in your workspace with optional filtering. |
+| `clipform_get_form` | Retrieve a form's details including all nodes in sequential order. |
+| `clipform_update_form` | Update a form's title, publish status, settings, or tags. |
+| `clipform_delete_form` | Permanently delete a form and all its nodes. |
+| `clipform_add_node` | Add a new node to an existing form. |
+| `clipform_update_node` | Update one or more existing nodes' text, type, config, or options. |
+| `clipform_delete_node` | Delete a node from a form. |
+| `clipform_upload_node_media` | Upload media for one or more nodes. |
+| `clipform_get_node_media` | Get the media attached to a node, including processing status. |
+| `clipform_delete_node_media` | Remove media from a node. |
+| `clipform_set_logic` | Set routing logic on one or more nodes. |
+| `clipform_log_generation` | Save an audit trail for a generated form. |
+| `clipform_search_news` | Fallback news lookup for clients without native web search. |
+| `clipform_youtube_transcript` | Extract the transcript, title, and channel info from a YouTube video. |
+| `clipform_generate_tts` | Generate narration audio from text with word-level captions. |
+| `clipform_generate_video` | Generate a video from images, video clips, or both, synced to an audio track. |
+| `clipform_search_media` | Search images or stock video clips. |
+| `clipform_render_composition` | Render a specialised video composition to MP4 or PNG - custom animated visuals that clipform_generate_video can't provide, such as geography animations or designed motion graphics. |
+| `clipform_search_music` | Search for royalty-free music tracks and ambient sounds. |
+| `clipform_list_compositions` | Browse available video compositions and their expected props schemas. |
+| `clipform_list_assets` | List available creative assets (sound effects, animations, fonts) for video compositions. |
+| `clipform_check_render` | Check the status of a render job started by clipform_generate_video or clipform_render_composition. |
+| `clipform_fetch_boundary` | Fetch a GeoJSON boundary polygon for a country, city, or region. |
+| `clipform_get_guide` | Retrieve craft knowledge for building a specific form type. |
+| `clipform_get_workflow` | Retrieve a step-by-step build workflow for creating a specific form type. |
 
 ## Example
 
@@ -112,6 +107,6 @@ Forms are created with a start node and end screen automatically - you just add
 ## Links
 
 - [Clipform](https://clipform.io) - Create interactive video forms
-- [Documentation](https://clipform.io/docs/guides/mcp) - Full guide with node types, scoring, and more
+- [Documentation](https://clipform.io/docs/guides/mcp) - Full guide with node types and more
 
 > Craft guides (`clipform://guides/*`, `clipform_get_guide`) are fetched from the Clipform API at runtime, so the server needs a reachable `API_URL` and valid `CLIPFORM_API_KEY` to serve them.

package/README.template.md

@@ -0,0 +1,91 @@
+<!--
+  GENERATED FILE SOURCE TEMPLATE.
+  README.md is generated from this template by scripts/sync-mcp-server-readme.mjs.
+  Edit prose HERE, never in README.md. URLs/package come from @vid-master/config;
+  the tool list is generated from the live server (createServer()._registeredTools),
+  so adding/removing a tool updates the README automatically - never hand-list tools.
+-->
+# {{PKG}}
+
+MCP server for [Clipform]({{SITE}}) - build and manage video-style forms from any MCP client (Claude, ChatGPT, Cursor, Windsurf, etc.).
+
+## Install
+
+There are two ways to connect: **remote** (recommended, uses your Clipform account) and **local** (anonymous, free-tier limits).
+
+### Remote (recommended)
+
+Use this if you have a Clipform account. Forms are created directly in your workspace and your plan tier applies (no 3-node cap on Pro).
+
+**Claude (claude.ai):** Settings → Connectors → Add custom connector → enter `{{MCP_URL}}`
+
+**ChatGPT:** Settings → Connectors → Advanced → enable Developer Mode → Create connector → enter `{{MCP_URL}}` (requires Pro/Team/Enterprise)
+
+**Any MCP client with OAuth:** Point it at `{{MCP_URL}}` - discovery, registration, and auth are handled automatically via OAuth 2.1 + Dynamic Client Registration (RFC 7591).
+
+### Local - Claude Code / Claude Desktop / Cursor / etc.
+
+Use this for stdio-based MCP clients. Pass your API key to authenticate with your workspace and plan tier.
+
+**Claude Code:**
+
+```bash
+claude mcp add clipform -e CLIPFORM_API_KEY=cf_xxx -- npx -y {{PKG}}
+```
+
+**Claude Desktop / Cursor / Windsurf / OpenClaw** - add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "clipform": {
+      "command": "npx",
+      "args": ["-y", "{{PKG}}"],
+      "env": {
+        "CLIPFORM_API_KEY": "cf_xxx",
+        "API_URL": "{{API_URL}}"
+      }
+    }
+  }
+}
+```
+
+Self-service API key generation is coming soon. For now, your API key is provided during onboarding or via your account settings - contact support if you need one.
+
+You can also pass the key as a CLI flag: `npx -y {{PKG}} --api-key=cf_xxx`
+
+**Anonymous mode** (no API key): Forms go into a shared workspace with the free-tier 3-node limit. You'll get a claim URL to move forms into your account.
+
+### Environment variables
+
+| Variable | Required | Purpose |
+|----------|----------|---------|
+| `CLIPFORM_API_KEY` | For workspace auth | Bearer key - forms land in the key's workspace with its plan limits. Also unlocks the creative tools (search, TTS, video rendering). Omit for anonymous mode. |
+| `API_URL` | Yes | Clipform API base URL (`{{API_URL}}`, or your local/self-hosted API). |
+
+## Tools
+
+Your MCP client lists these automatically on connect (via `tools/list`). Full reference - arguments, schemas, and examples - is in the [docs]({{DOCS_URL}}).
+
+{{TOOLS}}
+
+## Example
+
+> Create a Clipform called "Customer Feedback" with a choice question asking "How would you rate our service?" with options Excellent, Good, Fair, Poor, then an open-ended question asking "Any additional comments?", and finish with an end screen saying "Thanks for your feedback!"
+
+## How it works
+
+**Remote (OAuth):** Bearer tokens are audience-bound to `{{MCP_URL}}` (RFC 8707) and scoped to `mcp` only. Forms land directly in the workspace you approved during consent.
+
+**Local with API key:** The `CLIPFORM_API_KEY` is sent as a standard `Authorization: Bearer` header. Forms are created directly in the key's workspace with your plan tier limits.
+
+**Local anonymous (no key):** Forms go into a shared unclaimed workspace. No auth is needed to edit them - the form UUID is the only credential. You'll get a claim URL to transfer ownership. Free-tier 3-node limit applies.
+
+Forms are created with a start node and end screen automatically - you just add the nodes in between.
+
+## Links
+
+- [Clipform]({{SITE}}) - Create interactive video forms
+- [Documentation]({{DOCS_URL}}) - Full guide with node types and more
+
+> Craft guides (`clipform://guides/*`, `clipform_get_guide`) are fetched from the Clipform API at runtime, so the server needs a reachable `API_URL` and valid `CLIPFORM_API_KEY` to serve them.

package/dist/{chunk-WHNDWLHI.js → chunk-CILPQ5ZL.js}

@@ -6,7 +6,7 @@ import {
   getWorkflowText,
   objectType,
   registerPrompts
-} from "./chunk-QT3RFCCN.js";
+} from "./chunk-UGVXQM5S.js";
 import {
   GUIDE_TYPES,
   QUIZ_VARIANTS,
@@ -14,7 +14,7 @@ import {
   getGuideUri,
   guideFallbackText,
   registerResources
-} from "./chunk-ZTJU467D.js";
+} from "./chunk-EZHJR3UM.js";
 import {
   BUSINESS,
   CONTACT_FIELDS,
@@ -23,15 +23,18 @@ import {
   KEN_BURNS_EFFECTS,
   KEN_BURNS_FIT_MODES,
   KEN_BURNS_PRESETS,
+  LABS_COMPOSITION_IDS,
   MCP_TOOL_TIERS,
   NODE_TYPES,
   NON_COUNTABLE_TYPES,
+  PUBLIC_COMPOSITION_IDS,
   SLIDESHOW_TRANSITIONS,
+  SOCIAL_COMPOSITION_IDS,
   callApi,
   errorResult,
   resolveFormType,
   textResult
-} from "./chunk-KBWMI24E.js";
+} from "./chunk-WCC65GB5.js";
 import {
   __commonJS,
   __export,
@@ -16984,33 +16987,14 @@ import { fileURLToPath } from "url";
 var _endScreen = NODE_TYPES.end_screen.config_schema.properties;
 var END_SCREEN_ICONS = _endScreen.icon.enum;
 var END_SCREEN_CTA_TYPES = _endScreen.cta_type.enum;
-var PUBLIC_COMPOSITIONS = [
-  "Map",
-  "Grid",
-  "GridList",
-  "ObscuredReveal",
-  "Timeline",
-  "NumberLine",
-  "CountdownRing",
-  "CountrySilhouetteClip",
-  "FlagRevealGB",
-  "FlagRevealJP",
-  "FlagRevealBR",
-  "ColorCards",
-  "TextReveal",
-  "EmojiPuzzle",
-  "BeforeAfter",
-  "MediaSlideshow",
-  "TitleCard",
-  "ParallaxImage"
+var PUBLIC_COMPOSITIONS = PUBLIC_COMPOSITION_IDS;
+var LABS_COMPOSITIONS = LABS_COMPOSITION_IDS;
+var SOCIAL_COMPOSITIONS = SOCIAL_COMPOSITION_IDS;
+var EXPOSED_COMPOSITIONS = [
+  ...PUBLIC_COMPOSITIONS,
+  ...process.env.CLIPFORM_LABS === "1" ? LABS_COMPOSITIONS : [],
+  ...process.env.CLIPFORM_SOCIAL === "1" ? SOCIAL_COMPOSITIONS : []
 ];
-var LABS_COMPOSITIONS = [
-  "StatCounter",
-  "ListReveal",
-  "Scene",
-  "Spin3D"
-];
-var EXPOSED_COMPOSITIONS = process.env.CLIPFORM_LABS === "1" ? [...PUBLIC_COMPOSITIONS, ...LABS_COMPOSITIONS] : PUBLIC_COMPOSITIONS;
 
 // src/lib/schemas.ts
 var ACTIVE_NODE_TYPES = Object.entries(NODE_TYPES).filter(([, def]) => def.is_active && !def.is_system).map(([type]) => type);
@@ -19030,4 +19014,4 @@ export {
   JSONRPCMessageSchema,
   createServer
 };
-//# sourceMappingURL=chunk-WHNDWLHI.js.map
+//# sourceMappingURL=chunk-CILPQ5ZL.js.map