@monster-orange/den 0.0.0 → 0.2.0

package/src/ui/mcp/api.ts

@@ -0,0 +1,284 @@
+/**
+ * The MCP server's client for the running web server's HTTP API. The MCP
+ * server holds no state of its own: agents and the web UI share the server's
+ * state and its guards. This client can reach only the routes below, and it
+ * sends the agent's audit headers (see shared/agent-actor.ts) on every call.
+ */
+import { product } from "../../shared/product.js";
+import { LIFECYCLE_CMDS, Refusal } from "./guards.js";
+
+export type Query = Record<string, string | string[] | undefined>;
+
+/** The web server isn't answering; the message names the start command. */
+export class DenWebDown extends Error {
+  constructor(baseUrl: string, cli: string) {
+    super(
+      `The ${product().title} web server is not running at ${baseUrl}. ` +
+        `Start it with \`${cli} web up\` (the MCP server never starts it for you).`,
+    );
+    this.name = "DenWebDown";
+  }
+}
+
+/** The web server answered with an error status. */
+export class DenHttpError extends Error {
+  constructor(
+    readonly method: string,
+    readonly path: string,
+    readonly status: number,
+    readonly body: string,
+  ) {
+    super(`${method} ${path} → ${status}: ${body}`);
+    this.name = "DenHttpError";
+  }
+}
+
+/** Read routes: GET only. */
+const READ_ROUTES = new Set([
+  "/api/health",
+  "/api/services",
+  "/api/applications",
+  "/api/graph",
+  "/api/workspaces",
+  "/api/environments",
+  "/api/logs/search",
+  "/api/service/taillog",
+  "/api/service/logs",
+  "/api/modules",
+  "/api/test-sources",
+  "/api/security/latest",
+  "/api/security/plan",
+  "/api/release/status",
+  "/api/release/runs",
+  "/api/manifest/validate",
+  "/api/stacks",
+  "/api/edge",
+  "/api/server-info",
+]);
+
+/** Action routes and their method. Anything else is never reached. */
+const ACTION_ROUTES: Record<string, string> = {
+  "/api/service/exec": "GET",
+  "/api/run": "GET",
+  "/api/workspace/sync": "POST",
+};
+
+/**
+ * Throws a Refusal unless (method, path) is an allowed route. Never reached:
+ * sudo-password, aws/login, terminal/open, editor/open, workspace/exec,
+ * settings writes, workspace create/rename/mode, server-log, config, deploys.
+ * service/exec is allowed only for up/down/restart with env=local.
+ */
+export function assertAllowedRequest(
+  method: string,
+  path: string,
+  query: Query,
+): void {
+  const ok =
+    (READ_ROUTES.has(path) &&
+      (method === "GET" ||
+        (method === "POST" && path === "/api/manifest/validate"))) ||
+    ACTION_ROUTES[path] === method;
+  if (!ok) throw new Refusal(`${method} ${path} is not exposed to agents.`);
+  if (path === "/api/service/exec") {
+    const cmd = String(query.cmd ?? "");
+    if (!(LIFECYCLE_CMDS as readonly string[]).includes(cmd))
+      throw new Refusal(
+        `service/exec "${cmd}" refused: only ${LIFECYCLE_CMDS.join(", ")}.`,
+      );
+    if (query.env !== "local")
+      throw new Refusal("service/exec refused: env=local only.");
+  }
+}
+
+export interface SseEvent {
+  type?: string;
+  text?: string;
+  exitCode?: number;
+  [k: string]: unknown;
+}
+
+export interface StreamOpts {
+  method?: "GET" | "POST";
+  /** Stop after this many output lines (a follow stream never ends itself). */
+  maxLines: number;
+  /** Stop after this long, whatever is happening. */
+  timeoutMs: number;
+  /** Stop once nothing has arrived for this long (for log tails). */
+  idleMs?: number;
+  /** Stop when this event arrives (e.g. a detached `up` handing off). */
+  stopOn?: (e: SseEvent) => boolean;
+}
+
+export interface StreamResult {
+  events: SseEvent[];
+  lines: string[];
+  ended: "done" | "closed" | "limit" | "timeout" | "idle" | "stopped";
+  exitCode?: number;
+}
+
+export interface DenApi {
+  baseUrl: string;
+  /** A JSON route. */
+  get(
+    path: string,
+    query?: Query,
+    method?: "GET" | "POST",
+    body?: unknown,
+  ): Promise<unknown>;
+  /** An SSE route, read to a bound; the connection is closed after. */
+  stream(path: string, query: Query, opts: StreamOpts): Promise<StreamResult>;
+}
+
+function buildUrl(base: string, path: string, query: Query = {}): string {
+  const u = new URL(path, base);
+  for (const [k, v] of Object.entries(query)) {
+    if (v === undefined) continue;
+    for (const one of Array.isArray(v) ? v : [v]) u.searchParams.append(k, one);
+  }
+  return u.toString();
+}
+
+function isConnectionError(e: unknown): boolean {
+  const err = e as { name?: string; cause?: { code?: string } };
+  if (err?.name === "AbortError") return false;
+  const code = err?.cause?.code ?? "";
+  return (
+    err?.name === "TypeError" ||
+    ["ECONNREFUSED", "ECONNRESET", "ENOTFOUND", "EHOSTUNREACH"].includes(code)
+  );
+}
+
+const OUTPUT_TYPES = new Set(["line", "cmd", "error"]);
+
+export function createDenApi(opts: {
+  baseUrl: string;
+  cli: string;
+  headers: () => Record<string, string>;
+}): DenApi {
+  const { baseUrl, cli } = opts;
+
+  async function request(
+    method: string,
+    path: string,
+    query: Query,
+    signal?: AbortSignal,
+    body?: unknown,
+  ): Promise<Response> {
+    assertAllowedRequest(method, path, query);
+    try {
+      const res = await fetch(buildUrl(baseUrl, path, query), {
+        method,
+        headers: {
+          ...opts.headers(),
+          ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+        },
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        signal,
+      });
+      if (!res.ok) {
+        const text = (await res.text()).slice(0, 2000);
+        throw new DenHttpError(method, path, res.status, text);
+      }
+      return res;
+    } catch (e) {
+      if (isConnectionError(e)) throw new DenWebDown(baseUrl, cli);
+      throw e;
+    }
+  }
+
+  return {
+    baseUrl,
+
+    async get(path, query = {}, method = "GET", body) {
+      const res = await request(method, path, query, undefined, body);
+      const text = await res.text();
+      try {
+        return JSON.parse(text) as unknown;
+      } catch {
+        return text;
+      }
+    },
+
+    async stream(path, query, s) {
+      const ac = new AbortController();
+      const res = await request(s.method ?? "GET", path, query, ac.signal);
+      const events: SseEvent[] = [];
+      const lines: string[] = [];
+      let exitCode: number | undefined;
+      let ended: StreamResult["ended"] = "closed";
+      let stop = false;
+
+      const finish = (why: StreamResult["ended"]): void => {
+        if (stop) return;
+        stop = true;
+        ended = why;
+        ac.abort();
+      };
+      const overall = setTimeout(() => finish("timeout"), s.timeoutMs);
+      let idle: ReturnType<typeof setTimeout> | undefined;
+      const bumpIdle = (): void => {
+        if (!s.idleMs) return;
+        if (idle) clearTimeout(idle);
+        idle = setTimeout(() => finish("idle"), s.idleMs);
+      };
+      bumpIdle();
+
+      const onEvent = (e: SseEvent): void => {
+        events.push(e);
+        if (OUTPUT_TYPES.has(String(e.type)) && typeof e.text === "string") {
+          for (const l of e.text.replace(/\n+$/, "").split("\n")) {
+            if (lines.length >= s.maxLines) return finish("limit");
+            lines.push(l);
+          }
+          if (lines.length >= s.maxLines) return finish("limit");
+        }
+        if (e.type === "done") {
+          if (typeof e.exitCode === "number") exitCode = e.exitCode;
+          return finish("done");
+        }
+        if (s.stopOn?.(e)) finish("stopped");
+      };
+
+      try {
+        const reader = res.body?.getReader();
+        const decoder = new TextDecoder();
+        let buf = "";
+        while (reader && !stop) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          bumpIdle();
+          buf += decoder.decode(value, { stream: true });
+          let i: number;
+          while (!stop && (i = buf.indexOf("\n\n")) !== -1) {
+            const chunk = buf.slice(0, i);
+            buf = buf.slice(i + 2);
+            const data = chunk
+              .split("\n")
+              .filter((l) => l.startsWith("data:"))
+              .map((l) => l.slice(5).trimStart())
+              .join("\n");
+            if (!data) continue;
+            try {
+              onEvent(JSON.parse(data) as SseEvent);
+            } catch {
+              onEvent({ type: "line", text: data });
+            }
+          }
+        }
+      } catch (e) {
+        if (!stop) throw e;
+      } finally {
+        clearTimeout(overall);
+        if (idle) clearTimeout(idle);
+        if (!stop) ac.abort();
+      }
+      return {
+        events,
+        lines,
+        ended,
+        ...(exitCode !== undefined ? { exitCode } : {}),
+      };
+    },
+  };
+}

