@mandujs/mcp 0.29.0 → 0.31.0

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,