jui-tools-mcp-server 2.15.11 → 2.16.0

package/README.md

@@ -46,7 +46,7 @@ bash ~/.jsonui-mcp-server/install.sh
 bash ~/.jsonui-mcp-server/uninstall.sh
 ```
 
-## Available Tools (46)
+## Available Tools (51)
 
 ### Group A: コンポーネント仕様参照 (9)
 
@@ -126,6 +126,20 @@ bash ~/.jsonui-mcp-server/uninstall.sh
 
 > `jsonui-test mock serve`（常駐 HTTP + run-target 実行）は RCE 面のため **MCP 非公開**（CLI 直叩き限定）。
 
+### Group G: jui viz (5)
+
+Claude Code のセッションを見るローカルのビューア（`jui viz`）。**Claude Code のセッションだけを見せる**（Codex など他のエージェントのセッションは出ない）。どれもホームフォルダで走り、`JUI_PROJECT_DIR` は使わない。
+
+| Tool | Description | CLI |
+|------|-------------|-----|
+| `viz_status` | サーバーが動いているか（pid・URL）、`~/.claude/settings.json` のフック（18 個中いくつ）、権限の中継が登録済みか（`relay=false` で中継の確認を省く） | `jui viz status --json [--with-relay]` |
+| `viz_doctor` | viz の環境の点検（Python パッケージ・フックとその Python・ポート・claude CLI） | `jui viz doctor --json` |
+| `viz_start` | サーバーをバックグラウンドで起動し、`/health` が応答したら URL を返す。動いていれば起動せずに `alreadyRunning` で返す | `jui viz start --json [--port N]` |
+| `viz_stop` | jui が記録したサーバーだけを止める | `jui viz stop` |
+| `viz_open` | 動いているサーバーのページをブラウザで開く（動いていなければ失敗。先に `viz_start`） | `jui viz open` |
+
+> フックと中継の導入（`jui viz hooks install` / `jui viz relay install`）は `~/.claude/settings.json` と利用者の MCP 設定を書くので **MCP 非公開**（CLI で行う）。jui が古いと（`viz` / `start` / `--with-relay` が無い）、結果の `update_jui` に更新の手順が出る。
+
 ## Testing
 
 単体テストは [vitest](https://vitest.dev/)（ESM ネイティブで本リポジトリのモジュール構成とそのまま噛み合うため採用）。

package/dist/index.js

@@ -46,6 +46,12 @@ import { register as registerDocGenerateComponent } from "./tools/doc/doc_genera
 import { register as registerDocGenerateHtml } from "./tools/doc/doc_generate_html.js";
 import { register as registerDocRulesInit } from "./tools/doc/doc_rules_init.js";
 import { register as registerDocRulesShow } from "./tools/doc/doc_rules_show.js";
+// --- Group G: jui viz (Claude Code sessions viewer) ---
+import { register as registerVizStatus } from "./tools/viz/viz_status.js";
+import { register as registerVizDoctor } from "./tools/viz/viz_doctor.js";
+import { register as registerVizStart } from "./tools/viz/viz_start.js";
+import { register as registerVizStop } from "./tools/viz/viz_stop.js";
+import { register as registerVizOpen } from "./tools/viz/viz_open.js";
 // --- Group F: jsonui-test CLI ---
 import { register as registerTestValidate } from "./tools/test/test_validate.js";
 import { register as registerTestGenerateScreen } from "./tools/test/test_generate_screen.js";
@@ -120,7 +126,7 @@ registerDocRulesShow(server, config);
 registerListApiSpecs(server, config);
 registerListApiModels(server, config);
 registerPreviewApiModelSync(server, config);
-// Register Group F: jsonui-test CLI (8 tools)
+// Register Group F: jsonui-test CLI (10 tools)
 // mock serve is intentionally NOT exposed (long-running local HTTP server that
 // executes run-targets — kept to direct CLI use only). test_mock_generate
 // covers both scaffold (default) and drift-check (check=true) modes.
@@ -134,7 +140,14 @@ registerTestMockGenerate(server, config);
 registerTestArtifactsPull(server, config);
 registerTestArtifactsStatus(server, config);
 registerTestContractsCoverage(server, config);
-log(`Registered 41 tools (7 spec + 6 context + 8 jui + 9 doc + 3 api + 8 test)`);
+// Register Group G: jui viz (5 tools). Hooks / relay install stay with the
+// jui CLI (they write ~/.claude/settings.json and the user's MCP config).
+registerVizStatus(server);
+registerVizDoctor(server);
+registerVizStart(server);
+registerVizStop(server);
+registerVizOpen(server);
+log(`Registered 51 tools (9 spec + 7 context + 8 jui + 9 doc + 3 api + 10 test + 5 viz)`);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/tools/viz/viz_common.d.ts

@@ -0,0 +1,13 @@
+import { 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 declare const CLAUDE_CODE_ONLY = "jui viz shows Claude Code sessions only (Claude Code \u306E\u30BB\u30C3\u30B7\u30E7\u30F3\u3060\u3051\u3092\u898B\u305B\u308B).";
+export declare const UPDATE_JUI = "curl -fsSL https://raw.githubusercontent.com/Tai-Kimura/jsonui-cli/main/installer/bootstrap.sh | bash";
+export declare function outdatedJui(result: CliResult): string | undefined;
+export declare function runViz(args: string[], timeout?: number): Promise<CliResult>;
+/** The tool's text: the CLI's JSON (when it printed one) inside the usual envelope. */
+export declare function vizResult(result: CliResult): string;

package/dist/tools/viz/viz_common.js

@@ -0,0 +1,50 @@
+import { homedir } from "os";
+import { runCli } 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: /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) {
+    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, timeout) {
+    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) {
+    let parsed = undefined;
+    try {
+        parsed = JSON.parse(result.stdout);
+    }
+    catch {
+        // not JSON (stop / open print a line)
+    }
+    const notInstalled = result.exitCode === "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/dist/tools/viz/viz_doctor.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function register(server: McpServer): void;

package/dist/tools/viz/viz_doctor.js

@@ -0,0 +1,14 @@
+import { CLAUDE_CODE_ONLY, runViz, vizResult } from "./viz_common.js";
+export function register(server) {
+    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) {
+            return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+    });
+}

package/dist/tools/viz/viz_open.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function register(server: McpServer): void;

package/dist/tools/viz/viz_open.js

@@ -0,0 +1,14 @@
+import { CLAUDE_CODE_ONLY, runViz, vizResult } from "./viz_common.js";
+export function register(server) {
+    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) {
+            return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+    });
+}

package/dist/tools/viz/viz_start.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function register(server: McpServer): void;

package/dist/tools/viz/viz_start.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { CLAUDE_CODE_ONLY, runViz, vizResult } from "./viz_common.js";
+export function register(server) {
+    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) {
+            return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+    });
+}

package/dist/tools/viz/viz_status.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function register(server: McpServer): void;

package/dist/tools/viz/viz_status.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { CLAUDE_CODE_ONLY, runViz, vizResult } from "./viz_common.js";
+export function register(server) {
+    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) {
+            return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+    });
+}

package/dist/tools/viz/viz_stop.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function register(server: McpServer): void;

package/dist/tools/viz/viz_stop.js

@@ -0,0 +1,13 @@
+import { CLAUDE_CODE_ONLY, runViz, vizResult } from "./viz_common.js";
+export function register(server) {
+    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) {
+            return { content: [{ type: "text", text: `Error: ${e.message}` }] };
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jui-tools-mcp-server",
-  "version": "2.15.11",
+  "version": "2.16.0",
   "description": "MCP server for JsonUI project management - wraps jui and jsonui-doc CLIs plus component spec lookup",
   "main": "dist/index.js",
   "scripts": {

package/src/index.ts

@@ -53,6 +53,13 @@ import { register as registerDocGenerateHtml } from "./tools/doc/doc_generate_ht
 import { register as registerDocRulesInit } from "./tools/doc/doc_rules_init.js";
 import { register as registerDocRulesShow } from "./tools/doc/doc_rules_show.js";
 
+// --- Group G: jui viz (Claude Code sessions viewer) ---
+import { register as registerVizStatus } from "./tools/viz/viz_status.js";
+import { register as registerVizDoctor } from "./tools/viz/viz_doctor.js";
+import { register as registerVizStart } from "./tools/viz/viz_start.js";
+import { register as registerVizStop } from "./tools/viz/viz_stop.js";
+import { register as registerVizOpen } from "./tools/viz/viz_open.js";
+
 // --- Group F: jsonui-test CLI ---
 import { register as registerTestValidate } from "./tools/test/test_validate.js";
 import { register as registerTestGenerateScreen } from "./tools/test/test_generate_screen.js";
@@ -144,7 +151,7 @@ registerListApiSpecs(server, config);
 registerListApiModels(server, config);
 registerPreviewApiModelSync(server, config);
 
-// Register Group F: jsonui-test CLI (8 tools)
+// Register Group F: jsonui-test CLI (10 tools)
 // mock serve is intentionally NOT exposed (long-running local HTTP server that
 // executes run-targets — kept to direct CLI use only). test_mock_generate
 // covers both scaffold (default) and drift-check (check=true) modes.
@@ -159,7 +166,15 @@ registerTestArtifactsPull(server, config);
 registerTestArtifactsStatus(server, config);
 registerTestContractsCoverage(server, config);
 
-log(`Registered 41 tools (7 spec + 6 context + 8 jui + 9 doc + 3 api + 8 test)`);
+// Register Group G: jui viz (5 tools). Hooks / relay install stay with the
+// jui CLI (they write ~/.claude/settings.json and the user's MCP config).
+registerVizStatus(server);
+registerVizDoctor(server);
+registerVizStart(server);
+registerVizStop(server);
+registerVizOpen(server);
+
+log(`Registered 51 tools (9 spec + 7 context + 8 jui + 9 doc + 3 api + 10 test + 5 viz)`);
 
 async function main() {
   const transport = new StdioServerTransport();

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/tool_count.test.ts

@@ -0,0 +1,53 @@
+/**
+ * The tool count is written in two places by hand — the startup log in
+ * src/index.ts and the README's "Available Tools (N)" with one "(n)" per
+ * group — and the log said 41 (8 test) for a while after the server had
+ * 46 (10 test). Both are checked against the tools the source registers:
+ * one `server.tool(` per file under src/tools/<group>/, and one register call
+ * per tool in index.ts.
+ */
+import { readdirSync, readFileSync } from "fs";
+import { join } from "path";
+import { describe, expect, it } from "vitest";
+
+const ROOT = join(__dirname, "..");
+const GROUPS = ["spec", "context", "jui", "doc", "api", "test", "viz"]; // README Groups A..G, in order
+
+function registeredIn(group: string): string[] {
+  const dir = join(ROOT, "src", "tools", group);
+  const names: string[] = [];
+  for (const file of readdirSync(dir).filter((f) => f.endsWith(".ts"))) {
+    const text = readFileSync(join(dir, file), "utf-8");
+    for (const m of text.matchAll(/server\.tool\(\s*"([a-z_]+)"/g)) names.push(m[1]);
+  }
+  return names;
+}
+
+const counts = Object.fromEntries(GROUPS.map((g) => [g, registeredIn(g).length]));
+const total = Object.values(counts).reduce((a, b) => a + b, 0);
+
+describe("tool count", () => {
+  it("every tool directory is a known group", () => {
+    const dirs = readdirSync(join(ROOT, "src", "tools"), { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+    expect(dirs.sort()).toEqual([...GROUPS].sort());
+  });
+
+  it("index.ts registers each tool once and its log line says how many, per group", () => {
+    const index = readFileSync(join(ROOT, "src", "index.ts"), "utf-8");
+    expect(index.match(/^register[A-Za-z]+\(server(, (config|loader))?\);$/gm)!.length).toBe(total);
+    const line = index.match(/Registered (\d+) tools \(([^)]*)\)/);
+    expect(line).not.toBeNull();
+    expect(Number(line![1])).toBe(total);
+    expect(line![2]).toBe(GROUPS.map((g) => `${counts[g]} ${g}`).join(" + "));
+  });
+
+  it("the README says the same", () => {
+    const readme = readFileSync(join(ROOT, "README.md"), "utf-8");
+    expect(readme.match(/^## Available Tools \((\d+)\)$/m)![1]).toBe(String(total));
+    const headers = [...readme.matchAll(/^### Group ([A-Z]): .*\((\d+)\)$/gm)];
+    expect(headers.map((h) => h[1])).toEqual(GROUPS.map((_, i) => String.fromCharCode(65 + i)));
+    expect(headers.map((h) => Number(h[2]))).toEqual(GROUPS.map((g) => counts[g]));
+  });
+});

package/tests/tools_viz.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Group G (jui viz) tool wrappers. child_process is mocked: the tests pin the
+ * argv each tool builds, that it runs in the home folder (never the project
+ * dir), the envelope it returns, and the update hint for a jui that predates
+ * viz / start / --with-relay. The stderr samples are what those jui versions
+ * print, copied from real runs (2026-10-18), not written from memory.
+ */
+import { homedir } from "os";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const execFileMock = vi.hoisted(() => vi.fn());
+vi.mock("child_process", () => ({ execFile: execFileMock }));
+vi.mock("node:child_process", () => ({ execFile: execFileMock }));
+
+import { register as registerVizStatus } from "../src/tools/viz/viz_status.js";
+import { register as registerVizDoctor } from "../src/tools/viz/viz_doctor.js";
+import { register as registerVizStart } from "../src/tools/viz/viz_start.js";
+import { register as registerVizStop } from "../src/tools/viz/viz_stop.js";
+import { register as registerVizOpen } from "../src/tools/viz/viz_open.js";
+import { cleanupTempDirs, createToolHarness, makeTempDir, type ToolHarness } from "./helpers.js";
+
+type ExecCallback = (error: any, stdout: string, stderr: string) => void;
+
+let recorded: { command: string; args: string[]; options: Record<string, any> }[];
+let nextResponse: { error?: any; stdout?: string; stderr?: string };
+let harness: ToolHarness;
+
+const VIZ_TOOLS = ["viz_status", "viz_doctor", "viz_start", "viz_stop", "viz_open"];
+
+// jui 1.9.37 (no viz at all)
+const NO_VIZ =
+  "usage: jui [-h] [--version]\n" +
+  "           {init,i,generate,g,build,b,verify,migrate-layouts,lint-generated,lint-strings,ls,sync_tool,hotload,conformance,screens} ...\n" +
+  "jui: error: argument command: invalid choice: 'viz' (choose from init, i, generate, g, build, b, verify, migrate-layouts, lint-generated, lint-strings, ls, sync_tool, hotload, conformance, screens)\n";
+// feature/jui-viz b69ac616 (viz, but no start)
+const NO_START =
+  "usage: jui viz [-h]\n" +
+  "               {serve,status,stop,open,doctor,hooks,export-demo,relay} ...\n" +
+  "jui viz: error: argument viz_cmd: invalid choice: 'start' (choose from serve, status, stop, open, doctor, hooks, export-demo, relay)\n";
+// the same jui, asked for status --with-relay
+const NO_WITH_RELAY =
+  "usage: jui [-h] [--version]\n" +
+  "           {init,i,generate,g,build,b,verify,migrate-layouts,lint-generated,lint-strings,ls,sync_tool,hotload,conformance,screens,viz} ...\n" +
+  "jui: error: unrecognized arguments: --with-relay\n";
+
+function failWithCode(code: number | string, stdout = "", stderr = ""): void {
+  nextResponse = { error: Object.assign(new Error(`exit ${code}`), { code }), stdout, stderr };
+}
+
+beforeEach(() => {
+  recorded = [];
+  nextResponse = {};
+  execFileMock.mockReset();
+  execFileMock.mockImplementation((command: string, args: string[], options: any, callback: ExecCallback) => {
+    recorded.push({ command, args, options });
+    callback(nextResponse.error ?? null, nextResponse.stdout ?? "", nextResponse.stderr ?? "");
+    return { stdin: { end() {} } };
+  });
+  harness = createToolHarness();
+  registerVizStatus(harness.server);
+  registerVizDoctor(harness.server);
+  registerVizStart(harness.server);
+  registerVizStop(harness.server);
+  registerVizOpen(harness.server);
+});
+
+afterEach(() => {
+  delete process.env.JUI_PROJECT_DIR;
+  cleanupTempDirs();
+});
+
+describe("viz tools", () => {
+  it("every description says only Claude Code sessions are shown", () => {
+    expect([...harness.tools.keys()]).toEqual(VIZ_TOOLS);
+    for (const name of VIZ_TOOLS) {
+      expect(harness.tools.get(name)!.description).toContain("Claude Code のセッションだけを見せる");
+    }
+  });
+
+  it.each([
+    ["viz_status", {}, ["viz", "status", "--json", "--with-relay"]],
+    ["viz_status", { relay: true }, ["viz", "status", "--json", "--with-relay"]],
+    ["viz_status", { relay: false }, ["viz", "status", "--json"]],
+    ["viz_doctor", {}, ["viz", "doctor", "--json"]],
+    ["viz_start", {}, ["viz", "start", "--json"]],
+    ["viz_start", { port: 18011 }, ["viz", "start", "--json", "--port", "18011"]],
+    ["viz_stop", {}, ["viz", "stop"]],
+    ["viz_open", {}, ["viz", "open"]],
+  ])("%s %j runs jui %j in the home folder, not the project", async (tool, params, argv) => {
+    process.env.JUI_PROJECT_DIR = makeTempDir("project");
+    await harness.call(tool, params);
+    expect(recorded).toHaveLength(1);
+    expect(recorded[0].command).toBe("jui");
+    expect(recorded[0].args).toEqual(argv);
+    expect(recorded[0].options.cwd).toBe(homedir());
+    expect(recorded[0].options.cwd).not.toBe(process.env.JUI_PROJECT_DIR);
+  });
+
+  it("viz_start waits longer than jui's own 15 s", async () => {
+    await harness.call("viz_start");
+    expect(recorded[0].options.timeout).toBeGreaterThan(15_000);
+  });
+
+  it("viz_start rejects a port outside 1-65535 before running anything", async () => {
+    await expect(harness.call("viz_start", { port: 0 })).rejects.toThrow();
+    await expect(harness.call("viz_start", { port: 70000 })).rejects.toThrow();
+    expect(execFileMock).not.toHaveBeenCalled();
+  });
+
+  it("passes the CLI's JSON through as result", async () => {
+    const started = { running: true, alreadyRunning: false, pid: 4242, url: "http://127.0.0.1:18011/", log: "/h/serve.log" };
+    nextResponse = { stdout: JSON.stringify(started) + "\n" };
+    expect(JSON.parse(await harness.call("viz_start"))).toEqual({ success: true, result: started });
+  });
+
+  it("a failed start keeps the CLI's JSON and reports failure, with no update hint", async () => {
+    const failed = { running: false, error: "jui viz serve が終了しました（終了コード 1）", logTail: "ポート 18011 は使用中です" };
+    failWithCode(1, JSON.stringify(failed));
+    expect(JSON.parse(await harness.call("viz_start"))).toEqual({ success: false, result: failed });
+  });
+
+  it("a line that is not JSON comes back as output", async () => {
+    nextResponse = { stdout: "jui viz: 止めました (pid 4242)\n" };
+    expect(JSON.parse(await harness.call("viz_stop"))).toEqual({ success: true, output: "jui viz: 止めました (pid 4242)\n" });
+  });
+
+  it.each([
+    ["viz_status", {}, NO_VIZ, "`jui viz`"],
+    ["viz_start", {}, NO_VIZ, "`jui viz`"],
+    ["viz_start", {}, NO_START, "`jui viz start`"],
+    ["viz_status", {}, NO_WITH_RELAY, "`jui viz status --with-relay`"],
+  ])("%s on an old jui names what is missing and how to update", async (tool, params, stderr, missing) => {
+    failWithCode(2, "", stderr);
+    const parsed = JSON.parse(await harness.call(tool, params));
+    expect(parsed.success).toBe(false);
+    expect(parsed.errors).toBe(stderr);
+    expect(parsed.update_jui).toBe(
+      `The installed jui has no ${missing}. Update jui, then call this tool again: ` +
+        "curl -fsSL https://raw.githubusercontent.com/Tai-Kimura/jsonui-cli/main/installer/bootstrap.sh | bash"
+    );
+  });
+
+  it("another argparse error is not taken for an old jui", async () => {
+    failWithCode(2, "", "jui viz: error: argument --port: invalid int value: 'x'\n");
+    expect(JSON.parse(await harness.call("viz_start")).update_jui).toBeUndefined();
+  });
+
+  it("no jui on PATH says so", async () => {
+    failWithCode("ENOENT");
+    const parsed = JSON.parse(await harness.call("viz_status"));
+    expect(parsed.success).toBe(false);
+    expect(parsed.update_jui).toMatch(/^jui is not installed \(not found on PATH\)\. Install it: curl /);
+  });
+});