@monster-orange/den 0.2.0 → 0.2.2

package/src/ui/mcp/connect.ts

@@ -0,0 +1,304 @@
+/**
+ * `<cli> mcp connect`: register this distribution's MCP server with the
+ * agents a developer uses, so nobody hand-edits an MCP config.
+ *
+ * Each client is a strategy: where its config lives (or which of its own
+ * CLIs registers a server) and in which shape. Planning is pure (tests drive
+ * it with a fake home and PATH); applying it writes one JSON key or runs the
+ * client's own `mcp add`. Nothing else in a client's config is touched.
+ *
+ * The registered command is the distribution's bin shim by absolute path,
+ * with PATH pinned so that GUI clients (which start without the login shell's
+ * PATH, so without nvm's node) can launch it.
+ */
+import * as path from "path";
+
+export type Scope = "user" | "project";
+
+/** What gets registered: one stdio server. */
+export interface ServerSpec {
+  name: string;
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+}
+
+export interface ConnectEnv {
+  home: string;
+  platform: NodeJS.Platform;
+  /** %APPDATA% on Windows. */
+  appData?: string;
+  /** The project directory for project scope (where the agent runs). */
+  projectDir: string;
+  /** Whether an executable is on PATH. */
+  which: (bin: string) => boolean;
+  /** Whether a file or directory exists. */
+  exists: (p: string) => boolean;
+}
+
+/** One change to make. */
+export type ConnectAction =
+  | {
+      kind: "json";
+      file: string;
+      /** Top-level key holding the servers: mcpServers, or servers (VS Code). */
+      key: "mcpServers" | "servers";
+      name: string;
+      entry: Record<string, unknown>;
+    }
+  | {
+      kind: "exec";
+      /** Run first, failure ignored: makes the add idempotent. */
+      remove?: string[];
+      add: string[];
+      /** Exit 0 when the server is registered (for status). */
+      check?: string[];
+    };
+
+export interface McpClient {
+  id: string;
+  title: string;
+  scopes: Scope[];
+  /** Whether the client looks installed here. */
+  detect(env: ConnectEnv): boolean;
+  plan(spec: ServerSpec, scope: Scope, env: ConnectEnv): ConnectAction;
+}
+
+const stdioEntry = (s: ServerSpec): Record<string, unknown> => ({
+  command: s.command,
+  args: s.args,
+  ...(Object.keys(s.env).length ? { env: s.env } : {}),
+});
+
+const envFlags = (flag: string, env: Record<string, string>): string[] =>
+  Object.entries(env).flatMap(([k, v]) => [flag, `${k}=${v}`]);
+
+function appSupport(env: ConnectEnv, app: string): string {
+  if (env.platform === "darwin")
+    return path.join(env.home, "Library", "Application Support", app);
+  if (env.platform === "win32")
+    return path.join(
+      env.appData ?? path.join(env.home, "AppData", "Roaming"),
+      app,
+    );
+  return path.join(env.home, ".config", app);
+}
+
+const json = (
+  file: string,
+  spec: ServerSpec,
+  key: "mcpServers" | "servers" = "mcpServers",
+  entry: Record<string, unknown> = stdioEntry(spec),
+): ConnectAction => ({ kind: "json", file, key, name: spec.name, entry });
+
+export const MCP_CLIENTS: readonly McpClient[] = [
+  {
+    id: "claude-code",
+    title: "Claude Code",
+    scopes: ["user", "project"],
+    detect: (e) => e.which("claude"),
+    plan: (s, scope, e) =>
+      scope === "project"
+        ? json(path.join(e.projectDir, ".mcp.json"), s)
+        : {
+            kind: "exec",
+            remove: ["claude", "mcp", "remove", "--scope", "user", s.name],
+            add: [
+              "claude",
+              "mcp",
+              "add",
+              "--scope",
+              "user",
+              ...envFlags("-e", s.env),
+              s.name,
+              "--",
+              s.command,
+              ...s.args,
+            ],
+            check: ["claude", "mcp", "get", s.name],
+          },
+  },
+  {
+    id: "codex",
+    title: "Codex CLI",
+    scopes: ["user"],
+    detect: (e) => e.which("codex"),
+    plan: (s) => ({
+      kind: "exec",
+      remove: ["codex", "mcp", "remove", s.name],
+      add: [
+        "codex",
+        "mcp",
+        "add",
+        ...envFlags("--env", s.env),
+        s.name,
+        "--",
+        s.command,
+        ...s.args,
+      ],
+      check: ["codex", "mcp", "get", s.name],
+    }),
+  },
+  {
+    id: "cursor",
+    title: "Cursor",
+    scopes: ["user", "project"],
+    detect: (e) => e.which("cursor") || e.exists(path.join(e.home, ".cursor")),
+    plan: (s, scope, e) =>
+      json(
+        path.join(
+          scope === "project" ? e.projectDir : e.home,
+          ".cursor",
+          "mcp.json",
+        ),
+        s,
+      ),
+  },
+  {
+    id: "vscode",
+    title: "VS Code (Copilot agent)",
+    scopes: ["user", "project"],
+    detect: (e) => e.which("code"),
+    plan: (s, scope, e) =>
+      scope === "project"
+        ? json(path.join(e.projectDir, ".vscode", "mcp.json"), s, "servers", {
+            type: "stdio",
+            ...stdioEntry(s),
+          })
+        : {
+            kind: "exec",
+            add: [
+              "code",
+              "--add-mcp",
+              JSON.stringify({ name: s.name, type: "stdio", ...stdioEntry(s) }),
+            ],
+          },
+  },
+  {
+    id: "claude-desktop",
+    title: "Claude Desktop",
+    scopes: ["user"],
+    detect: (e) => e.exists(appSupport(e, "Claude")),
+    plan: (s, _scope, e) =>
+      json(path.join(appSupport(e, "Claude"), "claude_desktop_config.json"), s),
+  },
+  {
+    id: "windsurf",
+    title: "Windsurf",
+    scopes: ["user"],
+    detect: (e) =>
+      e.which("windsurf") ||
+      e.exists(path.join(e.home, ".codeium", "windsurf")),
+    plan: (s, _scope, e) =>
+      json(path.join(e.home, ".codeium", "windsurf", "mcp_config.json"), s),
+  },
+  {
+    id: "gemini",
+    title: "Gemini CLI",
+    scopes: ["user", "project"],
+    detect: (e) => e.which("gemini"),
+    plan: (s, scope, e) =>
+      json(
+        path.join(
+          scope === "project" ? e.projectDir : e.home,
+          ".gemini",
+          "settings.json",
+        ),
+        s,
+      ),
+  },
+];
+
+export function findClient(id: string): McpClient | undefined {
+  return MCP_CLIENTS.find((c) => c.id === id);
+}
+
+/** The PATH a launched server needs: node's own directory first. */
+export function serverPath(nodeBinDir: string, platform: NodeJS.Platform) {
+  const base =
+    platform === "win32"
+      ? []
+      : ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"];
+  return [nodeBinDir, ...base.filter((d) => d !== nodeBinDir)].join(
+    platform === "win32" ? ";" : ":",
+  );
+}
+
+/** The server this distribution registers. */
+export function serverSpec(o: {
+  cli: string;
+  distRoot: string;
+  nodeBinDir: string;
+  platform: NodeJS.Platform;
+  port?: number;
+}): ServerSpec {
+  return {
+    name: o.cli,
+    command: path.join(o.distRoot, "bin", o.cli),
+    args: ["mcp", ...(o.port !== undefined ? ["--port", String(o.port)] : [])],
+    env: { PATH: serverPath(o.nodeBinDir, o.platform) },
+  };
+}
+
+// ── JSON configs ────────────────────────────────────────────────────────────
+
+/**
+ * `text` (a client's config file, or null when absent) with `name` set under
+ * `key`. Refuses to rewrite a file it cannot parse: a client's config is the
+ * developer's, and clobbering it loses their other servers.
+ */
+export function mergeJsonConfig(
+  text: string | null,
+  key: string,
+  name: string,
+  entry: Record<string, unknown> | null,
+): string {
+  let doc: Record<string, unknown> = {};
+  if (text !== null && text.trim()) {
+    try {
+      doc = JSON.parse(text) as Record<string, unknown>;
+    } catch (e) {
+      throw new Error(
+        `not valid JSON (${(e as Error).message}); fix it or add the server by hand`,
+      );
+    }
+    if (!doc || typeof doc !== "object" || Array.isArray(doc))
+      throw new Error("not a JSON object; add the server by hand");
+  }
+  const servers =
+    doc[key] && typeof doc[key] === "object" && !Array.isArray(doc[key])
+      ? { ...(doc[key] as Record<string, unknown>) }
+      : {};
+  if (entry === null) delete servers[name];
+  else servers[name] = entry;
+  return `${JSON.stringify({ ...doc, [key]: servers }, null, 2)}\n`;
+}
+
+/** Whether a JSON config already registers `name` with this entry. */
+export function jsonHasEntry(
+  text: string | null,
+  key: string,
+  name: string,
+  entry: Record<string, unknown>,
+): "connected" | "different" | "absent" {
+  if (!text) return "absent";
+  try {
+    const doc = JSON.parse(text) as Record<string, Record<string, unknown>>;
+    const have = doc?.[key]?.[name];
+    if (have === undefined) return "absent";
+    return JSON.stringify(have) === JSON.stringify(entry)
+      ? "connected"
+      : "different";
+  } catch {
+    return "absent";
+  }
+}
+
+/** A generic snippet for any other MCP client. */
+export function genericSnippet(spec: ServerSpec): string {
+  return JSON.stringify(
+    { mcpServers: { [spec.name]: stdioEntry(spec) } },
+    null,
+    2,
+  );
+}

