@formfeed/mcp 0.3.2 → 0.3.4

package/README.md

@@ -23,7 +23,9 @@ A test key renders free with a watermark; a live key consumes units. `FORMFEED_R
 
 ## Hosted (Streamable HTTP)
 
-`https://mcp.formfeed.dev/mcp` with `Authorization: Bearer ff_…`. Self-host the same endpoint with
-`formfeed-mcp --http --port 8790`.
+`https://mcp.formfeed.dev/mcp/<workspace id>` signs in with your Formfeed account (OAuth; the client
+opens the browser), `https://mcp.formfeed.dev/mcp` takes `Authorization: Bearer ff_…`. Self-host the
+same endpoint with `formfeed-mcp --http --port 8790`, plus `--auth-server <issuer>` for OAuth sign-in
+against your own Supabase Auth.
 
 Documentation: <https://docs.formfeed.dev/integrations/mcp>

package/bin/formfeed-mcp.mjs

@@ -18058,7 +18058,7 @@ var require_liquid_node = __commonJS({
         return false;
       return isFalsy(value, this.context) ? defaultValue : value;
     }
-    function json(value, space = 0) {
+    function json2(value, space = 0) {
       const memoryLimit = this.context.memoryLimit;
       return JSON.stringify(value, (_key, val2) => {
         chargeJsonReplacerValue(memoryLimit, val2);
@@ -18094,9 +18094,9 @@ var require_liquid_node = __commonJS({
     var misc = {
       default: defaultFilter,
       raw,
-      jsonify: json,
+      jsonify: json2,
       to_integer,
-      json,
+      json: json2,
       inspect
     };
     var escapeMap = {
@@ -21410,7 +21410,6 @@ var require_liquid_node = __commonJS({
 // packages/mcp/src/lib/transports.ts
 import { createServer } from "node:http";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 
 // packages/mcp/src/lib/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -77504,6 +77503,7 @@ function toDate2(value, tz) {
 function escapeHtml(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
+var isNamedArgs = (v2) => !!v2 && typeof v2 === "object" && !Array.isArray(v2) && !(v2 instanceof Date);
 var str = (v2) => v2 === void 0 || v2 === null ? "" : String(v2);
 var opt = (v2, fallback) => v2 === void 0 || v2 === null || v2 === "" ? fallback : v2;
 var wordsByLang = {
@@ -77538,7 +77538,7 @@ var formatHelpers = [
     name: "number",
     doc: {
       signature: "number(value, decimals?, locale?)",
-      description: "Formats a number with grouping and a fixed number of decimals.",
+      description: "Formats a number with grouping. With decimals, exactly that many (rounded half away from zero); without, the decimals the number has, at most three, so 1234.5 \u2192 1.234,5 and 2.34567 \u2192 2,346. Use number(0) for whole numbers.",
       example: "{{ qty | number(2) }} \u2192 1.234,00",
       category: "format"
     },
@@ -77632,15 +77632,26 @@ var formatHelpers = [
   {
     name: "round",
     doc: {
-      signature: "round(value, decimals = 0)",
-      description: "Rounds half away from zero.",
-      example: "{{ 2.345 | round(2) }} gives 2.35",
+      signature: "round(value, decimals = 0, method = 'common')",
+      description: "Rounds to the given decimals, as Jinja2's round does: 'common' rounds half away from zero, 'floor' always down and 'ceil' always up.",
+      example: "{{ 2.345 | round(2) }} gives 2.35, {{ 2.349 | round(2, 'floor') }} gives 2.34",
       category: "format"
     },
-    fn: (_ctx, value, decimals) => {
+    // `round(2, method='floor')` (Jinja2) and `round: 2, method: 'floor'` (Liquid) arrive as a
+    // trailing object, as does a Handlebars hash
+    fn: (_ctx, value, ...args2) => {
       const n = toNumber(value);
-      const f2 = 10 ** (decimals === void 0 || decimals === null ? 0 : Number(decimals));
-      return Number.isNaN(n) ? "" : Math.round((Math.abs(n) + Number.EPSILON) * f2) / f2 * Math.sign(n);
+      if (Number.isNaN(n)) return "";
+      const named = args2.find(isNamedArgs) ?? {};
+      const [decimals, method] = args2.filter((a) => !isNamedArgs(a));
+      const places = Number(opt(decimals, opt(named["precision"], opt(named["decimals"], 0))));
+      const how = String(opt(method, opt(named["method"], "common")));
+      const f2 = 10 ** places;
+      const scaled = Number((Math.abs(n) * f2).toPrecision(15));
+      if (how === "floor") return (n < 0 ? -Math.ceil(scaled) : Math.floor(scaled)) / f2;
+      if (how === "ceil") return (n < 0 ? -Math.floor(scaled) : Math.ceil(scaled)) / f2;
+      if (how !== "common") throw new Error(`round: method must be 'common', 'floor' or 'ceil', not '${how}'`);
+      return Math.round(scaled + Number.EPSILON) / f2 * Math.sign(n);
     }
   },
   {
@@ -82395,6 +82406,7 @@ var Formfeed = class {
   fetchImpl;
   maxRetries;
   timeoutMs;
+  extraHeaders;
   constructor(options) {
     if (!options.apiKey) throw new FormfeedError("invalid_request", "apiKey is required", 0);
     this.apiKey = options.apiKey;
@@ -82402,6 +82414,7 @@ var Formfeed = class {
     this.fetchImpl = options.fetch ?? globalThis.fetch;
     this.maxRetries = options.maxRetries ?? 3;
     this.timeoutMs = options.timeoutMs ?? 12e4;
+    this.extraHeaders = Object.fromEntries(Object.entries(options.headers ?? {}).map(([name, value]) => [name.toLowerCase(), value]));
     if (!this.fetchImpl) throw new FormfeedError("invalid_request", "fetch is not available; pass options.fetch", 0);
   }
   renders = {
@@ -82669,11 +82682,20 @@ var Formfeed = class {
         );
       }
     },
-    schema: (idOrSlug, options = {}) => this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/schema`, void 0, options),
+    /**
+     * The JSON Schema of the template's data: stored, else inferred from the sample data. Of the
+     * published (else the latest) version, or of `version`: `published`, `latest`, a number or a
+     * channel name.
+     */
+    schema: (idOrSlug, options = {}) => {
+      const { version, ...rest } = options;
+      const query = version === void 0 ? "" : `?version=${encodeURIComponent(String(version))}`;
+      return this.request("GET", `/templates/${encodeURIComponent(idOrSlug)}/schema${query}`, void 0, rest);
+    },
     /**
      * Checks a version with data without rendering: syntax, header and footer, missing partials,
      * runtime errors and the data against the stored schema. Free. Without `data`, the version's
-     * sample data is checked.
+     * sample data is checked. `version` takes a channel name too.
      */
     validate: (idOrSlug, input = {}, options = {}) => this.request("POST", `/templates/${encodeURIComponent(idOrSlug)}/validate`, input, options)
   };
@@ -82712,7 +82734,8 @@ var Formfeed = class {
     const headers = {
       authorization: `Bearer ${this.apiKey}`,
       accept: as === "bytes" ? "*/*" : "application/json",
-      "user-agent": "formfeed-sdk-ts/0.3"
+      "user-agent": "formfeed-sdk-ts/0.3",
+      ...this.extraHeaders
     };
     const isForm = typeof FormData !== "undefined" && body instanceof FormData;
     if (body !== void 0 && !isForm) headers["content-type"] = "application/json";
@@ -82748,14 +82771,14 @@ var Formfeed = class {
       if (res.status === 204) return { status: 204, body: void 0 };
       if (as === "bytes" && res.ok) return { status: res.status, body: new Uint8Array(await res.arrayBuffer()) };
       const text2 = await res.text();
-      let json = null;
+      let json2 = null;
       try {
-        json = text2 ? JSON.parse(text2) : null;
+        json2 = text2 ? JSON.parse(text2) : null;
       } catch {
         if (res.ok) throw new FormfeedError("invalid_response", `the API answered HTTP ${res.status} with a body that is not JSON`, res.status);
       }
       if (!res.ok) {
-        const problem = json ?? {};
+        const problem = json2 ?? {};
         throw new FormfeedError(
           problem.code ?? `http_${res.status}`,
           problem.detail ?? problem.title ?? `HTTP ${res.status}`,
@@ -82764,7 +82787,7 @@ var Formfeed = class {
           res.headers.get("x-request-id")
         );
       }
-      return { status: res.status, body: json };
+      return { status: res.status, body: json2 };
     }
   }
   backoff(attempt, retryAfter) {
@@ -82780,7 +82803,7 @@ var encoder2 = new TextEncoder();
 // packages/mcp/src/lib/server.ts
 import { z as z2 } from "zod";
 var CONVERT_LIMIT_BYTES = 20 * 1024 * 1024;
-var SERVER_INFO = { name: "formfeed", version: "0.3.2" };
+var SERVER_INFO = { name: "formfeed", version: "0.3.4" };
 var engineSchema = z2.enum(["jinja2", "liquid", "handlebars"]);
 var outputSchema = z2.enum(outputFormats);
 var kindSchema = z2.enum(["pdf", "image", "docx", "pptx"]);
@@ -82816,6 +82839,7 @@ function failure(e) {
 function createFormfeedServer(options) {
   const client = new Formfeed({
     apiKey: options.apiKey,
+    headers: { "user-agent": `formfeed-mcp/${SERVER_INFO.version}`, ...options.workspaceId ? { "x-formfeed-workspace": options.workspaceId } : {} },
     ...options.region ? { region: options.region } : {},
     ...options.baseUrl ? { baseUrl: options.baseUrl } : {},
     ...options.fetch ? { fetch: options.fetch } : {}
@@ -83044,6 +83068,102 @@ function createFormfeedServer(options) {
   return server;
 }
 
+// packages/mcp/src/lib/web.ts
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+var WORKSPACE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var API_KEY = /^ff_(live|test)_/;
+var JWT = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+var MCP_PATH = "/mcp";
+var RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
+function resourceMetadata(origin, workspaceId, authorizationServer2) {
+  return {
+    resource: `${origin}${MCP_PATH}/${workspaceId}`,
+    authorization_servers: [authorizationServer2.replace(/\/$/, "")],
+    bearer_methods_supported: ["header"],
+    // Supabase Auth accepts the OIDC identity scopes only; what the token may do is the gateway's decision
+    scopes_supported: ["openid", "email", "profile"],
+    resource_name: "Formfeed",
+    resource_documentation: "https://docs.formfeed.dev/integrations/mcp"
+  };
+}
+function tokenExpired(token, now = Date.now()) {
+  const part = token.split(".")[1] ?? "";
+  try {
+    const json2 = atob(part.replace(/-/g, "+").replace(/_/g, "/"));
+    const exp = JSON.parse(json2).exp;
+    return typeof exp === "number" && exp * 1e3 <= now;
+  } catch {
+    return false;
+  }
+}
+function json(body, status, headers = {}) {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json", ...headers } });
+}
+function bearer(request) {
+  const auth = request.headers.get("authorization") ?? "";
+  return /^Bearer\s+/i.test(auth) ? auth.replace(/^Bearer\s+/i, "").trim() : "";
+}
+function mcpFetchHandler(options = {}) {
+  const authorizationServer2 = options.authorizationServer?.replace(/\/$/, "");
+  return async (request) => {
+    const url = new URL(request.url);
+    const origin = (options.publicOrigin ?? url.origin).replace(/\/$/, "");
+    const path = url.pathname.replace(/\/+$/, "") || "/";
+    if (path === "/healthz") return json({ ok: true }, 200);
+    if (path === RESOURCE_METADATA_PATH || path.startsWith(`${RESOURCE_METADATA_PATH}${MCP_PATH}`)) {
+      if (!authorizationServer2) return json({ error: "This endpoint takes API keys only; no authorization server is configured" }, 404);
+      const workspaceId2 = path.slice(`${RESOURCE_METADATA_PATH}${MCP_PATH}/`.length);
+      if (path === RESOURCE_METADATA_PATH || path === `${RESOURCE_METADATA_PATH}${MCP_PATH}`)
+        return json(
+          {
+            resource: `${origin}${MCP_PATH}`,
+            authorization_servers: [authorizationServer2],
+            bearer_methods_supported: ["header"],
+            resource_name: "Formfeed",
+            resource_documentation: "https://docs.formfeed.dev/integrations/mcp",
+            // the OAuth resource is one workspace: add its id to the path
+            formfeed_workspace_path: `${origin}${MCP_PATH}/{workspace_id}`
+          },
+          200
+        );
+      if (!WORKSPACE_ID.test(workspaceId2)) return json({ error: "The workspace id is not a UUID" }, 404);
+      return json(resourceMetadata(origin, workspaceId2, authorizationServer2), 200);
+    }
+    if (path !== MCP_PATH && !path.startsWith(`${MCP_PATH}/`)) return new Response(null, { status: 404 });
+    const workspaceId = path === MCP_PATH ? null : path.slice(MCP_PATH.length + 1);
+    if (workspaceId !== null && !WORKSPACE_ID.test(workspaceId))
+      return json({ error: `The path is /mcp for an API key or /mcp/<workspace id> for a signed-in member` }, 404);
+    const credential = bearer(request);
+    if (workspaceId === null) {
+      if (!credential) return json({ error: "Authorization: Bearer <formfeed api key> required; a signed-in member connects to /mcp/<workspace id>" }, 401, { "www-authenticate": 'Bearer realm="formfeed"' });
+      if (!API_KEY.test(credential) && JWT.test(credential))
+        return json({ error: "An access token needs its workspace: connect to /mcp/<workspace id>" }, 401, { "www-authenticate": 'Bearer realm="formfeed"' });
+    } else {
+      if (!authorizationServer2) return json({ error: "This endpoint takes API keys only; connect to /mcp with a key" }, 404);
+      const metadata = `${origin}${RESOURCE_METADATA_PATH}${MCP_PATH}/${workspaceId}`;
+      const challenge = (description) => ({
+        "www-authenticate": `Bearer realm="formfeed", resource_metadata="${metadata}", error="invalid_token", error_description="${description}"`
+      });
+      if (!credential || !JWT.test(credential)) return json({ error: "Sign in: this endpoint takes an OAuth access token" }, 401, challenge("an access token is required"));
+      if (tokenExpired(credential)) return json({ error: "The access token expired" }, 401, challenge("the access token expired"));
+    }
+    const mcp = createFormfeedServer({
+      apiKey: credential,
+      ...workspaceId ? { workspaceId } : {},
+      ...options.baseUrl ? { baseUrl: options.baseUrl } : {},
+      ...options.region ? { region: options.region } : {},
+      ...options.fetch ? { fetch: options.fetch } : {}
+    });
+    const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: void 0, enableJsonResponse: true });
+    await mcp.connect(transport);
+    try {
+      return await transport.handleRequest(request);
+    } finally {
+      void mcp.close().catch(() => void 0);
+    }
+  };
+}
+
 // packages/mcp/src/lib/transports.ts
 async function startStdio(options) {
   const server = createFormfeedServer({ localFiles: true, ...options });
@@ -83051,52 +83171,58 @@ async function startStdio(options) {
 }
 async function startHttp(options = {}) {
   const host = options.host ?? "127.0.0.1";
-  const path = options.path ?? "/mcp";
+  const { port: _port, host: _host, ...handlerOptions } = options;
+  void _port;
+  void _host;
+  const handler = mcpFetchHandler(handlerOptions);
   const server = createServer((req, res) => {
-    void handle(req, res).catch((e) => {
+    void toRequest(req, host).then(handler).then((response) => send(response, res)).catch((e) => {
       if (!res.headersSent) res.writeHead(500, { "content-type": "application/json" });
       res.end(JSON.stringify({ error: e instanceof Error ? e.message : String(e) }));
     });
   });
-  async function handle(req, res) {
-    const url = new URL(req.url ?? "/", `http://${host}`);
-    if (url.pathname === "/healthz") {
-      res.writeHead(200, { "content-type": "application/json" });
-      res.end(JSON.stringify({ ok: true }));
-      return;
-    }
-    if (url.pathname !== path) {
-      res.writeHead(404);
-      res.end();
-      return;
-    }
-    const auth = req.headers.authorization ?? "";
-    const apiKey = auth.startsWith("Bearer ") ? auth.slice(7).trim() : "";
-    if (!apiKey) {
-      res.writeHead(401, { "content-type": "application/json", "www-authenticate": 'Bearer realm="formfeed"' });
-      res.end(JSON.stringify({ error: "Authorization: Bearer <formfeed api key> required" }));
-      return;
-    }
-    const mcp = createFormfeedServer({ apiKey, baseUrl: options.baseUrl, region: options.region, fetch: options.fetch });
-    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
-    res.on("close", () => {
-      void transport.close();
-      void mcp.close();
-    });
-    await mcp.connect(transport);
-    await transport.handleRequest(req, res);
-  }
   await new Promise((resolve2, reject) => {
     server.once("error", reject);
     server.listen(options.port ?? 8790, host, () => resolve2());
   });
   const port = server.address().port;
   return {
-    url: `http://${host}:${port}${path}`,
+    url: `http://${host}:${port}${MCP_PATH}`,
     port,
     close: () => new Promise((resolve2) => server.close(() => resolve2()))
   };
 }
+async function toRequest(req, host) {
+  const url = new URL(req.url ?? "/", `http://${req.headers.host ?? host}`);
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (Array.isArray(value)) for (const v2 of value) headers.append(name, v2);
+    else if (value !== void 0) headers.set(name, value);
+  }
+  const chunks = [];
+  for await (const chunk of req) chunks.push(chunk);
+  const method = req.method ?? "GET";
+  const body = method === "GET" || method === "HEAD" ? void 0 : new Uint8Array(Buffer.concat(chunks));
+  return new Request(url, { method, headers, ...body ? { body } : {} });
+}
+async function send(response, res) {
+  const headers = {};
+  response.headers.forEach((value, name) => {
+    headers[name] = name === "set-cookie" ? [...headers[name] ?? [], value] : value;
+  });
+  res.writeHead(response.status, headers);
+  if (!response.body) {
+    res.end();
+    return;
+  }
+  const reader = response.body.getReader();
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    res.write(value);
+  }
+  res.end();
+}
 
 // packages/mcp/src/main.ts
 var args = process.argv.slice(2);
@@ -83106,12 +83232,14 @@ var flag = (name) => {
 };
 var baseUrl = process.env["FORMFEED_BASE_URL"];
 var region = process.env["FORMFEED_REGION"];
+var authorizationServer = flag("--auth-server") ?? process.env["FORMFEED_AUTH_SERVER"];
+var publicOrigin = flag("--public-origin") ?? process.env["FORMFEED_PUBLIC_ORIGIN"];
 if (args.includes("--help") || args.includes("-h")) {
   process.stdout.write(
-    "formfeed-mcp: Model Context Protocol server for Formfeed\n\n  formfeed-mcp              stdio; needs FORMFEED_API_KEY\n  formfeed-mcp --http       Streamable HTTP on --port (8790) and --host (127.0.0.1); the key comes from Authorization: Bearer\n"
+    "formfeed-mcp: Model Context Protocol server for Formfeed\n\n  formfeed-mcp              stdio; needs FORMFEED_API_KEY\n  formfeed-mcp --http       Streamable HTTP on --port (8790) and --host (127.0.0.1); the key comes from Authorization: Bearer\n                            --auth-server <issuer> (or FORMFEED_AUTH_SERVER) also opens /mcp/<workspace id> for OAuth access tokens;\n                            --public-origin <url> (or FORMFEED_PUBLIC_ORIGIN) is the origin clients see behind a proxy\n"
   );
 } else if (args.includes("--http")) {
-  startHttp({ port: Number(flag("--port") ?? 8790), host: flag("--host") ?? "127.0.0.1", baseUrl, region }).then(
+  startHttp({ port: Number(flag("--port") ?? 8790), host: flag("--host") ?? "127.0.0.1", baseUrl, region, authorizationServer, publicOrigin }).then(
     (h) => process.stderr.write(`formfeed-mcp listening on ${h.url}
 `)
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formfeed/mcp",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Model Context Protocol server for Formfeed: list templates, read data schemas, validate and render documents from AI agents.",
   "license": "MIT",
   "author": {