@flowriki/agent 0.1.0-beta.28 → 0.1.0-beta.29

package/README.md

@@ -25,6 +25,30 @@ npx @flowriki/agent@latest doctor      # diagnose setup problems
 npx @flowriki/agent@latest disconnect  # forget this computer's credential
 ```
 
+## Write tests with Claude
+
+The agent is also an MCP server, so Claude Code or Claude Desktop can write
+Flowriki tests for you, on your own Claude plan. Claude drives a browser on
+this computer, each step is performed before it is kept, and what it writes is
+saved to a **new branch** for you to review and publish in the dashboard.
+
+Connect this computer first (`connect` above), then add Flowriki to Claude:
+
+```
+claude mcp add flowriki -- npx -y @flowriki/agent@latest mcp
+```
+
+For Claude Desktop, add this to its MCP settings (`claude_desktop_config.json`):
+
+```json
+{ "mcpServers": { "flowriki": { "command": "npx", "args": ["-y", "@flowriki/agent@latest", "mcp"] } } }
+```
+
+Then ask, for example: *"Write a Flowriki test that signs up and verifies the
+email"*. Claude reads your project's features, sign-in profiles and helpers,
+and uses them. You do not run `mcp` yourself — Claude starts it. It works
+alongside `start`, in a browser window of its own.
+
 ## What you do not need
 
 No checkout of Flowriki, and nothing to build. `connect` and `start` are the

package/dist/{chunk-PETFNOJA.js → chunk-3SU3RBVY.js}

@@ -6,7 +6,7 @@ import os from "os";
 import path from "path";
 import { createRequire } from "module";
 import { spawnSync } from "child_process";
-var AGENT_VERSION = "0.1.0-beta.28";
+var AGENT_VERSION = "0.1.0-beta.29";
 async function prepareBrowsers() {
   if (browsersReady()) {
     return { ok: true, already: true, message: "chromium is already installed" };
@@ -11206,7 +11206,17 @@ export {
   AGENT_VERSION,
   prepareBrowsers,
   browsersReady,
+  connectionFor,
+  resolveService,
   connect,
+  RecordedStepSchema,
+  authenticationResolver,
+  checkAssertion,
+  openRunSession,
+  closeRunSession,
+  replayFlow,
+  executeStep,
+  helperRunner,
   resolveCheckouts,
   start,
   status,

package/dist/cli.js

@@ -1,17 +1,757 @@
 #!/usr/bin/env node
 import {
   AGENT_VERSION,
+  RecordedStepSchema,
+  authenticationResolver,
+  checkAssertion,
+  closeRunSession,
   connect,
+  connectionFor,
   disconnect,
   doctor,
+  executeStep,
+  helperRunner,
+  openRunSession,
   prepareBrowsers,
+  replayFlow,
   resolveCheckouts,
+  resolveService,
   start,
   status
-} from "./chunk-PETFNOJA.js";
+} from "./chunk-3SU3RBVY.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
+
+// src/mcp/protocol.ts
+import readline from "readline";
+var PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+async function handle(message, tools, info) {
+  const reply = (result) => ({ jsonrpc: "2.0", id: message.id ?? null, result });
+  const fail = (code, text2) => ({ jsonrpc: "2.0", id: message.id ?? null, error: { code, message: text2 } });
+  if (message.id === void 0 || message.id === null) return null;
+  switch (message.method) {
+    case "initialize": {
+      const asked = String(message.params?.["protocolVersion"] ?? "");
+      const version = PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0];
+      return reply({
+        protocolVersion: version,
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: { name: info.name, version: info.version },
+        instructions: info.instructions
+      });
+    }
+    case "ping":
+      return reply({});
+    case "tools/list":
+      return reply({
+        tools: tools.map(({ name, title, description, inputSchema, annotations }) => ({
+          name,
+          ...title ? { title } : {},
+          description,
+          inputSchema,
+          ...annotations ? { annotations } : {}
+        }))
+      });
+    case "tools/call": {
+      const name = String(message.params?.["name"] ?? "");
+      const tool = tools.find((t) => t.name === name);
+      if (!tool) return fail(-32602, `no tool named ${name}`);
+      const args = message.params?.["arguments"] ?? {};
+      try {
+        return reply(await tool.run(args));
+      } catch (error) {
+        return reply({ content: [{ type: "text", text: error.message }], isError: true });
+      }
+    }
+    default:
+      return fail(-32601, `method not found: ${message.method}`);
+  }
+}
+function serve(tools, info, io = {}) {
+  const input = io.input ?? process.stdin;
+  const output = io.output ?? process.stdout;
+  if (!io.output) {
+    console.log = console.info = console.warn = console.debug = (...args) => {
+      process.stderr.write(`${args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ")}
+`);
+    };
+  }
+  const lines = readline.createInterface({ input, crlfDelay: Infinity });
+  const pending = /* @__PURE__ */ new Set();
+  lines.on("line", (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      output.write(`${JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } })}
+`);
+      return;
+    }
+    const task = handle(message, tools, info).then((answer) => {
+      if (answer) output.write(`${JSON.stringify(answer)}
+`);
+    });
+    pending.add(task);
+    void task.finally(() => pending.delete(task));
+  });
+  return new Promise((resolve) => lines.on("close", () => void Promise.allSettled([...pending]).then(() => resolve())));
+}
+
+// src/mcp/service-client.ts
+var ServiceClient = class {
+  constructor(connection, fetcher = fetch) {
+    this.connection = connection;
+    this.fetcher = fetcher;
+  }
+  connection;
+  fetcher;
+  get origin() {
+    return this.connection.service;
+  }
+  async call(path, init = {}) {
+    const res = await this.fetcher(`${this.connection.service}${path}`, {
+      ...init,
+      headers: {
+        "x-flowriki-device": this.connection.deviceId,
+        "x-flowriki-device-secret": this.connection.secret,
+        "content-type": "application/json"
+      }
+    });
+    const text2 = await res.text();
+    let body = {};
+    try {
+      body = text2 ? JSON.parse(text2) : {};
+    } catch {
+    }
+    if (!res.ok) {
+      if (res.status === 404 && !("error" in body)) {
+        throw new Error("the Flowriki service does not offer this yet \u2014 it may need updating");
+      }
+      throw new Error(String(body["error"] ?? `the service answered ${res.status}`));
+    }
+    return body;
+  }
+  projects() {
+    return this.call("/api/agent/projects");
+  }
+  catalog(projectId) {
+    return this.call(`/api/agent/catalog?projectId=${encodeURIComponent(projectId)}`);
+  }
+  prepare(projectId, steps, signIn) {
+    return this.call(`/api/agent/prepare?projectId=${encodeURIComponent(projectId)}`, {
+      method: "POST",
+      body: JSON.stringify({ steps, ...signIn ? { signIn } : {} })
+    });
+  }
+  saveFlow(projectId, title, flow) {
+    return this.call(
+      `/api/agent/flows?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify({ title, flow }) }
+    );
+  }
+};
+
+// src/mcp/session.ts
+var MAX_TREE = 14e3;
+var STEP_TIMEOUT_MS = 1e4;
+var ACTIONS = ["click", "dblclick", "rightclick", "hover", "fill", "select", "check", "press", "navigate", "back", "forward"];
+var isAction = (value) => ACTIONS.includes(String(value));
+var LANDMARKS = /* @__PURE__ */ new Set(["main", "navigation", "banner", "contentinfo", "complementary", "search", "form", "dialog", "alertdialog", "region", "group", "list", "table", "menu", "toolbar", "tablist"]);
+function scopeOf(within) {
+  const said = within?.trim() ?? "";
+  if (!said) return { scope: "" };
+  return LANDMARKS.has(said.toLowerCase()) ? { scope: "", scopeRole: said.toLowerCase() } : { scope: said };
+}
+function describe(step) {
+  const target = step.name ? `${step.role || "element"} "${step.name}"` : step.role || "";
+  const where = step.scope ? ` in "${step.scope}"` : step.scopeRole ? ` in the ${step.scopeRole}` : "";
+  switch (step.type) {
+    case "fill":
+      return `type "${step.value}" into ${target}${where}`;
+    case "select":
+      return `choose "${step.value}" in ${target}${where}`;
+    case "check":
+      return `${step.value === "false" ? "untick" : "tick"} ${target}${where}`;
+    case "press":
+      return `press ${step.value}${target ? ` in ${target}` : ""}`;
+    case "navigate":
+      return `go to ${step.value}`;
+    case "back":
+    case "forward":
+      return `browser ${step.type}`;
+    case "assert":
+      return `check ${step.proposals.map((p) => `${p.kind}${p.op && p.op !== "equals" ? ` ${p.op}` : ""} "${String(p.value)}"${p.target?.name ? ` on ${p.target.role} "${p.target.name}"` : ""}`).join(", ")}`;
+    case "useHelper":
+      return `use helper ${step.name || step.helper?.helperId} \u2192 {{${step.helper?.saveAs}}}${step.helper?.then === "open" ? ", then open it" : ""}`;
+    default:
+      return `${step.type} ${target}${where}`;
+  }
+}
+var AuthoringSession = class {
+  constructor(service, opts = {}) {
+    this.service = service;
+    this.opts = opts;
+  }
+  service;
+  opts;
+  run = null;
+  page = null;
+  values = /* @__PURE__ */ new Map();
+  resolvers = null;
+  draft = null;
+  catalog = null;
+  get open() {
+    return this.run !== null;
+  }
+  requireOpen() {
+    if (!this.run || !this.page || !this.draft) throw new Error("no flow is being written \u2014 call start_flow first");
+    return { page: this.page, draft: this.draft, run: this.run };
+  }
+  /** What the steps so far, plus any about to run, need from the service:
+   *  sign-ins, helpers, and their secret values. Asked again whenever a new
+   *  helper or sign-in appears, never kept beyond this process. */
+  async prepare(extra = []) {
+    const draft = this.draft;
+    const prepared = await this.service.prepare(draft.projectId, [...draft.steps, ...extra], draft.signIn ?? null);
+    const runHelper = helperRunner(prepared.helpers, prepared.secrets);
+    this.resolvers = {
+      resolveAuth: authenticationResolver(prepared.authentications),
+      resolveSecret: (ref) => prepared.secrets[ref],
+      ...runHelper ? { runHelper } : {}
+    };
+    return this.resolvers;
+  }
+  baseUrl() {
+    const base = this.catalog?.baseUrl ?? "";
+    if (!base) throw new Error("this project has no base URL \u2014 set one in the project's settings first");
+    return base;
+  }
+  /** Open a browser for a new flow, signed in first if asked. */
+  async start(input, catalog) {
+    await this.close();
+    this.catalog = catalog;
+    this.draft = { ...input, steps: [] };
+    this.values = /* @__PURE__ */ new Map();
+    const base = this.baseUrl();
+    this.run = await openRunSession({ steps: [], headless: this.opts.headless ?? false });
+    this.page = this.run.page;
+    if (input.signIn) {
+      const resolvers = await this.prepare();
+      const signIn = {
+        id: "sign-in",
+        type: "signIn",
+        auth: { ...input.signIn, from: "loginPage" },
+        role: "",
+        name: "Sign in",
+        scope: "",
+        value: "",
+        secret: false,
+        legacySelector: "",
+        proposals: []
+      };
+      this.page = await executeStep(this.page, signIn, {
+        pages: this.run.pages,
+        ...resolvers,
+        values: this.values,
+        baseUrl: base,
+        timeoutMs: 2e4,
+        navigationTimeoutMs: 45e3
+      });
+    } else {
+      await this.page.goto(new URL(input.startPath || "/", base).href, { waitUntil: "domcontentloaded", timeout: 45e3 });
+    }
+    return this.snapshot();
+  }
+  /** The page as Claude reads it: where it is, and what is on it by role and name. */
+  async snapshot() {
+    const { page, draft } = this.requireOpen();
+    await page.waitForLoadState("domcontentloaded", { timeout: 1e4 }).catch(() => void 0);
+    let tree = await page.locator("body").ariaSnapshot({ timeout: 8e3 }).catch((e) => `(could not read the page: ${e.message})`);
+    if (tree.length > MAX_TREE) tree = `${tree.slice(0, MAX_TREE)}
+\u2026 (cut \u2014 the page is long; act on what is above, or scroll with press "PageDown")`;
+    const title = await page.title().catch(() => "");
+    return `Page: ${page.url()}${title ? ` \u2014 "${title}"` : ""}
+Steps so far: ${draft.steps.length}
+
+${tree}`;
+  }
+  /** Do one thing on the page, and keep it as a step if it worked. */
+  async act(input) {
+    const { page, draft, run } = this.requireOpen();
+    const navigating = input.action === "navigate" || input.action === "back" || input.action === "forward";
+    if (!navigating && input.action !== "press" && !(input.role && input.name)) {
+      throw new Error(`${input.action} needs the element's role and name, exactly as read_page shows them`);
+    }
+    if ((input.action === "fill" || input.action === "select" || input.action === "press" || input.action === "navigate") && input.value === void 0) {
+      throw new Error(`${input.action} needs a value`);
+    }
+    const step = RecordedStepSchema.parse({
+      id: `s${draft.steps.length + 1}_${Date.now().toString(36)}`,
+      type: input.action,
+      role: navigating ? "" : input.role ?? "",
+      name: navigating ? "" : input.name ?? "",
+      ...scopeOf(input.within),
+      value: input.action === "check" ? input.value === "false" ? "false" : "true" : input.value ?? "",
+      secret: false,
+      legacySelector: "",
+      proposals: [],
+      // A path is the application's own, so the step replays on whichever
+      // environment the run is pointed at rather than the one written on.
+      ...input.action === "navigate" && input.value?.startsWith("/") ? { navigationBase: "application" } : {}
+    });
+    try {
+      this.page = await executeStep(page, step, {
+        pages: run.pages,
+        values: this.values,
+        baseUrl: this.baseUrl(),
+        ...this.resolvers ?? {},
+        timeoutMs: STEP_TIMEOUT_MS,
+        navigationTimeoutMs: 45e3
+      });
+    } catch (error) {
+      throw new Error(`That did not work, and was not kept: ${error.message.split("\n")[0]}
+
+${await this.snapshot()}`);
+    }
+    await this.settle();
+    draft.steps.push(step);
+    return `Step ${draft.steps.length} kept: ${describe(step)}.
+
+${await this.snapshot()}`;
+  }
+  /** Check something about the page now, and keep the check if it holds. */
+  async check(input) {
+    const { page, draft } = this.requireOpen();
+    if ((input.kind === "heading" || input.kind === "message" || input.kind === "screen") && input.op && input.op !== "equals" && !input.role) {
+      throw new Error(`a ${input.kind} check without role and name matches the whole ${input.kind} \u2014 give its full text with op equals, or name the element (role + name) and use kind "text" with op ${input.op}`);
+    }
+    const assertion = RecordedStepSchema.shape.proposals.element.parse({
+      kind: input.kind,
+      value: input.value,
+      enabled: true,
+      ...input.op && input.op !== "equals" ? { op: input.op } : {},
+      ...input.role ? { target: { role: input.role, name: input.name ?? "", ...scopeOf(input.within) } } : {}
+    });
+    try {
+      await checkAssertion(page, assertion.kind, assertion.value, 5e3, assertion);
+    } catch (error) {
+      throw new Error(`That is not true of the page right now, so it was not kept: ${error.message.split("\n")[0]}`);
+    }
+    const step = RecordedStepSchema.parse({
+      id: `c${draft.steps.length + 1}_${Date.now().toString(36)}`,
+      type: "assert",
+      role: "",
+      name: "",
+      scope: "",
+      value: "",
+      secret: false,
+      legacySelector: "",
+      proposals: [assertion]
+    });
+    draft.steps.push(step);
+    return `Step ${draft.steps.length} kept: ${describe(step)}.`;
+  }
+  /** Get a value from outside the page — an email code, a 2FA code, a text,
+   *  an API reply — and keep the step that gets it. */
+  async useHelper(input) {
+    const { page, draft, run } = this.requireOpen();
+    const helper = this.catalog?.helpers.find((h) => h.id === input.helperId || h.name.toLowerCase() === input.helperId.toLowerCase());
+    if (!helper) throw new Error(`no helper "${input.helperId}" \u2014 project_catalog lists them; one can be made on the Helpers screen`);
+    const missing = helper.inputs.filter((name) => !(input.inputs ?? {})[name]);
+    if (missing.length) throw new Error(`${helper.name} needs ${missing.map((n) => `{{${n}}}`).join(", ")} in inputs`);
+    const step = RecordedStepSchema.parse({
+      id: `h${draft.steps.length + 1}_${Date.now().toString(36)}`,
+      type: "useHelper",
+      role: "",
+      name: helper.name,
+      scope: "",
+      value: "",
+      secret: false,
+      legacySelector: "",
+      proposals: [],
+      helper: { helperId: helper.id, inputs: input.inputs ?? {}, saveAs: input.saveAs || (helper.kind === "mailbox" ? "code" : "value"), then: input.then ?? "remember" }
+    });
+    const resolvers = await this.prepare([step]);
+    let got = { value: "", detail: "" };
+    try {
+      this.page = await executeStep(page, step, {
+        pages: run.pages,
+        values: this.values,
+        baseUrl: this.baseUrl(),
+        ...resolvers,
+        timeoutMs: STEP_TIMEOUT_MS,
+        navigationTimeoutMs: 45e3,
+        onHelper: (answer) => {
+          got = answer;
+        }
+      });
+    } catch (error) {
+      throw new Error(`The helper did not get a value, and the step was not kept: ${error.message}`);
+    }
+    await this.settle();
+    draft.steps.push(step);
+    return `Step ${draft.steps.length} kept: ${describe(step)}. It got "${got.value}" (${got.detail}). Use {{${step.helper.saveAs}}} as the value of a later step.` + (step.helper.then === "open" ? `
+
+${await this.snapshot()}` : "");
+  }
+  list() {
+    const draft = this.draft;
+    if (!draft) return "No flow is being written.";
+    const head = `"${draft.name}"${draft.signIn ? ", signed in first" : ""}, starting at ${draft.startPath}`;
+    if (draft.steps.length === 0) return `${head}. No steps yet.`;
+    return `${head}:
+${draft.steps.map((s, i) => `${i + 1}. ${describe(s)}`).join("\n")}`;
+  }
+  /** Drop a step from the draft. The browser is not wound back — replay to
+   *  see the flow as it now stands. */
+  remove(number) {
+    const { draft } = this.requireOpen();
+    if (!Number.isInteger(number) || number < 1 || number > draft.steps.length) throw new Error(`there is no step ${number}`);
+    const [gone] = draft.steps.splice(number - 1, 1);
+    return `Removed step ${number} (${describe(gone)}). The browser was not undone \u2014 replay_flow shows the flow as it now stands.
+
+${this.list()}`;
+  }
+  /** Run the whole draft from the start, in a browser of its own, the way a
+   *  run will — the proof the steps work together, not just one at a time. */
+  async replay() {
+    const { draft } = this.requireOpen();
+    if (draft.steps.length === 0) throw new Error("there are no steps to replay yet");
+    const resolvers = await this.prepare();
+    const steps = [
+      ...draft.signIn ? [RecordedStepSchema.parse({ id: "sign-in", type: "signIn", auth: { ...draft.signIn, from: "loginPage" }, role: "", name: "Sign in", scope: "", value: "", secret: false, legacySelector: "", proposals: [] })] : [],
+      ...draft.steps
+    ];
+    const outcome = await replayFlow({ steps, baseUrl: this.baseUrl(), startPath: draft.startPath, headless: true, ...resolvers });
+    const lines = outcome.steps.map((s) => `${s.status === "passed" ? "\u2713" : s.status === "failed" ? "\u2717" : "\xB7"} ${s.name || s.type}${s.status === "failed" && s.detail ? ` \u2014 ${s.detail}` : ""}`);
+    return `${outcome.status === "passed" ? "The whole flow passed from the start." : `The flow ${outcome.status}${outcome.error ? `: ${outcome.error}` : ""}.`}
+${lines.join("\n")}`;
+  }
+  /** Save the draft as a flow on a new branch, for a person to review. */
+  async save(title) {
+    const { draft } = this.requireOpen();
+    if (draft.steps.length === 0) throw new Error("there are no steps to save yet");
+    if (!draft.steps.some((s) => s.type === "assert" || s.proposals.length > 0)) {
+      throw new Error("the flow checks nothing \u2014 add at least one check (add_check) that proves it worked, then save");
+    }
+    const saved = await this.service.saveFlow(draft.projectId, title || `Write "${draft.name}" with Claude`, {
+      name: draft.name,
+      ...draft.featureId ? { featureId: draft.featureId } : { featureName: draft.featureName },
+      startPath: draft.startPath,
+      steps: draft.steps,
+      ...draft.signIn ? { signIn: draft.signIn } : {}
+    });
+    const review = `${this.service.origin}/projects/${draft.projectId}/changes/${saved.changeId}`;
+    return `Saved "${draft.name}" on a new branch, ${saved.branch}. Nothing is published yet.
+Review and publish it here: ${review}`;
+  }
+  async close() {
+    const run = this.run;
+    this.run = null;
+    this.page = null;
+    this.resolvers = null;
+    if (run) await closeRunSession(run, { passed: true }).catch(() => void 0);
+  }
+  /** Let a click's consequences land before the page is read again. */
+  async settle() {
+    const page = this.page;
+    if (!page) return;
+    await page.waitForLoadState("domcontentloaded", { timeout: 1e4 }).catch(() => void 0);
+    await page.waitForTimeout(300);
+  }
+};
+
+// src/mcp/tools.ts
+var INSTRUCTIONS = `Flowriki tools write UI tests by driving a real browser on this computer.
+Every step you take is performed first and kept only if it worked, so the flow
+you save already ran once. Saved flows go to a NEW branch that a person reviews
+and publishes in the Flowriki dashboard \u2014 nothing you do is published.
+
+How to write a good Flowriki test:
+1. Call project_catalog first. Reuse an existing feature for the flow when one
+   fits; otherwise name a new one. Check the existing flows so you do not write
+   one that already exists.
+2. One flow is one user journey with one purpose ("Sign up and verify email",
+   "Pay by card"), named the way a tester would say it.
+3. If the journey needs somebody signed in, pass signIn with a profile and an
+   account from the catalog to start_flow. Never type real credentials.
+4. Read the page with read_page and act using the role and name EXACTLY as the
+   page shows them (e.g. button "Continue", textbox "Email"). If a name appears
+   more than once, pass "within" with the name of the region, dialog or form
+   that holds the one you mean.
+5. For things outside the page \u2014 an emailed code or link, an authenticator
+   code, a text message, an API call \u2014 use use_helper with a helper from the
+   catalog, then type {{its saveAs name}} into the field that needs it.
+6. End with at least one check (add_check) that proves the journey worked:
+   a heading, a message, the URL. Saving is refused for a flow that checks nothing.
+7. Before saving, call replay_flow to run the whole flow from the start. If a
+   step fails there, fix it (remove_step, act again) and replay again.
+8. Save with save_flow and give the person the review link it returns.
+Test data you invent (a new user's email or password for a sign-up) is fine to
+type; prefer an address the project's mailbox helper can read, such as
+qa+something@ the mailbox's own domain.`;
+var text = (value, isError = false) => ({ content: [{ type: "text", text: value }], ...isError ? { isError } : {} });
+var str = (value) => typeof value === "string" ? value : value === void 0 || value === null ? void 0 : String(value);
+function authoringTools(service, session) {
+  let defaultProject = null;
+  const catalogs = /* @__PURE__ */ new Map();
+  const projectFor = async (asked) => {
+    const named = str(asked);
+    if (named) return defaultProject = named;
+    if (session.draft) return session.draft.projectId;
+    if (defaultProject) return defaultProject;
+    const { projects } = await service.projects();
+    if (projects.length === 1) return defaultProject = projects[0].id;
+    if (projects.length === 0) throw new Error("this account is not on any Flowriki project yet \u2014 create one in the dashboard");
+    throw new Error(`which project? Pass projectId \u2014 one of: ${projects.map((p) => `${p.name} (${p.id})`).join(", ")}`);
+  };
+  const catalogOf = async (projectId, fresh = false) => {
+    if (!fresh && catalogs.has(projectId)) return catalogs.get(projectId);
+    const catalog = await service.catalog(projectId);
+    catalogs.set(projectId, catalog);
+    return catalog;
+  };
+  return [
+    {
+      name: "list_projects",
+      title: "List Flowriki projects",
+      description: "The Flowriki projects you can write tests for, with your role on each. Only needed when you are on more than one.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async () => {
+        const { projects } = await service.projects();
+        return text(projects.length ? projects.map((p) => `${p.name} \u2014 id ${p.id}, you are ${p.role}`).join("\n") : "You are not on any project yet.");
+      }
+    },
+    {
+      name: "project_catalog",
+      title: "What a test can be built from",
+      description: "The project's base URL, features (folders for flows), existing flows, sign-in profiles with their accounts, and helpers (email codes, 2FA, SMS, API calls). Read this before starting a flow.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string", description: "Optional when you are on one project." } }, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const c = await catalogOf(projectId, true);
+        const flowsBy = (featureId) => c.flows.filter((f) => f.featureId === featureId).map((f) => `    - ${f.name} (${f.steps} steps)`).join("\n");
+        return text([
+          `Project ${projectId}. Base URL: ${c.baseUrl || "(not set)"}`,
+          c.environments.length ? `Environments: ${c.environments.map((e) => `${e.name} ${e.baseUrl}`).join(", ")}` : "",
+          `
+Features:${c.features.length ? "" : " none yet"}`,
+          ...c.features.map((f) => `  - ${f.name} (id ${f.id})${f.description ? ` \u2014 ${f.description}` : ""}
+${flowsBy(f.id)}`),
+          `
+Sign-in profiles:${c.signIns.length ? "" : " none"}`,
+          ...c.signIns.map((s) => `  - ${s.name} (profileId ${s.profileId}): ${s.accounts.map((a) => `${a.name} (accountId ${a.accountId})`).join(", ") || "no accounts yet"}`),
+          `
+Helpers:${c.helpers.length ? "" : " none \u2014 they are made on the Helpers screen"}`,
+          ...c.helpers.map((h) => `  - ${h.name} (id ${h.id}) \u2014 ${h.what}${h.inputs.length ? `; needs ${h.inputs.map((n) => `{{${n}}}`).join(", ")}` : ""}${h.description ? ` \u2014 ${h.description}` : ""}`)
+        ].filter(Boolean).join("\n"));
+      }
+    },
+    {
+      name: "start_flow",
+      title: "Start writing a flow",
+      description: "Open a browser on this computer at the project's app and start a new flow. Returns the page. Closes any flow that was being written.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: `The flow's name: the user journey, e.g. "Sign up and verify email".` },
+          feature: { type: "string", description: "The feature it belongs to: an existing feature's id or name, or a new name." },
+          startPath: { type: "string", description: 'Where it starts, relative to the base URL. Default "/".' },
+          signIn: {
+            type: "object",
+            description: "Start signed in, with a profile (and optionally an account) from project_catalog.",
+            properties: { profileId: { type: "string" }, accountId: { type: "string" } },
+            required: ["profileId"],
+            additionalProperties: false
+          },
+          projectId: { type: "string" }
+        },
+        required: ["name", "feature"],
+        additionalProperties: false
+      },
+      annotations: { openWorldHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const catalog = await catalogOf(projectId, true);
+        const featureAsked = str(args["feature"]) ?? "";
+        const feature = catalog.features.find((f) => f.id === featureAsked || f.name.toLowerCase() === featureAsked.toLowerCase());
+        const signIn = args["signIn"];
+        if (signIn && !catalog.signIns.some((s) => s.profileId === signIn.profileId)) {
+          throw new Error(`no sign-in profile ${signIn.profileId} \u2014 project_catalog lists them`);
+        }
+        const page = await session.start({
+          projectId,
+          name: str(args["name"]) ?? "Untitled flow",
+          ...feature ? { featureId: feature.id } : { featureName: featureAsked },
+          startPath: str(args["startPath"]) || "/",
+          ...signIn?.profileId ? { signIn: { profileId: signIn.profileId, ...signIn.accountId ? { accountId: signIn.accountId } : {} } } : {}
+        }, catalog);
+        return text(`Started "${str(args["name"])}"${feature ? ` in ${feature.name}` : ` in a new feature, ${featureAsked}`}. The browser is open.
+
+${page}`);
+      }
+    },
+    {
+      name: "read_page",
+      title: "Read the page",
+      description: "The current page as its accessibility tree: each element's role and name, which is exactly what act and add_check refer to.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async () => text(await session.snapshot())
+    },
+    {
+      name: "act",
+      title: "Do one thing on the page",
+      description: `Perform one step and keep it in the flow if it worked. Returns the page afterwards. click/dblclick/rightclick/hover: role + name. fill: role + name + value (may use {{values}} from helpers). select: role + name + the option's label as value. check: role + name, value "true" or "false". press: a key such as "Enter" as value, optionally role + name of where. navigate: a path such as "/settings" or a full URL as value. back/forward: nothing.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          action: { type: "string", enum: ["click", "dblclick", "rightclick", "hover", "fill", "select", "check", "press", "navigate", "back", "forward"] },
+          role: { type: "string", description: "The element's role as read_page shows it, e.g. button, link, textbox, checkbox, combobox." },
+          name: { type: "string", description: "The element's accessible name, exactly as read_page shows it." },
+          within: { type: "string", description: "When the name is not unique: the name of the region, dialog, form or navigation that holds it." },
+          value: { type: "string" }
+        },
+        required: ["action"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        if (!isAction(args["action"])) throw new Error("action must be one of click, dblclick, rightclick, hover, fill, select, check, press, navigate, back, forward");
+        return text(await session.act({
+          action: args["action"],
+          ...str(args["role"]) ? { role: str(args["role"]) } : {},
+          ...str(args["name"]) !== void 0 ? { name: str(args["name"]) } : {},
+          ...str(args["within"]) ? { within: str(args["within"]) } : {},
+          ...str(args["value"]) !== void 0 ? { value: str(args["value"]) } : {}
+        }));
+      }
+    },
+    {
+      name: "add_check",
+      title: "Add a check",
+      description: "Assert something about the page as it is now, and keep it in the flow if it holds. Page checks need only kind + value: heading, url (a path), title, message. Element checks also need role + name: text, value, visible, hidden, checked, count. op: equals (default), contains or matches.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          kind: { type: "string", enum: ["heading", "url", "title", "message", "screen", "text", "value", "visible", "hidden", "checked", "enabled", "count"] },
+          value: { type: "string", description: `What it should be: the heading's words, the path, "true" for a state, a number for count.` },
+          op: { type: "string", enum: ["equals", "contains", "matches"] },
+          role: { type: "string" },
+          name: { type: "string" },
+          within: { type: "string" }
+        },
+        required: ["kind", "value"],
+        additionalProperties: false
+      },
+      run: async (args) => text(await session.check({
+        kind: str(args["kind"]),
+        value: str(args["value"]) ?? "",
+        ...str(args["op"]) ? { op: str(args["op"]) } : {},
+        ...str(args["role"]) ? { role: str(args["role"]), name: str(args["name"]) ?? "" } : {},
+        ...str(args["within"]) ? { within: str(args["within"]) } : {}
+      }))
+    },
+    {
+      name: "use_helper",
+      title: "Use a helper",
+      description: `Get a value from outside the page with one of the project's helpers \u2014 the code or link from a verification email, an authenticator code, an SMS code, a field of an API reply \u2014 and keep the step. Later steps use it as {{saveAs}}. then: "open" goes to the value as a link (for verification links).`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          helperId: { type: "string", description: "The helper's id or name from project_catalog." },
+          inputs: { type: "object", additionalProperties: { type: "string" }, description: `Values for the helper's {{names}}, e.g. {"email": "qa+signup1@example.com"}.` },
+          saveAs: { type: "string", description: "What to call the value, e.g. code. Default: code for a mailbox, value otherwise." },
+          then: { type: "string", enum: ["remember", "open"] }
+        },
+        required: ["helperId"],
+        additionalProperties: false
+      },
+      run: async (args) => text(await session.useHelper({
+        helperId: str(args["helperId"]),
+        ...args["inputs"] && typeof args["inputs"] === "object" ? { inputs: Object.fromEntries(Object.entries(args["inputs"]).map(([k, v]) => [k, String(v)])) } : {},
+        ...str(args["saveAs"]) ? { saveAs: str(args["saveAs"]) } : {},
+        ...args["then"] === "open" ? { then: "open" } : {}
+      }))
+    },
+    {
+      name: "list_steps",
+      title: "List the flow's steps",
+      description: "The flow being written, step by step.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async () => text(session.list())
+    },
+    {
+      name: "remove_step",
+      title: "Remove a step",
+      description: "Remove one step by its number in list_steps. The browser is not wound back; use replay_flow to see the flow as it now stands.",
+      inputSchema: { type: "object", properties: { number: { type: "integer", minimum: 1 } }, required: ["number"], additionalProperties: false },
+      annotations: { destructiveHint: true },
+      run: async (args) => text(session.remove(Number(args["number"])))
+    },
+    {
+      name: "replay_flow",
+      title: "Replay the flow from the start",
+      description: "Run the whole flow from the beginning in a fresh browser, exactly as a test run will, and report each step. Do this before saving.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+      run: async () => text(await session.replay())
+    },
+    {
+      name: "save_flow",
+      title: "Save the flow to a branch",
+      description: "Save the flow to a new branch in the project's repository, for a person to review and publish. Returns the review link. Refused if the flow checks nothing.",
+      inputSchema: { type: "object", properties: { title: { type: "string", description: "The branch's title \u2014 what this change adds." } }, additionalProperties: false },
+      run: async (args) => text(await session.save(str(args["title"])))
+    },
+    {
+      name: "close_browser",
+      title: "Close the browser",
+      description: "Close the browser and drop the flow being written, unsaved.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { destructiveHint: true },
+      run: async () => {
+        await session.close();
+        session.draft = null;
+        return text("Closed.");
+      }
+    }
+  ];
+}
+
+// src/mcp/index.ts
+async function runMcp(opts) {
+  let service;
+  try {
+    service = resolveService(opts.service);
+  } catch (error) {
+    process.stderr.write(`${error.message}
+`);
+    return 2;
+  }
+  const connection = connectionFor(service);
+  const session = connection ? new AuthoringSession(new ServiceClient(connection), opts.headless ? { headless: true } : {}) : null;
+  let tools = connection && session ? authoringTools(new ServiceClient(connection), session) : authoringTools(null, null);
+  if (!connection) {
+    const why = `This computer is not connected to Flowriki at ${service}. Run \`flowriki-agent connect\` in a terminal, approve it in your browser, then restart Claude.`;
+    tools = tools.map((tool) => ({ ...tool, run: async () => ({ content: [{ type: "text", text: why }], isError: true }) }));
+  }
+  const closing = async () => {
+    await session?.close();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void closing());
+  process.on("SIGTERM", () => void closing());
+  await serve(tools, { name: "flowriki", version: opts.version, instructions: INSTRUCTIONS });
+  await session?.close();
+  return 0;
+}
+
+// src/cli.ts
 var paint = (code) => (s) => `\x1B[${code}m${s}\x1B[0m`;
 var bold = paint("1");
 var dim = paint("2");
