@pi-archimedes/mcp 2.3.0

package/src/renderer.test.ts

@@ -0,0 +1,326 @@
+import { describe, it, expect, vi } from "vitest";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+  renderDirectCall,
+  renderDirectResult,
+  renderProxyCall,
+  renderProxyResult,
+  extractServerName,
+  formatProxyCallServer,
+} from "./renderer.js";
+
+// ── Mocks ───────────────────────────────────────────────────────────────────
+
+vi.mock("@earendil-works/pi-tui", () => {
+  class MockText {
+    private _content = "";
+
+    constructor(initial: string = "") {
+      this._content = initial;
+    }
+
+    setText(content: string): void {
+      this._content = content;
+    }
+
+    getContent(): string {
+      return this._content;
+    }
+  }
+  return {
+    Text: MockText,
+  };
+});
+
+// Same class the renderer's `instanceof Text` check sees (the mock).
+import { Text as MockText } from "@earendil-works/pi-tui";
+
+/** The runtime mock exposes getContent(); the real Text type does not. */
+type MockTextShim = { getContent(): string };
+
+// Fake theme: wraps text in visible markers so assertions can verify which
+// color token each fragment used.
+const theme = {
+  fg: (token: string, text?: string) =>
+    text === undefined ? `[${token}]` : `[${token}:${text}]`,
+  bold: (text: string) => `**${text}**`,
+} as unknown as Theme;
+
+// A theme whose fg() throws — renderers must never propagate errors.
+const throwingTheme = {
+  fg: () => {
+    throw new Error("theme exploded");
+  },
+  bold: (text: string) => text,
+} as unknown as Theme;
+
+// ── Shared fixtures ─────────────────────────────────────────────────────────
+
+const TOOL = "postgres_describe_table";
+const SERVER = "postgres";
+const ARGS = { schema: "public", table: "model_files" };
+const RESULT = { content: [{ type: "text", text: "Hello\nWorld" }] };
+
+// Line 1 header: blue bold "mcp" + orange server name.
+const HEADER = `[toolTitle:**mcp**] [accent:${SERVER}]`;
+
+function ctx(extra: Record<string, unknown> = {}): Record<string, unknown> {
+  return { ...extra };
+}
+
+// ── extractServerName ────────────────────────────────────────────────────────
+
+describe("extractServerName", () => {
+  it("takes the first segment before the underscore", () => {
+    expect(extractServerName("atlassian_searchJiraIssuesUsingJql")).toBe(
+      "atlassian",
+    );
+    expect(extractServerName("postgres_describe_table")).toBe("postgres");
+  });
+
+  it("returns the whole name when there is no underscore", () => {
+    expect(extractServerName("mcp")).toBe("mcp");
+  });
+});
+
+// ── formatProxyCallServer ────────────────────────────────────────────────────
+
+describe("formatProxyCallServer", () => {
+  it("extracts the server from the tool name", () => {
+    expect(formatProxyCallServer({ tool: "atlassian_search" })).toBe(
+      "atlassian",
+    );
+  });
+
+  it("prefers explicit args.server", () => {
+    expect(formatProxyCallServer({ tool: "atlassian_search", server: "s1" })).toBe(
+      "atlassian",
+    );
+    expect(formatProxyCallServer({ server: "s1" })).toBe("s1");
+  });
+
+  it("falls back to action words for non-tool calls", () => {
+    expect(formatProxyCallServer({ search: "jira" })).toBe("search");
+    expect(formatProxyCallServer({ describe: "t1" })).toBe("describe");
+    expect(formatProxyCallServer({ connect: "s1" })).toBe("connect");
+    expect(formatProxyCallServer({ action: "weird" })).toBe("weird");
+    expect(formatProxyCallServer({})).toBe("status");
+  });
+});
+
+// ── renderDirectCall ────────────────────────────────────────────────────────
+
+describe("renderDirectCall", () => {
+  const content = (c: unknown) => (c as unknown as MockTextShim).getContent();
+
+  it("renders the header only: blue mcp + orange server name", () => {
+    const out = renderDirectCall(TOOL, { ...ARGS }, theme, ctx());
+    expect(content(out)).toBe(HEADER);
+  });
+
+  it("never throws — degrades to plain text when the theme throws", () => {
+    const out = renderDirectCall(TOOL, { ...ARGS }, throwingTheme, ctx());
+    expect(content(out)).toBe(`mcp ${TOOL}`);
+  });
+
+  it("reuses the lastComponent instance", () => {
+    const last = new MockText("stale");
+    const out = renderDirectCall(TOOL, { ...ARGS }, theme, ctx({ lastComponent: last }));
+    expect(out).toBe(last);
+    expect(content(out)).toBe(HEADER);
+  });
+});
+
+// ── renderDirectResult ──────────────────────────────────────────────────────
+
+describe("renderDirectResult", () => {
+  const content = (c: unknown) => (c as unknown as MockTextShim).getContent();
+
+  it("collapsed success: green tick + muted tool name, NO result text", () => {
+    const out = renderDirectResult(
+      TOOL,
+      RESULT,
+      { expanded: false },
+      theme,
+      ctx({ isError: false, args: { ...ARGS } }),
+    );
+    expect(content(out)).toBe(`[success:✓ ][muted:${TOOL}]`);
+    expect(content(out)).not.toContain("Hello");
+  });
+
+  it("collapsed error: red cross + muted tool name", () => {
+    const out = renderDirectResult(
+      TOOL,
+      RESULT,
+      { expanded: false },
+      theme,
+      ctx({ isError: true, args: { ...ARGS } }),
+    );
+    expect(content(out)).toBe(`[error:✗ ][muted:${TOOL}]`);
+  });
+
+  it("isPartial: running glyph (muted) + muted tool name, no content", () => {
+    const out = renderDirectResult(
+      TOOL,
+      RESULT,
+      { isPartial: true },
+      theme,
+      ctx({ isError: false, args: { ...ARGS } }),
+    );
+    expect(content(out)).toBe(`[muted:▸ ][muted:${TOOL}]`);
+  });
+
+  it("expanded success: dim args JSON + blank line + full text", () => {
+    const out = renderDirectResult(
+      TOOL,
+      RESULT,
+      { expanded: true },
+      theme,
+      ctx({ isError: false, args: { ...ARGS } }),
+    );
+    expect(content(out)).toBe(
+      `[dim:{\n  "schema": "public",\n  "table": "model_files"\n}]\n\n` +
+        `[toolOutput:Hello]\n[toolOutput:World]`,
+    );
+  });
+
+  it("expanded error: full text in error colour", () => {
+    const out = renderDirectResult(
+      TOOL,
+      { content: [{ type: "text", text: "boom" }] },
+      { expanded: true },
+      theme,
+      ctx({ isError: true, args: { ...ARGS } }),
+    );
+    expect(content(out)).toBe(
+      `[dim:{\n  "schema": "public",\n  "table": "model_files"\n}]\n\n[error:boom]`,
+    );
+  });
+
+  it("expanded empty content: (empty result) after the args block", () => {
+    const out = renderDirectResult(
+      TOOL,
+      { content: [] },
+      { expanded: true },
+      theme,
+      ctx({ isError: false, args: { ...ARGS } }),
+    );
+    expect(content(out)).toBe(
+      `[dim:{\n  "schema": "public",\n  "table": "model_files"\n}]\n\n` +
+        `[muted:(empty result)]`,
+    );
+  });
+
+  it("expanded honours context.expanded when options.expanded is unset", () => {
+    const out = renderDirectResult(
+      TOOL,
+      RESULT,
+      {},
+      theme,
+      ctx({ isError: false, expanded: true, args: { ...ARGS } }),
+    );
+    expect(content(out)).toContain("[toolOutput:Hello]");
+  });
+
+  it("never throws — degrades to empty text when the theme throws", () => {
+    const out = renderDirectResult(
+      TOOL,
+      RESULT,
+      { expanded: false },
+      throwingTheme,
+      ctx({ isError: false, args: { ...ARGS } }),
+    );
+    expect(content(out)).toBe("");
+  });
+
+  it("reuses the lastComponent instance", () => {
+    const last = new MockText("stale");
+    const out = renderDirectResult(
+      TOOL,
+      RESULT,
+      { expanded: false },
+      theme,
+      ctx({ isError: false, args: { ...ARGS }, lastComponent: last }),
+    );
+    expect(out).toBe(last);
+    expect(content(out)).toBe(`[success:✓ ][muted:${TOOL}]`);
+  });
+});
+
+// ── renderProxyCall (gateway) ───────────────────────────────────────────────
+
+describe("renderProxyCall", () => {
+  const content = (c: unknown) => (c as unknown as MockTextShim).getContent();
+  const PROXY_ARGS = {
+    tool: "postgres_describe_table",
+    args: { table: "model_files" },
+  };
+
+  it("renders the header: blue mcp + orange server (from tool name)", () => {
+    const out = renderProxyCall({ ...PROXY_ARGS }, theme, ctx());
+    expect(content(out)).toBe(HEADER);
+  });
+
+  it("search action: header shows the action word", () => {
+    const out = renderProxyCall({ search: "jira" }, theme, ctx());
+    expect(content(out)).toBe("[toolTitle:**mcp**] [accent:search]");
+  });
+
+  it("never throws — degrades to plain 'mcp' when the theme throws", () => {
+    const out = renderProxyCall({ ...PROXY_ARGS }, throwingTheme, ctx());
+    expect(content(out)).toBe("mcp");
+  });
+});
+
+// ── renderProxyResult (gateway) ─────────────────────────────────────────────
+
+describe("renderProxyResult", () => {
+  const content = (c: unknown) => (c as unknown as MockTextShim).getContent();
+  const PROXY_CONTEXT_ARGS = {
+    tool: "postgres_describe_table",
+    args: { sql: "SELECT 1" },
+  };
+
+  it("collapsed success: green tick + muted tool name", () => {
+    const out = renderProxyResult(
+      { content: [{ type: "text", text: "out" }] },
+      { expanded: false },
+      theme,
+      ctx({ isError: false, args: { ...PROXY_CONTEXT_ARGS } }),
+    );
+    expect(content(out)).toBe(`[success:✓ ][muted:postgres_describe_table]`);
+  });
+
+  it("collapsed error: red cross + muted tool name", () => {
+    const out = renderProxyResult(
+      { content: [{ type: "text", text: "out" }] },
+      { expanded: false },
+      theme,
+      ctx({ isError: true, args: { ...PROXY_CONTEXT_ARGS } }),
+    );
+    expect(content(out)).toBe(`[error:✗ ][muted:postgres_describe_table]`);
+  });
+
+  it("expanded: formats ONLY the nested args.args (not the gateway args)", () => {
+    const out = renderProxyResult(
+      { content: [{ type: "text", text: "out" }] },
+      { expanded: true },
+      theme,
+      ctx({ isError: false, args: { ...PROXY_CONTEXT_ARGS } }),
+    );
+    expect(content(out)).toBe(
+      `[dim:{\n  "sql": "SELECT 1"\n}]\n\n[toolOutput:out]`,
+    );
+    expect(content(out)).not.toContain("describe_table\"");
+  });
+
+  it("no tool name (search action): falls back to 'mcp'", () => {
+    const out = renderProxyResult(
+      { content: [{ type: "text", text: "ok" }] },
+      { expanded: false },
+      theme,
+      ctx({ isError: false, args: { search: "jira" } }),
+    );
+    expect(content(out)).toBe(`[success:✓ ][muted:mcp]`);
+  });
+});

