@monster-orange/den 0.4.3 → 0.4.5

package/src/ui/mcp/scope.ts

@@ -191,6 +191,20 @@ function grantsNote(scope: McpScope): string {
     : "no grants";
 }
 
+/**
+ * How a person gives `scope`'s agent a grant to `other` (MCP-2.3, AG spec
+ * §5b): config in git, then a restart. An agent never grants itself one.
+ */
+export function grantHint(scope: McpScope, other: string): string {
+  const id = scope.actor.slice("agent:".length);
+  return (
+    `To reach it, a person adds "${printable(other)}" to agents.${id}.grants ` +
+    `in the org config and restarts the agent (agents start passes --grant); ` +
+    "an agent can't grant itself one. For names and status counts of every " +
+    "workspace, call org_summary."
+  );
+}
+
 /** The refusal for a call that names `other`; it names the agent's grants. */
 export function otherWorkspace(
   tool: string,
@@ -199,7 +213,8 @@ export function otherWorkspace(
 ): ScopeRefusal {
   return new ScopeRefusal(
     `${tool}: this MCP server is scoped to workspace "${scope.workspace}" ` +
-      `(${scope.actor}; ${grantsNote(scope)}); "${printable(other)}" is another workspace, so nothing was read or run.`,
+      `(${scope.actor}; ${grantsNote(scope)}); "${printable(other)}" is another workspace, so nothing was read or run. ` +
+      grantHint(scope, other),
   );
 }
 
@@ -299,8 +314,10 @@ function focusedOf(body: unknown): string | null {
 export async function assertScopeExists(
   api: DenApi,
   scope: McpScope,
+  /** An /api/workspaces body already read (else it is read now). */
+  read?: unknown,
 ): Promise<unknown> {
-  const body = await api.get("/api/workspaces");
+  const body = read ?? (await api.get("/api/workspaces"));
   if (!(scope.workspace in asRecord(asRecord(body).workspaces)))
     throw new ScopeRefusal(
       `this MCP server is scoped to workspace "${scope.workspace}", which does not exist in this distribution.`,
@@ -375,7 +392,10 @@ export async function assertServicesInScope(
   if (outside.length)
     throw new ScopeRefusal(
       `${tool}: ${outside.map(printable).join(", ")} ${outside.length === 1 ? "is" : "are"} not a service ` +
-        `of workspace "${scope.workspace}", the only one this MCP server serves; nothing was read.`,
+        `of workspace "${scope.workspace}", the only one this MCP server serves; nothing was read. ` +
+        "Logs and service details stay inside each workspace (logs can hold " +
+        "secrets), and a grant does not widen them; org_summary has every " +
+        "workspace's status counts.",
     );
 }
 

package/src/ui/mcp/server.ts

@@ -49,7 +49,9 @@ 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);
+  // Scoped, each workspace tool is registered pinned (MCP-2.2): "this
+  // workspace only", and no workspace parameter unless there are grants.
+  const tools = toolsFor(opts.cfg, opts.scope);
   const server = new McpServer(
     { name: p.name, version: engineVersion() ?? "0.0.0" },
     {
@@ -61,8 +63,11 @@ export function createDenMcpServer(opts: DenMcpOptions): McpServer {
           : "Read-only: the org has enabled no actions (mcp.actions).") +
         (opts.scope
           ? ` Scoped to workspace "${opts.scope.workspace}" as ${opts.scope.actor}: ` +
-            "a call naming another workspace is refused, and lists show this one only."
-          : ""),
+            "a call naming another workspace is refused, and lists show this one only, " +
+            "each with a `scope` block saying how much is hidden. org_summary has " +
+            "every workspace and repo (names and status counts), the graph, the " +
+            "edge and the environments: start there for the whole picture."
+          : " org_summary has the whole org at a glance: start there."),
     },
   );
 
@@ -222,8 +227,10 @@ export async function runOneShot(
   opts: OneShotOptions,
 ): Promise<number> {
   const out = opts.out ?? ((t: string) => process.stdout.write(t));
+  // The tools exactly as the stdio server registers them: pinned when scoped.
+  const tools = toolsFor(opts.cfg, opts.scope);
   if (shot.kind === "list") {
-    const names = toolsFor(opts.cfg).map((t) => t.name);
+    const names = tools.map((t) => t.name);
     out(names.length ? `${names.join("\n")}\n` : "");
     return 0;
   }
@@ -235,11 +242,18 @@ export async function runOneShot(
   };
   // The stdio server validates arguments against each tool's schema (the
   // SDK does it); a one-shot must too, and strictly: it is typed by hand, so
-  // an unknown or misspelt key is an error, not silently dropped.
+  // an unknown or misspelt key is an error, not silently dropped. Scoped,
+  // the schema is the pinned one; a `workspace` it dropped (no grants) is
+  // still taken, so naming another workspace gets Den's refusal (callTool),
+  // never a silent answer about the scope's own.
   let args = shot.args;
-  const tool = toolsFor(opts.cfg).find((t) => t.name === shot.tool);
+  const tool = tools.find((t) => t.name === shot.tool);
   if (tool) {
-    const parsed = z.object(tool.shape).strict().safeParse(args);
+    const shape =
+      opts.scope && !("workspace" in tool.shape) && "workspace" in args
+        ? { ...tool.shape, workspace: z.string().optional() }
+        : tool.shape;
+    const parsed = z.object(shape).strict().safeParse(args);
     if (!parsed.success) {
       const err = opts.err ?? ((t: string) => process.stderr.write(t));
       const lines = parsed.error.issues.map((i) => {
@@ -384,6 +398,16 @@ export async function runMcp(rawArgv: string[]): Promise<void> {
           ...scopeInfo(scope ?? undefined),
         }),
     });
+    // Say the scope on stderr (stdout is the result): a one-shot that ran
+    // unscoped must never pass for a scoped one.
+    if (scope)
+      process.stderr.write(
+        `${cli} mcp --call: scoped to ${scope.workspace} as ${scope.actor}` +
+          (scope.grants?.length
+            ? ` · grants: ${scope.grants.join(", ")}`
+            : "") +
+          "\n",
+      );
     process.exitCode = await runOneShot(shot, {
       cfg,
       cli,

package/src/ui/mcp/tools.ts

@@ -45,6 +45,14 @@ import {
   pinWorkspace,
   type McpScope,
 } from "./scope.js";
+import {
+  graphInScope,
+  mergeGraphs,
+  orgSummary,
+  scopeBlock,
+  statusView,
+  workspaceRepos,
+} from "./views.js";
 
 export interface ToolContext {
   api: DenApi;
@@ -173,37 +181,104 @@ const READ_TOOLS: DenTool[] = [
   read(
     "status",
     "Service health",
-    "Health of every service in the workspace (what `status` shows): up/down, mode, and what was checked: `url` for an HTTP check, `check` for a shell command or a container check (`container <project>/<service>`).",
+    "Health of every service in the workspace (what `status` shows): `counts`, then each service's `state` (up, down, redirect, pending, unknown, not-checked; `why` when there is no plain verdict), mode, and what was checked: `url` for an HTTP check, `check` for a shell command or a container check (`container <project>/<service>`). A redirect (302 → /login) answers, so it is not down.",
     { env: envArg, workspace: workspaceArg },
-    (a, { api }) =>
-      api.get("/api/health", { env: envOf(a), workspace: str(a.workspace) }),
+    async (a, { api, scope }) => {
+      const env = envOf(a);
+      const view = statusView(
+        await api.get("/api/health", { env, workspace: str(a.workspace) }),
+        env,
+      );
+      return scope
+        ? await withScope(api, scope, a, view, {
+            count: (view.services as unknown[]).length,
+            noun: "service",
+          })
+        : view;
+    },
   ),
   read(
     "services",
     "Services",
     "The workspace's services: repo, service, mode (managed or dev-managed), lifecycle commands, dependencies.",
     { env: envArg, workspace: workspaceArg },
-    (a, { api }) =>
-      api.get("/api/services", { env: envOf(a), workspace: str(a.workspace) }),
+    async (a, { api, scope }) => {
+      const list = await api.get("/api/services", {
+        env: envOf(a),
+        workspace: str(a.workspace),
+      });
+      if (!scope) return list;
+      const services = Array.isArray(list) ? list : [];
+      return withScope(
+        api,
+        scope,
+        a,
+        { services },
+        { count: services.length, noun: "service" },
+      );
+    },
   ),
   read(
     "applications",
     "Applications",
     "Org > Application > Repo > Services for a workspace (what `apps --json` shows).",
     { workspace: workspaceArg },
-    (a, { api }) =>
-      api.get("/api/applications", { workspace: str(a.workspace) }),
+    async (a, { api, scope }) => {
+      const tree = await api.get("/api/applications", {
+        workspace: str(a.workspace),
+      });
+      if (!scope) return tree;
+      const t =
+        tree && typeof tree === "object" && !Array.isArray(tree)
+          ? (tree as Record<string, unknown>)
+          : { applications: tree };
+      const apps = Array.isArray(t.applications) ? t.applications : [];
+      return withScope(api, scope, a, t, {
+        count: apps.length,
+        noun: "application",
+      });
+    },
   ),
   read(
     "graph",
     "Dependency graph",
-    "The derived dependency graph and its startup order; `seed` narrows it to one repo's closure.",
+    "The derived dependency graph; `seed` narrows it to one repo's closure. Unscoped with no `workspace` it is the org-wide map (`map: \"org-wide\"`: every active workspace's repos and edges, `workspaces` naming them; `order` only when one is active), with `workspace` that workspace's (`map: \"workspace\"`, with its startup order). Scoped, the workspace's own repos and the edges out of them (`outside` names the repos they depend on elsewhere; the org-wide map is `org_summary.graph`).",
     {
       seed: z.string().optional().describe("Repo whose closure to show"),
       workspace: workspaceArg,
     },
-    (a, { api }) =>
-      api.get("/api/graph", { seed: str(a.seed), workspace: str(a.workspace) }),
+    async (a, { api, scope }) => {
+      // Unscoped and naming nothing: the org-wide map, every active
+      // workspace's graph merged (the web server derives one per workspace).
+      if (!scope && !str(a.seed) && !str(a.workspace))
+        return orgGraph(api, (p, q) => api.get(p, q));
+      const graph = await api.get("/api/graph", {
+        seed: str(a.seed),
+        workspace: str(a.workspace),
+      });
+      if (!scope)
+        return graph && typeof graph === "object" && !Array.isArray(graph)
+          ? {
+              map: str(a.seed) ? "closure" : "workspace",
+              ...(str(a.workspace) ? { workspace: str(a.workspace) } : {}),
+              ...(graph as Record<string, unknown>),
+            }
+          : graph;
+      const body = await scopeWorkspacesBody(api, scope);
+      const shown = String(a.workspace);
+      const view = graphInScope(graph, workspaceRepos(body, shown));
+      const { hiddenNodes, ...rest } = view;
+      return {
+        ...rest,
+        scope: scopeBlock(
+          scope,
+          body,
+          shown,
+          { count: (view.nodes as unknown[]).length, noun: "repo" },
+          { graphNodes: hiddenNodes as number },
+        ),
+      };
+    },
   ),
   read(
     "workspaces",
@@ -212,7 +287,44 @@ const READ_TOOLS: DenTool[] = [
     {},
     async (_a, { api, scope }) => {
       const body = await api.get("/api/workspaces");
-      return scope ? filterWorkspacesBody(body, scope) : body;
+      if (!scope) return body;
+      const filtered = filterWorkspacesBody(body, scope);
+      return {
+        ...filtered,
+        scope: {
+          ...(filtered.scope as Record<string, unknown>),
+          ...scopeBlock(scope, body, scope.workspace, {
+            count: 1,
+            noun: "workspace",
+          }),
+        },
+      };
+    },
+  ),
+  read(
+    "org_summary",
+    "Org summary",
+    'The whole org at a glance, for every agent: each workspace and repo with status counts (running, partial, stopped; up, down, redirect, not checked), the dependency graph (names and edge kinds), the edge (up, TLS, whether HTTPS serves) and the environments. Scoped, `yours` adds your own workspace\'s services in full. It never carries logs, env values, commands, URLs or check output from outside your workspace. Start here for "what are our servers?".',
+    {},
+    async (_a, { api, scope }) => {
+      const workspaces = await api.get("/api/workspaces");
+      const [health, graph, edge, environments, own] = await Promise.all([
+        api.get("/api/health", { env: "local" }),
+        // Names and edge kinds only (orgSummary drops the evidence).
+        orgGraph(api, (p, q) => softGet(api, p, q), workspaces),
+        softGet(api, "/api/edge"),
+        api.get("/api/environments"),
+        scope
+          ? api.get("/api/health", {
+              env: "local",
+              workspace: scope.workspace,
+            })
+          : Promise.resolve(undefined),
+      ]);
+      return orgSummary(
+        { workspaces, health, graph, edge, environments, own },
+        scope,
+      );
     },
   ),
   read(
@@ -372,7 +484,7 @@ const READ_TOOLS: DenTool[] = [
   read(
     "stacks",
     "Stacks",
-    "Compose stacks (what `stack ls/ps/health` show): name, project, routes and container health.",
+    "Compose stacks (what `stack ls/ps/health` show): name, project, routes and container health. An empty list says why (`why`).",
     {
       workspace: workspaceArg,
       health: z
@@ -380,21 +492,151 @@ const READ_TOOLS: DenTool[] = [
         .optional()
         .describe("Check container health (default true)"),
     },
-    (a, { api }) =>
-      api.get("/api/stacks", {
+    async (a, { api, scope }) => {
+      const body = (await api.get("/api/stacks", {
         workspace: str(a.workspace),
         health: a.health === false ? "0" : "1",
-      }),
+      })) as Record<string, unknown>;
+      const all = Array.isArray(body?.stacks)
+        ? (body.stacks as { repo?: unknown }[])
+        : [];
+      if (!scope) {
+        if (all.length || body?.why !== undefined) return body;
+        return {
+          ...body,
+          why: "no stacks (the web server gave no reason; it predates 0.4.4)",
+        };
+      }
+      const wsBody = await scopeWorkspacesBody(api, scope);
+      const shown = String(a.workspace);
+      const mine = new Set(workspaceRepos(wsBody, shown));
+      const stacks = all.filter((s) => mine.has(String(s.repo)));
+      const hiddenStacks = all.length - stacks.length;
+      const why = stacks.length
+        ? undefined
+        : hiddenStacks
+          ? `no stacks in workspace "${shown}": the ${hiddenStacks} stack${hiddenStacks === 1 ? "" : "s"} listed belong to repos outside it`
+          : ((body?.why as string | undefined) ??
+            "no stacks (the web server gave no reason; it predates 0.4.4)");
+      return withScope(
+        api,
+        scope,
+        a,
+        { ...body, stacks, ...(why ? { why } : {}) },
+        { count: stacks.length, noun: "stack" },
+        { stacks: hiddenStacks },
+      );
+    },
   ),
   read(
     "edge_status",
     "Edge status",
-    "The HTTPS edge: up or down, its routes and its cert names.",
+    "The HTTPS edge: up or down, its routes and its cert names. `https` says the TLS strategy, who supplies the cert (den, or the distribution under tls strategy files) and whether HTTPS is serving; `certIssuedByDen` replaces the deprecated `certIssued`.",
     {},
-    (_a, { api }) => api.get("/api/edge"),
+    async (_a, { api }) => {
+      const edge = await api.get("/api/edge");
+      const e =
+        edge && typeof edge === "object"
+          ? (edge as Record<string, unknown>)
+          : null;
+      // A web server before 0.4.4: say what certIssued means.
+      if (e && e.certIssued !== undefined && e.https === undefined)
+        return {
+          ...e,
+          certIssuedMeans:
+            "whether Den minted the cert itself (mkcert); false under tls strategy files, where the distribution supplies it, even while HTTPS serves. Restart the web server for https.serving.",
+        };
+      return edge;
+    },
   ),
 ];
 
+/**
+ * The /api/workspaces body a scoped answer is counted against, read at most
+ * once every few seconds per scope (one tool call often makes several).
+ */
+const WORKSPACES_TTL_MS = 5_000;
+const workspacesSeen = new WeakMap<McpScope, { at: number; body: unknown }>();
+async function scopeWorkspacesBody(
+  api: DenApi,
+  scope: McpScope,
+): Promise<unknown> {
+  const hit = workspacesSeen.get(scope);
+  if (hit && Date.now() - hit.at < WORKSPACES_TTL_MS) return hit.body;
+  const body = await api.get("/api/workspaces");
+  workspacesSeen.set(scope, { at: Date.now(), body });
+  return body;
+}
+
+/** `answer` with the scope it was served under (MCP-2.2). */
+async function withScope(
+  api: DenApi,
+  scope: McpScope,
+  args: Args,
+  answer: Record<string, unknown>,
+  shows: { count: number; noun: string },
+  extraHidden: Record<string, number> = {},
+): Promise<Record<string, unknown>> {
+  const body = await scopeWorkspacesBody(api, scope);
+  return {
+    scope: scopeBlock(
+      scope,
+      body,
+      str(args.workspace) ?? scope.workspace,
+      shows,
+      extraHidden,
+    ),
+    ...answer,
+  };
+}
+
+/** A read whose HTTP error is part of the answer, not the whole call's. */
+async function softGet(
+  api: DenApi,
+  path: string,
+  query?: Query,
+): Promise<unknown> {
+  try {
+    return await api.get(path, query);
+  } catch (e) {
+    if (e instanceof DenHttpError)
+      return { error: `${e.status} from ${e.path}` };
+    throw e;
+  }
+}
+
+/**
+ * The org-wide graph: each active workspace's /api/graph, merged
+ * (mergeGraphs). With no active workspace, the web server's default one.
+ * `read`: an /api/workspaces body already read.
+ */
+async function orgGraph(
+  api: DenApi,
+  get: (path: string, query?: Query) => Promise<unknown>,
+  read?: unknown,
+): Promise<unknown> {
+  const body = read ?? (await api.get("/api/workspaces"));
+  const active =
+    body &&
+    typeof body === "object" &&
+    Array.isArray((body as Record<string, unknown>).active)
+      ? ((body as Record<string, unknown>).active as unknown[]).map(String)
+      : [];
+  if (!active.length) {
+    const g = await get("/api/graph");
+    return g && typeof g === "object" && !Array.isArray(g)
+      ? { map: "org-wide", ...(g as Record<string, unknown>) }
+      : g;
+  }
+  const graphs = await Promise.all(
+    active.map(async (workspace) => ({
+      workspace,
+      graph: await get("/api/graph", { workspace }),
+    })),
+  );
+  return mergeGraphs(graphs);
+}
+
 // ── Action tools ────────────────────────────────────────────────────────────
 
 /** Find the /api/services entry an action names (repo + optional service). */
@@ -580,13 +822,73 @@ export const READ_TOOL_NAMES: readonly string[] = READ_TOOLS.map((t) => t.name);
 export const ACTION_TOOL_NAMES: readonly McpAction[] = MCP_ACTIONS;
 
 /** The tools to register: every read tool, plus the actions the org named. */
-export function toolsFor(cfg: ResolvedMcpConfig): DenTool[] {
-  return [
+export function toolsFor(cfg: ResolvedMcpConfig, scope?: McpScope): DenTool[] {
+  const tools = [
     ...READ_TOOLS,
     ...MCP_ACTIONS.filter((a) => cfg.actions.includes(a)).map(
       (a) => ACTION_TOOLS[a],
     ),
   ];
+  return scope ? tools.map((t) => pinnedTool(t, scope)) : tools;
+}
+
+/**
+ * Tools that answer about one workspace, and so are "this workspace only"
+ * on a scoped server. The rest are the org's (environments, the edge,
+ * releases, security scans, the org summary) or take no workspace data.
+ */
+const WORKSPACE_TOOLS = new Set([
+  "status",
+  "services",
+  "applications",
+  "graph",
+  "workspaces",
+  "logs_search",
+  "logs_tail",
+  "tests_available",
+  "manifest_validate",
+  "stacks",
+  "service_up",
+  "service_down",
+  "service_restart",
+  "workspace_sync",
+  "run_tests",
+]);
+
+/**
+ * A tool as a scoped server registers it (MCP-2.2): its description says
+ * "this workspace only", and its `workspace` parameter is dropped, since it
+ * can only be the pinned one. With grants the parameter stays, to name a
+ * granted workspace, and says which those are. callTool still refuses a
+ * `workspace` naming another one (a one-shot or an old client may send it).
+ */
+export function pinnedTool(t: DenTool, scope: McpScope): DenTool {
+  if (!WORKSPACE_TOOLS.has(t.name)) return t;
+  const grants = scope.grants ?? [];
+  const only =
+    ` This workspace only ("${scope.workspace}"` +
+    (grants.length ? `, or a granted one: ${grants.join(", ")}` : "") +
+    "); every other workspace is in org_summary, names and counts only.";
+  let shape = t.shape;
+  if ("workspace" in t.shape) {
+    const rest = { ...t.shape };
+    delete rest.workspace;
+    // A string, not an enum of the allowed names: a schema rejection
+    // ("expected one of …") would hide Den's refusal, which names
+    // agents.<id>.grants and how a person grants one (MCP-2.3).
+    shape = grants.length
+      ? {
+          ...rest,
+          workspace: z
+            .string()
+            .optional()
+            .describe(
+              `"${scope.workspace}" (the default) or a granted workspace: ${grants.map((g) => `"${g}"`).join(", ")}; any other is refused`,
+            ),
+        }
+      : rest;
+  }
+  return { ...t, description: t.description + only, shape };
 }
 
 /**
@@ -719,7 +1021,12 @@ async function scopeArgs(
   scope: McpScope,
 ): Promise<Args> {
   if (!verifiedScopes.has(scope)) {
-    await assertScopeExists(ctx.api, scope);
+    // The body is the one scoped answers count against (one read).
+    await assertScopeExists(
+      ctx.api,
+      scope,
+      await scopeWorkspacesBody(ctx.api, scope),
+    );
     verifiedScopes.add(scope);
   }
   if (!("workspace" in tool.shape)) return args;