feat(web/apps): spec-conformant Apps host + CLI/deep-link path for programmatic review

AGENTS.md

@@ -59,6 +59,8 @@ v2 is **not** an npm workspace — each client under `clients/*` keeps its own `
 
 After installing, `npm run build` builds all clients. The launcher scripts (`npm run web` / `web:dev`) run the built launcher, so build first; for day-to-day web iteration use `cd clients/web && npm run dev`.
 
+For automated MCP App review (CLI-first probe + one-shot web render), see [docs/mcp-app-review.md](docs/mcp-app-review.md).
+
 ## Repository & Project Board
 
 - **Repo**: https://github.com/modelcontextprotocol/inspector.git

clients/cli/__tests__/app-info.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect } from "vitest";
+import { runCli } from "./helpers/cli-runner.js";
+import { getTestMcpServerCommand } from "@modelcontextprotocol/inspector-test-server";
+
+/**
+ * The default test server has no MCP App tools, so this exercises the
+ * negative path: `--app-info` prints `{"hasApp":false,...}` on stdout and
+ * exits 2. The positive path is unit-tested at the `extractAppInfo` level
+ * (`clients/web/src/test/core/apps.test.ts`) and end-to-end via the
+ * `mcpAppDemo` fixture.
+ */
+describe("--app-info", () => {
+  it("rejects --app-info on a method other than tools/call or tools/list", async () => {
+    const { command, args } = getTestMcpServerCommand();
+    const result = await runCli([
+      command,
+      ...args,
+      "--method",
+      "resources/list",
+      "--app-info",
+    ]);
+    expect(result.exitCode).toBe(1);
+    expect(result.stderr).toContain(
+      "--app-info requires --method tools/call (with --tool-name) or --method tools/list",
+    );
+  });
+
+  it("emits NDJSON (one app-info line per tool) on --method tools/list --app-info", async () => {
+    const { command, args } = getTestMcpServerCommand();
+    const result = await runCli([
+      command,
+      ...args,
+      "--method",
+      "tools/list",
+      "--app-info",
+    ]);
+    expect(result.exitCode).toBe(0);
+    const lines = result.stdout.trim().split("\n");
+    expect(lines.length).toBeGreaterThan(1);
+    const infos = lines.map(
+      (l) => JSON.parse(l) as { hasApp: boolean; toolName: string },
+    );
+    // Every line is a valid app-info object with a toolName.
+    expect(infos.every((i) => typeof i.toolName === "string")).toBe(true);
+    // The fixture's `mcp_app_demo` is the (only) App tool.
+    const demo = infos.find((i) => i.toolName === "mcp_app_demo");
+    expect(demo?.hasApp).toBe(true);
+    expect(infos.filter((i) => i.hasApp).length).toBe(1);
+  });
+
+  it("emits {hasApp:false} as one JSON line and exits 2 for a non-App tool", async () => {
+    const { command, args } = getTestMcpServerCommand();
+    const result = await runCli([
+      command,
+      ...args,
+      "--method",
+      "tools/call",
+      "--tool-name",
+      "echo",
+      "--app-info",
+    ]);
+    expect(result.exitCode).toBe(2);
+    const line = result.stdout.trim().split("\n")[0];
+    const info = JSON.parse(line) as { hasApp: boolean; toolName: string };
+    expect(info).toEqual({ hasApp: false, toolName: "echo" });
+    expect(result.stderr).toContain("has no MCP App UI resource");
+  });
+
+  it("exits 5 (TOOL_ERROR, code:tool_not_found) when the tool is not found — distinct from the no-app exit-2", async () => {
+    const { command, args } = getTestMcpServerCommand();
+    const result = await runCli([
+      command,
+      ...args,
+      "--method",
+      "tools/call",
+      "--tool-name",
+      "no-such-tool",
+      "--app-info",
+    ]);
+    expect(result.exitCode).toBe(5);
+    expect(result.stdout).toBe("");
+    const envelope = JSON.parse(result.stderr.trim()) as {
+      error: { code: string };
+    };
+    expect(envelope.error.code).toBe("tool_not_found");
+  });
+
+  it("emits the resource-side csp/permissions and exits 0 for an App tool", async () => {
+    const { command, args } = getTestMcpServerCommand();
+    const result = await runCli([
+      command,
+      ...args,
+      "--method",
+      "tools/call",
+      "--tool-name",
+      "mcp_app_demo",
+      "--app-info",
+    ]);
+    expect(result.exitCode).toBe(0);
+    const info = JSON.parse(result.stdout.trim().split("\n")[0]) as {
+      hasApp: boolean;
+      toolName: string;
+      resourceUri: string;
+      csp: unknown;
+      permissions: unknown;
+      prefersBorder: boolean;
+      resourceMimeType: string;
+    };
+    expect(info.hasApp).toBe(true);
+    expect(info.toolName).toBe("mcp_app_demo");
+    expect(info.resourceUri).toBe("ui://demo/widget.html");
+    expect(info.csp).toEqual({ connectDomains: [], resourceDomains: [] });
+    expect(info.permissions).toEqual({ clipboard: false });
+    expect(info.prefersBorder).toBe(true);
+    expect(info.resourceMimeType).toBe("text/html");
+  });
+
+  it("does not collect app-info on a plain text-mode tools/call (use --format json or --app-info)", async () => {
+    const { command, args } = getTestMcpServerCommand();
+    const result = await runCli([
+      command,
+      ...args,
+      "--method",
+      "tools/call",
+      "--tool-name",
+      "mcp_app_demo",
+      "--tool-arg",
+      "title=hello",
+    ]);
+    expect(result.exitCode).toBe(0);
+    expect(result.stdout).not.toContain("--- MCP App Info ---");
+    expect(result.stdout).not.toContain("hasApp");
+    // stdout is now a single JSON value (the tool result) so `| jq` works.
+    expect(() => JSON.parse(result.stdout)).not.toThrow();
+  });
+
+  it("does not invoke the tool when --app-info is set", async () => {
+    // get_sum requires numeric a/b args; without --app-info this would fail
+    // with a tool error. With --app-info the tool is never called, so the
+    // only error is the no-app exit-2.
+    const { command, args } = getTestMcpServerCommand();
+    const result = await runCli([
+      command,
+      ...args,
+      "--method",
+      "tools/call",
+      "--tool-name",
+      "get_sum",
+      "--app-info",
+    ]);
+    expect(result.exitCode).toBe(2);
+    expect(result.output).not.toContain("isError");
+  });
+});

clients/cli/__tests__/error-handler.test.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect, vi, afterEach } from "vitest";
-import { handleError } from "../src/error-handler.js";
+import {
+  CliExitCodeError,
+  EXIT_CODES,
+  classifyError,
+  formatErrorOutput,
+  handleError,
+} from "../src/error-handler.js";
 
 /**
  * `handleError` is the binary's last-resort error sink (wired up in
@@ -13,33 +19,142 @@ describe("handleError", () => {
     vi.restoreAllMocks();
   });
 
-  it("logs an Error's message and exits with code 1", () => {
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  it("emits a JSON error envelope on stderr and exits with the classified code", () => {
+    const writeSpy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((() => true) as never);
     const exitSpy = vi
       .spyOn(process, "exit")
       .mockImplementation((() => undefined) as never);
 
     handleError(new Error("boom"));
 
-    expect(errorSpy).toHaveBeenCalledWith("boom");
-    expect(exitSpy).toHaveBeenCalledWith(1);
+    expect(exitSpy).toHaveBeenCalledWith(EXIT_CODES.USAGE);
+    const written = writeSpy.mock.calls[0]![0] as string;
+    const parsed = JSON.parse(written) as {
+      error: { code: string; message: string };
+    };
+    expect(parsed.error.code).toBe("error");
+    expect(parsed.error.message).toBe("boom");
   });
 
-  it("logs a string error verbatim", () => {
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-    vi.spyOn(process, "exit").mockImplementation((() => undefined) as never);
+  it("uses a CliExitCodeError's exitCode and envelope code", () => {
+    vi.spyOn(process.stderr, "write").mockImplementation((() => true) as never);
+    const exitSpy = vi
+      .spyOn(process, "exit")
+      .mockImplementation((() => undefined) as never);
 
-    handleError("plain failure");
+    handleError(
+      new CliExitCodeError(EXIT_CODES.NO_APP, "no app", { code: "no_app" }),
+    );
 
-    expect(errorSpy).toHaveBeenCalledWith("plain failure");
+    expect(exitSpy).toHaveBeenCalledWith(EXIT_CODES.NO_APP);
   });
+});
 
-  it("falls back to 'Unknown error' for non-Error, non-string values", () => {
-    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
-    vi.spyOn(process, "exit").mockImplementation((() => undefined) as never);
+describe("classifyError", () => {
+  it("classifies a 401 status as AUTH_REQUIRED", () => {
+    const err = Object.assign(new Error("Unauthorized"), { status: 401 });
+    const { exitCode, envelope } = classifyError(err, {
+      url: "https://x.example/mcp",
+    });
+    expect(exitCode).toBe(EXIT_CODES.AUTH_REQUIRED);
+    expect(envelope.code).toBe("auth_required");
+    expect(envelope.status).toBe(401);
+    expect(envelope.url).toBe("https://x.example/mcp");
+  });
+
+  it("classifies a WWW-Authenticate message as AUTH_REQUIRED without a status", () => {
+    const { exitCode } = classifyError(
+      new Error("Dynamic client registration failed: WWW-Authenticate Bearer"),
+    );
+    expect(exitCode).toBe(EXIT_CODES.AUTH_REQUIRED);
+  });
+
+  it("classifies ENOTFOUND / fetch failed as UNREACHABLE", () => {
+    const err = new Error("fetch failed");
+    (err as { cause?: unknown }).cause = new Error(
+      "getaddrinfo ENOTFOUND no.such.host",
+    );
+    const { exitCode, envelope } = classifyError(err);
+    expect(exitCode).toBe(EXIT_CODES.UNREACHABLE);
+    expect(envelope.cause).toContain("ENOTFOUND");
+  });
+
+  it("classifies a connection-refused cause as UNREACHABLE", () => {
+    const err = new Error("connect ECONNREFUSED 127.0.0.1:1");
+    expect(classifyError(err).exitCode).toBe(EXIT_CODES.UNREACHABLE);
+  });
+
+  it("falls back to USAGE for an unrecognized Error", () => {
+    expect(classifyError(new Error("something else")).exitCode).toBe(
+      EXIT_CODES.USAGE,
+    );
+  });
 
-    handleError({ unexpected: true });
+  it("handles a string error", () => {
+    const { exitCode, envelope } = classifyError("plain failure");
+    expect(exitCode).toBe(EXIT_CODES.USAGE);
+    expect(envelope.message).toBe("plain failure");
+  });
+
+  it("handles a non-Error, non-string value", () => {
+    const { envelope } = classifyError({ unexpected: true });
+    expect(envelope.message).toBe("Unknown error");
+  });
+
+  it("preserves a CliExitCodeError's explicit envelope code over the default", () => {
+    const { envelope } = classifyError(
+      new CliExitCodeError(EXIT_CODES.TOOL_ERROR, "x", {
+        code: "tool_not_found",
+      }),
+    );
+    expect(envelope.code).toBe("tool_not_found");
+  });
+
+  it("derives a default envelope code for a bare CliExitCodeError", () => {
+    expect(
+      classifyError(new CliExitCodeError(EXIT_CODES.UNREACHABLE, "x")).envelope
+        .code,
+    ).toBe("unreachable");
+    expect(
+      classifyError(new CliExitCodeError(EXIT_CODES.NO_APP, "x")).envelope.code,
+    ).toBe("no_app");
+    expect(
+      classifyError(new CliExitCodeError(EXIT_CODES.AUTH_REQUIRED, "x"))
+        .envelope.code,
+    ).toBe("auth_required");
+    expect(
+      classifyError(new CliExitCodeError(EXIT_CODES.TOOL_ERROR, "x")).envelope
+        .code,
+    ).toBe("tool_error");
+    expect(
+      classifyError(new CliExitCodeError(EXIT_CODES.USAGE, "x")).envelope.code,
+    ).toBe("error");
+  });
+
+  it("captures a non-Error cause as a string", () => {
+    const err = new Error("outer");
+    (err as { cause?: unknown }).cause = { reason: "blocked" };
+    const { envelope } = classifyError(err);
+    expect(envelope.cause).toBe("[object Object]");
+  });
+
+  it("reads a numeric SDK-style .code as an HTTP status", () => {
+    const err = Object.assign(new Error("forbidden"), { code: 403 });
+    const { exitCode, envelope } = classifyError(err);
+    expect(exitCode).toBe(EXIT_CODES.AUTH_REQUIRED);
+    expect(envelope.status).toBe(403);
+  });
+});
 
-    expect(errorSpy).toHaveBeenCalledWith("Unknown error");
+describe("formatErrorOutput", () => {
+  it("emits one JSON line on stderr ending in a newline", () => {
+    const { stderr, exitCode } = formatErrorOutput(new Error("nope"));
+    expect(stderr.endsWith("\n")).toBe(true);
+    expect(stderr.split("\n").length).toBe(2);
+    const parsed = JSON.parse(stderr) as { error: { message: string } };
+    expect(parsed.error.message).toBe("nope");
+    expect(exitCode).toBe(EXIT_CODES.USAGE);
   });
 });