package/src/ui/mcp/guards.ts

@@ -0,0 +1,141 @@
+/**
+ * The MCP server's guards. Each one throws a Refusal (the tool then returns
+ * an error naming the rule) before anything reaches the web API. They sit on
+ * top of the web server's own checks, which still apply.
+ */
+import type { Environment } from "../../shared/types/index.js";
+import {
+  isProductionEnv,
+  type ResolvedMcpConfig,
+} from "../../shared/den-config.js";
+import {
+  placementRefusal,
+  type Placement,
+} from "../../shared/manifest/placement.js";
+
+/** A guard said no. The message says which rule and how to change it. */
+export class Refusal extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "Refusal";
+  }
+}
+
+/** The only manifest commands an agent may run. */
+export const LIFECYCLE_CMDS = ["up", "down", "restart"] as const;
+export type LifecycleCmd = (typeof LIFECYCLE_CMDS)[number];
+
+export function assertLifecycleCmd(cmd: string): asserts cmd is LifecycleCmd {
+  if (!(LIFECYCLE_CMDS as readonly string[]).includes(cmd))
+    throw new Refusal(
+      `"${cmd}" is not a lifecycle command: agents may run only ${LIFECYCLE_CMDS.join(", ")}.`,
+    );
+}
+
+/** Service lifecycle actions run on this machine only. */
+export function assertLocalEnv(env: string): void {
+  if (env !== "local")
+    throw new Refusal(
+      `service actions are local only (env "${env}" refused); nothing remote is ever started or stopped.`,
+    );
+}
+
+/** The fields of an /api/services entry the guards read. */
+export interface ServiceEntryLike {
+  repo?: string;
+  service?: string;
+  commands: string[];
+  mode?: string;
+  /** R13: where the service runs (absent from an older web server). */
+  runs?: Placement["runs"];
+  target?: Placement["target"];
+}
+
+/**
+ * Whether Den runs this service on this machine: the served `runs` is
+ * "local" and it has a local `up` command. A web server that does not serve
+ * `runs` yet is judged by the `up` command alone.
+ */
+export function runsLocally(entry: ServiceEntryLike): boolean {
+  if (entry.runs !== undefined && entry.runs !== "local") return false;
+  return entry.commands.includes("up");
+}
+
+export function assertRunsLocally(entry: ServiceEntryLike): void {
+  const address = `${entry.repo ?? "?"}/${entry.service ?? "?"}`;
+  if (entry.runs === "remote")
+    throw new Refusal(
+      placementRefusal(
+        address,
+        { runs: "remote", target: entry.target ?? null },
+        (e) => isProductionEnv(e),
+      ) ?? `${address} runs remotely; nothing to start here`,
+    );
+  if (!runsLocally(entry))
+    throw new Refusal(
+      `${address} is not run locally (its manifest has no local "up" command), so agents may not start, stop or restart it.`,
+    );
+}
+
+const PRODUCTION: readonly string[] = ["production", "prod"];
+
+/**
+ * run_tests: production never; otherwise only the envs the org listed in
+ * `mcp.run_tests.envs` (default [local]). Security `full` (active attacks) is
+ * local only.
+ */
+export function assertRunTestsAllowed(
+  args: { pillar: string; env: string; mode?: string },
+  cfg: ResolvedMcpConfig,
+): void {
+  if (PRODUCTION.includes(args.env))
+    throw new Refusal("run_tests never targets production.");
+  if (!cfg.runTestsEnvs.includes(args.env as Environment))
+    throw new Refusal(
+      `env "${args.env}" is not in mcp.run_tests.envs (allowed: ${cfg.runTestsEnvs.join(", ")}).`,
+    );
+  if (
+    args.pillar === "security" &&
+    args.mode === "full" &&
+    args.env !== "local"
+  )
+    throw new Refusal(
+      `security mode "full" (active attacks) is local only (env "${args.env}" refused).`,
+    );
+}
+
+/** The security CLI's dry-run verdict, from /api/security/plan. */
+export interface SecurityPlanLike {
+  ok: boolean;
+  errors?: string[];
+}
+
+/** A security run must pass the CLI's own plan: owned hosts, mode ceiling. */
+export function assertSecurityPlanOk(plan: SecurityPlanLike): void {
+  if (!plan.ok)
+    throw new Refusal(
+      `the security plan refused this run: ${(plan.errors ?? []).join(" ") || "no reason given"}`,
+    );
+}
+
+/** workspace_sync <repo>: the repo must be a managed clone in the workspace. */
+export function assertSyncableRepo(
+  repo: string,
+  services: readonly ServiceEntryLike[],
+): void {
+  const entries = services.filter((s) => s.repo === repo);
+  if (entries.length === 0)
+    throw new Refusal(`no repo named "${repo}" in the workspace.`);
+  if (!entries.some((s) => s.mode === "managed"))
+    throw new Refusal(
+      `${repo} is dev-managed (your own checkout): sync only updates managed clones, never a dev-managed one.`,
+    );
+}
+
+/** Log tools read local sources unless the org set `mcp.logs.remote: true`. */
+export function assertLogsEnv(env: string, cfg: ResolvedMcpConfig): void {
+  if (env !== "local" && !cfg.logsRemote)
+    throw new Refusal(
+      `remote log sources (env "${env}") are off: set mcp.logs.remote: true to allow them.`,
+    );
+}

