@fitchmultz/pi-mcp-adapter 5.0.0 → 6.0.0

package/dist/tool-metadata.js

@@ -1,12 +1,13 @@
 import { getToolUiResourceUri } from "@modelcontextprotocol/ext-apps/app-bridge";
-import { formatToolName, isToolAllowed, resolveToolPrefix } from "./types.js";
+import { formatToolName, isServerDisabled, isToolAllowed, resolveToolPrefix } from "./types.js";
 import { resourceNameToToolName } from "./resource-tools.js";
 import { extractToolUiStreamMode } from "./utils.js";
 import { extractUiToolVisibility, isUiToolVisibleToModel } from "./ui-tool-visibility.js";
 export function buildToolMetadata(tools, resources, definition, serverName, prefix) {
     const metadata = [];
     const failedTools = [];
-    const seenNames = new Set();
+    if (isServerDisabled(definition))
+        return { metadata, failedTools };
     const effectivePrefix = resolveToolPrefix(definition, prefix);
     for (const tool of tools) {
         if (!tool?.name) {
@@ -17,14 +18,10 @@ export function buildToolMetadata(tools, resources, definition, serverName, pref
             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;
         try {
             uiResourceUri = getToolUiResourceUri({ _meta: tool._meta });
@@ -34,11 +31,10 @@ export function buildToolMetadata(tools, resources, definition, serverName, pref
         }
         const uiStreamMode = extractToolUiStreamMode(tool._meta);
         metadata.push({
+            ...tool,
             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 } : {}),
@@ -46,20 +42,19 @@ export function buildToolMetadata(tools, resources, definition, serverName, pref
     }
     if (definition.exposeResources !== false) {
         for (const resource of resources) {
+            if (!resource?.name || !resource?.uri)
+                continue;
             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,
+                resourceDescriptor: resource,
             });
         }
     }
@@ -68,18 +63,29 @@ export function buildToolMetadata(tools, resources, definition, serverName, pref
 export function totalToolCount(state) {
     let count = 0;
     for (const metadata of state.toolMetadata.values()) {
-        count += metadata.length;
+        count += metadata.filter(tool => tool.resourceUri === undefined).length;
     }
     return count;
 }
+export function toToolDescriptor(server, tool) {
+    const { name: path, originalName: name, resourceUri: _resourceUri, resourceDescriptor: _resourceDescriptor, uiResourceUri: _uiResourceUri, uiVisibility: _uiVisibility, uiStreamMode: _uiStreamMode, ...descriptor } = tool;
+    return { ...descriptor, server, path, name };
+}
+export function catalogCoverage(state, server) {
+    const servers = Object.keys(state.config.mcpServers).filter(name => (!server || name === server) && !isServerDisabled(state.config.mcpServers[name]));
+    const knownServers = servers.filter(name => state.toolMetadata.has(name));
+    const unknownServers = servers.filter(name => !state.toolMetadata.has(name));
+    return { complete: unknownServers.length === 0, knownServers, unknownServers };
+}
 export function findToolByName(metadata, toolName) {
     if (!metadata)
         return undefined;
-    const exact = metadata.find(m => m.name === toolName);
-    if (exact)
-        return exact;
+    const exact = metadata.filter(m => m.name === toolName);
+    if (exact.length > 0)
+        return exact.length === 1 ? exact[0] : undefined;
     const normalized = toolName.replace(/-/g, "_");
-    return metadata.find(m => m.name.replace(/-/g, "_") === normalized);
+    const matches = metadata.filter(m => m.name.replace(/-/g, "_") === normalized);
+    return matches.length === 1 ? matches[0] : undefined;
 }
 export function formatSchema(schema, indent = "  ") {
     if (!schema || typeof schema !== "object" || Array.isArray(schema)) {

package/dist/tool-registrar.d.ts

@@ -1,10 +1,10 @@
 import type { McpContent, ContentBlock } from "./types.ts";
+import { type McpPayloadFile } from "./mcp-output-guard.ts";
 /**
  * Transform MCP content types to Pi content blocks.
  */
 export declare function transformMcpContent(content: McpContent[]): ContentBlock[];
-/**
- * Resolve a tool result's content blocks, falling back to structuredContent
- * when content is empty.
- */
+/** Human content and structured content are complementary protocol fields. */
 export declare function resolveMcpResultContent(result: Record<string, unknown>): ContentBlock[];
+/** Persist content the model cannot consume; never imply an audio/blob payload was rendered. */
+export declare function renderMcpResultContent(result: Record<string, unknown>, payloadFiles?: McpPayloadFile[]): ContentBlock[];

package/dist/tool-registrar.js

@@ -1,6 +1,5 @@
-// 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).
+// MCP protocol content to model-visible content.
+import { formatMcpPayloadFile } from "./mcp-output-guard.js";
 /**
  * Transform MCP content types to Pi content blocks.
  */
@@ -18,7 +17,7 @@ export function transformMcpContent(content) {
         }
         if (c.type === "resource") {
             const resourceUri = c.resource?.uri ?? "(no URI)";
-            const resourceContent = c.resource?.text ?? (c.resource ? JSON.stringify(c.resource) : "(no content)");
+            const resourceContent = c.resource?.text ?? (c.resource?.blob !== undefined ? "[Binary content; not rendered]" : "(no content)");
             return {
                 type: "text",
                 text: `[Resource: ${resourceUri}]\n${resourceContent}`,
@@ -35,24 +34,30 @@ export function transformMcpContent(content) {
         if (c.type === "audio") {
             return {
                 type: "text",
-                text: `[Audio content: ${c.mimeType ?? "audio/*"}]`,
+                text: `[Audio content: ${c.mimeType ?? "audio/*"}; not rendered]`,
             };
         }
         return { type: "text", text: JSON.stringify(c) };
     });
 }
-/**
- * Resolve a tool result's content blocks, falling back to structuredContent
- * when content is empty.
- */
+/** Human content and structured content are complementary protocol fields. */
 export function resolveMcpResultContent(result) {
     const blocks = transformMcpContent((Array.isArray(result.content) ? result.content : []));
-    if (blocks.length > 0)
-        return blocks;
     if (result.structuredContent !== undefined) {
-        return [{ type: "text", text: stringifyStructuredContent(result.structuredContent) }];
+        blocks.push({ type: "text", text: stringifyStructuredContent(result.structuredContent) });
     }
-    return [];
+    return blocks;
+}
+/** Persist content the model cannot consume; never imply an audio/blob payload was rendered. */
+export function renderMcpResultContent(result, payloadFiles = []) {
+    const content = Array.isArray(result.contents)
+        ? result.contents.map(resource => typeof resource.text === "string" ? { type: "text", text: resource.text } : { type: "resource", resource })
+        : Array.isArray(result.content) ? result.content : [];
+    const rendered = content.map((block, index) => {
+        const file = payloadFiles.find(file => file.index === index);
+        return file ? { type: "text", text: formatMcpPayloadFile(file) } : block;
+    });
+    return resolveMcpResultContent({ ...result, content: rendered });
 }
 function stringifyStructuredContent(value) {
     try {

package/dist/tool-result-renderer.d.ts

@@ -10,6 +10,9 @@ export interface McpProxyToolCallInput {
     connect?: string;
     describe?: string;
     search?: string;
+    query?: string;
+    uri?: string;
+    ref?: string;
     includeSchemas?: boolean;
     server?: string;
     action?: string;

package/dist/tool-result-renderer.js

@@ -79,8 +79,15 @@ function hasUsefulObjectContent(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value) && Object.keys(value).length > 0;
 }
 export function formatMcpProxyToolCallLines(args, maxInputChars = DEFAULT_MAX_CALL_INPUT_CHARS) {
-    if (args.action === "ui-messages")
+    if (args.action === "ui-messages" || args.action === "status")
         return [`mcp ${args.action}`];
+    if (args.action) {
+        const target = args.tool ?? args.query ?? args.uri ?? args.ref;
+        let line = `mcp ${args.action}${target ? ` ${target}` : ""}${args.server ? `${target ? " @" : ""} ${args.server}` : ""}`;
+        if (args.action === "search" && args.includeSchemas === false)
+            line += " (schemas hidden)";
+        return args.action === "call" && args.args ? [line, formatJsonish(args.args, maxInputChars)] : [line];
+    }
     if (args.tool) {
         const target = args.server ? `${args.tool} @ ${args.server}` : args.tool;
         const lines = [`mcp call ${target}`];
@@ -102,8 +109,6 @@ export function formatMcpProxyToolCallLines(args, maxInputChars = DEFAULT_MAX_CA
     }
     if (args.server)
         return [`mcp list ${args.server}`];
-    if (args.action)
-        return [`mcp ${args.action}`];
     return ["mcp status"];
 }
 export function formatMcpDirectToolCallLines(displayName, args, maxInputChars = DEFAULT_MAX_CALL_INPUT_CHARS) {

package/dist/types.d.ts

@@ -13,6 +13,8 @@ export interface McpServerStatusSnapshot {
     readonly name: string;
     readonly status: McpServerRuntimeStatus;
     readonly toolCount: number;
+    /** False means the server has not been discovered, rather than an empty inventory. */
+    readonly catalogKnown?: boolean;
     readonly resourceCount?: number;
     readonly failedAgoSeconds?: number;
     readonly disabled: boolean;
@@ -30,21 +32,10 @@ type SdkTool = ListToolsResult["tools"][number];
 type SdkResource = ListResourcesResult["resources"][number];
 type SdkPrompt = ListPromptsResult["prompts"][number];
 type SdkPromptArgument = NonNullable<SdkPrompt["arguments"]>[number];
-export interface McpTool {
-    name: SdkTool["name"];
-    title?: SdkTool["title"];
-    description?: SdkTool["description"];
+export interface McpTool extends Omit<SdkTool, "inputSchema"> {
     inputSchema?: SdkTool["inputSchema"];
-    annotations?: SdkTool["annotations"];
-    _meta?: SdkTool["_meta"];
-}
-export interface McpResource {
-    uri: SdkResource["uri"];
-    name: SdkResource["name"];
-    description?: SdkResource["description"];
-    mimeType?: SdkResource["mimeType"];
-    _meta?: SdkResource["_meta"];
 }
+export type McpResource = SdkResource;
 export interface McpPromptArgument {
     name: SdkPromptArgument["name"];
     description?: SdkPromptArgument["description"];
@@ -327,7 +318,7 @@ export interface McpSettings {
     /** Freeze direct-tool registration after the initial sync. Automatic metadata updates
      * (reconnects, lazy-connect, tool-list-changed) won't rebuild the system prompt,
      * preserving the prompt-cache prefix. The agent rediscovers explicitly via
-     * mcp({ connect: "server" }). Default: false. */
+     * mcp({ action: "connect", server: "server" }). Default: false. */
     freezeDirectTools?: boolean;
     autoAuth?: boolean;
     sampling?: boolean;
@@ -411,15 +402,14 @@ export interface McpAdapterOptions {
     onToolCall?: (event: McpToolCallEvent) => Promise<void>;
 }
 export type ServerDefinition = ServerEntry;
-export interface ToolMetadata {
+export interface ToolMetadata extends Omit<McpTool, "name" | "description"> {
     name: string;
     originalName: string;
     description: string;
     resourceUri?: string;
+    resourceDescriptor?: McpResource;
     uiResourceUri?: string;
     uiVisibility?: UiToolVisibility[];
-    inputSchema?: unknown;
-    annotations?: McpTool["annotations"];
     uiStreamMode?: UiStreamMode;
 }
 export interface PromptMetadata {
@@ -430,16 +420,9 @@ export interface PromptMetadata {
     description: string;
     arguments: McpPromptArgument[];
 }
-export interface DirectToolSpec {
+export interface DirectToolSpec extends Omit<ToolMetadata, "name"> {
     serverName: string;
-    originalName: string;
     prefixedName: string;
-    description: string;
-    inputSchema?: unknown;
-    annotations?: McpTool["annotations"];
-    resourceUri?: string;
-    uiResourceUri?: string;
-    uiStreamMode?: UiStreamMode;
 }
 export interface ServerProvenance {
     path: string;
@@ -450,20 +433,12 @@ export interface McpAuthResult {
     ok: boolean;
     message?: string;
 }
-export interface CachedTool {
-    name: string;
-    description?: string;
-    inputSchema?: unknown;
-    annotations?: McpTool["annotations"];
+export interface CachedTool extends McpTool {
     uiResourceUri?: string;
     uiVisibility?: UiToolVisibility[];
-    uiStreamMode?: "eager" | "stream-first";
-}
-export interface CachedResource {
-    uri: string;
-    name: string;
-    description?: string;
+    uiStreamMode?: UiStreamMode;
 }
+export type CachedResource = McpResource;
 export interface CachedPrompt {
     name: string;
     title?: string;

package/dist/utils.js

@@ -246,11 +246,9 @@ export function truncateAtWord(text, target) {
     return truncated + "...";
 }
 export function normalizeDirectToolInputSchema(schema) {
-    const inputSchema = schema && typeof schema === "object" && !Array.isArray(schema)
-        ? schema
+    return schema && typeof schema === "object" && !Array.isArray(schema)
+        ? structuredClone(schema)
         : { type: "object", properties: {} };
-    const { $schema, additionalProperties, ...normalized } = inputSchema;
-    return normalized;
 }
 export function formatAuthRequiredMessage(config, serverName, defaultMessage) {
     const template = config.settings?.authRequiredMessage;

package/gateway-arguments.ts

@@ -0,0 +1,73 @@
+import { Type } from "typebox";
+import { MAX_PAGE_SIZE, MAX_TOOL_NAME_LENGTH } from "./search-ranking.ts";
+
+const actions = ["status", "search", "list", "describe", "call", "connect", "instructions", "resources", "read-resource", "read-result", "auth-start", "auth-complete", "ui-messages"] as const;
+export type GatewayArguments = {
+  action: typeof actions[number];
+  server?: string;
+  tool?: string;
+  args?: Record<string, unknown>;
+  query?: string;
+  includeSchemas?: boolean;
+  limit?: number;
+  offset?: number;
+  uri?: string;
+  ref?: string;
+  path?: string;
+  fields?: string[];
+};
+
+const requirements: Partial<Record<GatewayArguments["action"], string[]>> = {
+  search: ["query"], list: ["server"], describe: ["tool"], call: ["tool"],
+  connect: ["server"], instructions: ["server"], resources: ["server"],
+  "read-resource": ["server", "uri"], "read-result": ["ref"], "auth-start": ["server"], "auth-complete": ["server"],
+};
+
+export const gatewayParameters = Type.Object({
+  action: Type.Unsafe<GatewayArguments["action"]>({ type: "string", enum: [...actions] }),
+  server: Type.Optional(Type.String({ description: "MCP server; required for server and resource actions." })),
+  tool: Type.Optional(Type.String({ maxLength: MAX_TOOL_NAME_LENGTH, description: "Exact tool name for call or describe. Use server to disambiguate." })),
+  args: Type.Optional(Type.Object({}, { additionalProperties: true, description: "Tool arguments, or {redirectUrl} for auth-complete." })),
+  query: Type.Optional(Type.String({ description: "Search terms. Prefer mcp_search to discover and load tools." })),
+  includeSchemas: Type.Optional(Type.Boolean({ description: "Include complete schemas in search results (default true)." })),
+  limit: Type.Optional(Type.Integer({ minimum: 1, description: "Page size (default 12, max 100); for read-result, characters of selected JSON." })),
+  offset: Type.Optional(Type.Integer({ minimum: 0, description: "Zero-based item offset; for read-result, character offset in selected JSON." })),
+  uri: Type.Optional(Type.String({ description: "Exact MCP resource URI for read-resource." })),
+  ref: Type.Optional(Type.String({ description: "Saved result reference returned by an earlier MCP call; read-result never calls the server again." })),
+  path: Type.Optional(Type.String({ description: "JSON Pointer into a saved result, e.g. /structuredContent/rows." })),
+  fields: Type.Optional(Type.Array(Type.String(), { description: "Immediate object fields to retain when reading a saved result." })),
+}, {
+  additionalProperties: false,
+  allOf: [
+    ...Object.entries(requirements).map(([action, required]) => ({ if: { properties: { action: { const: action } } }, then: { required } })),
+    { if: { properties: { action: { enum: ["search", "list", "connect", "resources"] } } }, then: { properties: { limit: { maximum: MAX_PAGE_SIZE } } } },
+  ],
+});
+
+/** Migrate stored v5 calls before host validation; the advertised schema stays explicit. */
+export function prepareGatewayArguments(input: unknown): GatewayArguments {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("MCP arguments must be an object");
+  const value = input as Record<string, unknown>;
+  let action = value.action;
+  const result = { ...value };
+  if (action === undefined) {
+    action = value.tool ? "call" : value.connect ? "connect" : value.describe ? "describe" : value.instructions ? "instructions" : value.search !== undefined ? "search" : value.server ? "list" : "status";
+    if (action === "connect") result.server = value.connect;
+    if (action === "describe") result.tool = value.describe;
+    if (action === "instructions") result.server = value.instructions;
+    if (action === "search") result.query = value.search;
+  }
+  for (const key of ["connect", "describe", "instructions", "search"]) delete result[key];
+  if (!actions.includes(action as GatewayArguments["action"])) throw new Error(`Unknown MCP action: ${String(action)}`);
+  result.action = action;
+  if (typeof result.args === "string") {
+    result.args = result.args === "" ? undefined : JSON.parse(result.args);
+  }
+  if (result.args !== undefined && (!result.args || typeof result.args !== "object" || Array.isArray(result.args))) {
+    throw new Error("Invalid args: expected a JSON object");
+  }
+  for (const field of requirements[action as GatewayArguments["action"]] ?? []) {
+    if (typeof result[field] !== "string" || (field !== "query" && result[field] === "")) throw new Error(`${action} requires ${field}`);
+  }
+  return result as GatewayArguments;
+}