@clipform/mcp-server 3.3.2 → 3.8.0

package/README.md

@@ -44,17 +44,13 @@ claude mcp add clipform -e CLIPFORM_API_KEY=cf_xxx -- npx -y @clipform/mcp-serve
 }
 ```
 
-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 @clipform/mcp-server --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.
+Generate an API key in your Clipform dashboard under **Developers > API keys**. The local server always needs one - to try Clipform without an account, connect to `https://mcp.clipform.io` instead (see "How it works").
 
 ### 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. |
+| `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). Required by the local server. |
 | `API_URL` | Yes | Clipform API base URL (`https://api.clipform.io`, or your local/self-hosted API). |
 
 ## Tools
@@ -106,7 +102,9 @@ Your MCP client lists these automatically on connect (via `tools/list`). Full re
 
 **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.
+**Remote anonymous (no sign-in):** Connecting to `https://mcp.clipform.io` without signing in builds into a temporary account of the session's own. Forms stay drafts with a private preview link - nothing goes live - and while unclaimed, the form UUID is the credential to edit it. Build results include a one-time claim URL that signs you into that account (on the first form, periodically after, and at the form limit); free-plan limits apply. The local stdio server always needs `CLIPFORM_API_KEY`.
+
+These tools need a signed-in Clipform account (OAuth, or an API key): `clipform_list_forms`, `clipform_whoami`, `clipform_get_results`, `clipform_get_responses`, `clipform_delete_form`. An anonymous remote session that calls one is asked to sign in instead. Everything else, including `clipform_get_guide`, `clipform_get_workflow` and `clipform_list_assets`, works without an account.
 
 Forms are created with a start node and end screen automatically - you just add the nodes in between.
 

package/README.template.md

@@ -50,17 +50,13 @@ claude mcp add clipform -e CLIPFORM_API_KEY=cf_xxx -- npx -y {{PKG}}
 }
 ```
 
-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.
+Generate an API key in your Clipform dashboard under **Developers > API keys**. The local server always needs one - to try Clipform without an account, connect to `{{MCP_URL}}` instead (see "How it works").
 
 ### 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. |
+| `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). Required by the local server. |
 | `API_URL` | Yes | Clipform API base URL (`{{API_URL}}`, or your local/self-hosted API). |
 
 ## Tools
@@ -79,7 +75,9 @@ Your MCP client lists these automatically on connect (via `tools/list`). Full re
 
 **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.
+**Remote anonymous (no sign-in):** Connecting to `{{MCP_URL}}` without signing in builds into a temporary account of the session's own. Forms stay drafts with a private preview link - nothing goes live - and while unclaimed, the form UUID is the credential to edit it. Build results include a one-time claim URL that signs you into that account (on the first form, periodically after, and at the form limit); free-plan limits apply. The local stdio server always needs `CLIPFORM_API_KEY`.
+
+These tools need a signed-in Clipform account (OAuth, or an API key): `clipform_list_forms`, `clipform_whoami`, `clipform_get_results`, `clipform_get_responses`, `clipform_delete_form`. An anonymous remote session that calls one is asked to sign in instead. Everything else, including `clipform_get_guide`, `clipform_get_workflow` and `clipform_list_assets`, works without an account.
 
 Forms are created with a start node and end screen automatically - you just add the nodes in between.
 

package/dist/api-client.d.ts