package/src/ui/mcp/server.ts

@@ -0,0 +1,147 @@
+/**
+ * `<cli> mcp`: an MCP server over stdio, a thin client of the running web
+ * server (http://localhost:<web.port>). Agents and the web UI share one
+ * state and one set of guards; nothing is started implicitly.
+ *
+ * stdout carries the protocol only: diagnostics go to stderr.
+ */
+import { randomUUID } from "crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { agentAuditHeaders } from "../../shared/agent-actor.js";
+import {
+  readMcpConfig,
+  type ResolvedMcpConfig,
+} from "../../shared/den-config.js";
+import { readWebPort } from "../../shared/edge/config.js";
+import { engineVersion } from "../../shared/paths.js";
+import { product } from "../../shared/product.js";
+import { DEFAULT_PORT } from "../../shared/constants.js";
+import { createDenApi, type DenApi } from "./api.js";
+import { callTool, toolsFor, type ToolContext } from "./tools.js";
+
+export interface DenMcpOptions {
+  cfg: ResolvedMcpConfig;
+  baseUrl: string;
+  cli: string;
+  /** One id per MCP server process, recorded with every action. */
+  session?: string;
+  pid?: number;
+  /** For tests: an API in place of the HTTP client. */
+  api?: DenApi;
+  log?: (line: string) => void;
+}
+
+export function createDenMcpServer(opts: DenMcpOptions): McpServer {
+  const p = product();
+  const session = opts.session ?? randomUUID();
+  const log = opts.log ?? ((l: string) => process.stderr.write(`${l}\n`));
+  const tools = toolsFor(opts.cfg);
+  const server = new McpServer(
+    { name: p.name, version: engineVersion() ?? "0.0.0" },
+    {
+      instructions:
+        `${p.title}: local services, workspaces, logs and tests for this org, ` +
+        `through the running ${p.title} web server (\`${opts.cli} web up\`). ` +
+        (opts.cfg.actions.length
+          ? `Actions enabled: ${opts.cfg.actions.join(", ")}.`
+          : "Read-only: the org has enabled no actions (mcp.actions)."),
+    },
+  );
+
+  // The client's self-reported name/version, known once it has initialized.
+  const client = () => server.server.getClientVersion();
+  const api =
+    opts.api ??
+    createDenApi({
+      baseUrl: opts.baseUrl,
+      cli: opts.cli,
+      headers: () =>
+        agentAuditHeaders({
+          client: client()?.name ?? "unknown",
+          clientVersion: client()?.version ?? "unknown",
+          mcpPid: opts.pid ?? process.pid,
+          session,
+        }),
+    });
+  const ctx: ToolContext = { api, cfg: opts.cfg, cli: opts.cli };
+
+  for (const t of tools) {
+    server.registerTool(
+      t.name,
+      {
+        title: t.title,
+        description: t.description,
+        inputSchema: t.shape,
+        annotations: {
+          readOnlyHint: !t.action,
+          destructiveHint: t.action,
+          openWorldHint: false,
+        },
+      },
+      async (args: Record<string, unknown>) => {
+        const r = await callTool(t.name, args ?? {}, ctx);
+        if (t.action || r.isError) {
+          const who = client();
+          log(
+            `[mcp] ${t.name} ${r.isError ? "refused/failed" : "ok"} · ` +
+              `${who?.name ?? "unknown"} ${who?.version ?? ""} · session ${session}` +
+              (r.isError ? ` · ${r.text.split("\n")[0]}` : ""),
+          );
+        }
+        return {
+          content: [{ type: "text" as const, text: r.text }],
+          isError: r.isError,
+        };
+      },
+    );
+  }
+  return server;
+}
+
+function parsePort(argv: string[]): number | undefined {
+  const i = argv.indexOf("--port");
+  const raw =
+    i !== -1
+      ? argv[i + 1]
+      : argv.find((a) => a.startsWith("--port="))?.slice(7);
+  if (raw === undefined) return undefined;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1 || n > 65535)
+    throw new Error(`--port must be a port number, got "${raw}"`);
+  return n;
+}
+
+export const MCP_USAGE = (cli: string): string =>
+  [
+    `Usage: ${cli} mcp [--port <web port>]`,
+    "",
+    `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.",
+  ].join("\n");
+
+/** Run `<cli> mcp` until stdin closes. */
+export async function runMcp(argv: string[]): Promise<void> {
+  const cli = product().cli;
+  if (argv.includes("-h") || argv.includes("--help")) {
+    process.stderr.write(`${MCP_USAGE(cli)}\n`);
+    return;
+  }
+  let port = parsePort(argv);
+  if (port === undefined) {
+    try {
+      port = readWebPort();
+    } catch {
+      port = DEFAULT_PORT;
+    }
+  }
+  const cfg = readMcpConfig();
+  const baseUrl = `http://localhost:${port}`;
+  const server = createDenMcpServer({ cfg, baseUrl, cli });
+  await server.connect(new StdioServerTransport());
+  process.stderr.write(
+    `${cli} mcp: ${toolsFor(cfg).length} tools ` +
+      `(${cfg.actions.length ? `actions: ${cfg.actions.join(", ")}` : "read only"}) → ${baseUrl}\n`,
+  );
+}