@mandujs/mcp 0.36.2 → 0.37.0

package/src/tools/kitchen.ts

@@ -27,34 +27,69 @@ export const kitchenToolDefinitions: Tool[] = [
       required: [],
     },
   },
+  {
+    name: "mandu.devtools.context",
+    description:
+      "Read the Kitchen Agent Supervisor context pack — one call returns the current situation, recommended skill/MCP tools, knowledge cards, a copyable prompt, and the next safe action. Combines routes, recent errors, HTTP traffic, MCP usage, bundle manifest, diagnose report, and changed files. Use this at session start or whenever you are unsure what to work on next. Requires `mandu dev` to be running.",
+    annotations: {
+      readOnlyHint: true,
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        includeBundle: {
+          type: "boolean",
+          description:
+            "Include bundle manifest summary (.mandu/manifest.json). Default true. Set false to skip on very large projects.",
+        },
+        includeDiagnose: {
+          type: "boolean",
+          description:
+            "Include the extended diagnose report. Default true. Set false to lower latency when a11y_hints / package_export_gaps are noisy.",
+        },
+        includeDiff: {
+          type: "boolean",
+          description:
+            "Include git diff against MANDU_DIFF_BASE (default HEAD). Default true. Set false to skip when git is unavailable.",
+        },
+      },
+      required: [],
+    },
+  },
 ];
 
