@usefillo/mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fillo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# @usefillo/mcp
+
+The [Fillo](https://fillo.so) MCP server. It gives a coding agent the full Fillo
+loop — provision a workspace, scaffold a form into the host repo, publish it, and
+query its responses — without leaving the session, authenticated exactly like a
+human CLI user.
+
+### 📚 Full documentation → **[fillo.so/docs](https://fillo.so/docs)**
+
+## Install
+
+Claude Code:
+
+```sh
+claude mcp add fillo -- npx -y @usefillo/mcp
+```
+
+Cursor / VS Code / any MCP client: run `npx -y @usefillo/mcp` over stdio. Set
+`FILLO_API` to point at a non-production deployment.
+
+## Credentials
+
+The server reads the same credentials the CLI writes to `~/.fillo/config.json`,
+or from the environment:
+
+- `FILLO_TOKEN` — a `fcli_…` login token (from `npx @usefillo/cli login`).
+  Authenticated tools (`fillo_list_forms`, publishing to a claimed workspace).
+- `FILLO_PK` — a `pk_…` publishable key. `fillo_provision_workspace` mints one
+  and saves it for you.
+- `FILLO_API_KEY` — a `fsk_…` workspace API key, minted in **Settings →
+  Connections** of a claimed workspace. Required by the response tools.
+- `FILLO_API` — overrides the origin (default `https://fillo.so`).
+- `FILLO_CONFIG_DIR` — overrides the config directory (default `~/.fillo`).
+
+The server never prints login tokens, API keys, or claim tokens into the
+transcript. The `pk_` publishable key is safe to surface (it lives in browser
+code), so `fillo_provision_workspace` returns it for you to wire into the app's
+public env.
+
+## Tools
+
+| Tool | Auth | What it does |
+| --- | --- | --- |
+| `fillo_provision_workspace` | none (needs an email) | Create an unclaimed preview workspace, return its `pk_` key and caps, and email its claim link. |
+| `fillo_whoami` | login token or `pk_` | Report the active credential and workspace. |
+| `fillo_push_form` | login token or `pk_` | Create or update a form from a schema + handle. |
+| `fillo_list_forms` | login token | List the workspace's forms. |
+| `fillo_get_form` | none (published) | Fetch a published form's schema, theme, and capabilities. |
+| `fillo_search_examples` | none | Search the curated Fillo example library. |
+| `fillo_docs` | none | Fetch a Fillo docs page as Markdown by topic. |
+| `fillo_list_responses` | `fsk_` API key | List a form's responses (claimed workspaces only). |
+| `fillo_get_response` | `fsk_` API key | Fetch one response (claimed workspaces only). |
+| `fillo_claim_status` | `pk_` | Report the provisioned workspace's caps and claim deadline. |
+
+No destructive tools. Every tool is a thin wrapper over Fillo's public HTTP API —
+the server never touches the database and imports no app code, so workspace
+scoping, rate limits, and validation stay in one place.
+
+## Links
+
+- **Docs:** [fillo.so/docs](https://fillo.so/docs)
+- **Website:** [fillo.so](https://fillo.so)
+
+MIT licensed.

package/dist/index.js

@@ -0,0 +1,574 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/config.ts
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var DEFAULT_API = "https://fillo.so";
+var REQUEST_TIMEOUT_MS = 3e4;
+var CLIENT_VERSION = `@usefillo/mcp@${packageVersion()}`;
+function packageVersion() {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(new URL("../package.json", import.meta.url), "utf8")
+    );
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+function apiOrigin() {
+  return (process.env.FILLO_API ?? DEFAULT_API).replace(/\/$/, "");
+}
+function configDir() {
+  return process.env.FILLO_CONFIG_DIR?.trim() || join(homedir(), ".fillo");
+}
+function configPath() {
+  return join(configDir(), "config.json");
+}
+function readConfig() {
+  try {
+    const parsed = JSON.parse(readFileSync(configPath(), "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    const record = parsed;
+    const provision = record.provision && typeof record.provision === "object" && !Array.isArray(record.provision) ? record.provision : void 0;
+    return {
+      ...typeof record.token === "string" ? { token: record.token } : {},
+      ...typeof record.tokenApi === "string" ? { tokenApi: record.tokenApi } : {},
+      ...typeof record.pk === "string" ? { pk: record.pk } : {},
+      ...typeof record.apiKey === "string" ? { apiKey: record.apiKey } : {},
+      ...provision ? { provision } : {}
+    };
+  } catch {
+    return {};
+  }
+}
+function writeConfig(next) {
+  const dir = configDir();
+  mkdirSync(dir, { recursive: true, mode: 448 });
+  try {
+    chmodSync(dir, 448);
+  } catch {
+  }
+  writeFileSync(configPath(), JSON.stringify(next, null, 2), { mode: 384 });
+  try {
+    chmodSync(configPath(), 384);
+  } catch {
+  }
+}
+function resolveToken() {
+  const fromEnv = process.env.FILLO_TOKEN?.trim();
+  if (fromEnv) return fromEnv;
+  const cfg = readConfig();
+  if (!cfg.token) return void 0;
+  const boundTo = cfg.tokenApi?.replace(/\/$/, "");
+  if (!boundTo) return apiOrigin() === DEFAULT_API ? cfg.token : void 0;
+  return boundTo === apiOrigin() ? cfg.token : void 0;
+}
+function resolvePk() {
+  return process.env.FILLO_PK?.trim() || readConfig().pk;
+}
+function resolveApiKey() {
+  return process.env.FILLO_API_KEY?.trim() || readConfig().apiKey;
+}
+function resolveProvision() {
+  const provision = readConfig().provision;
+  if (!provision) return void 0;
+  if (provision.api && provision.api.replace(/\/$/, "") !== apiOrigin()) return void 0;
+  return provision;
+}
+
+// src/result.ts
+function ok(summary, data) {
+  return build(summary, data, false);
+}
+function fail(summary, data) {
+  return build(summary, data, true);
+}
+function build(summary, data, isError) {
+  const content = [{ type: "text", text: summary }];
+  if (data !== void 0) content.push({ type: "text", text: JSON.stringify(data) });
+  return isError ? { content, isError: true } : { content };
+}
+
+// src/tools/claim-status.ts
+var DAY_MS = 24 * 60 * 60 * 1e3;
+function registerClaimStatus(server) {
+  server.registerTool(
+    "fillo_claim_status",
+    {
+      title: "Check a preview workspace's claim deadline",
+      description: "Report an unclaimed preview workspace's response cap and claim deadline so you can tell the user the real date to claim it by. Uses the caps returned when fillo_provision_workspace ran on this machine. If none is recorded, it says so. The claim link is emailed (never printed); the developer claims by opening that email and signing in.",
+      inputSchema: {}
+    },
+    async () => {
+      const provision = resolveProvision();
+      if (!provision) {
+        if (resolvePk()) {
+          return ok(
+            "A publishable key is configured, but no provisioning record is stored on this machine, so the claim deadline is not known here. If you provisioned elsewhere, the claim link was emailed then; open it and sign in to claim.",
+            { mode: "publishable-key", api: apiOrigin() }
+          );
+        }
+        return fail(
+          "No provisioned workspace is recorded on this machine. Run fillo_provision_workspace first, or open the claim link Fillo emailed when it was provisioned."
+        );
+      }
+      const expiresMs = provision.expiresAt ? Date.parse(provision.expiresAt) : Number.NaN;
+      const daysLeft = Number.isFinite(expiresMs) ? Math.max(0, Math.round((expiresMs - Date.now()) / DAY_MS)) : void 0;
+      const expired = Number.isFinite(expiresMs) && expiresMs <= Date.now();
+      return ok(
+        expired ? `This preview workspace's ${provision.expiresAt} hold has passed. The claim link Fillo emailed to ${provision.email ?? "the provisioning address"} may no longer work \u2014 provision a fresh workspace if needed.` : `Unclaimed preview workspace: up to ${provision.responseCap ?? "a capped number of"} responses, hold ${provision.expiresAt ? `ends ${provision.expiresAt}` : "active"}${daysLeft !== void 0 ? ` (~${daysLeft} day${daysLeft === 1 ? "" : "s"} left)` : ""}. Claim it by opening the link Fillo emailed to ${provision.email ?? "the provisioning address"} and signing in.`,
+        {
+          mode: "provisional",
+          api: apiOrigin(),
+          organizationId: provision.organizationId,
+          claimLinkEmailedTo: provision.email,
+          responseCap: provision.responseCap,
+          expiresAt: provision.expiresAt,
+          daysLeft,
+          expired
+        }
+      );
+    }
+  );
+}
+
+// src/tools/docs.ts
+import { z } from "zod";
+
+// src/http.ts
+async function filloFetch(path, init = {}) {
+  const query = init.searchParams?.toString();
+  const url = `${apiOrigin()}${path}${query ? `?${query}` : ""}`;
+  const headers = { "X-Fillo-Client": CLIENT_VERSION };
+  if (init.body !== void 0) headers["Content-Type"] = "application/json";
+  if (init.token) headers.Authorization = `Bearer ${init.token}`;
+  const res = await fetch(url, {
+    method: init.method ?? "GET",
+    headers,
+    ...init.body !== void 0 ? { body: JSON.stringify(init.body) } : {},
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  });
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : void 0;
+  } catch {
+    json = void 0;
+  }
+  return { status: res.status, ok: res.ok, text, json };
+}
+function apiErrorMessage(res, fallback) {
+  const message = res.json && typeof res.json === "object" ? res.json.error : void 0;
+  return typeof message === "string" && message ? message : `${fallback} (HTTP ${res.status}).`;
+}
+
+// src/tools/docs.ts
+var TOPICS = [
+  "embed",
+  "authoring",
+  "reference",
+  "styling",
+  "troubleshooting",
+  "prefill",
+  "webhooks",
+  "custom-ui",
+  "api"
+];
+function registerDocs(server) {
+  server.registerTool(
+    "fillo_docs",
+    {
+      title: "Read a Fillo documentation page",
+      description: "Fetch a Fillo documentation page as Markdown by topic, straight from the live site so it is never stale. No credential needed. Topics: embed (install + render), authoring (defineForm / JSX), reference (schema/field reference), styling, troubleshooting, prefill, webhooks, custom-ui, api (the read/management API). Read the relevant page before implementing.",
+      inputSchema: {
+        topic: z.enum(TOPICS).describe("Which docs page to fetch.")
+      }
+    },
+    async ({ topic }) => {
+      const res = await filloFetch(`/docs/${topic}.md`);
+      if (!res.ok || !res.text) {
+        return fail(`Couldn't fetch the "${topic}" docs page (HTTP ${res.status}).`);
+      }
+      return ok(res.text);
+    }
+  );
+}
+
+// src/tools/get-form.ts
+import { z as z2 } from "zod";
+function registerGetForm(server) {
+  server.registerTool(
+    "fillo_get_form",
+    {
+      title: "Get a published form's schema",
+      description: "Fetch a published form's schema, theme, capabilities, and closed flag by form id or slug. No credential needed \u2014 only published forms are served (drafts return not-found). Use this to verify what went live after fillo_push_form, or to read an existing form before editing it.",
+      inputSchema: {
+        form: z2.string().describe("Form id or slug (the trailing id of a /f/<slug> URL also works).")
+      }
+    },
+    async ({ form }) => {
+      const res = await filloFetch(`/api/v1/forms/${encodeURIComponent(form)}`);
+      if (res.status === 404) {
+        return fail(
+          `No published form "${form}". It may be a draft (publish it first) or the id/slug may be wrong.`
+        );
+      }
+      if (!res.ok || typeof res.json?.id !== "string") {
+        return fail(apiErrorMessage(res, "Couldn't fetch the form"));
+      }
+      const title = res.json.schema && typeof res.json.schema.title === "string" ? res.json.schema.title : void 0;
+      return ok(
+        `Form "${res.json.id}"${title ? ` \u2014 "${title}"` : ""}${res.json.closed ? " (closed to new responses)" : ""}.`,
+        res.json
+      );
+    }
+  );
+}
+
+// src/tools/get-response.ts
+import { z as z3 } from "zod";
+var NEEDS_KEY = "Reading a response needs a workspace API key (`fsk_\u2026`). This works only on a CLAIMED workspace: claim it, then mint a key in Settings \u2192 Connections and set FILLO_API_KEY.";
+function registerGetResponse(server) {
+  server.registerTool(
+    "fillo_get_response",
+    {
+      title: "Get one response",
+      description: "Fetch a single response by id: its answer data, meta, form version, and file references (id, name, size \u2014 file bytes stay in the customer's storage). Needs a workspace API key (`fsk_\u2026`) in FILLO_API_KEY on a CLAIMED workspace. A withheld/quarantined or cross-workspace id returns not-found. Get ids from fillo_list_responses.",
+      inputSchema: {
+        id: z3.string().describe("Response id (e.g. from fillo_list_responses).")
+      }
+    },
+    async ({ id }) => {
+      const apiKey = resolveApiKey();
+      if (!apiKey) return fail(NEEDS_KEY);
+      const res = await filloFetch(`/api/v1/manage/responses/${encodeURIComponent(id)}`, {
+        token: apiKey
+      });
+      if (res.status === 401) return fail(NEEDS_KEY);
+      if (res.status === 403) {
+        return fail("This API key is missing the responses:read scope. Mint a key with read access in Settings \u2192 Connections.");
+      }
+      if (res.status === 404) {
+        return fail(`No response "${id}" in this key's workspace (it may be withheld, deleted, or in another workspace).`);
+      }
+      if (!res.ok || typeof res.json?.id !== "string") {
+        return fail(apiErrorMessage(res, "Couldn't fetch the response"));
+      }
+      const fileCount = Array.isArray(res.json.files) ? res.json.files.length : 0;
+      return ok(
+        `Response "${res.json.id}" on form "${res.json.formId}"` + (fileCount ? ` with ${fileCount} file reference${fileCount === 1 ? "" : "s"}.` : "."),
+        res.json
+      );
+    }
+  );
+}
+
+// src/tools/list-forms.ts
+function registerListForms(server) {
+  server.registerTool(
+    "fillo_list_forms",
+    {
+      title: "List the workspace's forms",
+      description: "List every form in the signed-in workspace with its id, name, status (draft/published), and hosted URL. Needs a login token (FILLO_TOKEN or `npx @usefillo/cli login`); a `pk_` publishable key is not enough. If no token is set, run `fillo login` first.",
+      inputSchema: {}
+    },
+    async () => {
+      const token = resolveToken();
+      if (!token) {
+        return fail(
+          "Listing forms needs a login token. Set FILLO_TOKEN or run `npx @usefillo/cli login`, then retry."
+        );
+      }
+      const res = await filloFetch("/api/v1/cli/forms", { token });
+      if (res.status === 401) {
+        return fail("Login token is invalid or expired. Run `npx @usefillo/cli login`, or set a fresh FILLO_TOKEN.");
+      }
+      if (!res.ok || !Array.isArray(res.json?.forms)) {
+        return fail(apiErrorMessage(res, "Couldn't list forms"));
+      }
+      const forms = res.json.forms;
+      return ok(
+        forms.length ? `${forms.length} form${forms.length === 1 ? "" : "s"}: ` + forms.map((f) => `${f.name ?? "Untitled"} (${f.status ?? "?"})`).join(", ") : "No forms in this workspace yet.",
+        { forms: res.json.forms }
+      );
+    }
+  );
+}
+
+// src/tools/list-responses.ts
+import { z as z4 } from "zod";
+var NEEDS_KEY2 = "Reading responses needs a workspace API key (`fsk_\u2026`). This works only on a CLAIMED workspace: claim it, then mint a key in Settings \u2192 Connections and set FILLO_API_KEY. A `pk_` key or login token cannot read responses.";
+function registerListResponses(server) {
+  server.registerTool(
+    "fillo_list_responses",
+    {
+      title: "List a form's responses",
+      description: "List a form's accepted responses (keyset-paginated), newest first. Needs a workspace API key (`fsk_\u2026`) in FILLO_API_KEY \u2014 available only on a CLAIMED workspace (claim, then mint one in Settings \u2192 Connections). Filters use the responses-grid grammar: `range`, `q` (full-text), `source`, `respondent`, and repeated `where` clauses of the form `fieldId:op:value` (e.g. score:eq:10). Withheld/quarantined rows are never returned. Follow `nextCursor` to page.",
+      inputSchema: {
+        form: z4.string().describe("Form id or slug to read responses from."),
+        range: z4.string().optional().describe("Date range filter (grid grammar)."),
+        q: z4.string().optional().describe("Full-text search across answers."),
+        source: z4.string().optional().describe("Filter by response source."),
+        respondent: z4.string().optional().describe("Filter by respondent id."),
+        where: z4.array(z4.string()).optional().describe("Field filters, each `fieldId:op:value`, e.g. ['score:eq:10']."),
+        cursor: z4.string().optional().describe("Opaque cursor from a prior page's nextCursor."),
+        limit: z4.number().int().min(1).max(100).optional().describe("Page size (default server-set).")
+      }
+    },
+    async ({ form, range, q, source, respondent, where, cursor, limit }) => {
+      const apiKey = resolveApiKey();
+      if (!apiKey) return fail(NEEDS_KEY2);
+      const searchParams = new URLSearchParams();
+      if (range) searchParams.set("range", range);
+      if (q) searchParams.set("q", q);
+      if (source) searchParams.set("source", source);
+      if (respondent) searchParams.set("respondent", respondent);
+      for (const clause of where ?? []) searchParams.append("where", clause);
+      if (cursor) searchParams.set("cursor", cursor);
+      if (limit) searchParams.set("limit", String(limit));
+      const res = await filloFetch(
+        `/api/v1/manage/forms/${encodeURIComponent(form)}/responses`,
+        { token: apiKey, searchParams }
+      );
+      if (res.status === 401) return fail(NEEDS_KEY2);
+      if (res.status === 403) {
+        return fail("This API key is missing the responses:read scope. Mint a key with read access in Settings \u2192 Connections.");
+      }
+      if (res.status === 404) {
+        return fail(`No form "${form}" in this key's workspace. Check the id, or the key may belong to another workspace.`);
+      }
+      if (!res.ok || !Array.isArray(res.json?.data)) {
+        return fail(apiErrorMessage(res, "Couldn't list responses"));
+      }
+      const rows = res.json.data;
+      return ok(
+        `${rows.length} response${rows.length === 1 ? "" : "s"} on this page` + (res.json.nextCursor ? " (more available \u2014 follow nextCursor)." : "."),
+        res.json
+      );
+    }
+  );
+}
+
+// src/tools/provision.ts
+import { z as z5 } from "zod";
+function registerProvisionWorkspace(server) {
+  server.registerTool(
+    "fillo_provision_workspace",
+    {
+      title: "Provision a Fillo workspace",
+      description: "Create an unclaimed preview Fillo workspace so you can take a form live during integration before the developer signs up. No credential needed, but an email is REQUIRED \u2014 Fillo emails the private claim link to that inbox (it is never returned here). Returns a `pk_` publishable key (safe for browser/public env such as NEXT_PUBLIC_FILLO_KEY) plus the caps: up to N responses and a hold window. The key is saved locally so fillo_push_form and fillo_claim_status can use it. Next: push a form with fillo_push_form, then tell the user to open the emailed link and sign in to claim the workspace before the hold expires. Rate limited to 5/hour per network and 3/hour per email; a repeat email returns a collision error \u2014 reuse the emailed link.",
+      inputSchema: {
+        email: z5.string().email().describe("Where Fillo emails the private claim link. Ask the developer for theirs.")
+      }
+    },
+    async ({ email }) => {
+      const res = await filloFetch("/api/v1/workspaces/provision", {
+        method: "POST",
+        body: { email, source: "mcp" }
+      });
+      if (!res.ok || typeof res.json?.key !== "string") {
+        return fail(apiErrorMessage(res, "Couldn't provision a workspace"));
+      }
+      const key = res.json.key;
+      const organizationId = typeof res.json.organizationId === "string" ? res.json.organizationId : void 0;
+      const responseCap = typeof res.json.limits?.responses === "number" ? res.json.limits.responses : void 0;
+      const expiresAt = typeof res.json.limits?.expiresAt === "string" ? res.json.limits.expiresAt : void 0;
+      const emailedTo = typeof res.json.claim?.email === "string" ? res.json.claim.email : email;
+      writeConfig({
+        ...readConfig(),
+        pk: key,
+        provision: { organizationId, email: emailedTo, responseCap, expiresAt, api: apiOrigin() }
+      });
+      return ok(
+        `Provisioned an unclaimed Fillo workspace. Publishable key returned below \u2014 put it in the app's public env (e.g. NEXT_PUBLIC_FILLO_KEY). The claim link was emailed to ${emailedTo}. Push a form with fillo_push_form, then have the developer open that email and sign in to claim the workspace` + (expiresAt ? ` before ${expiresAt}.` : "."),
+        {
+          publishableKey: key,
+          organizationId,
+          responseCap,
+          expiresAt,
+          claimLinkEmailedTo: emailedTo
+        }
+      );
+    }
+  );
+}
+
+// src/tools/push-form.ts
+import { z as z6 } from "zod";
+function registerPushForm(server) {
+  server.registerTool(
+    "fillo_push_form",
+    {
+      title: "Create or update a Fillo form",
+      description: 'Create or update a form from a FormSchema plus a stable handle (an idempotent id \u2014 reuse it to update the same form). Needs a credential: a login token (FILLO_TOKEN / `fillo login`) publishes directly; a `pk_` publishable key (from fillo_provision_workspace) takes the form live on an unclaimed preview workspace, or stages a draft for review once the workspace is claimed. If neither is set, run fillo_provision_workspace or `fillo login` first. The server validates the schema and returns the form id, status, and hosted URL; embed it with <FilloForm formId="\u2026" />. Handle: letters, digits, dashes, max 64 chars.',
+      inputSchema: {
+        handle: z6.string().describe("Stable idempotent form id (letters, digits, dashes, max 64). Reuse to update."),
+        schema: z6.record(z6.string(), z6.unknown()).describe("The FormSchema object: title, pages (with blocks/fields), and settings."),
+        theme: z6.record(z6.string(), z6.unknown()).optional().describe("Optional theme tokens (colorScheme, primary, background, text, radius, fontFamily).")
+      }
+    },
+    async ({ handle, schema, theme }) => {
+      const token = resolveToken();
+      if (token) {
+        const res = await filloFetch("/api/v1/cli/forms", {
+          method: "POST",
+          token,
+          body: { handle, schema, theme: theme ?? null, publish: true }
+        });
+        if (!res.ok || typeof res.json?.formId !== "string") {
+          return fail(apiErrorMessage(res, "Couldn't push the form"));
+        }
+        const { formId, slug, url, updated } = res.json;
+        return ok(
+          `${updated ? "Updated" : "Published"} form "${formId}"${url ? `, live at ${url}` : ""}. Embed it with <FilloForm formId="${formId}" />.`,
+          { mode: "token", formId, slug, url, status: "published", updated: !!updated }
+        );
+      }
+      const pk = resolvePk();
+      if (pk) {
+        const res = await filloFetch("/api/v1/forms/sync", {
+          method: "POST",
+          body: { key: pk, id: handle, schema, theme: theme ?? null }
+        });
+        if (!res.ok || typeof res.json?.formId !== "string" || res.json?.syncError) {
+          const syncError = res.json?.syncError;
+          const message = syncError && typeof syncError.message === "string" && syncError.message || apiErrorMessage(res, "Couldn't sync the form");
+          return fail(message, syncError?.code ? { code: syncError.code } : void 0);
+        }
+        const { formId, slug, status, staged, warning } = res.json;
+        const live = status === "published" && slug ? `${apiOrigin()}/f/${slug}` : void 0;
+        const label = status === "published" ? `Live at ${live}` : staged ? "Staged as a draft for dashboard review" : "Saved as a draft";
+        return ok(
+          `Synced form "${formId}" (${status ?? "draft"}). ${label}. Embed it with <FilloForm formId="${formId}" />.` + (warning ? ` Note: ${warning}` : ""),
+          { mode: "publishable-key", formId, slug, status, staged: !!staged, url: live, warning }
+        );
+      }
+      return fail(
+        "No credential to push with. Run fillo_provision_workspace for a preview workspace, or set FILLO_TOKEN (or `npx @usefillo/cli login`) to publish to an existing account."
+      );
+    }
+  );
+}
+
+// src/tools/search-examples.ts
+import { z as z7 } from "zod";
+function registerSearchExamples(server) {
+  server.registerTool(
+    "fillo_search_examples",
+    {
+      title: "Search Fillo form examples",
+      description: "Search Fillo's curated example library (templates, implementations, and style recipes) for a use case before authoring a form from scratch. No credential needed. Returns full schema and code so you can adapt the closest match to the host app's routes, layout, and visual style rather than guessing. Always prefer adapting an example over inventing a schema.",
+      inputSchema: {
+        q: z7.string().describe("What you need, e.g. 'contact form with file upload' or 'NPS survey'."),
+        kind: z7.enum(["template", "implementation", "style"]).optional().describe("Restrict to one kind of example."),
+        framework: z7.string().optional().describe("Restrict to a framework, e.g. 'react' or 'dom'."),
+        capability: z7.string().optional().describe("Restrict to a capability, e.g. 'uploads' or 'conditional'."),
+        limit: z7.number().int().min(1).max(12).optional().describe("Max results (1\u201312, default 5).")
+      }
+    },
+    async ({ q, kind, framework, capability, limit }) => {
+      const searchParams = new URLSearchParams({ q: q ?? "", detail: "full" });
+      if (kind) searchParams.set("kind", kind);
+      if (framework) searchParams.set("framework", framework);
+      if (capability) searchParams.set("capability", capability);
+      if (limit) searchParams.set("limit", String(limit));
+      const res = await filloFetch("/api/v1/agent-examples/search", { searchParams });
+      if (!res.ok || !res.json) {
+        return fail(apiErrorMessage(res, "Couldn't search examples"));
+      }
+      const results = Array.isArray(res.json.results) ? res.json.results : res.json;
+      const count = Array.isArray(results) ? results.length : void 0;
+      return ok(
+        count === void 0 ? "Example search results below." : `${count} example${count === 1 ? "" : "s"} for "${q ?? ""}".`,
+        res.json
+      );
+    }
+  );
+}
+
+// src/tools/whoami.ts
+function registerWhoami(server) {
+  server.registerTool(
+    "fillo_whoami",
+    {
+      title: "Show the active Fillo credential",
+      description: "Report which Fillo credential is active and what it can reach. With a login token (FILLO_TOKEN or `fillo login`) it confirms the signed-in workspace. With only a `pk_` publishable key (from fillo_provision_workspace) it reports the unclaimed preview workspace's caps and claim state. If nothing is set up, it says exactly what to do: run fillo_provision_workspace, or set FILLO_TOKEN / run `fillo login`. Never prints token material.",
+      inputSchema: {}
+    },
+    async () => {
+      const token = resolveToken();
+      if (token) {
+        const res = await filloFetch("/api/v1/cli/whoami", { token });
+        if (res.status === 401) {
+          return fail("Login token is invalid or expired. Run `npx @usefillo/cli login`, or set a fresh FILLO_TOKEN.");
+        }
+        if (!res.ok) return fail(apiErrorMessage(res, "whoami failed"));
+        const workspace = typeof res.json?.workspace === "string" ? res.json.workspace : void 0;
+        return ok(
+          workspace ? `Signed in with a login token. Workspace: ${workspace}.` : "Signed in with a login token.",
+          { mode: "token", workspace, api: apiOrigin() }
+        );
+      }
+      const pk = resolvePk();
+      if (pk) {
+        const provision = resolveProvision();
+        if (provision) {
+          return ok(
+            `A publishable key for an unclaimed preview workspace is configured. The claim link was emailed to ${provision.email ?? "the provisioning address"}` + (provision.expiresAt ? `; claim it before ${provision.expiresAt}.` : "."),
+            {
+              mode: "provisional",
+              api: apiOrigin(),
+              organizationId: provision.organizationId,
+              claimLinkEmailedTo: provision.email,
+              responseCap: provision.responseCap,
+              expiresAt: provision.expiresAt
+            }
+          );
+        }
+        return ok(
+          "A publishable key is configured, but no provisioning record was found on this machine. A `pk_` key resolves and syncs forms; claim state is only visible from the browser that provisioned it, or with a login token after claiming. Sign in and set FILLO_TOKEN to see the live workspace.",
+          { mode: "publishable-key", api: apiOrigin() }
+        );
+      }
+      return fail(
+        "No Fillo credential is set up. Run fillo_provision_workspace to start a preview workspace, or set FILLO_TOKEN (or run `npx @usefillo/cli login`) to use an existing account."
+      );
+    }
+  );
+}
+
+// src/tools/index.ts
+function registerTools(server) {
+  registerProvisionWorkspace(server);
+  registerWhoami(server);
+  registerPushForm(server);
+  registerListForms(server);
+  registerGetForm(server);
+  registerSearchExamples(server);
+  registerDocs(server);
+  registerListResponses(server);
+  registerGetResponse(server);
+  registerClaimStatus(server);
+}
+
+// src/index.ts
+async function main() {
+  const version = CLIENT_VERSION.split("@").pop() ?? "0.0.0";
+  const server = new McpServer({ name: "fillo", version });
+  registerTools(server);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write(`Fillo MCP server ready (${CLIENT_VERSION}) \u2192 ${apiOrigin()}
+`);
+}
+main().catch((error) => {
+  process.stderr.write(`Fillo MCP server failed to start: ${error instanceof Error ? error.message : String(error)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@usefillo/mcp",
+  "version": "0.2.0",
+  "description": "Fillo MCP server — provision, scaffold, publish, and query forms from your coding agent.",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "forms",
+    "fillo",
+    "agent"
+  ],
+  "homepage": "https://fillo.so",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "fillo-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "node --test test/*.test.mjs",
+    "typecheck": "tsc --noEmit"
+  }
+}