jui-tools-mcp-server 2.15.11 → 2.17.0

package/src/tools/infra/infra_prices_validate.ts

@@ -0,0 +1,41 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { ServerConfig } from "../../config.js";
+import { failure, need, problems, runDocJson, text } from "./infra_common.js";
+
+/**
+ * `jsonui-doc validate infra-prices <project> --json`: the room's own price files (<infra.dir>/prices, or
+ * infra.prices_dir). Exit 0: no error; 1: errors; 2: the folder cannot be read (reason).
+ */
+export function register(server: McpServer, config: ServerConfig) {
+  server.tool(
+    "infra_prices_validate",
+    "Validate the server room's own price files (docs/infra/prices/*.json — only for what the bundled prices lack) with `jsonui-doc validate infra-prices --json`. Returns the files used, how many prices, and the problems by severity and code with the first 20. Needs jsonui-cli 2.3.15+.",
+    {
+      project_dir: z.string().optional().describe("Project directory with jui.config.json (overrides JUI_PROJECT_DIR env)"),
+    },
+    async ({ project_dir }) => {
+      try {
+        const projectDir = config.resolveProjectDir(project_dir);
+        const { exitCode, data } = await runDocJson(["validate", "infra-prices", projectDir, "--json"], projectDir);
+        need(data, ["ok"], "validate infra-prices");
+        if (!data.ok) {
+          need(data, ["reason", "message"], "validate infra-prices");
+          return text({ ok: false, exit: exitCode, readable: false, reason: data.reason, message: data.message });
+        }
+        need(data, ["dir", "files", "problems", "count"], "validate infra-prices");
+        return text({
+          ok: exitCode === 0,
+          exit: exitCode,
+          readable: true,
+          dir: data.dir,
+          files: data.files,
+          count: data.count,
+          problems: problems(data.problems, "validate infra-prices"),
+        });
+      } catch (e: any) {
+        return failure(e);
+      }
+    }
+  );
+}

package/src/tools/infra/infra_seed.ts

@@ -0,0 +1,88 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { ServerConfig } from "../../config.js";
+import { ContractError, FIRST, failure, need, text } from "./infra_common.js";
+import { runCli } from "../../cli_runner.js";
+
+/**
+ * `jsonui-doc seed infra <project> -o <dir>`: a draft model from what the project already says (Compose, Terraform /
+ * OpenTofu, Kubernetes, CloudFormation / SAM / CDK, wrangler, PaaS files, SDK imports and env names; never state,
+ * tfvars or .env values), and its report (what it read, what it could not place). By default the draft is written to
+ * a temp folder and read back — nothing in the project changes; write: true writes <infra.dir>/seed (the draft is a
+ * starting point, never read as the model). Exit 0: drafted; 2: refused (bad config, the draft fails its own check,
+ * or a draft is already there without force).
+ */
+
+function infraDir(projectDir: string): string {
+  try {
+    const cfg = JSON.parse(readFileSync(join(projectDir, "jui.config.json"), "utf-8"));
+    if (typeof cfg?.infra?.dir === "string") return cfg.infra.dir;
+  } catch {
+    // no config, or not JSON: the CLI says so itself
+  }
+  return "docs/infra";
+}
+
+function readJson(path: string, what: string): any {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    throw new ContractError(`seed infra wrote no readable ${what} at ${path}`);
+  }
+}
+
+export function summarize(draft: any, report: any) {
+  need(draft, ["nodes", "groups", "edges"], "seed infra draft");
+  need(report, ["inputs", "unmatched", "skipped", "skippedCount", "notes", "withheld"], "seed infra report");
+  return {
+    counts: { nodes: draft.nodes.length, groups: draft.groups.length, edges: draft.edges.length,
+      flows: Array.isArray(draft.flows) ? draft.flows.length : 0 },
+    environments: (draft.environments ?? []).map((e: any) => e.id),
+    nodes: draft.nodes.slice(0, 50).map((n: any) => ({
+      id: n.id, category: n.category, provider: n.provider, service: n.service, iac: n.iac, environments: n.environments,
+    })),
+    inputs: report.inputs,
+    unmatched: Object.fromEntries(Object.entries(report.unmatched).map(([provider, u]: [string, any]) =>
+      [provider, { count: u.count, items: (u.items ?? []).slice(0, FIRST) }])),
+    notDrawn: report.notDrawn ?? {},
+    skipped: { count: report.skippedCount, first: report.skipped.slice(0, FIRST) },
+    notes: report.notes.slice(0, FIRST),
+    withheld: report.withheld,
+  };
+}
+
+export function register(server: McpServer, config: ServerConfig) {
+  server.tool(
+    "infra_seed",
+    "Draft the server room's model from the project's IaC, config files and code with `jsonui-doc seed infra` (Compose, Terraform/OpenTofu, Kubernetes, CloudFormation/SAM/CDK, wrangler, Firebase/PaaS files, SDK imports and env var names — never Terraform state, tfvars or .env values). Returns the draft's counts and nodes (id, category, provider, service, iac), what was read, what could not be placed (unmatched, by provider) or was skipped, and notes. By default nothing in the project is written; write: true writes <infra.dir>/seed/draft.json and seed-report.json (a starting point to copy from — the model is docs/infra/*.json).",
+    {
+      project_dir: z.string().optional().describe("Project directory with jui.config.json (overrides JUI_PROJECT_DIR env)"),
+      write: z.boolean().optional().describe("Write the draft to <infra.dir>/seed in the project (default false: read only)"),
+      force: z.boolean().optional().describe("With write: replace a draft already there"),
+    },
+    async ({ project_dir, write, force }) => {
+      const temp = write ? null : mkdtempSync(join(tmpdir(), "jui-mcp-seed-"));
+      try {
+        const projectDir = config.resolveProjectDir(project_dir);
+        const out = temp ?? join(projectDir, infraDir(projectDir), "seed");
+        const args = ["seed", "infra", projectDir, "-o", out];
+        if (write && force) args.push("--force");
+        const result = await runCli("jsonui-doc", args, { cwd: projectDir, timeout: 180_000 });
+        if (result.exitCode !== 0 || !existsSync(join(out, "draft.json"))) {
+          return text({ ok: false, exit: result.exitCode,
+            message: (result.stderr || result.stdout).trim().split("\n").slice(-5).join("\n") });
+        }
+        const summary = summarize(readJson(join(out, "draft.json"), "draft.json"),
+          readJson(join(out, "seed-report.json"), "seed-report.json"));
+        return text({ ok: true, exit: 0, written: write ? out : null, ...summary });
+      } catch (e: any) {
+        return failure(e);
+      } finally {
+        if (temp) rmSync(temp, { recursive: true, force: true });
+      }
+    }
+  );
+}