-export function kitchenTools(projectRoot: string) {
-  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
-    "mandu.kitchen.errors": async (args: Record<string, unknown>) => {
-      const { clear = false } = args as { clear?: boolean };
+/**
+ * Resolve the dev server base URL. Prefers the port parsed from the
+ * currently running `mandu dev` stdout; falls back to mandu config; final
+ * default is 3333. Shared by every Kitchen-backed MCP tool so they all
+ * agree on where to fetch from.
+ */
+async function resolveDevServerBaseUrl(projectRoot: string): Promise<string> {
+  let port: number | undefined;
 
-      // Detect port from the running dev server output first, then fall back to config
-      let port: number | undefined;
-
-      const serverState = getDevServerState();
-      if (serverState) {
-        // Parse the actual port from dev server stdout (e.g. "http://localhost:3333")
-        for (const line of serverState.output) {
-          const portMatch = line.match(/https?:\/\/localhost:(\d+)/);
-          if (portMatch) {
-            port = parseInt(portMatch[1], 10);
-          }
-        }
+  const serverState = getDevServerState();
+  if (serverState) {
+    for (const line of serverState.output) {
+      const portMatch = line.match(/https?:\/\/localhost:(\d+)/);
+      if (portMatch) {
+        port = parseInt(portMatch[1], 10);
       }
+    }
+  }
 
-      // Fall back to config if we couldn't detect from running server
-      if (!port) {
-        const config = await loadManduConfig(projectRoot);
-        port = config.server?.port ?? 3333;
-      }
+  if (!port) {
+    const config = await loadManduConfig(projectRoot);
+    port = config.server?.port ?? 3333;
+  }
 
-      const baseUrl = `http://localhost:${port}`;
+  return `http://localhost:${port}`;
+}
+
+export function kitchenTools(projectRoot: string) {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.kitchen.errors": async (args: Record<string, unknown>) => {
+      const { clear = false } = args as { clear?: boolean };
+      const baseUrl = await resolveDevServerBaseUrl(projectRoot);
 
       try {
         // Fetch errors from Kitchen API
@@ -98,10 +133,61 @@ export function kitchenTools(projectRoot: string) {
         };
       }
     },
+
+    /**
+     * Plan 18 P0-1 — read-only Agent Supervisor context pack.
+     *
+     * Fetches `/__kitchen/api/agent-context` and returns the full pack
+     * so an agent can self-orient with a single call: current situation,
+     * top tool recommendation, knowledge cards, copyable prompt, and the
+     * next safe action. Three optional toggles let the caller skip
+     * expensive signals when latency matters.
+     */
+    "mandu.devtools.context": async (args: Record<string, unknown>) => {
+      const {
+        includeBundle = true,
+        includeDiagnose = true,
+        includeDiff = true,
+      } = args as { includeBundle?: boolean; includeDiagnose?: boolean; includeDiff?: boolean };
+
+      const baseUrl = await resolveDevServerBaseUrl(projectRoot);
+      const params = new URLSearchParams();
+      if (!includeBundle) params.set("bundle", "0");
+      if (!includeDiagnose) params.set("diagnose", "0");
+      if (!includeDiff) params.set("diff", "0");
+      const query = params.toString();
+      const url = `${baseUrl}/__kitchen/api/agent-context${query ? `?${query}` : ""}`;
+
+      try {
+        const res = await fetch(url);
+        if (!res.ok) {
+          return {
+            success: false,
+            message: `Dev server not reachable at ${baseUrl}. Is 'mandu dev' running?`,
+            status: res.status,
+          };
+        }
+
+        const pack = await res.json() as Record<string, unknown>;
+        return {
+          success: true,
+          message: "Agent Supervisor context pack retrieved.",
+          pack,
+          relatedSkills: ["mandu-agent-workflow", "mandu-debug"],
+        };
+      } catch {
+        return {
+          success: false,
+          message: `Cannot connect to dev server at ${baseUrl}. Make sure 'mandu dev' is running.`,
+        };
+      }
+    },
   };
 
-  // Backward-compatible alias
+  // Backward-compatible aliases (underscore form for legacy MCP clients
+  // that don't accept dots in tool names).
   handlers["mandu_kitchen_errors"] = handlers["mandu.kitchen.errors"];
+  handlers["mandu_devtools_context"] = handlers["mandu.devtools.context"];
 
   return handlers;
 }

package/src/tools/lint.ts

@@ -1,226 +1,226 @@
-/**
- * MCP tools — `mandu.lint` + `mandu.lint.setup`
- *
- * Gives agents a first-class way to:
- *   1. Run oxlint on a project and get structured error/warning counts
- *      (read-only, no side effects).
- *   2. One-shot install oxlint + scaffold `.oxlintrc.json` + wire
- *      scripts on an existing project (destructive — writes files).
- *
- * The setup tool mirrors `mandu lint --setup`. We spawn the CLI as a
- * subprocess rather than linking to the CLI source so MCP builds
- * don't pull `packages/cli` into their import graph.
- */
-
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
-import path from "node:path";
-import fs from "node:fs/promises";
-
-// ─────────────────────────────────────────────────────────────────────────
-// Shared helpers
-// ─────────────────────────────────────────────────────────────────────────
-
-async function oxlintAvailable(rootDir: string): Promise<boolean> {
-  const binName = process.platform === "win32" ? "oxlint.exe" : "oxlint";
-  const localBin = path.resolve(rootDir, "node_modules", ".bin", binName);
-  try {
-    await fs.access(localBin);
-    return true;
-  } catch {
-    // Not in local node_modules — probe PATH.
-  }
-  try {
-    const proc = Bun.spawn({
-      cmd: ["bun", "x", "oxlint", "--version"],
-      cwd: rootDir,
-      stdout: "ignore",
-      stderr: "ignore",
-    });
-    return (await proc.exited) === 0;
-  } catch {
-    return false;
-  }
-}
-
-interface LintParsed {
-  errors: number;
-  warnings: number;
-  raw: string;
-  parseFailed: boolean;
-}
-
-async function runOxlintOnce(rootDir: string, typeAware: boolean): Promise<LintParsed> {
-  const cmd = typeAware
-    ? ["bun", "x", "oxlint", "--type-aware", "."]
-    : ["bun", "x", "oxlint", "."];
-  const proc = Bun.spawn({
-    cmd,
-    cwd: rootDir,
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  const [stdout, stderr] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-  ]);
-  await proc.exited;
-  const raw = stderr + stdout;
-  const match = raw.match(/Found (\d+) warnings? and (\d+) errors?/);
-  if (!match) {
-    return { errors: 0, warnings: 0, raw, parseFailed: true };
-  }
-  return {
-    errors: Number(match[2]),
-    warnings: Number(match[1]),
-    raw,
-    parseFailed: false,
-  };
-}
-
-// ─────────────────────────────────────────────────────────────────────────
-// mandu.lint — run oxlint, return counts
-// ─────────────────────────────────────────────────────────────────────────
-
-interface LintInput {
-  typeAware?: unknown;
-}
-
-interface LintResult {
-  installed: boolean;
-  ran: boolean;
-  errors: number;
-  warnings: number;
-  passed: boolean;
-  hint?: string;
-  rawTail?: string;
-}
-
-async function handleLint(projectRoot: string, input: LintInput): Promise<LintResult> {
-  const typeAware = input.typeAware === true;
-  const installed = await oxlintAvailable(projectRoot);
-  if (!installed) {
-    return {
-      installed: false,
-      ran: false,
-      errors: 0,
-      warnings: 0,
-      passed: false,
-      hint:
-        "oxlint is not installed in this project. Call `mandu.lint.setup` or run `mandu lint --setup` in the shell to install + configure.",
-    };
-  }
-  const result = await runOxlintOnce(projectRoot, typeAware);
-  if (result.parseFailed) {
-    return {
-      installed: true,
-      ran: true,
-      errors: 0,
-      warnings: 0,
-      passed: false,
-      hint: "oxlint ran but output could not be parsed. See `rawTail` for the last 2 KB.",
-      rawTail: result.raw.slice(-2048),
-    };
-  }
-  return {
-    installed: true,
-    ran: true,
-    errors: result.errors,
-    warnings: result.warnings,
-    passed: result.errors === 0,
-  };
-}
-
-// ─────────────────────────────────────────────────────────────────────────
-// mandu.lint.setup — install oxlint + wire scripts + baseline
-// ─────────────────────────────────────────────────────────────────────────
-
-interface LintSetupInput {
-  dryRun?: unknown;
-}
-
-interface LintSetupResult {
-  ok: boolean;
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-  dryRun: boolean;
-  hint?: string;
-}
-
-async function handleLintSetup(projectRoot: string, input: LintSetupInput): Promise<LintSetupResult> {
-  const dryRun = input.dryRun === true;
-  const args = ["run", "--cwd", projectRoot, "mandu", "lint", "--setup", "--yes"];
-  if (dryRun) args.push("--dry-run");
-  const proc = Bun.spawn({
-    cmd: ["bun", ...args],
-    cwd: projectRoot,
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  const [stdout, stderr] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-  ]);
-  const exitCode = await proc.exited;
-  const ok = exitCode === 0;
-  return {
-    ok,
-    stdout,
-    stderr,
-    exitCode,
-    dryRun,
-    hint: ok
-      ? dryRun
-        ? "Dry-run completed. Re-run without `dryRun: true` to apply the changes."
-        : "Setup completed. Run `mandu.lint` to see the current baseline."
-      : "Setup command failed. See `stderr` for details. A frequent cause is `mandu` CLI not being installed — `bun add -D @mandujs/cli` in the project first.",
-  };
-}
-
-// ─────────────────────────────────────────────────────────────────────────
-// MCP tool definitions + handler map
-// ─────────────────────────────────────────────────────────────────────────
-
-export const lintToolDefinitions: Tool[] = [
-  {
-    name: "mandu.lint",
-    description:
-      "Run oxlint on the project and return structured error/warning counts. Read-only — never modifies files. Pass `typeAware: true` to also run `oxlint --type-aware` (requires `oxlint-tsgolint`). Agents should call this after edits as part of the guardrail chain alongside `mandu.guard.check` and `mandu.doctor`.",
-    annotations: { readOnlyHint: true },
-    inputSchema: {
-      type: "object",
-      properties: {
-        typeAware: {
-          type: "boolean",
-          description:
-            "Run `oxlint --type-aware` in addition to the core pass (requires `oxlint-tsgolint`). Default false.",
-        },
-      },
-      required: [],
-    },
-  },
-  {
-    name: "mandu.lint.setup",
-    description:
-      "Install oxlint into an existing project: copies `.oxlintrc.json`, wires `lint`/`lint:fix` scripts, adds `oxlint` devDep, runs `bun install`. Idempotent — re-running produces no additional changes. Destructive — writes files. Set `dryRun: true` to print the plan only.",
-    annotations: { readOnlyHint: false, destructiveHint: true },
-    inputSchema: {
-      type: "object",
-      properties: {
-        dryRun: {
-          type: "boolean",
-          description: "Print the plan without writing files. Default false.",
-        },
-      },
-      required: [],
-    },
-  },
-];
-
-export function lintTools(projectRoot: string) {
-  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
-    "mandu.lint": async (args) => handleLint(projectRoot, args as LintInput),
-    "mandu.lint.setup": async (args) => handleLintSetup(projectRoot, args as LintSetupInput),
-  };
-  return handlers;
-}
+/**
+ * MCP tools — `mandu.lint` + `mandu.lint.setup`
+ *
+ * Gives agents a first-class way to:
+ *   1. Run oxlint on a project and get structured error/warning counts
+ *      (read-only, no side effects).
+ *   2. One-shot install oxlint + scaffold `.oxlintrc.json` + wire
+ *      scripts on an existing project (destructive — writes files).
+ *
+ * The setup tool mirrors `mandu lint --setup`. We spawn the CLI as a
+ * subprocess rather than linking to the CLI source so MCP builds
+ * don't pull `packages/cli` into their import graph.
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+
+// ─────────────────────────────────────────────────────────────────────────
+// Shared helpers
+// ─────────────────────────────────────────────────────────────────────────
+
+async function oxlintAvailable(rootDir: string): Promise<boolean> {
+  const binName = process.platform === "win32" ? "oxlint.exe" : "oxlint";
+  const localBin = path.resolve(rootDir, "node_modules", ".bin", binName);
+  try {
+    await fs.access(localBin);
+    return true;
+  } catch {
+    // Not in local node_modules — probe PATH.
+  }
+  try {
+    const proc = Bun.spawn({
+      cmd: ["bun", "x", "oxlint", "--version"],
+      cwd: rootDir,
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    return (await proc.exited) === 0;
+  } catch {
+    return false;
+  }
+}
+
+interface LintParsed {
+  errors: number;
+  warnings: number;
+  raw: string;
+  parseFailed: boolean;
+}
+
+async function runOxlintOnce(rootDir: string, typeAware: boolean): Promise<LintParsed> {
+  const cmd = typeAware
+    ? ["bun", "x", "oxlint", "--type-aware", "."]
+    : ["bun", "x", "oxlint", "."];
+  const proc = Bun.spawn({
+    cmd,
+    cwd: rootDir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  await proc.exited;
+  const raw = stderr + stdout;
+  const match = raw.match(/Found (\d+) warnings? and (\d+) errors?/);
+  if (!match) {
+    return { errors: 0, warnings: 0, raw, parseFailed: true };
+  }
+  return {
+    errors: Number(match[2]),
+    warnings: Number(match[1]),
+    raw,
+    parseFailed: false,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// mandu.lint — run oxlint, return counts
+// ─────────────────────────────────────────────────────────────────────────
+
+interface LintInput {
+  typeAware?: unknown;
+}
+
+interface LintResult {
+  installed: boolean;
+  ran: boolean;
+  errors: number;
+  warnings: number;
+  passed: boolean;
+  hint?: string;
+  rawTail?: string;
+}
+
+async function handleLint(projectRoot: string, input: LintInput): Promise<LintResult> {
+  const typeAware = input.typeAware === true;
+  const installed = await oxlintAvailable(projectRoot);
+  if (!installed) {
+    return {
+      installed: false,
+      ran: false,
+      errors: 0,
+      warnings: 0,
+      passed: false,
+      hint:
+        "oxlint is not installed in this project. Call `mandu.lint.setup` or run `mandu lint --setup` in the shell to install + configure.",
+    };
+  }
+  const result = await runOxlintOnce(projectRoot, typeAware);
+  if (result.parseFailed) {
+    return {
+      installed: true,
+      ran: true,
+      errors: 0,
+      warnings: 0,
+      passed: false,
+      hint: "oxlint ran but output could not be parsed. See `rawTail` for the last 2 KB.",
+      rawTail: result.raw.slice(-2048),
+    };
+  }
+  return {
+    installed: true,
+    ran: true,
+    errors: result.errors,
+    warnings: result.warnings,
+    passed: result.errors === 0,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// mandu.lint.setup — install oxlint + wire scripts + baseline
+// ─────────────────────────────────────────────────────────────────────────
+
+interface LintSetupInput {
+  dryRun?: unknown;
+}
+
+interface LintSetupResult {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+  dryRun: boolean;
+  hint?: string;
+}
+
+async function handleLintSetup(projectRoot: string, input: LintSetupInput): Promise<LintSetupResult> {
+  const dryRun = input.dryRun === true;
+  const args = ["run", "--cwd", projectRoot, "mandu", "lint", "--setup", "--yes"];
+  if (dryRun) args.push("--dry-run");
+  const proc = Bun.spawn({
+    cmd: ["bun", ...args],
+    cwd: projectRoot,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  const exitCode = await proc.exited;
+  const ok = exitCode === 0;
+  return {
+    ok,
+    stdout,
+    stderr,
+    exitCode,
+    dryRun,
+    hint: ok
+      ? dryRun
+        ? "Dry-run completed. Re-run without `dryRun: true` to apply the changes."
+        : "Setup completed. Run `mandu.lint` to see the current baseline."
+      : "Setup command failed. See `stderr` for details. A frequent cause is `mandu` CLI not being installed — `bun add -D @mandujs/cli` in the project first.",
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// MCP tool definitions + handler map
+// ─────────────────────────────────────────────────────────────────────────
+
+export const lintToolDefinitions: Tool[] = [
+  {
+    name: "mandu.lint",
+    description:
+      "Run oxlint on the project and return structured error/warning counts. Read-only — never modifies files. Pass `typeAware: true` to also run `oxlint --type-aware` (requires `oxlint-tsgolint`). Agents should call this after edits as part of the guardrail chain alongside `mandu.guard.check` and `mandu.doctor`.",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      type: "object",
+      properties: {
+        typeAware: {
+          type: "boolean",
+          description:
+            "Run `oxlint --type-aware` in addition to the core pass (requires `oxlint-tsgolint`). Default false.",
+        },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "mandu.lint.setup",
+    description:
+      "Install oxlint into an existing project: copies `.oxlintrc.json`, wires `lint`/`lint:fix` scripts, adds `oxlint` devDep, runs `bun install`. Idempotent — re-running produces no additional changes. Destructive — writes files. Set `dryRun: true` to print the plan only.",
+    annotations: { readOnlyHint: false, destructiveHint: true },
+    inputSchema: {
+      type: "object",
+      properties: {
+        dryRun: {
+          type: "boolean",
+          description: "Print the plan without writing files. Default false.",
+        },
+      },
+      required: [],
+    },
+  },
+];
+
+export function lintTools(projectRoot: string) {
+  const handlers: Record<string, (args: Record<string, unknown>) => Promise<unknown>> = {
+    "mandu.lint": async (args) => handleLint(projectRoot, args as LintInput),
+    "mandu.lint.setup": async (args) => handleLintSetup(projectRoot, args as LintSetupInput),
+  };
+  return handlers;
+}