@clipform/mcp-server 2.10.2 → 2.10.4

package/dist/caps-DBnfcEyJ.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What a connected surface can actually do, derived from the connect-time
+ * toolset filter (#3309) so the guidance layers (server instructions, prompt
+ * recipes, `clipform_get_workflow`, craft guides) never reference a tool the
+ * surface doesn't register (#3681).
+ *
+ * The Claude Connectors Directory surface (`mcp.clipform.io/forms`) is
+ * account + forms only: no media generation and no research helpers. A
+ * workflow that still says "call clipform_generate_tts" there sends the model
+ * at a tool that doesn't exist, which shows up in review as failed tool
+ * calls. Every guidance producer takes a ServerCaps and gates on it.
+ */
+interface ServerCaps {
+    /** Narration, video, image, music, render, and asset tools are registered. */
+    media: boolean;
+    /** News lookup and the generation audit log are registered. */
+    research: boolean;
+}
+
+export type { ServerCaps as S };

package/dist/{chunk-UBJ7CZL2.js → chunk-A5RVUIGS.js}

@@ -2,9 +2,10 @@ import {
   ALL_VARIANTS,
   FORM_TYPES,
   FORM_TYPE_KEYS,
+  FULL_CAPS,
   callApi,
   getSessionContext
-} from "./chunk-IL26A4IN.js";
+} from "./chunk-O35IVA4L.js";
 
 // src/lib/guides.ts
 var guidesPromise = null;
@@ -42,6 +43,14 @@ function guideFallbackText(uri) {
     `forms tight - every question must earn its place.`
   ].join("\n");
 }
+function applyCapsToGuide(text, caps) {
+  if (caps.media) return text;
+  return [
+    "> **This connection exposes form-building tools only** - no narration, video, image, or music tools. Where this guide mentions narration, media, or rendering, skip that part and carry the same craft into the written question text.",
+    "",
+    text
+  ].join("\n");
+}
 
 // src/resources.ts
 var GUIDE_TYPES = FORM_TYPE_KEYS;
@@ -62,10 +71,10 @@ function getGuideUri(type, variant) {
   }
   return `clipform://guides/${type}`;
 }