package/src/tools/infra/infra_validate.ts

@@ -0,0 +1,44 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { ServerConfig } from "../../config.js";
+import { failure, need, problems, runDocJson, text } from "./infra_common.js";
+
+/**
+ * `jsonui-doc validate infra <project> --json`: the room's model (docs/infra/*.json, or jui.config.json's infra.dir)
+ * read as jui viz reads it — each file against the schema and the shapes of secrets, then merged, and its flows
+ * walked. Exit 0: no error (warnings alone are 0); 1: errors; 2: nothing could be read (reason).
+ */
+export function register(server: McpServer, config: ServerConfig) {
+  server.tool(
+    "infra_validate",
+    "Validate the server room's infra model (docs/infra/*.json: environments, groups, nodes, edges, flows) with `jsonui-doc validate infra --json`. Returns whether it could be read (and why not), the files used, the counts, and the problems by severity and code with the first 20 (file, path, code, message). Flow problems (flow.*) name the rule a step most likely missed. Needs jsonui-cli 2.3.15+.",
+    {
+      project_dir: z.string().optional().describe("Project directory with jui.config.json (overrides JUI_PROJECT_DIR env)"),
+    },
+    async ({ project_dir }) => {
+      try {
+        const projectDir = config.resolveProjectDir(project_dir);
+        const { exitCode, data } = await runDocJson(["validate", "infra", projectDir, "--json"], projectDir);
+        need(data, ["ok"], "validate infra");
+        if (!data.ok && data.reason !== "invalid") {
+          need(data, ["reason", "message"], "validate infra");
+          return text({ ok: false, exit: exitCode, readable: false, reason: data.reason, message: data.message });
+        }
+        need(data, ["dir", "files", "problems"], "validate infra");
+        return text({
+          ok: exitCode === 0,
+          exit: exitCode,
+          readable: data.ok,
+          dir: data.dir,
+          files: data.files,
+          environments: (data.environments ?? []).map((e: any) => e.id),
+          counts: data.counts ?? null,
+          flows: Array.isArray(data.flows) ? data.flows.length : null,
+          problems: problems(data.problems, "validate infra"),
+        });
+      } catch (e: any) {
+        return failure(e);
+      }
+    }
+  );
+}

package/src/tools/viz/viz_common.ts