package/src/ui/mcp/guards.ts

@@ -61,7 +61,10 @@ export function runsLocally(entry: ServiceEntryLike): boolean {
   return entry.commands.includes("up");
 }
 
-export function assertRunsLocally(entry: ServiceEntryLike): void {
+export function assertRunsLocally(
+  entry: ServiceEntryLike,
+  command: string = "up",
+): void {
   const address = `${entry.repo ?? "?"}/${entry.service ?? "?"}`;
   if (entry.runs === "remote")
     throw new Refusal(
@@ -69,7 +72,8 @@ export function assertRunsLocally(entry: ServiceEntryLike): void {
         address,
         { runs: "remote", target: entry.target ?? null },
         (e) => isProductionEnv(e),
-      ) ?? `${address} runs remotely; nothing to start here`,
+        command,
+      ) ?? `${address} runs remotely; nothing to ${command} here`,
     );
   if (!runsLocally(entry))
     throw new Refusal(

package/src/ui/mcp/server.ts

@@ -115,13 +115,78 @@ function parsePort(argv: string[]): number | undefined {
 export const MCP_USAGE = (cli: string): string =>
   [
     `Usage: ${cli} mcp [--port <web port>]`,
+    `       ${cli} mcp --list`,
+    `       ${cli} mcp --call <tool> ['<json args>']`,
     "",
     `An MCP server over stdio for agents, a client of the running web server`,
     `(\`${cli} web up\`; default port: config web.port). Read tools always;`,
     "actions only as named in the org config's mcp.actions. See docs/distributions.md.",
+    "",
+    "--list prints the tool names; --call runs one tool through the same guards,",
+    "prints its text result and exits 1 if the tool reports an error.",
+    "",
+    `Register it with your agents: ${cli} mcp clients, then ${cli} mcp connect <client> (or --all).`,
   ].join("\n");
 
-/** Run `<cli> mcp` until stdin closes. */
+/** A one-shot invocation: `--list`, or `--call <tool> [json]`. */
+export type OneShot =
+  | { kind: "list" }
+  | { kind: "call"; tool: string; args: Record<string, unknown> };
+
+/** The one-shot `argv` asks for, or null for the stdio server. */
+export function parseOneShot(argv: string[]): OneShot | null {
+  const i = argv.indexOf("--call");
+  if (i !== -1) {
+    const tool = argv[i + 1];
+    if (!tool || tool.startsWith("-"))
+      throw new Error("--call needs a tool name: --call <tool> ['<json>']");
+    const raw = argv[i + 2];
+    if (raw === undefined || raw.startsWith("--"))
+      return { kind: "call", tool, args: {} };
+    let args: unknown;
+    try {
+      args = JSON.parse(raw);
+    } catch (e) {
+      throw new Error(
+        `--call ${tool}: arguments are not JSON (${(e as Error).message})`,
+      );
+    }
+    if (args === null || typeof args !== "object" || Array.isArray(args))
+      throw new Error(`--call ${tool}: arguments must be a JSON object`);
+    return { kind: "call", tool, args: args as Record<string, unknown> };
+  }
+  return argv.includes("--list") ? { kind: "list" } : null;
+}
+
+export interface OneShotOptions {
+  cfg: ResolvedMcpConfig;
+  cli: string;
+  api: DenApi;
+  out?: (text: string) => void;
+  err?: (text: string) => void;
+}
+
+/**
+ * Run a one-shot through the tool layer the stdio server uses (callTool:
+ * mcp.actions, every guard, redaction). Returns the exit code.
+ */
+export async function runOneShot(
+  shot: OneShot,
+  opts: OneShotOptions,
+): Promise<number> {
+  const out = opts.out ?? ((t: string) => process.stdout.write(t));
+  if (shot.kind === "list") {
+    const names = toolsFor(opts.cfg).map((t) => t.name);
+    out(names.length ? `${names.join("\n")}\n` : "");
+    return 0;
+  }
+  const ctx: ToolContext = { api: opts.api, cfg: opts.cfg, cli: opts.cli };
+  const r = await callTool(shot.tool, shot.args, ctx);
+  out(r.text.endsWith("\n") ? r.text : `${r.text}\n`);
+  return r.isError ? 1 : 0;
+}
+
+/** Run `<cli> mcp` until stdin closes (or one `--call` / `--list`). */
 export async function runMcp(argv: string[]): Promise<void> {
   const cli = product().cli;
   if (argv.includes("-h") || argv.includes("--help")) {
@@ -138,6 +203,24 @@ export async function runMcp(argv: string[]): Promise<void> {
   }
   const cfg = readMcpConfig();
   const baseUrl = `http://localhost:${port}`;
+  const shot = parseOneShot(argv);
+  if (shot) {
+    // Recorded like any MCP action: actor agent, this process, one session.
+    const session = randomUUID();
+    const api = createDenApi({
+      baseUrl,
+      cli,
+      headers: () =>
+        agentAuditHeaders({
+          client: `${cli} mcp --call`,
+          clientVersion: engineVersion() ?? "unknown",
+          mcpPid: process.pid,
+          session,
+        }),
+    });
+    process.exitCode = await runOneShot(shot, { cfg, cli, api });
+    return;
+  }
   const server = createDenMcpServer({ cfg, baseUrl, cli });
   await server.connect(new StdioServerTransport());
   process.stderr.write(

package/src/ui/mcp/tools.ts

@@ -85,15 +85,61 @@ function tail(r: StreamResult, n: number): string[] {
 }
 
 /** One line per stream: how it ended and its exit code. */
+/**
+ * Whether a streamed action failed: a non-zero exit, a detached service whose
+ * launcher exited non-zero, or a run that never finished (timeout).
+ */
+export function streamFailed(r: StreamResult): boolean {
+  if (r.ended === "timeout") return true;
+  if (r.exitCode !== undefined && r.exitCode !== 0) return true;
+  return r.events.some(
+    (e) =>
+      e.type === "service-exited" &&
+      typeof e.exitCode === "number" &&
+      e.exitCode !== 0,
+  );
+}
+
+/** An action that ran and failed: its output goes back with isError set. */
+export class ActionFailed extends Error {
+  constructor(readonly out: Record<string, unknown>) {
+    super("action failed");
+    this.name = "ActionFailed";
+  }
+}
+
+/**
+ * How the call ended, in words an agent reads about the service: a stream
+ * stopped at `ready` is "ready", at a launcher's exit "handed-off".
+ */
+function endedLabel(r: StreamResult): string {
+  if (r.ended !== "stopped") return r.ended;
+  const last = r.events.at(-1)?.type;
+  if (last === "ready") return "ready";
+  if (last === "service-exited") return "handed-off";
+  return r.ended;
+}
+
 function streamSummary(r: StreamResult, keep: number) {
   return {
-    ended: r.ended,
+    ended: endedLabel(r),
     ...(r.exitCode !== undefined ? { exitCode: r.exitCode } : {}),
     lines: r.lines.length,
     output: tail(r, keep),
   };
 }
 
+/** The action's result; thrown as ActionFailed when the stream failed. */
+function actionResult(
+  r: StreamResult,
+  keep: number,
+  head: Record<string, unknown> = {},
+): Record<string, unknown> {
+  const out = { ...head, ...streamSummary(r, keep) };
+  if (streamFailed(r)) throw new ActionFailed({ failed: true, ...out });
+  return out;
+}
+
 // ── Read tools ──────────────────────────────────────────────────────────────
 
 const read = (
@@ -354,7 +400,7 @@ function lifecycleTool(cmd: LifecycleCmd): DenTool {
         str(a.service),
         workspace,
       );
-      assertRunsLocally(entry);
+      assertRunsLocally(entry, cmd);
       const r = await api.stream(
         "/api/service/exec",
         {
@@ -368,16 +414,20 @@ function lifecycleTool(cmd: LifecycleCmd): DenTool {
           method: "GET",
           maxLines: 2000,
           timeoutMs: 180_000,
-          // A detached `up` keeps streaming the service's log; its launch
-          // script exiting is the hand-off.
-          stopOn: (e) => e.type === "service-exited",
+          // A detached start keeps streaming the service's log. It is done
+          // when the server says it is ready (health green, or still running
+          // with no check), or when its launch script exits (the hand-off).
+          stopOn: (e) => e.type === "ready" || e.type === "service-exited",
         },
       );
-      return {
+      const ready = r.events.find((e) => e.type === "ready");
+      return actionResult(r, 200, {
         service: `${entry.repo}/${entry.service}`,
         cmd,
-        ...streamSummary(r, 200),
-      };
+        ...(ready
+          ? { ready: true, healthChecked: ready.checked === true }
+          : {}),
+      });
     },
   };
 }
@@ -408,7 +458,7 @@ const ACTION_TOOLS: Record<McpAction, DenTool> = {
         maxLines: 5000,
         timeoutMs: 15 * 60_000,
       });
-      return streamSummary(r, 300);
+      return actionResult(r, 300);
     },
   },
   run_tests: {
@@ -453,7 +503,7 @@ const ACTION_TOOLS: Record<McpAction, DenTool> = {
         },
         { method: "GET", maxLines: 20_000, timeoutMs: 60 * 60_000 },
       );
-      return { pillar, env, ...streamSummary(r, 300) };
+      return actionResult(r, 300, { pillar, env });
     },
   },
 };
