@mandujs/mcp 0.28.2 → 0.30.0

package/src/tools/ate.ts

@@ -1,4 +1,5 @@
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
   ateExtract,
   ateGenerate,
@@ -13,7 +14,13 @@ import {
   detectCoverageGaps,
   precommitCheck,
 } from "@mandujs/ate";
-import type { OracleLevel } from "@mandujs/ate";
+import type { OracleLevel, AteMonitorEvent, FailureV1 } from "@mandujs/ate";
+import { eventBus } from "@mandujs/core/observability";
+import {
+  writePartialResults,
+  createAteProgressTracker,
+  type PartialRunResults,
+} from "./ate-run.js";
 
 export const ateToolDefinitions: Tool[] = [
   {
@@ -83,7 +90,13 @@ export const ateToolDefinitions: Tool[] = [
       "ATE Step 3 — Run: Execute the generated Playwright specs against a running Mandu dev server. " +
       "Collects test artifacts (screenshots, traces, results) in .mandu/ate/runs/{runId}/. " +
       "Requires the Mandu dev server to be running (use mandu_dev_start first). " +
-      "Returns a runId for use with mandu.ate.report and mandu.ate.heal.",
+      "Returns a runId for use with mandu.ate.report and mandu.ate.heal. " +
+      "Streams notifications/progress per spec_done event (issue #238). " +
+      "On timeout / kill, persists partial state under .mandu/reports/run-<runId>/results.json " +
+      "so mandu.ate.heal remains reachable after the 10-min watchdog. " +
+      "Issue #237 — scope filters (onlyFiles / onlyRoutes / grep) let callers " +
+      "run a single spec or route and stay under the 10-min MCP watchdog; omit " +
+      "them for the full suite.",
     inputSchema: {
       type: "object",
       properties: {
@@ -99,6 +112,32 @@ export const ateToolDefinitions: Tool[] = [
           items: { type: "string", enum: ["chromium", "firefox", "webkit"] },
           description: "Browsers to test against (default: ['chromium'])",
         },
+        onlyFiles: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Issue #237 — explicit spec file paths (absolute or relative to repoRoot). " +
+            "Forwarded to Playwright as positional <file> args.",
+        },
+        onlyRoutes: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Issue #237 — route ids (e.g. 'api-signup'). Resolved to spec paths via " +
+            "the spec-indexer. Unknown ids emit a warning; the remaining ids run.",
+        },
+        grep: {
+          type: "string",
+          description:
+            "Issue #237 — pass-through to Playwright --grep. Applied on top of the " +
+            "onlyFiles ∪ resolved(onlyRoutes) set.",
+        },
+        progressToken: {
+          type: ["string", "number"],
+          description:
+            "Optional MCP progress token. When present, per-spec progress notifications are " +
+            "sent with this token so the client can correlate them with the originating call.",
+        },
       },
       required: ["repoRoot"],
     },
@@ -154,6 +193,10 @@ export const ateToolDefinitions: Tool[] = [
       "ATE Step 5 — Heal: Analyze test failures from a run and generate safe diff suggestions for fixing the code. " +
       "Classifies failures by root cause (schema mismatch, missing handler, wrong status, selector stale, etc.) " +
       "and produces reviewable diffs — never auto-commits or overwrites files. " +
+      "Requires a runId produced by mandu.ate.run (or the partial-results stub written " +
+      "on timeout under .mandu/reports/run-<runId>/results.json). " +
+      "See mandu.brain.status for LLM availability — template-based heals always run; " +
+      "LLM-assisted analysis activates when active_tier is openai or anthropic. " +
       "Use mandu.ate.apply_heal to apply a specific suggestion after review. " +
       "Supports rollback via mandu_rollback if applied changes cause regressions.",
     inputSchema: {
@@ -288,7 +331,87 @@ export const ateToolDefinitions: Tool[] = [
   },
 ];
 
-export function ateTools(projectRoot: string) {
+export function ateTools(projectRoot: string, server?: Server) {
+  /**
+   * Shared subscription helper for `mandu.ate.run`. Wraps ateRun (which
+   * drives Playwright) with eventBus listeners so per-spec progress
+   * notifications flow through the MCP transport and a partial
+   * results.json is persisted on timeout / kill. Downstream consumers
+   * can then hand the runId to `mandu.ate.heal` even when the 10-min
+   * watchdog fired mid-run.
+   */
+  const runWithObservability = async (
+    input: Parameters<typeof ateRun>[0],
+    opts: { progressToken?: string | number } = {},
+  ) => {
+    const started = new Date().toISOString();
+
+    const tracker = createAteProgressTracker({
+      progressToken: opts.progressToken,
+      sendProgress: async (progress, total, message) => {
+        if (!server) return;
+        const snap = tracker.snapshot();
+        const token = opts.progressToken ?? snap.runId;
+        if (!token) return;
+        try {
+          await server.notification({
+            method: "notifications/progress",
+            params: { progressToken: token, progress, total, message },
+          });
+        } catch {
+          /* transport offline — never fail the run */
+        }
+      },
+    });
+
+    const unsubscribe = eventBus.on("ate", (event) => {
+      try {
+        const data = event.data as unknown as AteMonitorEvent | undefined;
+        if (!data || typeof data.kind !== "string") return;
+        tracker.handle(data);
+      } catch {
+        /* swallow — never break the run */
+      }
+    });
+
+    try {
+      return await ateRun(input);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const isTimeout = /timed out/i.test(message);
+      const snap = tracker.snapshot();
+      const partial: PartialRunResults = {
+        runId: snap.runId ?? `unknown-${Date.now()}`,
+        status: isTimeout ? "timed_out" : "error",
+        graphVersion: snap.graphVersion,
+        completedSpecs: snap.completedSpecs,
+        inProgressSpec: snap.inProgressSpec,
+        failures: snap.failures,
+        startedAt: started,
+        killedAt: new Date().toISOString(),
+        error: message,
+      };
+      const resultsPath = writePartialResults(input.repoRoot, partial);
+      return {
+        ok: false,
+        error: `ateRun failed: ${message}`,
+        partial,
+        resultsPath,
+        runId: partial.runId,
+      };
+    } finally {
+      try {
+        unsubscribe();
+      } catch {
+        /* no-op */
+      }
+    }
+  };
+  // Reserved for future use (progress capability detection). Not used
+  // during registration today but documented on the closure so the
+  // next caller understands the parameter shape.
+  void projectRoot;
+
   return {
     "mandu.ate.extract": async (args: Record<string, unknown>) => {
       const { repoRoot, tsconfigPath, routeGlobs, buildSalt } = args as {
@@ -308,14 +431,40 @@ export function ateTools(projectRoot: string) {
       return ateGenerate({ repoRoot, oracleLevel, onlyRoutes });
     },
     "mandu.ate.run": async (args: Record<string, unknown>) => {
-      const { repoRoot, baseURL, ci, headless, browsers } = args as {
+      const {
+        repoRoot,
+        baseURL,
+        ci,
+        headless,
+        browsers,
+        onlyFiles,
+        onlyRoutes,
+        grep,
+        progressToken,
+      } = args as {
         repoRoot: string;
         baseURL?: string;
         ci?: boolean;
         headless?: boolean;
         browsers?: ("chromium" | "firefox" | "webkit")[];
+        onlyFiles?: string[];
+        onlyRoutes?: string[];
+        grep?: string;
+        progressToken?: string | number;
       };
-      return await ateRun({ repoRoot, baseURL, ci, headless, browsers });
+      return await runWithObservability(
+        {
+          repoRoot,
+          baseURL,
+          ci,
+          headless,
+          browsers,
+          onlyFiles,
+          onlyRoutes,
+          grep,
+        },
+        { progressToken },
+      );
     },
     "mandu.ate.report": async (args: Record<string, unknown>) => {
       const { repoRoot, runId, startedAt, finishedAt, exitCode, oracleLevel, format, impact } = args as {

package/src/tools/brain.ts

@@ -33,7 +33,10 @@ export const brainToolDefinitions: Tool[] = [
   {
     name: "mandu.brain.doctor",
     description:
-      "Analyze Guard failures and suggest patches. Works with or without LLM - template-based analysis is always available.",
+      "Analyze Guard failures and suggest patches. Returns early with no LLM call when " +
+      "guard has no violations (passed: true). When violations are present and an LLM " +
+      "tier is active (see mandu.brain.status), runs LLM-assisted analysis and returns " +
+      "llmAssisted: true. Template-based analysis is always available as a fallback.",
     annotations: {
       readOnlyHint: true,
     },
@@ -212,6 +215,32 @@ export const brainToolDefinitions: Tool[] = [
 /** Module-level unsubscribe handle for MCP warning notifications */
 let mcpWarningUnsubscribe: (() => void) | null = null;
 
+/**
+ * Issue #237 Concern 4 — build a list of next-step suggestions for the
+ * currently resolved brain tier. Exposed for unit tests so the tier →
+ * suggestion mapping is pinned without spinning up a credential store.
+ *
+ * - openai / anthropic tiers → point at the LLM-heal loop + guard doctor.
+ * - ollama / template tiers → point at `mandu brain login` for higher
+ *   quality. Everyone also gets a generic status pointer.
+ */
+export function buildBrainStatusSuggestions(activeTier: string): string[] {
+  const suggestions: string[] = [];
+  if (activeTier === "openai" || activeTier === "anthropic") {
+    suggestions.push(
+      "Run mandu.ate.auto_pipeline or mandu.ate.run followed by mandu.ate.heal to exercise the LLM-healing loop.",
+    );
+    suggestions.push(
+      "Call mandu.brain.doctor after a mandu.guard.check failure to get LLM-assisted diagnosis + patch suggestions.",
+    );
+  } else if (activeTier === "ollama" || activeTier === "template") {
+    suggestions.push(
+      "Run `mandu brain login --provider=openai` (or --provider=anthropic) to unlock higher-quality LLM-assisted heal + doctor output.",
+    );
+  }
+  return suggestions;
+}
+
 /**
  * #236 — surface a clear error when a stale `@mandujs/core` resolves
  * under `node_modules/@mandujs/mcp/node_modules/` (Bun's installer
@@ -669,6 +698,12 @@ export function brainTools(projectRoot: string, server?: Server, monitor?: Activ
           : { logged_in: false };
     }
 
+    // Issue #237 Concern 4 — surface next-step suggestions keyed to the
+    // active tier so agents can find the LLM invocation paths without
+    // grep-archaeology. LLM tiers point at ate.heal / brain.doctor;
+    // offline tiers point at `mandu brain login` for an upgrade.
+    const suggestions = buildBrainStatusSuggestions(resolution.resolved);
+
     return {
       content: [
         {
@@ -679,6 +714,7 @@ export function brainTools(projectRoot: string, server?: Server, monitor?: Activ
               reason: resolution.reason,
               backend: store.backendName,
               providers,
+              suggestions,
             },
             null,
             2,

package/src/tools/index.ts

@@ -160,7 +160,19 @@ interface ToolModule {
     server?: Server,
     monitor?: ActivityMonitor
   ) => Record<string, (args: Record<string, unknown>) => Promise<unknown>>;
+  /**
+   * Hard requirement: skip registration entirely when `server` is
+   * absent. Used for tools that cannot function without MCP transport
+   * access (e.g. brain, project).
+   */
   requiresServer?: boolean;
+  /**
+   * Soft requirement: forward the `Server` instance when one is
+   * available, but register the tool either way. Used for tools that
+   * gracefully degrade (e.g. notifications/progress silently no-ops
+   * when the transport isn't attached).
+   */
+  acceptsServer?: boolean;
 }
 
 /**
@@ -182,10 +194,14 @@ const TOOL_MODULES: ToolModule[] = [
   { category: "runtime", definitions: runtimeToolDefinitions, handlers: runtimeTools },
   { category: "seo", definitions: seoToolDefinitions, handlers: seoTools },
   { category: "project", definitions: projectToolDefinitions, handlers: projectTools as ToolModule["handlers"], requiresServer: true },
-  { category: "ate", definitions: ateToolDefinitions, handlers: ateTools as ToolModule["handlers"] },
+  // ate + ate-run accept an optional Server so notifications/progress
+  // can flow (issue #238). `acceptsServer: true` forwards the server
+  // when available but still registers when it isn't — callers that
+  // boot without an MCP transport get progress no-oped silently.
+  { category: "ate", definitions: ateToolDefinitions, handlers: ateTools as ToolModule["handlers"], acceptsServer: true },
   { category: "ate-phase5", definitions: atePhase5ToolDefinitions, handlers: createAtePhase5Handlers as unknown as ToolModule["handlers"] },
   { category: "ate-context", definitions: ateContextToolDefinitions, handlers: ateContextTools },
-  { category: "ate-run", definitions: ateRunToolDefinitions, handlers: ateRunTools },
+  { category: "ate-run", definitions: ateRunToolDefinitions, handlers: ateRunTools as ToolModule["handlers"], acceptsServer: true },
   { category: "ate-flakes", definitions: ateFlakesToolDefinitions, handlers: ateFlakesTools },
   { category: "ate-prompt", definitions: atePromptToolDefinitions, handlers: atePromptTools },
   { category: "ate-exemplar", definitions: ateExemplarToolDefinitions, handlers: ateExemplarTools },
@@ -290,13 +306,21 @@ export function registerBuiltinTools(
     }
 
     try {
-      const handlers = module.requiresServer
-        ? (module.handlers as (root: string, srv: Server, mon: ActivityMonitor) => Record<string, (args: Record<string, unknown>) => Promise<unknown>>)(
-            projectRoot,
-            server!,
-            monitor!
-          )
-        : module.handlers(projectRoot);
+      let handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>>;
+      if (module.requiresServer) {
+        handlers = (module.handlers as (root: string, srv: Server, mon: ActivityMonitor) => Record<string, (args: Record<string, unknown>) => Promise<unknown>>)(
+          projectRoot,
+          server!,
+          monitor!,
+        );
+      } else if (module.acceptsServer) {
+        // Forward the Server when available; fall back to just projectRoot.
+        handlers = server
+          ? module.handlers(projectRoot, server)
+          : module.handlers(projectRoot);
+      } else {
+        handlers = module.handlers(projectRoot);
+      }
 
       const plugins = moduleToPlugins(module.definitions, handlers);
       mcpToolRegistry.registerAll(plugins, module.category);

package/src/tools/project.ts

@@ -11,9 +11,93 @@ import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import type { ActivityMonitor } from "../activity-monitor.js";
 import { spawn, type Subprocess } from "bun";
 import { execSync } from "child_process";
+import { createConnection } from "node:net";
 import path from "path";
 import fs from "fs/promises";
 
+/**
+ * Issue #237 Concern 3 — read `server.port` from `mandu.config.*` so
+ * `mandu.dev.start` can poll a deterministic port instead of timing
+ * out while scraping stdout. Returns `null` if the config is absent
+ * or doesn't explicitly set `server.port` (callers fall back to 3333,
+ * Mandu's documented default). We use the un-schema'd raw loader
+ * (`loadManduConfig`) so the schema's fill-in default doesn't mask a
+ * missing value — a user who set no port should poll 3333, not the
+ * schema's internal default.
+ *
+ * We intentionally catch every error — a brittle config reader here
+ * must never block dev_start. The polling path still proves liveness.
+ */
+export async function readConfiguredServerPort(
+  cwd: string,
+): Promise<number | null> {
+  try {
+    const core = await import("@mandujs/core");
+    const raw = await core.loadManduConfig(cwd);
+    const port = raw?.server?.port;
+    if (typeof port === "number" && Number.isFinite(port) && port > 0) {
+      return port;
+    }
+  } catch {
+    /* ignore — fall back to default */
+  }
+  return null;
+}
+
+/**
+ * Issue #237 Concern 3 — TCP connect probe. Resolves `true` on the
+ * first successful `connect`, `false` on any error or timeout.
+ * `node:net` is Node builtin and ships with Bun; no new dependency.
+ */
+export function probeTcpPort(
+  port: number,
+  hostname: string,
+  timeoutMs: number,
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    const sock = createConnection({ host: hostname, port });
+    const done = (ok: boolean) => {
+      try {
+        sock.destroy();
+      } catch {
+        /* noop */
+      }
+      resolve(ok);
+    };
+    sock.setTimeout(timeoutMs);
+    sock.once("connect", () => done(true));
+    sock.once("timeout", () => done(false));
+    sock.once("error", () => done(false));
+  });
+}
+
+/**
+ * Issue #237 Concern 3 — poll the configured port at a fixed interval
+ * until `waitMs` elapses. Returns the port on success, `null` on
+ * timeout. The caller chooses whether to fall back to the stdout
+ * scrape or report `port: <polled>` alongside the timeout message.
+ */
+export async function pollServerPort(
+  port: number,
+  hostname: string,
+  waitMs: number,
+  intervalMs = 200,
+): Promise<number | null> {
+  const deadline = Date.now() + waitMs;
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now();
+    const probeTimeout = Math.min(500, Math.max(50, remaining));
+    if (await probeTcpPort(port, hostname, probeTimeout)) {
+      return port;
+    }
+    const sleep = Math.min(intervalMs, Math.max(0, deadline - Date.now()));
+    if (sleep > 0) {
+      await new Promise((r) => setTimeout(r, sleep));
+    }
+  }
+  return null;
+}
+
 type DevServerState = {
   process: Subprocess;
   cwd: string;
@@ -173,7 +257,11 @@ export const projectToolDefinitions: Tool[] = [
   },
   {
     name: "mandu.dev.start",
-    description: "Start Mandu dev server (bun run dev).",
+    description:
+      "Start Mandu dev server (bun run dev). Issue #237 — polls server.port from " +
+      "mandu.config.ts (fallback 3333) via TCP connect for up to waitMs (default 15s) " +
+      "before declaring a port-detection timeout. On success: { port, url, message }. " +
+      "On timeout: still returns { port: <polled>, message } so callers can retry / probe.",
     annotations: {
       readOnlyHint: false,
     },
@@ -184,6 +272,12 @@ export const projectToolDefinitions: Tool[] = [
           type: "string",
           description: "Project directory to run dev server in (default: current project)",
         },
+        waitMs: {
+          type: "number",
+          description:
+            "How long (ms) to wait for the dev server to accept TCP connections on " +
+            "the configured port. Default 15000 (15s).",
+        },
       },
       required: [],
     },
@@ -318,7 +412,7 @@ export function projectTools(projectRoot: string, server?: Server, monitor?: Act
     },
 
     "mandu.dev.start": async (args: Record<string, unknown>) => {
-      const { cwd } = args as { cwd?: string };
+      const { cwd, waitMs } = args as { cwd?: string; waitMs?: number };
       if (devServerState || devServerStarting) {
         return {
           success: false,
@@ -334,6 +428,22 @@ export function projectTools(projectRoot: string, server?: Server, monitor?: Act
       try {
         const targetDir = cwd ? path.resolve(projectRoot, cwd) : projectRoot;
 
+        // Issue #237 Concern 3 — read `server.port` from mandu.config.*
+        // so we can poll a deterministic port instead of racing a
+        // regex against stdout. The env override takes precedence (it
+        // also takes precedence in the CLI — see cli/commands/dev.ts).
+        // Fall back to 3333 (Mandu's default) when neither is set.
+        const envPort = process.env.PORT ? Number(process.env.PORT) : null;
+        const configPort =
+          envPort && Number.isFinite(envPort)
+            ? envPort
+            : await readConfiguredServerPort(targetDir);
+        const polledPort = configPort ?? 3333;
+        const pollWaitMs =
+          typeof waitMs === "number" && Number.isFinite(waitMs) && waitMs > 0
+            ? waitMs
+            : 15_000;
+
         const proc = spawn(["bun", "run", "dev"], {
           cwd: targetDir,
           stdout: "pipe",
@@ -350,32 +460,6 @@ export function projectTools(projectRoot: string, server?: Server, monitor?: Act
         };
         devServerState = state;
 
-        // Wait for the server to output its port before returning
-        const portPromise = new Promise<{ port: number; url: string } | null>((resolve) => {
-          const PORT_DETECT_TIMEOUT_MS = 15_000;
-          const timeout = setTimeout(() => resolve(null), PORT_DETECT_TIMEOUT_MS);
-          const portPattern = /https?:\/\/[^:\s]+:(\d+)/;
-
-          const originalPush = state.output.push.bind(state.output);
-          state.output.push = (...items: string[]) => {
-            const result = originalPush(...items);
-            for (const item of items) {
-              const match = item.match(portPattern);
-              if (match) {
-                const detectedPort = parseInt(match[1], 10);
-                clearTimeout(timeout);
-                state.output.push = originalPush;
-                resolve({
-                  port: detectedPort,
-                  url: match[0],
-                });
-                break;
-              }
-            }
-            return result;
-          };
-        });
-
         consumeStream(proc.stdout, state, "stdout", server).catch(() => {});
         consumeStream(proc.stderr, state, "stderr", server).catch(() => {});
 
@@ -389,19 +473,28 @@ export function projectTools(projectRoot: string, server?: Server, monitor?: Act
           monitor.logEvent("dev", `Dev server started (${targetDir})`);
         }
 
-        // Wait for port detection (with timeout fallback)
-        const detected = await portPromise;
+        // Issue #237 Concern 3 — TCP poll the expected port. 127.0.0.1
+        // matches what the CLI prints; dual-stack (`::`) binds accept
+        // loopback v4 connects. We use 127.0.0.1 because `localhost`
+        // resolution varies across Windows + macOS.
+        const detectedPort = await pollServerPort(
+          polledPort,
+          "127.0.0.1",
+          pollWaitMs,
+        );
+
+        const url = detectedPort ? `http://localhost:${detectedPort}` : null;
 
         return {
           success: true,
           pid: proc.pid,
-          port: detected?.port ?? null,
-          url: detected?.url ?? null,
+          port: detectedPort ?? polledPort,
+          url,
           cwd: targetDir,
           startedAt: state.startedAt.toISOString(),
-          message: detected
-            ? `Dev server started on port ${detected.port}`
-            : "Dev server started (port detection timed out)",
+          message: detectedPort
+            ? `Dev server ready at http://localhost:${detectedPort}`
+            : `Dev server started (port detection timed out after ${pollWaitMs}ms polling ${polledPort})`,
         };
       } finally {
         devServerStarting = false;