-async function readGuide(uri) {
-  return await fetchGuideText(uri) ?? guideFallbackText(uri);
+async function readGuide(uri, caps) {
+  return applyCapsToGuide(await fetchGuideText(uri) ?? guideFallbackText(uri), caps);
 }
-function registerResources(server) {
+function registerResources(server, caps = FULL_CAPS) {
   for (const type of GUIDE_TYPES) {
     server.registerResource(
       `guide-${type}`,
@@ -79,7 +88,7 @@ function registerResources(server) {
         contents: [{
           uri: getGuideUri(type),
           mimeType: "text/markdown",
-          text: await readGuide(getGuideUri(type))
+          text: await readGuide(getGuideUri(type), caps)
         }]
       })
     );
@@ -97,7 +106,7 @@ function registerResources(server) {
         contents: [{
           uri: getGuideUri("quiz", variant),
           mimeType: "text/markdown",
-          text: await readGuide(getGuideUri("quiz", variant))
+          text: await readGuide(getGuideUri("quiz", variant), caps)
         }]
       })
     );
@@ -128,9 +137,10 @@ function registerResources(server) {
 export {
   fetchGuideText,
   guideFallbackText,
+  applyCapsToGuide,
   GUIDE_TYPES,
   QUIZ_VARIANTS,
   getGuideUri,
   registerResources
 };
-//# sourceMappingURL=chunk-UBJ7CZL2.js.map
+//# sourceMappingURL=chunk-A5RVUIGS.js.map

package/dist/chunk-A5RVUIGS.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lib/guides.ts","../src/resources.ts"],"sourcesContent":["import { callApi } from \"./api-client.js\";\nimport type { ServerCaps } from \"./caps.js\";\n\n/**\n * Craft guide bodies live server-side (#470) - the npm package is a shim\n * that fetches them at runtime instead of bundling them in the tarball.\n * One fetch per process (all ~30KB of guides in a single response), cached;\n * a failed fetch is NOT cached so the next read retries.\n */\n\nexport interface RemoteGuide {\n  type: string;\n  variant: string | null;\n  uri: string;\n  mimeType: string;\n  text: string;\n}\n\nlet guidesPromise: Promise<Map<string, RemoteGuide>> | null = null;\n\nasync function loadGuides(): Promise<Map<string, RemoteGuide>> {\n  const result = await callApi(\"/internal/mcp/guides\", { method: \"GET\" });\n  if (!result.ok) {\n    throw new Error(`Failed to load guides: ${result.error}`);\n  }\n  const guides = (result.data as { guides?: RemoteGuide[] }).guides ?? [];\n  return new Map(guides.map((g) => [g.uri, g]));\n}\n\n/** Fetch a guide body by its clipform:// URI. Returns null when unavailable. */\nexport async function fetchGuideText(uri: string): Promise<string | null> {\n  if (!guidesPromise) {\n    guidesPromise = loadGuides();\n  }\n  try {\n    const guides = await guidesPromise;\n    return guides.get(uri)?.text ?? null;\n  } catch (err) {\n    guidesPromise = null; // don't cache failures - retry on the next read\n    // Loud, not silent: a misconfigured API_URL/key otherwise degrades every\n    // guide to the stub with nothing in the logs.\n    console.error(`[guides] Failed to fetch ${uri}: ${err instanceof Error ? err.message : String(err)}`);\n    return null;\n  }\n}\n\n/** Shown in place of a guide when the API is unreachable or unauthenticated. */\nexport function guideFallbackText(uri: string): string {\n  return [\n    `# Guide unavailable`,\n    ``,\n    `The craft guide (${uri}) could not be loaded from the Clipform API.`,\n    `Guides are served at runtime and need a reachable API with a valid key -`,\n    `check API_URL and CLIPFORM_API_KEY, then try again.`,\n    ``,\n    `General principles in the meantime: write narration for the ear (short,`,\n    `conversational), never reveal answers in narration or media, and keep`,\n    `forms tight - every question must earn its place.`,\n  ].join(\"\\n\");\n}\n\n/**\n * Craft guide bodies are written for the full tool surface and mention the\n * narration/video tools by name. On a surface that doesn't register them\n * (the Claude Connectors Directory resource, #3681) prefix the guide with a\n * note so the model doesn't chase tools it can't call. The body itself is\n * untouched - the craft (question design, pacing) is the same either way.\n */\nexport function applyCapsToGuide(text: string, caps: ServerCaps): string {\n  if (caps.media) return text;\n  return [\n    \"> **This connection exposes form-building tools only** - no narration, video, image, or music tools. Where this guide mentions narration, media, or rendering, skip that part and carry the same craft into the written question text.\",\n    \"\",\n    text,\n  ].join(\"\\n\");\n}\n","import { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { getSessionContext } from \"./lib/session-context.js\";\nimport { FORM_TYPE_KEYS, FORM_TYPES, ALL_VARIANTS } from \"@vid-master/config\";\n\nexport const GUIDE_TYPES = FORM_TYPE_KEYS as readonly string[] as readonly [string, ...string[]];\nexport type GuideType = (typeof FORM_TYPE_KEYS)[number];\n\nexport const QUIZ_VARIANTS = ALL_VARIANTS as readonly string[] as readonly [string, ...string[]];\nexport type QuizVariant = (typeof ALL_VARIANTS)[number];\n// Guide BODIES are not bundled here (#470): the npm tarball ships only this\n// registration metadata. Text is fetched from the API at runtime - see\n// lib/guides.ts (cached per process, stub fallback when unreachable).\nimport { fetchGuideText, guideFallbackText, applyCapsToGuide } from \"./lib/guides.js\";\nimport { FULL_CAPS, type ServerCaps } from \"./lib/caps.js\";\n\nconst GUIDE_DESCRIPTIONS: Record<GuideType, string> = {\n  \"quiz\": \"Craft knowledge for writing engaging quizzes - difficulty curves, question psychology, narration style, scoring\",\n  \"survey\": \"Craft knowledge for feedback surveys, NPS, and research forms - brevity, rating scales, respondent fatigue\",\n  \"interview\": \"Craft knowledge for building interview forms - warm-up pacing, open questions, consent, video responses\",\n  \"funnel\": \"Craft knowledge for lead qualification funnels - planned feature, conditional routing coming soon\",\n  \"testimonial\": \"Craft knowledge for collecting testimonials and customer stories on video - storytelling prompts, comfort techniques, consent\",\n  \"application\": \"Craft knowledge for application and evaluation forms - multi-section structure, video responses for behavioural questions, screening\",\n  \"booking\": \"Craft knowledge for event registration and booking forms - minimal friction, video welcome, confirmation flow\",\n};\n\n// Sourced from config (single source of truth) so the agent-facing resource\n// descriptions can't drift from FORM_TYPES.quiz.variant_descriptions (#2534,\n// the exact pair packages/config/CLAUDE.md warns about).\nconst QUIZ_VARIANT_DESCRIPTIONS = FORM_TYPES.quiz.variant_descriptions;\n\nexport function getGuideUri(type: GuideType, variant?: QuizVariant): string {\n  if (type === \"quiz\" && variant) {\n    return `clipform://guides/quiz/${variant}`;\n  }\n  return `clipform://guides/${type}`;\n}\n\nasync function readGuide(uri: string, caps: ServerCaps): Promise<string> {\n  return applyCapsToGuide((await fetchGuideText(uri)) ?? guideFallbackText(uri), caps);\n}\n\nexport function registerResources(server: McpServer, caps: ServerCaps = FULL_CAPS) {\n  for (const type of GUIDE_TYPES) {\n    server.registerResource(\n      `guide-${type}`,\n      getGuideUri(type),\n      {\n        description: GUIDE_DESCRIPTIONS[type],\n        mimeType: \"text/markdown\",\n        annotations: { audience: [\"assistant\" as const], priority: 0.8 },\n      },\n      async () => ({\n        contents: [{\n          uri: getGuideUri(type),\n          mimeType: \"text/markdown\",\n          text: await readGuide(getGuideUri(type), caps),\n        }],\n      }),\n    );\n  }\n\n  for (const variant of QUIZ_VARIANTS) {\n    server.registerResource(\n      `guide-quiz-${variant}`,\n      getGuideUri(\"quiz\", variant),\n      {\n        description: QUIZ_VARIANT_DESCRIPTIONS[variant],\n        mimeType: \"text/markdown\",\n        annotations: { audience: [\"assistant\" as const], priority: 0.8 },\n      },\n      async () => ({\n        contents: [{\n          uri: getGuideUri(\"quiz\", variant),\n          mimeType: \"text/markdown\",\n          text: await readGuide(getGuideUri(\"quiz\", variant), caps),\n        }],\n      }),\n    );\n  }\n\n  server.registerResource(\n    \"context-session\",\n    \"clipform://context/session\",\n    {\n      description:\n        \"Current session info: auth mode, workspace name, plan name, and node/form limits. Read this before planning content to know your constraints.\",\n      mimeType: \"text/markdown\",\n      annotations: { audience: [\"assistant\"], priority: 1.0 },\n    },\n    async () => {\n      const text = await getSessionContext();\n      return {\n        contents: [\n          {\n            uri: \"clipform://context/session\",\n            mimeType: \"text/markdown\",\n            text: text || \"Session context unavailable - API may not be reachable.\",\n          },\n        ],\n      };\n    }\n  );\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-NCWQ42GI.js → chunk-EMQPJPF4.js}

@@ -6,20 +6,22 @@ import {
   getWorkflowText,
   objectType,
   registerPrompts
-} from "./chunk-4QF4KGPE.js";
+} from "./chunk-QZO6MGNN.js";
 import {
   GUIDE_TYPES,
   QUIZ_VARIANTS,
+  applyCapsToGuide,
   fetchGuideText,
   getGuideUri,
   guideFallbackText,
   registerResources
-} from "./chunk-UBJ7CZL2.js";
+} from "./chunk-A5RVUIGS.js";
 import {
   ACTIVE_NODE_TYPES,
   CONTACT_FIELDS,
   FEATURE_FLAGS,
   FORM_TYPE_ALIASES,
+  FULL_CAPS,
   KEN_BURNS_EFFECTS,
   KEN_BURNS_FIT_MODES,
   KEN_BURNS_PRESETS,
@@ -30,13 +32,14 @@ import {
   SLIDESHOW_TRANSITIONS,
   bfsOrder,
   callApi,
+  capsFromToolsets,
   defaultTarget,
   errorResult,
   exposedCompositionIds,
   resolveFormType,
   structuredResult,
   textResult
-} from "./chunk-IL26A4IN.js";
+} from "./chunk-O35IVA4L.js";
 import {
   getMcpAuth,
   runWithMcpTool
@@ -20456,7 +20459,7 @@ mainlandOnly excludes small islands and overseas territories (e.g. Corsica for F
 }
 
 // src/tools/get-guide.ts
-function registerGetGuideTool(server) {
+function registerGetGuideTool(server, caps = FULL_CAPS) {
   const aliasHint = Object.entries(FORM_TYPE_ALIASES).map(([alias, target]) => `${alias} \u2192 ${target}`).join(", ");
   server.registerTool(
     "clipform_get_guide",
@@ -20491,7 +20494,7 @@ Quiz variants (optional): ${QUIZ_VARIANTS.join(", ")} - appends variant-specific
       const type = resolved;
       const validVariant = type === "quiz" ? variant : void 0;
       const uri = getGuideUri(type, validVariant);
-      const content = await fetchGuideText(uri) ?? guideFallbackText(uri);
+      const content = applyCapsToGuide(await fetchGuideText(uri) ?? guideFallbackText(uri), caps);
       return {
         content: [{
           type: "resource",
@@ -20507,7 +20510,7 @@ Quiz variants (optional): ${QUIZ_VARIANTS.join(", ")} - appends variant-specific
 }
 
 // src/tools/get-workflow.ts
-function registerGetWorkflowTool(server) {
+function registerGetWorkflowTool(server, caps = FULL_CAPS) {
   const aliasHint = Object.entries(FORM_TYPE_ALIASES).map(([alias, target]) => `${alias} \u2192 ${target}`).join(", ");
   server.registerTool(
     "clipform_get_workflow",
@@ -20567,7 +20570,7 @@ Optional args by type:
       }
       const type = resolved;
       const validVariant = type === "quiz" ? variant : void 0;
-      const text = await getWorkflowText(type, args, validVariant);
+      const text = await getWorkflowText(type, args, validVariant, caps);
       return textResult(text);
     }
   );
@@ -20577,29 +20580,26 @@ Optional args by type:
 var __dirname = dirname(fileURLToPath(import.meta.url));
 var pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 var MCP_VERSION = pkg.version;
+var MCP_SERVER_IDENTITY = Object.freeze({
+  name: "clipform-mcp-server",
+  version: MCP_VERSION
+});
+function buildInstructions(caps) {
+  return [
+    "Clipform builds interactive video-style forms. When the brief is clear, build the form directly; when it's vague, ask one or two short questions first.",
+    caps.media && "Prefer rich media: video over images over plain text.",
+    caps.media ? "Before building, derive a register from the topic and audience (e.g. hype, playful, warm, considered, elegant, sombre); if the user states a mood explicitly, that wins. State the register once, then apply it to every rendering choice - narration tone, motion preset, music, pacing. Never mix registers in one form." : "Before building, derive a register from the topic and audience (e.g. hype, playful, warm, considered, elegant, sombre); if the user states a mood explicitly, that wins. State the register once, then apply it to every question, option, and end-screen line. Never mix registers in one form.",
+    "At the start of a build, call clipform_get_workflow to load the recipe for the form type, and clipform_get_guide for craft detail.",
+    "Every *_id argument is a UUID returned by the tools - not the short share_id from a form URL.",
+    "For an account-scoped request, call clipform_whoami first to confirm the active workspace and plan.",
+    caps.media ? "Deleting a form, node, or its media is permanent; those tools ask the user to confirm before running." : "Deleting a form or node is permanent; those tools ask the user to confirm before running."
+  ].filter((line) => typeof line === "string").join(" ");
+}
 function createServer(options) {
+  const caps = capsFromToolsets(options?.toolsets);
   const server = new McpServer(
-    {
-      name: "clipform-mcp-server",
-      version: MCP_VERSION
-    },
-    {
-      // Lands directly in the client's system prompt. This is the only
-      // high-level guidance external clients (claude.ai, Desktop, ChatGPT App)
-      // receive - they have no equivalent of the bot's system prompt. It is
-      // also the correct home for cross-tool / sequencing guidance, which must
-      // NOT go in individual tool descriptions (treated as prompt injection at
-      // directory review).
-      instructions: [
-        "Clipform builds interactive video-style forms. When the brief is clear, build the form directly; when it's vague, ask one or two short questions first.",
-        "Prefer rich media: video over images over plain text.",
-        "Before building, derive a register from the topic and audience (e.g. hype, playful, warm, considered, elegant, sombre); if the user states a mood explicitly, that wins. State the register once, then apply it to every rendering choice - narration tone, motion preset, music, pacing. Never mix registers in one form.",
-        "At the start of a build, call clipform_get_workflow to load the recipe for the form type, and clipform_get_guide for craft detail.",
-        "Every *_id argument is a UUID returned by the tools - not the short share_id from a form URL.",
-        "For an account-scoped request, call clipform_whoami first to confirm the active workspace and plan.",
-        "Deleting a form, node, or its media is permanent; those tools ask the user to confirm before running."
-      ].join(" ")
-    }
+    { ...MCP_SERVER_IDENTITY },
+    { instructions: buildInstructions(caps) }
   );
   const _registerTool = server.registerTool.bind(server);
   server.registerTool = (name, config2, handler) => {
@@ -20658,16 +20658,18 @@ function createServer(options) {
   registerListAssetsTool(server);
   registerCheckRenderTool(server);
   registerFetchBoundaryTool(server);
-  registerGetGuideTool(server);
-  registerGetWorkflowTool(server);
-  registerPrompts(server);
-  registerResources(server);
+  registerGetGuideTool(server, caps);
+  registerGetWorkflowTool(server, caps);
+  registerPrompts(server, caps);
+  registerResources(server, caps);
   return server;
 }
 
 export {
   JSONRPCMessageSchema,
   RENDER_TIMING,
+  MCP_SERVER_IDENTITY,
+  buildInstructions,
   createServer
 };
-//# sourceMappingURL=chunk-NCWQ42GI.js.map
+//# sourceMappingURL=chunk-EMQPJPF4.js.map