@fitchmultz/pi-mcp-adapter 5.0.0

package/tool-metadata.ts

@@ -0,0 +1,235 @@
+import { getToolUiResourceUri } from "@modelcontextprotocol/ext-apps/app-bridge";
+import type { McpExtensionState } from "./state.ts";
+import type { ToolMetadata, McpTool, McpResource, ServerEntry, ToolPrefix } from "./types.ts";
+import { formatToolName, isToolAllowed, resolveToolPrefix } from "./types.ts";
+import { resourceNameToToolName } from "./resource-tools.ts";
+import { extractToolUiStreamMode } from "./utils.ts";
+import { extractUiToolVisibility, isUiToolVisibleToModel } from "./ui-tool-visibility.ts";
+
+export function buildToolMetadata(
+  tools: McpTool[],
+  resources: McpResource[],
+  definition: ServerEntry,
+  serverName: string,
+  prefix: ToolPrefix
+): { metadata: ToolMetadata[]; failedTools: string[] } {
+  const metadata: ToolMetadata[] = [];
+  const failedTools: string[] = [];
+  const seenNames = new Set<string>();
+  const effectivePrefix = resolveToolPrefix(definition, prefix);
+
+  for (const tool of tools) {
+    if (!tool?.name) {
+      failedTools.push("(unnamed)");
+      continue;
+    }
+    if (!isToolAllowed(tool.name, serverName, effectivePrefix, definition.includeTools, definition.excludeTools)) {
+      continue;
+    }
+
+    const name = formatToolName(tool.name, serverName, effectivePrefix);
+    if (seenNames.has(name)) {
+      continue;
+    }
+
+    const uiVisibility = extractUiToolVisibility(tool._meta);
+    if (!isUiToolVisibleToModel(uiVisibility)) {
+      continue;
+    }
+    seenNames.add(name);
+
+    let uiResourceUri: string | undefined;
+    try {
+      uiResourceUri = getToolUiResourceUri({ _meta: tool._meta });
+    } catch {
+      failedTools.push(tool.name);
+    }
+    const uiStreamMode = extractToolUiStreamMode(tool._meta);
+    metadata.push({
+      name,
+      originalName: tool.name,
+      description: tool.description ?? "",
+      ...(tool.inputSchema !== undefined ? { inputSchema: tool.inputSchema } : {}),
+      ...(tool.annotations !== undefined ? { annotations: tool.annotations } : {}),
+      ...(uiResourceUri !== undefined ? { uiResourceUri } : {}),
+      ...(uiVisibility !== undefined ? { uiVisibility } : {}),
+      ...(uiStreamMode !== undefined ? { uiStreamMode } : {}),
+    });
+  }
+
+  if (definition.exposeResources !== false) {
+    for (const resource of resources) {
+      const baseName = `read_${resourceNameToToolName(resource.name)}`;
+      if (!isToolAllowed(baseName, serverName, effectivePrefix, definition.includeTools, definition.excludeTools)) {
+        continue;
+      }
+
+      const name = formatToolName(baseName, serverName, effectivePrefix);
+      if (seenNames.has(name)) {
+        continue;
+      }
+      seenNames.add(name);
+
+      metadata.push({
+        name,
+        originalName: baseName,
+        description: resource.description ?? `Read resource: ${resource.uri}`,
+        resourceUri: resource.uri,
+      });
+    }
+  }
+
+  return { metadata, failedTools };
+}
+
+export function totalToolCount(state: McpExtensionState): number {
+  let count = 0;
+  for (const metadata of state.toolMetadata.values()) {
+    count += metadata.length;
+  }
+  return count;
+}
+
+export function findToolByName(metadata: ToolMetadata[] | undefined, toolName: string): ToolMetadata | undefined {
+  if (!metadata) return undefined;
+  const exact = metadata.find(m => m.name === toolName);
+  if (exact) return exact;
+  const normalized = toolName.replace(/-/g, "_");
+  return metadata.find(m => m.name.replace(/-/g, "_") === normalized);
+}
+
+export function formatSchema(schema: unknown, indent = "  "): string {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    return `${indent}(no schema)`;
+  }
+
+  const s = schema as Record<string, unknown>;
+
+  if (s.type === "object" && s.properties && typeof s.properties === "object" && !Array.isArray(s.properties)) {
+    const props = s.properties as Record<string, unknown>;
+    const required = Array.isArray(s.required) ? s.required.filter((name): name is string => typeof name === "string") : [];
+
+    if (Object.keys(props).length === 0) {
+      return `${indent}(no parameters)`;
+    }
+
+    const lines: string[] = [];
+    for (const [name, propSchema] of Object.entries(props)) {
+      lines.push(...formatProperty(name, propSchema, required.includes(name), indent));
+    }
+    return lines.join("\n");
+  }
+
+  const lines = formatNestedSchema(s, indent);
+  if (lines.length > 0) {
+    return lines.join("\n");
+  }
+
+  const typeStr = formatType(s);
+  if (typeStr) {
+    return `${indent}(${typeStr})`;
+  }
+
+  return `${indent}(complex schema)`;
+}
+
+function formatProperty(name: string, schema: unknown, required: boolean, indent: string): string[] {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    return [`${indent}${name}${required ? " *required*" : ""}`];
+  }
+
+  const s = schema as Record<string, unknown>;
+  const parts = [`${indent}${name}`];
+  const typeStr = formatType(s);
+  if (typeStr) parts.push(`(${typeStr})`);
+  if (required) parts.push("*required*");
+  appendSchemaAnnotations(parts, s);
+
+  return [parts.join(" "), ...formatNestedSchema(s, `${indent}  `)];
+}
+
+function formatNestedSchema(schema: Record<string, unknown>, indent: string): string[] {
+  const lines: string[] = [];
+
+  if (Array.isArray(schema.anyOf)) {
+    lines.push(...formatVariants("anyOf", schema.anyOf, indent));
+  }
+  if (Array.isArray(schema.oneOf)) {
+    lines.push(...formatVariants("oneOf", schema.oneOf, indent));
+  }
+  if (schema.items !== undefined) {
+    lines.push(...formatProperty("items", schema.items, false, indent));
+  }
+  if (schema.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties)) {
+    const required = Array.isArray(schema.required) ? schema.required.filter((name): name is string => typeof name === "string") : [];
+    for (const [name, propSchema] of Object.entries(schema.properties as Record<string, unknown>)) {
+      lines.push(...formatProperty(name, propSchema, required.includes(name), indent));
+    }
+  }
+
+  return lines;
+}
+
+function formatVariants(keyword: "anyOf" | "oneOf", variants: unknown[], indent: string): string[] {
+  const lines = [`${indent}${keyword}:`];
+
+  for (const variant of variants) {
+    if (!variant || typeof variant !== "object" || Array.isArray(variant)) {
+      lines.push(`${indent}  - ${JSON.stringify(variant)}`);
+      continue;
+    }
+
+    const s = variant as Record<string, unknown>;
+    const typeStr = formatType(s) || "schema";
+    const parts = [`${indent}  - ${typeStr}`];
+    appendSchemaAnnotations(parts, s);
+    lines.push(parts.join(" "));
+    lines.push(...formatNestedSchema(s, `${indent}    `));
+  }
+
+  return lines;
+}
+
+function formatType(schema: Record<string, unknown>): string {
+  if (Object.hasOwn(schema, "const")) {
+    return `const ${JSON.stringify(schema.const)}`;
+  }
+
+  if (Array.isArray(schema.enum)) {
+    return `enum: ${schema.enum.map(v => JSON.stringify(v)).join(", ")}`;
+  }
+
+  if (Array.isArray(schema.type)) {
+    return schema.type.map(type => String(type)).join(" | ");
+  }
+
+  if (schema.type) {
+    return String(schema.type);
+  }
+
+  if (schema.properties && typeof schema.properties === "object" && !Array.isArray(schema.properties)) {
+    return "object";
+  }
+
+  if (schema.items !== undefined) {
+    return "array";
+  }
+
+  return "";
+}
+
+function appendSchemaAnnotations(parts: string[], schema: Record<string, unknown>): void {
+  if (schema.description && typeof schema.description === "string") {
+    parts.push(`- ${schema.description}`);
+  }
+
+  for (const key of ["minLength", "maxLength", "minimum", "maximum", "minItems", "maxItems", "format", "pattern"] as const) {
+    if (schema[key] !== undefined) {
+      parts.push(`[${key}: ${JSON.stringify(schema[key])}]`);
+    }
+  }
+
+  if (schema.default !== undefined) {
+    parts.push(`[default: ${JSON.stringify(schema.default)}]`);
+  }
+}

