@flowriki/agent 0.1.0-beta.3 → 0.1.0-beta.31

package/dist/cli.js

@@ -1,16 +1,795 @@
 #!/usr/bin/env node
 import {
   AGENT_VERSION,
+  RecordedStepSchema,
+  authenticationResolver,
+  checkAssertion,
+  closeRunSession,
   connect,
+  connectionFor,
   disconnect,
   doctor,
+  executeStep,
+  helperRunner,
+  openRunSession,
+  prepareBrowsers,
+  replayFlow,
   resolveCheckouts,
+  resolveService,
+  runtimeValue,
   start,
   status
-} from "./chunk-XT52RW5S.js";
+} from "./chunk-XSH3IU5Y.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");
+  }
+  createProject(name, repository, baseUrl) {
+    return this.call("/api/agent/projects", {
+      method: "POST",
+      body: JSON.stringify({ name, repository, ...baseUrl ? { baseUrl } : {} })
+    });
+  }
+  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) } } : {}
+    });
+    const filled = (text2) => text2.replace(/\{\{([a-zA-Z][a-zA-Z0-9_]*)\}\}/g, (_, name) => runtimeValue(this.values, name));
+    const expected = Array.isArray(assertion.value) ? assertion.value.map(filled) : filled(assertion.value);
+    try {
+      await checkAssertion(page, assertion.kind, expected, 5e3, { ...assertion, value: expected });
+    } 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.
+
+A new project \u2014 "set up Flowriki for this site, in this repository" \u2014 is made
+with create_project; it then becomes the project the other tools work on.
+
+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. For anything that must be NEW on every run \u2014 a sign-up's email or
+username \u2014 use {{unique}}: it is different on every run and the same within
+one, e.g. qa+{{unique}}@ the domain of the project's mailbox helper, so the
+helper can read that address's verification email with {"email": "qa+{{unique}}@\u2026"}.
+A test that types a fixed new email passes once and fails every run after.`;
+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: "create_project",
+      title: "Create a Flowriki project",
+      description: "Create a new Flowriki project, connected to a git repository where its tests will be stored, and pointed at the app to test. The repository must already exist and must not hold another Flowriki project. You become its owner.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: `The project's name, e.g. "Pizza Romano".` },
+          repository: { type: "string", description: "owner/name, or the repository's address, e.g. https://github.com/acme/shop-tests.git" },
+          baseUrl: { type: "string", description: "The app's address, e.g. https://shop.example.com/" }
+        },
+        required: ["name", "repository"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const made = await service.createProject(str(args["name"]) ?? "", str(args["repository"]) ?? "", str(args["baseUrl"]));
+        defaultProject = made.id;
+        catalogs.delete(made.id);
+        return text(`Created "${made.name}" (id ${made.id}), stored in ${made.repository}${made.baseUrl ? `, testing ${made.baseUrl}` : " \u2014 no base URL yet; set one in its settings"}.${made.note ? `
+Note: ${made.note}` : ""}
+It is now the project these tools work on. Open it: ${service.origin}/projects/${made.id}`);
+      }
+    },
+    {
+      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");
@@ -27,7 +806,11 @@ ${bold("USAGE")}
   flowriki-agent start              run the agent (stays in the foreground)
   flowriki-agent status             is it connected, and what is prepared
   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.
@@ -35,6 +818,7 @@ ${bold("OPTIONS")}
   --name <label>         how this computer appears in your dashboard
   --service <url>        advanced: a self-hosted Flowriki. Defaults to the
                          hosted service, which is what you want.
+  --no-open              print the approval link without opening a browser
   --json                 machine-readable output for status and doctor
   -h, --help             this
   -v, --version          version
@@ -54,6 +838,7 @@ async function main(argv) {
         name: { type: "string" },
         service: { type: "string" },
         json: { type: "boolean" },
+        "no-open": { type: "boolean" },
         help: { type: "boolean", short: "h" },
         version: { type: "boolean", short: "v" }
       }
@@ -77,8 +862,13 @@ 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"],
         ...service ? { service } : {},
         ...values.name ? { machineName: String(values.name) } : {},
         onProgress: (note) => {
@@ -89,7 +879,7 @@ Run \`flowriki-agent --help\`.`);
           console.log(`  ${url}
 `);
           if (note.detail?.["canOpen"] === false) {
-            console.log(dim("  No graphical session here \u2014 open that link on a computer that has one.\n"));
+            console.log(dim("  Open the approval link in your browser.\n"));
           } else {
             console.log(dim("  Opening it for you. If nothing happens, use the link above.\n"));
           }
@@ -106,6 +896,11 @@ Run \`flowriki-agent --help\`.`);
       return 0;
     }
     case "start": {
+      process.on("unhandledRejection", (reason) => {
+        const said = reason instanceof Error ? reason.stack ?? reason.message : String(reason);
+        console.error(red(`! a command failed without being handled \u2014 the agent is still running`));
+        console.error(dim(said.split("\n").slice(0, 4).join("\n")));
+      });
       const started = await start({
         ...service ? { service } : {},
         ...projects.length ? { projects } : {},
@@ -129,8 +924,7 @@ Run \`flowriki-agent --help\`.`);
       console.log(`${bold("Flowriki agent")} ${dim(AGENT_VERSION)}`);
       console.log(dim(`  connected as ${started.connection.machineName}`));
       if (started.projects.length === 0) {
-        console.log(yellow("  no projects prepared \u2014 this machine is online and idle"));
-        console.log(dim("  Add one:  flowriki-agent start --project /path/to/a/checkout"));
+        console.log(dim("  ready \u2014 this machine records and runs whatever the dashboard asks for"));
       }
       for (const project of started.projects) {
         console.log(dim(`  project  ${project.name}  (${project.root})`));
@@ -150,6 +944,11 @@ Run \`flowriki-agent --help\`.`);
       return await new Promise(() => {
       });
     }
+    case "prepare": {
+      const result = await prepareBrowsers();
+      console.log(result.ok ? green(result.message) : red(result.message));
+      return result.ok ? 0 : 1;
+    }
     case "status": {
       const state = status(service);
       if (values.json) {
@@ -182,7 +981,11 @@ Run \`flowriki-agent --help\`.`);
       console.log(`  node       ${found.node}  ${dim(`${found.platform}/${found.arch}`)}`);
       console.log(`  protocol   ${found.protocolVersion}`);
       console.log(`  data       ${found.dataDir}`);
-      console.log(`  service    ${found.service}  ${found.reachable ? green("reachable") : red("unreachable")}`);
+      console.log(
+        `  service    ${found.service}  ${found.reachable ? green("reachable") : red("unreachable")}` + // WHICH FLOWRIKI, from the service's own mouth. Not the site being
+        // tested — that is a project setting and changes nothing here.
+        (found.environment ? dim(`  [${found.environment}]`) : "")
+      );
       console.log(`  credential ${found.credentialFingerprint ?? dim("none stored")}`);
       console.log(
         `  browsers   ${found.playwright.chromiumInstalled ? green("chromium ready") : yellow("chromium not installed")}  ${dim(found.playwright.browsersPath ?? "")}`