@@ -0,0 +1,61 @@
+import { homedir } from "os";
+import { runCli, CliResult } from "../../cli_runner.js";
+
+/**
+ * Shared by the viz_* tools (`jui viz`, the local viewer of Claude Code
+ * sessions). jui viz reads ~/.claude and ~/.jsonui-cli/viz, not a project, so
+ * every call runs in the home folder — never JUI_PROJECT_DIR.
+ */
+
+/** Said in every viz_* description: other agents' sessions (Codex, …) are not shown. */
+export const CLAUDE_CODE_ONLY =
+  "jui viz shows Claude Code sessions only (Claude Code のセッションだけを見せる).";
+
+export const UPDATE_JUI =
+  "curl -fsSL https://raw.githubusercontent.com/Tai-Kimura/jsonui-cli/main/installer/bootstrap.sh | bash";
+
+/**
+ * The installed jui predates what the tool asks for. Matched on argparse's
+ * own words, as printed by the jui versions that lack each piece (measured
+ * 2026-10-18: jui 1.9.37 has no `viz`; feature/jui-viz before `start` has
+ * neither `start` nor `status --with-relay`).
+ */
+const OUTDATED: { pattern: RegExp; missing: string }[] = [
+  { pattern: /invalid choice: 'viz'/, missing: "`jui viz`" },
+  { pattern: /invalid choice: 'start'/, missing: "`jui viz start`" },
+  { pattern: /unrecognized arguments: .*--with-relay/, missing: "`jui viz status --with-relay`" },
+];
+
+export function outdatedJui(result: CliResult): string | undefined {
+  const hit = OUTDATED.find((o) => o.pattern.test(result.stderr));
+  if (!hit) return undefined;
+  return `The installed jui has no ${hit.missing}. Update jui, then call this tool again: ${UPDATE_JUI}`;
+}
+
+export async function runViz(args: string[], timeout?: number): Promise<CliResult> {
+  return runCli("jui", ["viz", ...args], { cwd: homedir(), timeout });
+}
+
+/** The tool's text: the CLI's JSON (when it printed one) inside the usual envelope. */
+export function vizResult(result: CliResult): string {
+  let parsed: unknown = undefined;
+  try {
+    parsed = JSON.parse(result.stdout);
+  } catch {
+    // not JSON (stop / open print a line)
+  }
+  const notInstalled = (result.exitCode as unknown) === "ENOENT";
+  return JSON.stringify(
+    {
+      success: result.exitCode === 0,
+      result: parsed,
+      output: parsed === undefined ? result.stdout || undefined : undefined,
+      errors: result.stderr || undefined,
+      update_jui: notInstalled
+        ? `jui is not installed (not found on PATH). Install it: ${UPDATE_JUI}`
+        : outdatedJui(result),
+    },
+    null,
+    2
+  );
+}

package/src/tools/viz/viz_doctor.ts

@@ -0,0 +1,20 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CLAUDE_CODE_ONLY, runViz, vizResult } from "./viz_common.js";
+
+export function register(server: McpServer) {
+  server.tool(
+    "viz_doctor",
+    "Check the environment for jui viz (the local viewer of Claude Code sessions): Python packages, the hooks and " +
+      "the Python they run, the port, the claude CLI. Each check has name, ok and detail. " +
+      CLAUDE_CODE_ONLY,
+    {},
+    async () => {
+      try {
+        const result = await runViz(["doctor", "--json"], 30_000);
+        return { content: [{ type: "text", text: vizResult(result) }] };
+      } catch (e: any) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+      }
+    }
+  );
+}

package/src/tools/viz/viz_open.ts

@@ -0,0 +1,20 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CLAUDE_CODE_ONLY, runViz, vizResult } from "./viz_common.js";
+
+export function register(server: McpServer) {
+  server.tool(
+    "viz_open",
+    "Open the running jui viz page (the local viewer of Claude Code sessions) in the user's browser. " +
+      "Fails when no server runs: call viz_start first. " +
+      CLAUDE_CODE_ONLY,
+    {},
+    async () => {
+      try {
+        const result = await runViz(["open"], 30_000);
+        return { content: [{ type: "text", text: vizResult(result) }] };
+      } catch (e: any) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+      }
+    }
+  );
+}

package/src/tools/viz/viz_start.ts

@@ -0,0 +1,27 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { CLAUDE_CODE_ONLY, runViz, vizResult } from "./viz_common.js";
+
+export function register(server: McpServer) {
+  server.tool(
+    "viz_start",
+    "Start the jui viz server (the local viewer of Claude Code sessions) in the background and return its URL " +
+      "on 127.0.0.1. A server already running is reported (alreadyRunning), not started again. Hooks and the " +
+      "relay are installed with the jui CLI, not here. " +
+      CLAUDE_CODE_ONLY,
+    {
+      port: z.number().int().min(1).max(65535).optional().describe("Port on 127.0.0.1 (default: the viz config, 7788)"),
+    },
+    async (params) => {
+      try {
+        const args = ["start", "--json"];
+        if (params.port !== undefined) { args.push("--port", String(params.port)); }
+        // jui waits up to 15 s for the server to answer.
+        const result = await runViz(args, 45_000);
+        return { content: [{ type: "text", text: vizResult(result) }] };
+      } catch (e: any) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+      }
+    }
+  );
+}

package/src/tools/viz/viz_status.ts