package/tool-registrar.ts

@@ -0,0 +1,69 @@
+// tool-registrar.ts - MCP content transformation
+// NOTE: Tools are NOT registered with Pi - only the unified `mcp` proxy tool is registered.
+// This keeps the LLM context small (1 tool instead of 100s).
+
+import type { McpContent, ContentBlock } from "./types.ts";
+
+/**
+ * Transform MCP content types to Pi content blocks.
+ */
+export function transformMcpContent(content: McpContent[]): ContentBlock[] {
+  return content.map(c => {
+    if (c.type === "text") {
+      return { type: "text" as const, text: c.text ?? "" };
+    }
+    if (c.type === "image") {
+      return {
+        type: "image" as const,
+        data: c.data ?? "",
+        mimeType: c.mimeType ?? "image/png",
+      };
+    }
+    if (c.type === "resource") {
+      const resourceUri = c.resource?.uri ?? "(no URI)";
+      const resourceContent = c.resource?.text ?? (c.resource ? JSON.stringify(c.resource) : "(no content)");
+      return {
+        type: "text" as const,
+        text: `[Resource: ${resourceUri}]\n${resourceContent}`,
+      };
+    }
+    if (c.type === "resource_link") {
+      const linkName = c.name ?? c.uri ?? "unknown";
+      const linkUri = c.uri ?? "(no URI)";
+      return {
+        type: "text" as const,
+        text: `[Resource Link: ${linkName}]\nURI: ${linkUri}`,
+      };
+    }
+    if (c.type === "audio") {
+      return {
+        type: "text" as const,
+        text: `[Audio content: ${c.mimeType ?? "audio/*"}]`,
+      };
+    }
+    return { type: "text" as const, text: JSON.stringify(c) };
+  });
+}
+
+/**
+ * Resolve a tool result's content blocks, falling back to structuredContent
+ * when content is empty.
+ */
+export function resolveMcpResultContent(result: Record<string, unknown>): ContentBlock[] {
+  const blocks = transformMcpContent((Array.isArray(result.content) ? result.content : []) as McpContent[]);
+  if (blocks.length > 0) return blocks;
+
+  if (result.structuredContent !== undefined) {
+    return [{ type: "text" as const, text: stringifyStructuredContent(result.structuredContent) }];
+  }
+
+  return [];
+}
+
+function stringifyStructuredContent(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}