@@ -532,6 +582,28 @@ async function notFoundMessage(
  * that refused, how to start the web server, or (when it runs an older Den
  * than the tool needs) how to restart it.
  */
+/**
+ * Tell the web server a guard refused an action, so the activity trail shows
+ * the attempt (F2). Best effort: a report that fails changes nothing.
+ */
+async function reportRefusal(
+  ctx: ToolContext,
+  tool: string,
+  args: Args,
+  reason: string,
+): Promise<void> {
+  try {
+    await ctx.api.get("/api/activity", {}, "POST", {
+      tool,
+      ...(typeof args.repo === "string" ? { repo: args.repo } : {}),
+      ...(typeof args.service === "string" ? { service: args.service } : {}),
+      reason,
+    });
+  } catch {
+    /* the refusal is still returned to the agent */
+  }
+}
+
 export async function callTool(
   name: string,
   args: Args,
@@ -548,12 +620,19 @@ export async function callTool(
     const text = typeof out === "string" ? out : JSON.stringify(out, null, 2);
     return { text: redactSecrets(text), isError: false };
   } catch (e) {
+    if (e instanceof ActionFailed)
+      return {
+        text: redactSecrets(JSON.stringify(e.out, null, 2)),
+        isError: true,
+      };
     if (e instanceof DenHttpError && e.status === 404) {
       const text = await notFoundMessage(e, name, ctx).catch(
         (inner: Error) => `Error: ${inner.message}`,
       );
       return { text: redactSecrets(text), isError: true };
     }
+    if (e instanceof Refusal && tool.action)
+      await reportRefusal(ctx, name, args, e.message);
     const msg =
       e instanceof Refusal
         ? `Refused: ${e.message}`

package/src/ui/server/audit.ts

@@ -20,9 +20,13 @@ export interface AuditEntry {
   clientVersion?: string;
   mcpPid?: number | null;
   session?: string;
-  /** exec | run | sync */
+  /** exec | run | sync, or the MCP tool name for a refused non-lifecycle call */
   verb: string;
   detail: string;
+  /** Set when the action never ran: a guard or the server refused it. */
+  outcome?: "refused";
+  /** Why it was refused (first line). */
+  reason?: string;
 }
 
 type Sink = (line: string, actor: AgentActor | null) => void;
@@ -43,7 +47,12 @@ export function actorSuffix(actor: Actor): string {
 
 export function recordAction(
   actor: Actor,
-  action: { verb: string; detail: string },
+  action: {
+    verb: string;
+    detail: string;
+    outcome?: "refused";
+    reason?: string;
+  },
 ): AuditEntry {
   const entry: AuditEntry = {
     ts: new Date().toISOString(),
@@ -58,13 +67,70 @@ export function recordAction(
       : {}),
     verb: action.verb,
     detail: action.detail,
+    ...(action.outcome ? { outcome: action.outcome } : {}),
+    ...(action.reason ? { reason: clean(action.reason, 300) } : {}),
   };
   ring.push(entry);
   if (ring.length > RING_MAX) ring.shift();
-  sink?.(`▶ ${action.verb} ${action.detail}${actorSuffix(actor)}`, actor);
+  const mark = entry.outcome === "refused" ? "✗" : "▶";
+  const why = entry.reason ? ` — refused: ${entry.reason}` : "";
+  sink?.(
+    `${mark} ${action.verb} ${action.detail}${why}${actorSuffix(actor)}`,
+    actor,
+  );
   return entry;
 }
 
+/** One line, printable characters only, at most `max` long. */
+function clean(v: unknown, max: number): string {
+  const line = String(v ?? "").split(/[\r\n]/)[0];
+  return [...line]
+    .filter((c) => c.charCodeAt(0) >= 0x20 && c.charCodeAt(0) !== 0x7f)
+    .join("")
+    .slice(0, max);
+}
+
+const SAFE_PART = /^[A-Za-z0-9._-]{1,128}$/;
+const LIFECYCLE_TOOL = /^service_(up|down|restart)$/;
+
+/**
+ * An MCP guard refused an agent's call before it reached an action route.
+ * The agent's own report, so every field is sanitised: a lifecycle tool with
+ * a valid repo becomes an "exec" entry for that service (what the panel's
+ * activity list shows); anything else is recorded under the tool's name.
+ */
+export function recordAgentRefusal(
+  actor: Actor,
+  report: {
+    tool?: unknown;
+    repo?: unknown;
+    service?: unknown;
+    reason?: unknown;
+  },
+): AuditEntry {
+  const tool = clean(report.tool, 64).replace(/[^A-Za-z0-9_]/g, "") || "tool";
+  const repo = typeof report.repo === "string" ? report.repo : "";
+  const service = typeof report.service === "string" ? report.service : "";
+  const lifecycle = LIFECYCLE_TOOL.exec(tool);
+  const reason = clean(report.reason, 300) || "refused";
+  if (lifecycle && SAFE_PART.test(repo)) {
+    const address =
+      service && SAFE_PART.test(service) ? `${repo}/${service}` : repo;
+    return recordAction(actor, {
+      verb: "exec",
+      detail: `${address} ${lifecycle[1]} (local)`,
+      outcome: "refused",
+      reason,
+    });
+  }
+  return recordAction(actor, {
+    verb: tool,
+    detail: "",
+    outcome: "refused",
+    reason,
+  });
+}
+
 /** The most recent actions, oldest first. */
 export function recentActions(): AuditEntry[] {
   return ring.slice();