@@ -0,0 +1,78 @@
+interface ApiOptions {
+    method?: string;
+    body?: Record<string, unknown>;
+    params?: Record<string, string>;
+    timeoutMs?: number;
+}
+type ApiResult = {
+    ok: true;
+    data: Record<string, unknown>;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+    apiMessage?: string;
+    code?: string;
+    reason?: string;
+};
+declare function callApi(path: string, options?: ApiOptions): Promise<ApiResult>;
+/** Next-step hint by status + path so an agent can recover instead of
+ *  retrying blind (#651). The raw API message stays first, hint second. */
+declare function recoveryHint(status: number, path: string, reason?: string): string | undefined;
+declare function errorResult(message: string, meta?: Record<string, unknown>): {
+    _meta?: Record<string, unknown> | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+/**
+ * True exactly when a callApi failure is the `assertNotAnonymous` account
+ * gate (apps/api/src/lib/anonymous-guard.ts) - triple-keyed on status + code
+ * + reason so an ordinary 403 (PLAN_LIMIT, a genuine authorization denial, a
+ * 500) never escalates an already-logged-in caller into a pointless OAuth
+ * re-auth (#4088 over-escalation guard). The only MCP-reachable trigger
+ * today is `clipform_update_form`'s `is_live: true` (publish) - see that
+ * tool's own comment for why `clipform_create_form`'s use of this same
+ * predicate is currently dead code.
+ */
+declare function isAnonymousAccountRequired(result: {
+    status: number;
+    code?: string;
+    reason?: string;
+}): boolean;
+/**
+ * Builds the `_meta["mcp/www_authenticate"]` array a tool result carries to
+ * trigger the Apps SDK's tool-level OAuth escalation (#4088): an array of
+ * RFC 6750 Bearer challenge strings, the runtime half of the two-part
+ * contract (the other half is the static MCP_TOOL_SECURITY declaration) -
+ * per the Apps SDK auth docs, metadata alone never triggers the flow,
+ * only a runtime error carrying this `_meta` key does. Same challenge shape
+ * `apps/api/src/mcp/handler.ts` already emits as a real `WWW-Authenticate`
+ * HTTP header for a bad/missing Bearer - this is the tool-result equivalent
+ * for a caller that reached a tool (anonymously) but hit a feature that
+ * requires an account.
+ */
+declare function authChallengeMeta(errorCode: string, description: string, resourceMetadata?: string): Record<string, unknown>;
+declare function textResult(text: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+/** Like textResult, but also carries a machine-readable `structuredContent`.
+ *  A tool that declares an `outputSchema` MUST return `structuredContent` on
+ *  every non-error result (the MCP SDK validates it and throws otherwise) - use
+ *  this for every success/empty path, and `errorResult` (exempt) for failures.
+ *  Project to the schema's explicit field set here - never pass raw API rows
+ *  (response-hygiene invariant, #797). */
+declare function structuredResult(text: string, structuredContent: Record<string, unknown>): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+};
+
+export { authChallengeMeta, callApi, errorResult, isAnonymousAccountRequired, recoveryHint, structuredResult, textResult };

package/dist/api-client.js

@@ -0,0 +1,22 @@
+import {
+  authChallengeMeta,
+  callApi,
+  errorResult,
+  isAnonymousAccountRequired,
+  recoveryHint,
+  structuredResult,
+  textResult
+} from "./chunk-JRASOR5T.js";
+import "./chunk-VPF6MLKM.js";
+import "./chunk-PBQ5BQWD.js";
+import "./chunk-G3PMV62Z.js";
+export {
+  authChallengeMeta,
+  callApi,
+  errorResult,
+  isAnonymousAccountRequired,
+  recoveryHint,
+  structuredResult,
+  textResult
+};
+//# sourceMappingURL=api-client.js.map

package/dist/api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/auth-context.d.ts

@@ -17,6 +17,7 @@ interface McpAuthContext {
     is_anonymous?: boolean;
     auth_via?: "oauth";
     mcp_mint_proof?: string;
+    mcp_session_proof?: string;
     resolveWorkspace?: (target: {
         workspace_id?: string;
         form_id?: string;
@@ -30,6 +31,10 @@ interface McpAuthContext {
         name: string;
     }[]>;
     default_workspace_id?: string;
+    mcp_session_id?: string;
+    loadInternalContent?: (kind: "guides" | "assets", params?: {
+        type?: string;
+    }) => Promise<Record<string, unknown>>;
 }
 /**
  * Marker header the in-process MCP tool layer sets on its outgoing API
@@ -65,8 +70,12 @@ declare const MCP_AUTH_VIA_HEADER = "x-clipform-auth-via";
  * victim's uid themselves (#3330 review).
  */
 declare const MCP_MINT_PROOF_HEADER = "x-clipform-mcp-mint-proof";
+/** #4090: carries `mcp_session_proof` (same trust model as MCP_MINT_PROOF_HEADER: HMAC-verified server-side, never trusted raw). */
+declare const MCP_SESSION_PROOF_HEADER = "x-clipform-mcp-session-proof";
+/** Carries `mcp_session_id` to the API for funnel analytics only (#4657). */
+declare const MCP_SESSION_ID_HEADER = "x-clipform-mcp-session-id";
 declare function runWithMcpAuth<T>(ctx: McpAuthContext, fn: () => Promise<T> | T): Promise<T> | T;
 declare function getMcpAuth(): McpAuthContext | undefined;
 declare function runWithMcpTool<T>(toolName: string, fn: () => Promise<T> | T): Promise<T> | T;
 
-export { MCP_ANONYMOUS_HEADER, MCP_AUTH_VIA_HEADER, MCP_MINT_PROOF_HEADER, type McpAuthContext, getMcpAuth, runWithMcpAuth, runWithMcpTool };
+export { MCP_ANONYMOUS_HEADER, MCP_AUTH_VIA_HEADER, MCP_MINT_PROOF_HEADER, MCP_SESSION_ID_HEADER, MCP_SESSION_PROOF_HEADER, type McpAuthContext, getMcpAuth, runWithMcpAuth, runWithMcpTool };

package/dist/auth-context.js

@@ -2,15 +2,19 @@ import {
   MCP_ANONYMOUS_HEADER,
   MCP_AUTH_VIA_HEADER,
   MCP_MINT_PROOF_HEADER,
+  MCP_SESSION_ID_HEADER,
+  MCP_SESSION_PROOF_HEADER,
   getMcpAuth,
   runWithMcpAuth,
   runWithMcpTool
-} from "./chunk-A5CFGL27.js";
+} from "./chunk-VPF6MLKM.js";
 import "./chunk-G3PMV62Z.js";
 export {
   MCP_ANONYMOUS_HEADER,
   MCP_AUTH_VIA_HEADER,
   MCP_MINT_PROOF_HEADER,
+  MCP_SESSION_ID_HEADER,
+  MCP_SESSION_PROOF_HEADER,
   getMcpAuth,
   runWithMcpAuth,
   runWithMcpTool