package/tool-result-renderer.ts

@@ -0,0 +1,286 @@
+import { keyHint, type AgentToolResult, type Theme, type ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { type Component, Text } from "@earendil-works/pi-tui";
+
+type McpToolResultDetails = Record<string, unknown> & { error?: unknown };
+type McpToolContentBlock = AgentToolResult<McpToolResultDetails>["content"][number];
+
+type RenderTheme = Pick<Theme, "fg" | "bold">;
+
+const plainTheme: RenderTheme = {
+  fg: (_name, text) => text,
+  bold: (text) => text,
+};
+
+export interface McpProxyToolCallInput {
+  tool?: string;
+  args?: string | object;
+  connect?: string;
+  describe?: string;
+  search?: string;
+  includeSchemas?: boolean;
+  server?: string;
+  action?: string;
+}
+
+interface McpToolRenderContext {
+  isError: boolean;
+}
+
+export interface McpToolResultDisplay {
+  lines: string[];
+  truncated: boolean;
+}
+
+const DEFAULT_MAX_CALL_INPUT_CHARS = 1500;
+const DEFAULT_MAX_COLLAPSED_LINES = 3;
+const DEFAULT_MAX_COLLAPSED_CHARS = 8000;
+const COLLAPSED_RENDER_CHAR_SLACK = 8;
+
+class CollapsibleText implements Component {
+  private readonly fullText: Text;
+  private readonly footerText: Text;
+  private collapsedText: { charBudget: number; fullyIncluded: boolean; text: Text } | null = null;
+
+  constructor(
+    private readonly text: string,
+    private readonly expanded: boolean,
+    private readonly maxCollapsedLines: number,
+    private readonly ellipsis: string,
+    private readonly expandHint: string,
+    private readonly preTruncated = false,
+  ) {
+    this.fullText = new Text(text, 0, 0);
+    this.footerText = new Text(`${ellipsis}\n${expandHint}`, 0, 0);
+  }
+
+  render(width: number): string[] {
+    if (this.expanded) {
+      return this.fullText.render(width);
+    }
+
+    const safeWidth = Math.max(1, Math.floor(width));
+    const charBudget = safeWidth * (this.maxCollapsedLines + 1) * COLLAPSED_RENDER_CHAR_SLACK;
+    if (!this.collapsedText || this.collapsedText.charBudget !== charBudget) {
+      const prefix = this.text.length > charBudget
+        ? this.text.slice(0, charBudget)
+        : this.text;
+      this.collapsedText = {
+        charBudget,
+        fullyIncluded: prefix === this.text,
+        text: new Text(prefix, 0, 0),
+      };
+    }
+
+    const lines = this.collapsedText.text.render(width);
+    if (!this.preTruncated && this.collapsedText.fullyIncluded && lines.length <= this.maxCollapsedLines) return lines;
+
+    return [
+      ...lines.slice(0, this.maxCollapsedLines),
+      ...this.footerText.render(width),
+    ];
+  }
+
+  invalidate(): void {}
+}
+
+function truncateText(value: string, maxChars: number): string {
+  if (value.length <= maxChars) return value;
+  return `${value.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+
+function formatJsonish(value: unknown, maxChars: number): string {
+  if (typeof value === "string") {
+    try {
+      return truncateText(JSON.stringify(JSON.parse(value), null, 2), maxChars);
+    } catch {
+      return truncateText(value, maxChars);
+    }
+  }
+
+  try {
+    return truncateText(JSON.stringify(value, null, 2), maxChars);
+  } catch {
+    return truncateText(String(value), maxChars);
+  }
+}
+
+function hasUsefulObjectContent(value: unknown): boolean {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && Object.keys(value).length > 0;
+}
+
+export function formatMcpProxyToolCallLines(
+  args: McpProxyToolCallInput,
+  maxInputChars = DEFAULT_MAX_CALL_INPUT_CHARS,
+): string[] {
+  if (args.action === "ui-messages") return [`mcp ${args.action}`];
+
+  if (args.tool) {
+    const target = args.server ? `${args.tool} @ ${args.server}` : args.tool;
+    const lines = [`mcp call ${target}`];
+    if (args.args) lines.push(formatJsonish(args.args, maxInputChars));
+    return lines;
+  }
+
+  if (args.connect) return [`mcp connect ${args.connect}`];
+  if (args.describe) return [`mcp describe ${args.describe}`];
+
+  if (args.search) {
+    let line = `mcp search ${args.search}`;
+    if (args.server) line += ` @ ${args.server}`;
+    if (args.includeSchemas === false) line += " (schemas hidden)";
+    return [line];
+  }
+
+  if (args.server) return [`mcp list ${args.server}`];
+  if (args.action) return [`mcp ${args.action}`];
+
+  return ["mcp status"];
+}
+
+export function formatMcpDirectToolCallLines(
+  displayName: string,
+  args: Record<string, unknown>,
+  maxInputChars = DEFAULT_MAX_CALL_INPUT_CHARS,
+): string[] {
+  if (!hasUsefulObjectContent(args)) return [displayName];
+  return [displayName, formatJsonish(args, maxInputChars)];
+}
+
+function renderToolCallLines(lines: string[], theme?: RenderTheme) {
+  const activeTheme = theme ?? plainTheme;
+  const [title = "mcp", ...rest] = lines;
+  const styledTitle = activeTheme.fg("toolTitle", activeTheme.bold(title));
+  const styledRest = rest.map(line => activeTheme.fg("muted", line));
+  return new Text([styledTitle, ...styledRest].join("\n"), 0, 0);
+}
+
+export function renderMcpProxyToolCall(args: McpProxyToolCallInput, theme?: RenderTheme) {
+  return renderToolCallLines(formatMcpProxyToolCallLines(args), theme);
+}
+
+export function createMcpDirectToolCallRenderer(displayName: string) {
+  return (args: Record<string, unknown>, theme?: RenderTheme) => {
+    return renderToolCallLines(formatMcpDirectToolCallLines(displayName, args), theme);
+  };
+}
+
+function blockToLines(block: McpToolContentBlock): string[] {
+  if (block.type === "text") {
+    return block.text.split("\n");
+  }
+  return [`[image: ${block.mimeType}]`];
+}
+
+function collectCollapsedResultLines(
+  content: AgentToolResult<McpToolResultDetails>["content"],
+  maxLines: number,
+  maxChars: number,
+): McpToolResultDisplay {
+  if (content.length === 0) return { lines: ["(empty result)"], truncated: false };
+
+  const lines: string[] = [];
+  let remainingChars = maxChars;
+  let truncated = false;
+
+  const appendLine = (line: string) => {
+    if (lines.length >= maxLines || remainingChars <= 0) {
+      truncated = true;
+      return false;
+    }
+
+    if (line.length > remainingChars) {
+      lines.push(line.slice(0, remainingChars));
+      truncated = true;
+      remainingChars = 0;
+      return false;
+    }
+
+    lines.push(line);
+    remainingChars -= line.length + 1;
+    return true;
+  };
+
+  for (const block of content) {
+    if (block.type !== "text") {
+      if (!appendLine(`[image: ${block.mimeType}]`)) break;
+      continue;
+    }
+
+    let start = 0;
+    while (start <= block.text.length) {
+      const newline = block.text.indexOf("\n", start);
+      const line = newline === -1 ? block.text.slice(start) : block.text.slice(start, newline);
+      if (!appendLine(line)) break;
+      if (newline === -1) break;
+      start = newline + 1;
+    }
+
+    if (truncated) break;
+  }
+
+  if (lines.length === 0) lines.push("");
+  if (truncated && lines.length >= maxLines) lines.push("…");
+  return { lines, truncated };
+}
+
+export function formatMcpToolResultIdentity(details: McpToolResultDetails | undefined): string | null {
+  if (details?.mode !== "call") return null;
+  const server = typeof details.server === "string"
+    ? details.server
+    : typeof details.hintServer === "string"
+      ? details.hintServer
+      : null;
+  if (!server) return null;
+  if (typeof details.tool === "string") return `MCP ${server}/${details.tool}`;
+  if (typeof details.resourceUri === "string") return `MCP ${server} resource ${details.resourceUri}`;
+  if (typeof details.requestedTool === "string") return `MCP ${server}/${details.requestedTool}`;
+  return null;
+}
+
+export function formatMcpToolResultLines(
+  result: Pick<AgentToolResult<McpToolResultDetails>, "content">,
+  expanded: boolean,
+  maxCollapsedLines = 3,
+  maxCollapsedChars = DEFAULT_MAX_COLLAPSED_CHARS,
+): McpToolResultDisplay {
+  if (!expanded) {
+    return collectCollapsedResultLines(result.content, maxCollapsedLines, maxCollapsedChars);
+  }
+
+  const allLines = result.content.flatMap(blockToLines);
+  const lines = allLines.length > 0 ? allLines : ["(empty result)"];
+  return { lines, truncated: false };
+}
+
+export function renderMcpToolResult(
+  result: AgentToolResult<unknown>,
+  options: ToolRenderResultOptions,
+  theme?: RenderTheme,
+  context?: McpToolRenderContext,
+) {
+  const activeTheme = theme ?? plainTheme;
+  if (options.isPartial) {
+    return new Text(activeTheme.fg("warning", "Running MCP tool..."), 0, 0);
+  }
+
+  const details = typeof result.details === "object" && result.details !== null
+    ? result.details as McpToolResultDetails
+    : {};
+  const hasErrorDetails = Boolean(details.error);
+  const expanded = options.expanded || context?.isError === true || hasErrorDetails;
+  const display = formatMcpToolResultLines(result, expanded);
+  const identity = formatMcpToolResultIdentity(details);
+  const output = [
+    ...(identity ? [activeTheme.fg("muted", identity)] : []),
+    ...display.lines.map((line) => activeTheme.fg("toolOutput", line)),
+  ].join("\n");
+
+  return new CollapsibleText(
+    output,
+    expanded,
+    DEFAULT_MAX_COLLAPSED_LINES + (identity ? 1 : 0),
+    activeTheme.fg("muted", "…"),
+    activeTheme.fg("muted", `(${keyHint("app.tools.expand", "to expand")})`),
+    display.truncated,
+  );
+}