@mandujs/mcp 0.29.0 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/mcp",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "Mandu MCP Server - Agent-native interface for Mandu framework operations",
   "type": "module",
   "main": "./src/index.ts",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@mandujs/core": "^0.42.0",
-    "@mandujs/ate": "^0.25.0",
+    "@mandujs/ate": "^0.25.1",
     "@mandujs/skills": "^0.18.0",
     "@modelcontextprotocol/sdk": "^1.25.3"
   },

package/src/tools/ate-run.ts

@@ -57,7 +57,10 @@ export const ateRunToolDefinitions: Tool[] = [
       "`graphVersion` (agent cache invalidation key), and trace/screenshot/dom artifacts " +
       "staged under .mandu/ate-artifacts/<runId>/. Use `shard: { current, total }` to " +
       "distribute across CI workers. Emits notifications/progress per spec_done event. " +
-      "On timeout / cancel, writes .mandu/reports/run-<runId>/results.json with partial state.",
+      "On timeout / cancel, writes .mandu/reports/run-<runId>/results.json with partial state. " +
+      "Issue #237 — `grep` narrows execution to specific `test(...)` titles inside the " +
+      "selected spec (forwarded to Playwright --grep / bun:test --test-name-pattern). " +
+      "For batch / multi-spec runs use mandu.ate.run (which also accepts onlyFiles + onlyRoutes).",
     inputSchema: {
       type: "object",
       properties: {
@@ -88,6 +91,12 @@ export const ateRunToolDefinitions: Tool[] = [
           type: "boolean",
           description: "Playwright only — capture trace. Default: true.",
         },
+        grep: {
+          type: "string",
+          description:
+            "Issue #237 — pass-through to Playwright --grep / bun:test --test-name-pattern. " +
+            "Filters by test-block title within the selected spec.",
+        },
         shard: {
           type: "object",
           properties: {
@@ -264,12 +273,13 @@ export function createAteProgressTracker(options: {
 export function ateRunTools(_projectRoot: string, server?: Server) {
   return {
     mandu_ate_run: async (args: Record<string, unknown>) => {
-      const { repoRoot, spec, headed, trace, shard, progressToken } = args as {
+      const { repoRoot, spec, headed, trace, shard, grep, progressToken } = args as {
         repoRoot: string;
         spec: string | { path: string };
         headed?: boolean;
         trace?: boolean;
         shard?: { current: number; total: number };
+        grep?: string;
         progressToken?: string | number;
       };
       if (!repoRoot || typeof repoRoot !== "string") {
@@ -336,6 +346,7 @@ export function ateRunTools(_projectRoot: string, server?: Server) {
           headed,
           trace,
           shard,
+          grep,
         });
       } catch (err) {
         // Runner timeout / exec error — persist partial state so heal

package/src/tools/ate.ts

@@ -93,7 +93,10 @@ export const ateToolDefinitions: Tool[] = [
       "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.",
+      "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: {
@@ -109,6 +112,26 @@ 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:
@@ -170,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: {
@@ -404,16 +431,38 @@ export function ateTools(projectRoot: string, server?: Server) {
       return ateGenerate({ repoRoot, oracleLevel, onlyRoutes });
     },
     "mandu.ate.run": async (args: Record<string, unknown>) => {
-      const { repoRoot, baseURL, ci, headless, browsers, progressToken } = 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 runWithObservability(
-        { repoRoot, baseURL, ci, headless, browsers },
+        {
+          repoRoot,
+          baseURL,
+          ci,
+          headless,
+          browsers,
+          onlyFiles,
+          onlyRoutes,
+          grep,
+        },
         { progressToken },
       );
     },

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/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;