@@ -0,0 +1,27 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { CLAUDE_CODE_ONLY, runViz, vizResult } from "./viz_common.js";
+
+export function register(server: McpServer) {
+  server.tool(
+    "viz_status",
+    "Report jui viz (the local viewer of Claude Code sessions): whether its server runs (pid, URL), the hooks in " +
+      "~/.claude/settings.json (installed of 18), and whether the permission relay is registered. " +
+      CLAUDE_CODE_ONLY,
+    {
+      relay: z.boolean().optional().describe(
+        "Also ask claude whether the permission relay is registered (default true; runs `claude mcp get`, a few seconds)"
+      ),
+    },
+    async (params) => {
+      try {
+        const args = ["status", "--json"];
+        if (params.relay !== false) { args.push("--with-relay"); }
+        const result = await runViz(args, 30_000);
+        return { content: [{ type: "text", text: vizResult(result) }] };
+      } catch (e: any) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+      }
+    }
+  );
+}

package/src/tools/viz/viz_stop.ts

@@ -0,0 +1,19 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CLAUDE_CODE_ONLY, runViz, vizResult } from "./viz_common.js";
+
+export function register(server: McpServer) {
+  server.tool(
+    "viz_stop",
+    "Stop the jui viz server (the local viewer of Claude Code sessions). Only the server jui recorded is stopped. " +
+      CLAUDE_CODE_ONLY,
+    {},
+    async () => {
+      try {
+        const result = await runViz(["stop"], 30_000);
+        return { content: [{ type: "text", text: vizResult(result) }] };
+      } catch (e: any) {
+        return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+      }
+    }
+  );
+}

package/tests/fixtures/infra/RECORDED_FROM

@@ -0,0 +1 @@
+7479faaf infra arms: a load with warnings alone is cost infra's 0 (still counted), and a price dropped by two rows warns once

package/tests/fixtures/infra/check-infra.json

@@ -0,0 +1,101 @@
+{
+  "ok": true,
+  "exit": 0,
+  "checks": [
+    {
+      "name": "infra-load",
+      "type": "builtin:infra-load",
+      "status": "ok",
+      "summary": {
+        "ok": 10,
+        "mismatch": 0,
+        "missing_in_impl": 0,
+        "missing_in_doc": 0,
+        "skipped": 6,
+        "warning": 2,
+        "unit": "node"
+      },
+      "results": [
+        {
+          "target": "load/ordinary/stripe",
+          "status": "skipped",
+          "confidence": "metadata",
+          "message": "its kind reads no load"
+        },
+        {
+          "target": "load/ordinary/api-role",
+          "status": "skipped",
+          "confidence": "metadata",
+          "message": "its kind reads no load"
+        },
+        {
+          "target": "load/ordinary/api-5xx",
+          "status": "skipped",
+          "confidence": "metadata",
+          "message": "its kind reads no load"
+        },
+        {
+          "target": "load/sale/stripe",
+          "status": "skipped",
+          "confidence": "metadata",
+          "message": "its kind reads no load"
+        },
+        {
+          "target": "load/sale/mailer",
+          "status": "warning",
+          "confidence": "metadata",
+          "expected": "emails",
+          "message": "billed by use, but this load definition gives it no load (undefined, not 0)"
+        },
+        {
+          "target": "load/sale/assets",
+          "status": "warning",
+          "confidence": "metadata",
+          "expected": "get_requests, put_requests, storage_gb, egress_gb",
+          "message": "billed by use, but this load definition gives it no load (undefined, not 0)"
+        },
+        {
+          "target": "load/sale/api-role",
+          "status": "skipped",
+          "confidence": "metadata",
+          "message": "its kind reads no load"
+        },
+        {
+          "target": "load/sale/api-5xx",
+          "status": "skipped",
+          "confidence": "metadata",
+          "message": "its kind reads no load"
+        }
+      ],
+      "warnings": [],
+      "report": "/private<ROOT>/room/docs/infra/load/.check-report.infra-load.json"
+    },
+    {
+      "name": "infra-code",
+      "type": "builtin:infra-code",
+      "status": "ok",
+      "summary": {
+        "ok": 0,
+        "mismatch": 0,
+        "missing_in_impl": 0,
+        "missing_in_doc": 0,
+        "skipped": 0,
+        "warning": 1,
+        "unit": "reference"
+      },
+      "results": [
+        {
+          "target": "stripe/stripe#evidence/0",
+          "status": "warning",
+          "confidence": "proof",
+          "expected": "backend/app/config.py",
+          "message": "the evidence file is not there"
+        }
+      ],
+      "warnings": [
+        "[unverified] *: only Python and JavaScript / TypeScript imports, AWS SDK clients and environment variable names are read (not values, not calls): a service reached another way is not seen"
+      ],
+      "report": "/private<ROOT>/room/docs/infra/.check-report.infra-code.json"
+    }
+  ]
+}