@monster-orange/den 0.1.0 → 0.2.1

package/src/ui/mcp/guards.ts

@@ -0,0 +1,145 @@
+/**
+ * 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,
+  command: string = "up",
+): 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),
+        command,
+      ) ?? `${address} runs remotely; nothing to ${command} 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,149 @@
+/**
+ * `<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.",
+    "",
+    `Register it with your agents: ${cli} mcp clients, then ${cli} mcp connect <client> (or --all).`,
+  ].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`,
+  );
+}