@@ -30,6 +770,9 @@ ${bold("USAGE")}
   flowriki-agent doctor             diagnose setup problems
   flowriki-agent prepare            download the browser recording needs
   flowriki-agent disconnect         forget this computer's credential
+  flowriki-agent mcp                Flowriki as tools for Claude \u2014 started by
+                                    Claude Code or Claude Desktop, not by you:
+                                    claude mcp add flowriki -- flowriki-agent mcp
 
 ${bold("OPTIONS")}
   --project <dir>        a checkout to serve; repeat for several.
@@ -81,6 +824,10 @@ Run \`flowriki-agent --help\`.`);
   const service = values.service ? String(values.service) : void 0;
   const projects = (values.project ?? []).map(String);
   switch (command) {
+    // FIRST, and before anything writes to stdout: in this mode stdout is the
+    // protocol, and one stray line of output is a message Claude rejects.
+    case "mcp":
+      return runMcp({ ...service ? { service } : {}, version: AGENT_VERSION });
     case "connect": {
       const result = await connect({
         open: !values["no-open"],

package/dist/engine.js

@@ -9,7 +9,7 @@ import {
   resolveCheckouts,
   start,
   status
-} from "./chunk-PETFNOJA.js";
+} from "./chunk-3SU3RBVY.js";
 export {
   AGENT_VERSION,
   browsersReady,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowriki/agent",
-  "version": "0.1.0-beta.28",
+  "version": "0.1.0-beta.29",
   "description": "Run Flowriki UI tests on your own computer. Connects this machine to your Flowriki account.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",