@formfeed/mcp 0.3.13 → 0.3.14

package/README.md

@@ -3,9 +3,9 @@
 [![formfeed MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/formfeed-dev/formfeed/badges/score.svg)](https://glama.ai/mcp/servers/formfeed-dev/formfeed)
 
 Model Context Protocol server for [Formfeed](https://formfeed.dev/?utm_source=npm&utm_content=mcp).
-Gives Claude, Cursor and other agents six tools: `list_templates`, `get_template_schema`,
+Gives Claude, Cursor and other agents seven tools: `list_templates`, `get_template_schema`,
 `validate_template` (free: the data against the template's schema, ad-hoc HTML offline), `render`, `convert_to_pdf` (Word, Excel,
-PowerPoint and OpenDocument to PDF) and `get_render`.
+PowerPoint and OpenDocument to PDF), `get_render` and `get_workspace` (which workspace the server works in, and the units left).
 
 ## stdio (Claude Desktop, Cursor, Claude Code)
 
@@ -26,9 +26,10 @@ A test key renders free with a watermark; a live key consumes units. `FORMFEED_R
 
 ## Hosted (Streamable HTTP)
 
-`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.
+`https://mcp.formfeed.dev/mcp` takes `Authorization: Bearer ff_…`, or signs in with your Formfeed
+account when no key is sent (OAuth; the client opens the browser, and you choose the workspace the
+agent works in). `https://mcp.formfeed.dev/mcp/<workspace id>` pins another workspace for a signed-in
+client. 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

@@ -21408,7 +21408,9 @@ var require_liquid_node = __commonJS({
 });
 
 // packages/mcp/src/lib/transports.ts
-import { createServer } from "node:http";
+import {
+  createServer
+} from "node:http";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // packages/mcp/src/lib/server.ts
@@ -81976,7 +81978,8 @@ var Formfeed = class {
           `render ${target.id} has no output (${target.status})`,
           0
         );
-      const res = await this.fetchImpl(target.download_url, {
+      const fetchImpl = this.fetchImpl;
+      const res = await fetchImpl(target.download_url, {
         signal: options.signal
       });
       if (!res.ok)
@@ -82492,8 +82495,9 @@ var Formfeed = class {
         () => controller.abort(options.signal?.reason)
       );
       let res;
+      const fetchImpl = this.fetchImpl;
       try {
-        res = await this.fetchImpl(url, {
+        res = await fetchImpl(url, {
           method,
           headers,
           body: body === void 0 ? void 0 : isForm ? body : JSON.stringify(body),
@@ -82565,7 +82569,7 @@ var encoder2 = new TextEncoder();
 // packages/mcp/src/lib/server.ts
 import { z as z3 } from "zod";
 var CONVERT_LIMIT_BYTES = 20 * 1024 * 1024;
-var SERVER_INFO = { name: "formfeed", version: "0.3.13" };
+var SERVER_INFO = { name: "formfeed", version: "0.3.14" };
 var READS = {
   readOnlyHint: true,
   destructiveHint: false,
@@ -82637,7 +82641,7 @@ function createFormfeedServer(options) {
     ...options.fetch ? { fetch: options.fetch } : {}
   });
   const server = new McpServer(SERVER_INFO, {
-    instructions: "Formfeed renders PDFs and images from HTML templates, and fills Word and PowerPoint templates (as DOCX, PPTX or PDF). Start with list_templates, read the data shape with get_template_schema, check data with validate_template, then call render and hand the download_url to the user. convert_to_pdf turns office documents into PDFs."
+    instructions: "Formfeed renders PDFs and images from HTML templates, and fills Word and PowerPoint templates (as DOCX, PPTX or PDF). Start with list_templates, read the data shape with get_template_schema, check data with validate_template, then call render and hand the download_url to the user. convert_to_pdf turns office documents into PDFs. get_workspace says which workspace this server works in and what the period has left."
   });
   server.registerTool(
     "list_templates",
@@ -82961,6 +82965,30 @@ function createFormfeedServer(options) {
       }
     }
   );
+  server.registerTool(
+    "get_workspace",
+    {
+      title: "Which workspace this server works in",
+      description: "Returns the workspace and organisation this server acts in, the plan, the environment (live or test) and the units of the current period: included, used and the balance of prepaid units. Call it when the user asks where a document will land or how many renders are left, or when list_templates returns nothing you expected. A signed-in agent works in the workspace chosen when it was connected, which the person changes in Formfeed under Account \u2192 Connected agents; an API key works in the workspace it was made for. Read-only and free.",
+      inputSchema: {},
+      annotations: READS
+    },
+    async () => {
+      try {
+        const { workspace, organization, plan, environment, period: period2, units } = await client.account.get();
+        return text3({
+          workspace,
+          organization,
+          plan,
+          environment,
+          period: period2,
+          units
+        });
+      } catch (e) {
+        return failure(e);
+      }
+    }
+  );
   return server;
 }
 
@@ -82993,12 +83021,20 @@ function tokenExpired(token, now = Date.now()) {
   }
 }
 function json(body, status, headers = {}) {
-  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json", ...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 challenge(metadata, description) {
+  return {
+    "www-authenticate": description ? `Bearer realm="formfeed", resource_metadata="${metadata}", error="invalid_token", error_description="${description}"` : `Bearer realm="formfeed", resource_metadata="${metadata}"`
+  };
+}
 function mcpFetchHandler(options = {}) {
   const authorizationServer2 = options.authorizationServer?.replace(/\/$/, "");
   return async (request) => {
@@ -83007,41 +83043,99 @@ function mcpFetchHandler(options = {}) {
     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 (!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"],
+            scopes_supported: ["openid", "email", "profile"],
             resource_name: "Formfeed",
             resource_documentation: "https://docs.formfeed.dev/integrations/mcp",
-            // the OAuth resource is one workspace: add its id to the path
+            // a signed-in client works in the workspace chosen at consent; this path pins another one
             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 (!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 });
+    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);
+      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"' });
+      const metadata = `${origin}${RESOURCE_METADATA_PATH}${MCP_PATH}`;
+      if (!credential)
+        return authorizationServer2 ? json(
+          {
+            error: "Authorization: Bearer <formfeed api key> required, or sign in with your Formfeed account"
+          },
+          401,
+          challenge(metadata)
+        ) : json(
+          { error: "Authorization: Bearer <formfeed api key> required" },
+          401,
+          { "www-authenticate": 'Bearer realm="formfeed"' }
+        );
+      if (!API_KEY.test(credential) && JWT.test(credential)) {
+        if (!authorizationServer2)
+          return json(
+            {
+              error: "This endpoint takes API keys only; no authorization server is configured for a sign-in"
+            },
+            401,
+            { "www-authenticate": 'Bearer realm="formfeed"' }
+          );
+        if (tokenExpired(credential))
+          return json(
+            { error: "The access token expired" },
+            401,
+            challenge(metadata, "the access token expired")
+          );
+      }
     } else {
-      if (!authorizationServer2) return json({ error: "This endpoint takes API keys only; connect to /mcp with a key" }, 404);
+      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"));
+      if (!credential || !JWT.test(credential))
+        return json(
+          { error: "Sign in: this endpoint takes an OAuth access token" },
+          401,
+          challenge(metadata, "an access token is required")
+        );
+      if (tokenExpired(credential))
+        return json(
+          { error: "The access token expired" },
+          401,
+          challenge(metadata, "the access token expired")
+        );
     }
     const mcp = createFormfeedServer({
       apiKey: credential,
@@ -83050,7 +83144,10 @@ function mcpFetchHandler(options = {}) {
       ...options.region ? { region: options.region } : {},
       ...options.fetch ? { fetch: options.fetch } : {}
     });
-    const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: void 0, enableJsonResponse: true });
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      sessionIdGenerator: void 0,
+      enableJsonResponse: true
+    });
     await mcp.connect(transport);
     try {
       return await transport.handleRequest(request);
@@ -83073,8 +83170,11 @@ async function startHttp(options = {}) {
   const handler = mcpFetchHandler(handlerOptions);
   const server = createServer((req, res) => {
     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) }));
+      if (!res.headersSent)
+        res.writeHead(500, { "content-type": "application/json" });
+      res.end(
+        JSON.stringify({ error: e instanceof Error ? e.message : String(e) })
+      );
     });
   });
   await new Promise((resolve2, reject) => {
@@ -83132,13 +83232,18 @@ var authorizationServer = flag("--auth-server") ?? process.env["FORMFEED_AUTH_SE
 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                            --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"
+    "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 takes OAuth access tokens on /mcp and /mcp/<workspace id>;\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, authorizationServer, publicOrigin }).then(
-    (h) => process.stderr.write(`formfeed-mcp listening on ${h.url}
-`)
-  );
+  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}
+`));
 } else {
   const apiKey = process.env["FORMFEED_API_KEY"];
   if (!apiKey) {

package/package.json

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