@bugmole/cli 0.4.0

package/src/registry-worker/mcp/tools.ts

@@ -0,0 +1,563 @@
+// Tools the hosted MCP endpoint offers. Each one calls the registry's own
+// routes as the signed-in person, so roles, plan limits and audit logging
+// apply exactly as they do in the dashboard.
+import YAML from "yaml";
+import { countFlowSteps, describeStepLabel, parseMaestroStyleFlow, type FlowStep } from "../../runtime/flow-language.js";
+
+/** Calls a registry route as the signed-in person. */
+export type RegistryCall = (
+  method: string,
+  path: string,
+  body?: unknown,
+  init?: { contentType?: string; raw?: boolean },
+) => Promise<{ status: number; json: any; text: string }>;
+
+export type ToolContext = {
+  call: RegistryCall;
+  dashboardUrl: string;
+};
+
+export type ToolResult = {
+  content: Array<{ type: "text"; text: string }>;
+  structuredContent?: Record<string, unknown>;
+  isError?: boolean;
+};
+
+type ToolDefinition = {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  annotations: { readOnlyHint: boolean; destructiveHint?: boolean; idempotentHint?: boolean; openWorldHint?: boolean };
+  run: (args: Record<string, unknown>, context: ToolContext) => Promise<ToolResult>;
+};
+
+export const FLOW_REFERENCE = `A flow is YAML: a header, a line with ---, then a list of steps.
+
+url: https://shop.example.com/login
+---
+- launchApp
+- tapOn: "Email"
+- inputText: "{{secret.SHOP_EMAIL}}"
+- tapOn: "Password"
+- inputText: "{{secret.SHOP_PASSWORD}}"
+- tapOn: "Sign in"
+- assertVisible: "Your orders"
+
+Steps:
+- launchApp (opens the header url), openLink: <url>, stopApp
+- tapOn: "<visible text>" (or { text, index, optional: true })
+- inputText: "<text>", eraseText, pressKey: Enter
+- assertVisible / assertNotVisible / assertClickable: "<text>" (".*" makes it a pattern)
+- scrollUntilVisible: "<text>", wait: <ms>, takeScreenshot: <name>
+- retry: { maxRetries: 2, commands: [ ...steps ] }
+- requestTempEmail: <name>, then use "{{name}}" in later steps; openEmailLink: <name>
+
+Describe what a person sees and does, never CSS selectors. Passwords go in
+{{secret.NAME}}, which a worker fills from BUGMOLE_FLOW_SECRET_NAME; never
+put a real password in a flow. The url's origin is replaced by the chosen
+environment's base URL when a run names an environment.`;
+
+const PLAN_ID = /^[a-z0-9][a-z0-9._-]{0,79}$/;
+
+function text(value: unknown): ToolResult {
+  const structured = value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : { result: value };
+  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], structuredContent: structured };
+}
+
+export function toolError(message: string): ToolResult {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+function problem(result: { status: number; json: any; text: string }, fallback: string): ToolResult {
+  const message = typeof result.json?.error === "string" ? result.json.error : fallback;
+  const code = typeof result.json?.code === "string" ? ` (${result.json.code})` : "";
+  if (result.status === 402) return toolError(`${message}${code}. Upgrade or raise the spending limit in Billing, or run on your own workers.`);
+  return toolError(`${message}${code}`);
+}
+
+function stringArg(args: Record<string, unknown>, name: string, required = true): string {
+  const value = args[name];
+  if (typeof value === "string" && value.trim()) return value.trim();
+  if (required) throw new ToolInputError(`${name} is required`);
+  return "";
+}
+
+export class ToolInputError extends Error {}
+
+const enc = encodeURIComponent;
+
+function runLink(context: ToolContext, projectId: string, runId: string): string {
+  return `${context.dashboardUrl}/runs?${new URLSearchParams({ project: projectId, run: runId })}`;
+}
+
+function planLink(context: ToolContext, projectId: string): string {
+  return `${context.dashboardUrl}/plans?${new URLSearchParams({ project: projectId })}`;
+}
+
+function flowKey(projectId: string, planId: string): string {
+  return `projects/${enc(projectId)}/spec/flows/${planId}.yaml`;
+}
+
+function planKey(projectId: string, planId: string): string {
+  return `projects/${enc(projectId)}/plans/${planId}.flow.yaml`;
+}
+
+/** The plan document the runner reads, pointing at the flow stored under spec/. */
+export function planDocument(input: { planId: string; name: string; journeyId: string; actor: string; steps: FlowStep[] }) {
+  return {
+    version: 2,
+    id: input.planId,
+    name: input.name,
+    description: `Written with an AI assistant through Bugmole MCP`,
+    suites: [
+      {
+        id: "default",
+        runs: "on_demand",
+        journeys: [
+          {
+            id: input.journeyId,
+            name: input.name,
+            actor: input.actor,
+            driver: "playwright",
+            platform: "web",
+            flow: `flows/${input.planId}.yaml`,
+            goal: input.name,
+            capabilities_required: [],
+            preconditions: [],
+            steps: input.steps.map((step, index) => ({ node_id: `step-${index + 1}`, action: describeStepLabel(step) })),
+          },
+        ],
+      },
+    ],
+  };
+}
+
+type RunRow = Record<string, any>;
+
+function runSummary(context: ToolContext, run: RunRow) {
+  const targets = Array.isArray(run.targetResults) ? run.targetResults : [];
+  return {
+    id: run.id,
+    planId: run.planId,
+    status: run.status,
+    where: run.executionMode === "cloud" ? "Bugmole Cloud" : "your workers",
+    environmentBaseUrl: run.environmentBaseUrl ?? undefined,
+    steps: { executed: run.stepsExecuted ?? 0, passed: run.stepsPassed ?? 0, failed: run.stepsFailed ?? 0 },
+    currentStep: run.currentStep ?? undefined,
+    error: run.errorMessage ?? undefined,
+    errorCode: run.errorCode ?? run.failureCode ?? undefined,
+    blockedReason: run.blockedReason ?? undefined,
+    durationMs: run.durationMs ?? undefined,
+    requestedAt: run.requestedAt,
+    completedAt: run.completedAt ?? undefined,
+    targets: targets.map((target: Record<string, any>) => {
+      const failed = Array.isArray(target.steps) ? target.steps.find((step: Record<string, any>) => step.status !== "passed") : undefined;
+      return {
+        id: target.targetId,
+        browser: target.device ? `${target.browser} (${target.device})` : target.browser,
+        status: target.status,
+        steps: { passed: target.stepsPassed ?? 0, failed: target.stepsFailed ?? 0 },
+        message: target.message ?? undefined,
+        failureCode: target.failureCode ?? undefined,
+        failedStep: failed ? { number: failed.index + 1, label: failed.label, message: failed.message } : undefined,
+        // Bugmole's own diagnosis: whether the test, the app or the environment is at fault, and a fix.
+        diagnosis: target.analysis
+          ? { title: target.analysis.title, cause: target.analysis.category, fix: target.analysis.fixSummary }
+          : undefined,
+      };
+    }),
+    link: runLink(context, run.projectId, run.id),
+  };
+}
+
+async function projectDefaults(context: ToolContext, projectId: string) {
+  const result = await context.call("GET", "/api/projects");
+  if (result.status !== 200) return null;
+  return (result.json.projects as Array<Record<string, any>>).find((project) => project.id === projectId) ?? null;
+}
+
+export const TOOLS: ToolDefinition[] = [
+  {
+    name: "list_projects",
+    title: "List projects",
+    description: "Lists the Bugmole projects you can use, with their environments (the base URLs tests run against) and where runs go by default. Start here to find a projectId.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    async run(_args, context) {
+      const result = await context.call("GET", "/api/projects");
+      if (result.status !== 200) return problem(result, "Could not list projects");
+      const projects = (result.json.projects as Array<Record<string, any>>).map((project) => ({
+        id: project.id,
+        name: project.name,
+        workspace: project.workspaceName,
+        storage: project.storageMode === "managed" ? "Bugmole" : "your own",
+        runsGoTo: project.defaultExecutionMode === "cloud" ? "Bugmole Cloud" : "your workers",
+        readOnly: Boolean(project.lockedAt),
+        environments: (project.environments ?? []).map((environment: Record<string, any>) => ({
+          id: environment.id,
+          name: environment.name,
+          baseUrl: environment.baseUrl,
+          default: environment.isDefault,
+        })),
+      }));
+      return text({ projects });
+    },
+  },
+  {
+    name: "list_test_plans",
+    title: "List test plans",
+    description: "Lists a project's test plans. Each plan runs one flow.",
+    inputSchema: {
+      type: "object",
+      properties: { projectId: { type: "string" } },
+      required: ["projectId"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    async run(args, context) {
+      const projectId = stringArg(args, "projectId");
+      const result = await context.call("GET", `/api/projects/${enc(projectId)}/plans`);
+      if (result.status !== 200) return problem(result, "Could not list plans");
+      const plans = (result.json.plans as Array<Record<string, any>>).map((plan) => ({
+        planId: plan.planId,
+        journeyId: plan.journeyId,
+        status: plan.status,
+        updatedAt: plan.updatedAt,
+      }));
+      return text({ plans, link: planLink(context, projectId) });
+    },
+  },
+  {
+    name: "get_test_plan",
+    title: "Read a test plan",
+    description: "Reads a test plan and the flow it runs, so you can review or change it.",
+    inputSchema: {
+      type: "object",
+      properties: { projectId: { type: "string" }, planId: { type: "string" } },
+      required: ["projectId", "planId"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    async run(args, context) {
+      const projectId = stringArg(args, "projectId");
+      const planId = stringArg(args, "planId");
+      const list = await context.call("GET", `/api/projects/${enc(projectId)}/plans`);
+      if (list.status !== 200) return problem(list, "Could not read plans");
+      const draft = (list.json.plans as Array<Record<string, any>>).find((plan) => plan.planId === planId);
+      if (!draft) return toolError(`No plan "${planId}" in this project. Use list_test_plans to see the plans.`);
+      const planFile = await context.call("GET", `/api/projects/${enc(projectId)}/artifacts/object?key=${enc(draft.objectKey)}`, undefined, { raw: true });
+      if (planFile.status === 503) return toolError("This project keeps its plans in its own storage, which Bugmole can't read. Open the plan in your repository instead.");
+      if (planFile.status !== 200) return problem(planFile, "Could not read the plan file");
+      let plan: any;
+      try {
+        plan = YAML.parse(planFile.text);
+      } catch {
+        return toolError("The plan file isn't valid YAML.");
+      }
+      const journey = (plan?.suites ?? []).flatMap((suite: any) => suite?.journeys ?? [])
+        .find((item: any) => item?.id === draft.journeyId) ?? plan?.suites?.[0]?.journeys?.[0];
+      const flowFile: unknown = journey?.flow ?? plan?.flow;
+      let flow: string | undefined;
+      if (typeof flowFile === "string" && !flowFile.split("/").includes("..")) {
+        const key = `projects/${enc(projectId)}/spec/${flowFile.replace(/^\/+/, "")}`;
+        const stored = await context.call("GET", `/api/projects/${enc(projectId)}/artifacts/object?key=${enc(key)}`, undefined, { raw: true });
+        if (stored.status === 200) flow = stored.text;
+      }
+      return text({
+        planId,
+        journeyId: draft.journeyId,
+        name: journey?.name ?? plan?.name,
+        platform: journey?.platform ?? plan?.platform,
+        flowFile: typeof flowFile === "string" ? flowFile : undefined,
+        flow: flow ?? null,
+        ...(flow ? {} : { note: "The flow file isn't in Bugmole storage; it lives with the project's own files." }),
+      });
+    },
+  },
+  {
+    name: "save_test_plan",
+    title: "Save a test plan",
+    description: `Checks a flow and saves it as a test plan (creating or replacing it), ready to run. Only for projects whose files are stored by Bugmole.\n\n${FLOW_REFERENCE}`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectId: { type: "string" },
+        planId: { type: "string", description: "Lowercase id, e.g. checkout-guest. Saving the same id replaces the plan." },
+        name: { type: "string", description: "What the flow proves, e.g. \"Guest can check out\"" },
+        flow: { type: "string", description: "The flow YAML" },
+        actor: { type: "string", description: "Who does this, e.g. guest, admin (default: user)" },
+      },
+      required: ["projectId", "planId", "name", "flow"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    async run(args, context) {
+      const projectId = stringArg(args, "projectId");
+      const planId = stringArg(args, "planId").toLowerCase();
+      const name = stringArg(args, "name").slice(0, 120);
+      // Stored as written; only the check trims.
+      const flow = typeof args.flow === "string" && args.flow.trim() ? args.flow : stringArg(args, "flow");
+      const actor = (stringArg(args, "actor", false) || "user").slice(0, 40);
+      if (!PLAN_ID.test(planId)) return toolError("planId must be lowercase letters, digits, dots, dashes or underscores (up to 80).");
+      if (flow.length > 100_000) return toolError("The flow is too long (100 KB at most).");
+      const project = await projectDefaults(context, projectId);
+      if (!project) return toolError(`No project "${projectId}" that you can use. Use list_projects.`);
+      if (project.storageMode !== "managed") {
+        return toolError("This project keeps its files in its own storage. Save the flow in the repository and publish it with `bugmole plan`, or use a project stored by Bugmole.");
+      }
+      const fallback = (project.environments ?? []).find((environment: Record<string, any>) => environment.isDefault)?.baseUrl;
+      let steps: FlowStep[];
+      try {
+        steps = parseMaestroStyleFlow(flow, fallback || undefined).steps;
+      } catch (error) {
+        return toolError(`The flow isn't valid: ${error instanceof Error ? error.message : String(error)}\n\n${FLOW_REFERENCE}`);
+      }
+      if (steps.length === 0) return toolError("The flow has no steps.");
+      const document = planDocument({ planId, name, journeyId: planId, actor, steps });
+      const putFlow = await context.call("PUT", `/api/projects/${enc(projectId)}/artifacts/object?key=${enc(flowKey(projectId, planId))}`, flow, { contentType: "text/yaml" });
+      if (putFlow.status !== 201) return problem(putFlow, "Could not save the flow");
+      const putPlan = await context.call("PUT", `/api/projects/${enc(projectId)}/artifacts/object?key=${enc(planKey(projectId, planId))}`, YAML.stringify(document), { contentType: "text/yaml" });
+      if (putPlan.status !== 201) return problem(putPlan, "Could not save the plan");
+      const published = await context.call("POST", `/api/projects/${enc(projectId)}/plans`, {
+        planId,
+        journeyId: planId,
+        objectKey: planKey(projectId, planId),
+      });
+      if (published.status !== 201) return problem(published, "Could not publish the plan");
+      return text({ planId, name, steps: countFlowSteps(steps), status: "saved", next: "run_tests", link: planLink(context, projectId) });
+    },
+  },
+  {
+    name: "run_tests",
+    title: "Run a test plan",
+    description: "Starts a run of a test plan. It runs on Bugmole Cloud (uses the workspace's cloud minutes) or on the project's own workers. Returns a run id; check it with get_run.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectId: { type: "string" },
+        planId: { type: "string" },
+        environmentId: { type: "string", description: "Which environment's base URL to test (default: the project's default environment)" },
+        where: { type: "string", enum: ["cloud", "my-workers"], description: "Default: the project's setting" },
+        browsers: {
+          type: "array",
+          items: { type: "string", enum: ["chromium", "firefox", "webkit", "msedge"] },
+          description: "Browsers to run in, in parallel (default: chromium)",
+        },
+      },
+      required: ["projectId", "planId"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    async run(args, context) {
+      const projectId = stringArg(args, "projectId");
+      const planId = stringArg(args, "planId");
+      const project = await projectDefaults(context, projectId);
+      if (!project) return toolError(`No project "${projectId}" that you can use. Use list_projects.`);
+      const where = args.where === "cloud" || args.where === "my-workers" ? args.where : undefined;
+      const executionMode = where ? (where === "cloud" ? "cloud" : "self") : (project.defaultExecutionMode === "cloud" ? "cloud" : "self");
+      let environmentId = stringArg(args, "environmentId", false);
+      if (!environmentId) environmentId = (project.environments ?? []).find((environment: Record<string, any>) => environment.isDefault)?.id ?? "";
+      const browsers = Array.isArray(args.browsers) ? args.browsers.filter((value): value is string => typeof value === "string") : [];
+      const created = await context.call("POST", `/api/projects/${enc(projectId)}/runs`, {
+        planId,
+        idempotencyKey: `mcp:${crypto.randomUUID()}`,
+        executionMode,
+        ...(environmentId ? { environmentId } : {}),
+        ...(browsers.length ? { targets: browsers.map((browser) => ({ browser })) } : {}),
+      });
+      if (created.status !== 201 && created.status !== 200) return problem(created, "Could not start the run");
+      const run = created.json.run;
+      return text({
+        runId: run.id,
+        status: run.status,
+        where: executionMode === "cloud" ? "Bugmole Cloud" : "your workers",
+        ...(executionMode === "self" ? { note: "A worker you run (`bugmole serve`) picks this up. It stays queued until one is online." } : {}),
+        next: "get_run",
+        link: runLink(context, projectId, run.id),
+      });
+    },
+  },
+  {
+    name: "get_run",
+    title: "Check a run",
+    description: "Shows a run's status, which steps passed or failed, errors, and the AI's explanation of a failure when there is one. Runs usually take a minute or two; check again while status is queued or running.",
+    inputSchema: {
+      type: "object",
+      properties: { runId: { type: "string" } },
+      required: ["runId"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    async run(args, context) {
+      const runId = stringArg(args, "runId");
+      const result = await context.call("GET", `/api/runs/${enc(runId)}`);
+      if (result.status !== 200) return problem(result, "Run not found");
+      const events = (result.json.events as Array<Record<string, any>>).slice(-15).map((event) => ({
+        type: event.type,
+        at: event.createdAt,
+        ...(event.payload?.currentStep ? { step: event.payload.currentStep } : {}),
+        ...(event.payload?.status ? { status: event.payload.status } : {}),
+        ...(event.payload?.message ? { message: event.payload.message } : {}),
+      }));
+      return text({ ...runSummary(context, result.json.run), recentEvents: events });
+    },
+  },
+  {
+    name: "list_runs",
+    title: "List recent runs",
+    description: "Lists a project's recent runs, newest first, optionally for one plan.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectId: { type: "string" },
+        planId: { type: "string" },
+        limit: { type: "number", minimum: 1, maximum: 50 },
+      },
+      required: ["projectId"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    async run(args, context) {
+      const projectId = stringArg(args, "projectId");
+      const planId = stringArg(args, "planId", false);
+      const limit = Math.min(50, Math.max(1, Number(args.limit) || 10));
+      const result = await context.call("GET", `/api/projects/${enc(projectId)}/runs`);
+      if (result.status !== 200) return problem(result, "Could not list runs");
+      const runs = (result.json.runs as RunRow[])
+        .filter((run) => !planId || run.planId === planId)
+        .slice(0, limit)
+        .map((run) => {
+          const { targets: _targets, ...summary } = runSummary(context, run);
+          return summary;
+        });
+      return text({ runs });
+    },
+  },
+  {
+    name: "explore_app",
+    title: "Explore an app",
+    description: "Asks Bugmole to explore a web app like a new user: it opens the URL, follows links and fills in forms, and saves a test plan for each flow it can write. Runs on Bugmole Cloud (uses cloud minutes) or the project's own workers. Check progress with get_exploration, then review the new plans with list_test_plans and get_test_plan.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectId: { type: "string" },
+        url: { type: "string", description: "Where to start, e.g. https://staging.shop.example.com" },
+        goal: { type: "string", description: "What to focus on, e.g. \"checkout as a guest\"" },
+        where: { type: "string", enum: ["cloud", "my-workers"], description: "Default: the project's setting" },
+      },
+      required: ["projectId", "url"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    async run(args, context) {
+      const projectId = stringArg(args, "projectId");
+      const url = stringArg(args, "url");
+      const goal = stringArg(args, "goal", false).slice(0, 500);
+      let parsed: URL;
+      try {
+        parsed = new URL(url);
+      } catch {
+        return toolError("url must be a full http(s) address.");
+      }
+      if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return toolError("url must be a full http(s) address.");
+      const project = await projectDefaults(context, projectId);
+      if (!project) return toolError(`No project "${projectId}" that you can use. Use list_projects.`);
+      const where = args.where === "cloud" || args.where === "my-workers" ? args.where : undefined;
+      const executionMode = where ? (where === "cloud" ? "cloud" : "self") : (project.defaultExecutionMode === "cloud" ? "cloud" : "self");
+      const created = await context.call("POST", `/api/projects/${enc(projectId)}/tasks`, {
+        title: `Explore ${parsed.host}${goal ? `: ${goal}` : ""}`.slice(0, 200),
+        description: `${goal ? `${goal}\n\n` : ""}${parsed.toString()}`,
+        taskType: "discovery",
+        idempotencyKey: `mcp:${crypto.randomUUID()}`,
+        executionMode,
+      });
+      if (created.status !== 201 && created.status !== 200) return problem(created, "Could not start exploring");
+      return text({
+        taskId: created.json.task.id,
+        status: created.json.task.status,
+        where: executionMode === "cloud" ? "Bugmole Cloud" : "your workers",
+        next: "get_exploration",
+      });
+    },
+  },
+  {
+    name: "get_exploration",
+    title: "Check an exploration",
+    description: "Shows how an exploration started with explore_app is going, and its summary when done.",
+    inputSchema: {
+      type: "object",
+      properties: { projectId: { type: "string" }, taskId: { type: "string" } },
+      required: ["projectId", "taskId"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    async run(args, context) {
+      const projectId = stringArg(args, "projectId");
+      const taskId = stringArg(args, "taskId");
+      const result = await context.call("GET", `/api/projects/${enc(projectId)}/tasks`);
+      if (result.status !== 200) return problem(result, "Could not read explorations");
+      const task = (result.json.tasks as Array<Record<string, any>>).find((row) => row.id === taskId);
+      if (!task) return toolError("No such exploration in this project (only the latest 100 are kept here).");
+      return text({
+        taskId: task.id,
+        title: task.title,
+        status: task.status,
+        progress: task.progressMessage ?? undefined,
+        summary: task.completionSummary ?? undefined,
+        error: task.errorMessage ?? undefined,
+        startedAt: task.startedAt ?? undefined,
+        completedAt: task.completedAt ?? undefined,
+        // Exploration saves a test plan for each flow it could write.
+        ...(task.status === "completed" ? { next: "list_test_plans" } : {}),
+      });
+    },
+  },
+  {
+    name: "list_journeys",
+    title: "List journeys",
+    description: "Lists the user journeys Bugmole knows for a project (from exploration or saved by people), with whether each has been verified by a passing run.",
+    inputSchema: {
+      type: "object",
+      properties: { projectId: { type: "string" } },
+      required: ["projectId"],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    async run(args, context) {
+      const projectId = stringArg(args, "projectId");
+      const result = await context.call("GET", `/api/projects/${enc(projectId)}/journeys`);
+      if (result.status !== 200) return problem(result, "Could not list journeys");
+      const latest = new Map<string, Record<string, any>>();
+      for (const revision of result.json.revisions as Array<Record<string, any>>) {
+        if (!latest.has(revision.journeyId)) latest.set(revision.journeyId, revision);
+      }
+      const journeys = [...latest.values()].map((revision) => ({
+        journeyId: revision.journeyId,
+        revision: revision.revision,
+        status: revision.status,
+        stability: revision.stability ?? undefined,
+        verifiedBy: revision.verificationRunId ?? undefined,
+        updatedAt: revision.createdAt,
+      }));
+      return text({ journeys });
+    },
+  },
+];
+
+export function toolList() {
+  return TOOLS.map(({ run: _run, ...definition }) => definition);
+}
+
+export async function callTool(name: string, args: unknown, context: ToolContext): Promise<ToolResult> {
+  const tool = TOOLS.find((candidate) => candidate.name === name);
+  if (!tool) return toolError(`Unknown tool: ${name}`);
+  const input = args && typeof args === "object" && !Array.isArray(args) ? (args as Record<string, unknown>) : {};
+  try {
+    return await tool.run(input, context);
+  } catch (error) {
+    if (error instanceof ToolInputError) return toolError(error.message);
+    console.error("[mcp] tool failed", name, error);
+    return toolError("Something went wrong on Bugmole's side. Try again in a moment.");
+  }
+}