package/src/renderer.ts

@@ -0,0 +1,239 @@
+import { Text } from "@earendil-works/pi-tui";
+import type { Component } from "@earendil-works/pi-tui";
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+import { renderToolHeader, renderStatusLabel } from "@pi-archimedes/core/tool-render";
+
+// Local aliases — the real ToolRenderContext has many more fields but we
+// only use these in the renderer. Using a local type avoids over-constraining
+// signatures and keeps the renderer tolerant of older pi versions (missing
+// fields simply read as undefined). Exported so the registration wiring can
+// cast pi's untyped context to the same loose shape.
+export type RenderContext = {
+  lastComponent?: Component;
+  isError?: boolean;
+  expanded?: boolean;
+  isPartial?: boolean;
+  argsComplete?: boolean;
+  executionStarted?: boolean;
+  args?: unknown;
+  state?: Record<string, unknown>;
+};
+
+type ToolResult = {
+  content: Array<{ type: string; text?: string }>;
+  details?: Record<string, unknown>;
+};
+
+type RenderOptions = { expanded?: boolean; isPartial?: boolean };
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Extract server name from a tool name (first segment before "_").
+ * e.g. "atlassian_searchJiraIssuesUsingJql" → "atlassian"
+ * Falls back to the full name if no underscore.
+ */
+export function extractServerName(toolName: string): string {
+  const idx = toolName.indexOf("_");
+  return idx === -1 ? toolName : toolName.slice(0, idx);
+}
+
+/**
+ * Get the server label for the mcp proxy call header.
+ * Uses args.server if provided, otherwise extracts from args.tool.
+ * Falls back to a generic action word for non-tool calls.
+ */
+export function formatProxyCallServer(args: {
+  tool?: string;
+  search?: string;
+  describe?: string;
+  connect?: string;
+  server?: string;
+  action?: string;
+}): string {
+  if (args.tool) return extractServerName(args.tool);
+  if (args.server) return args.server;
+  if (args.search) return `search`;
+  if (args.describe) return `describe`;
+  if (args.connect) return `connect`;
+  if (args.action) return args.action;
+  return "status";
+}
+
+/**
+ * Render the mcp proxy tool call row.
+ *
+ * Line 1: `mcp` (bold toolTitle) + server name (accent)
+ *
+ * Never throws.
+ */
+export function renderProxyCall(
+  args: Record<string, unknown>,
+  theme: Theme,
+  context: RenderContext,
+): Component {
+  const text = reuseText(context);
+  try {
+    const server = formatProxyCallServer(
+      args as Parameters<typeof formatProxyCallServer>[0],
+    );
+    text.setText(renderToolHeader("mcp", server, theme));
+  } catch {
+    try {
+      text.setText("mcp");
+    } catch {
+      // keep whatever the component last rendered
+    }
+  }
+  return text;
+}
+
+/**
+ * Render the mcp proxy tool result row.
+ *
+ * - isPartial (streaming partial, defensive): ▸ tool name muted
+ * - collapsed (default): ▸/✓/✗ + full tool name (muted/success/error)
+ * - expanded: nested args as dim JSON + full result text
+ *
+ * Never throws.
+ */
+export function renderProxyResult(
+  result: ToolResult,
+  options: RenderOptions,
+  theme: Theme,
+  context: RenderContext,
+): Component {
+  const args = isPlainObject(context.args) ? context.args : null;
+  const toolName = (args?.["tool"] as string | undefined) ?? "mcp";
+  const expandedArgs = args ? args["args"] : undefined;
+  return renderStatusLine(result, options, theme, context, toolName, expandedArgs);
+}
+
+/**
+ * Render a direct tool call row (e.g. atlassian_searchJiraIssuesUsingJql).
+ *
+ * Line 1: `mcp` (bold toolTitle) + server name (accent)
+ *
+ * Never throws.
+ */
+export function renderDirectCall(
+  displayName: string,
+  args: Record<string, unknown>,
+  theme: Theme,
+  context: RenderContext,
+): Component {
+  const text = reuseText(context);
+  try {
+    const server = extractServerName(displayName);
+    text.setText(renderToolHeader("mcp", server, theme));
+  } catch {
+    try {
+      text.setText(`mcp ${displayName}`);
+    } catch {
+      // keep whatever the component last rendered
+    }
+  }
+  return text;
+}
+
+/**
+ * Render a direct tool result row.
+ * ▸/✓/✗ + full display name (muted/success/error)
+ */
+export function renderDirectResult(
+  displayName: string,
+  result: ToolResult,
+  options: RenderOptions,
+  theme: Theme,
+  context: RenderContext,
+): Component {
+  const args = isPlainObject(context.args) ? context.args : null;
+  return renderStatusLine(result, options, theme, context, displayName, args);
+}
+
+// ── Shared renderer core ─────────────────────────────────────────────────────
+
+/**
+ * Render the result row as:
+ *   ▸ toolName   (muted, while partial/running)
+ *   ✓ toolName   (success, green)
+ *   ✗ toolName   (error, red)
+ * When expanded: dim JSON args block + full result text.
+ */
+function renderStatusLine(
+  result: ToolResult,
+  options: RenderOptions,
+  theme: Theme,
+  context: RenderContext,
+  toolName: string,
+  expandedArgs: unknown,
+): Component {
+  const text = reuseText(context);
+  try {
+    const expanded = options.expanded ?? context.expanded ?? false;
+
+    if (expanded) {
+      const parts: string[] = [];
+      if (expandedArgs !== undefined && expandedArgs !== null) {
+        const block = formatArgs(expandedArgs, 1200);
+        if (block) parts.push(theme.fg("dim", block));
+      }
+      const lines = result.content
+        .filter((b) => b.type === "text")
+        .flatMap((b) => (b.text ?? "").split("\n"));
+      const token = context.isError ? "error" : "toolOutput";
+      parts.push(
+        lines.length === 0
+          ? theme.fg("muted", "(empty result)")
+          : lines.map((l) => theme.fg(token, l)).join("\n"),
+      );
+      text.setText(parts.join("\n\n"));
+      return text;
+    }
+
+    if (options.isPartial) {
+      text.setText(renderStatusLabel("running", toolName, theme));
+      return text;
+    }
+
+    text.setText(
+      renderStatusLabel(context.isError ? "error" : "success", toolName, theme),
+    );
+  } catch {
+    try {
+      text.setText("");
+    } catch {
+      // keep whatever the component last rendered
+    }
+  }
+  return text;
+}
+
+// ── Private helpers ──────────────────────────────────────────────────────────
+
+function reuseText(context: RenderContext): Text {
+  return (context.lastComponent instanceof Text
+    ? context.lastComponent
+    : new Text("", 0, 0)) as Text;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Format args as compact JSON, truncated to maxChars.
+ * Strings pass through unchanged; other values are JSON.stringify'd.
+ * Truncation appends "…".
+ */
+function formatArgs(args: unknown, maxChars: number): string {
+  try {
+    const s =
+      typeof args === "string" ? args : JSON.stringify(args, null, 2);
+    return s.length > maxChars ? s.slice(0, maxChars) + "…" : s;
+  } catch {
+    return String(args).slice(0, maxChars);
+  }
+}

package/src/schema-validator.test.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from "vitest";
+import type { jsonSchemaValidator, JsonSchemaType } from "@modelcontextprotocol/sdk/validation";
+import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv";
+import { TolerantJsonSchemaValidator } from "./schema-validator.js";
+
+// Minimal shape of the schema Stitch ships for `upload_design_md.outputSchema`:
+// `variantScreenInstance` self-references the enclosing type via `$defs`, but
+// `$defs` is never emitted at the root. Raw Ajv throws exactly
+// "can't resolve reference #/$defs/ScreenInstance from id #" on this.
+const BROKEN_SCREEN_INSTANCE = {
+  description: "An instance of a screen on the project.",
+  type: "object",
+  properties: {
+    label: { description: "Optional. The screen label.", type: "string" },
+    variantScreenInstance: {
+      $ref: "#/$defs/ScreenInstance",
+      description: "Optional. The variant Screen Instance.",
+    },
+  },
+} as JsonSchemaType;
+
+const VALID_SIMPLE = {
+  type: "object",
+  properties: { ok: { type: "boolean" } },
+} as JsonSchemaType;
+
+const okPass = (returnThis: unknown) => ({
+  getValidator: () => returnThis,
+}) as unknown as jsonSchemaValidator;
+
+describe("TolerantJsonSchemaValidator", () => {
+  it("delegates to the inner validator when compilation succeeds", () => {
+    const marker = (input: unknown) => ({ valid: true as const, data: input, errorMessage: undefined as undefined });
+    const wrapper = new TolerantJsonSchemaValidator(okPass(marker));
+    expect(wrapper.getValidator(VALID_SIMPLE)).toBe(marker);
+  });
+
+  it("delegates to a working inner Ajv validator by default", () => {
+    const wrapper = new TolerantJsonSchemaValidator();
+    const v = wrapper.getValidator(VALID_SIMPLE);
+    expect(v({ ok: true })).toMatchObject({ valid: true });
+  });
+
+  it("passes data through untouched when the inner compile throws", () => {
+    const raw = new AjvJsonSchemaValidator();
+    expect(() => raw.getValidator(BROKEN_SCREEN_INSTANCE)).toThrow(/can't resolve reference #\/\$defs\/ScreenInstance/);
+
+    const wrapper = new TolerantJsonSchemaValidator();
+    const v = wrapper.getValidator(BROKEN_SCREEN_INSTANCE);
+    expect(v({ anything: "goes" })).toEqual({
+      valid: true,
+      data: { anything: "goes" },
+      errorMessage: undefined,
+    });
+  });
+});

package/src/schema-validator.ts

@@ -0,0 +1,42 @@
+/** Tolerant JSON Schema validator provider for the MCP SDK client. */
+
+import type {
+	JsonSchemaType,
+	JsonSchemaValidator,
+	jsonSchemaValidator,
+} from "@modelcontextprotocol/sdk/validation";
+import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv";
+
+/**
+ * Wrapper around the SDK's Ajv-based `jsonSchemaValidator` that survives
+ * unsound server-supplied JSON schemas.
+ *
+ * The SDK pre-compiles every tool's `outputSchema` during `tools/list`
+ * (`Client#_cachedToolOutputValidators`), and a schema with an
+ * unresolvable `$ref` throws at compile time — rejecting the whole tool
+ * list and making all of that server's tools unusable.
+ *
+ * Known offender: Google's Stitch MCP (`upload_design_md.outputSchema`
+ * declares `properties.variantScreenInstance.$ref = "#/$defs/ScreenInstance"`
+ * but ships no `$defs` at the root of the schema).
+ *
+ * A schema that fails to compile degrades to a pass-through validator
+ * (structured output data is not validated) instead of taking down the
+ * server. Skipped silently — the schema is third-party and the same
+ * one would warn again on every reconnect.
+ */
+export class TolerantJsonSchemaValidator implements jsonSchemaValidator {
+	private readonly _inner: jsonSchemaValidator;
+
+	constructor(inner?: jsonSchemaValidator) {
+		this._inner = inner ?? new AjvJsonSchemaValidator();
+	}
+
+	getValidator<T>(schema: JsonSchemaType): JsonSchemaValidator<T> {
+		try {
+			return this._inner.getValidator<T>(schema);
+		} catch {
+			return (input: unknown) => ({ valid: true, data: input as T, errorMessage: undefined });
+		}
+	}
+}