@f5-sales-demo/xcsh 19.51.2

package/src/mcp/tool-bridge.ts

@@ -0,0 +1,417 @@
+/**
+ * MCP to CustomTool bridge.
+ *
+ * Converts MCP tool definitions to CustomTool format for the agent.
+ */
+
+import type { AgentToolUpdateCallback } from "@f5xc-salesdemos/pi-agent-core";
+import { sanitizeSchemaForMCP } from "@f5xc-salesdemos/pi-ai/utils/schema";
+import { untilAborted } from "@f5xc-salesdemos/pi-utils";
+import type { TSchema } from "@sinclair/typebox";
+import type { SourceMeta } from "../capability/types";
+import type {
+	CustomTool,
+	CustomToolContext,
+	CustomToolResult,
+	RenderResultOptions,
+} from "../extensibility/custom-tools/types";
+import type { Theme } from "../modes/theme/theme";
+import { ToolAbortError, throwIfAborted } from "../tools/tool-errors";
+import { callTool } from "./client";
+import { renderMCPCall, renderMCPResult } from "./render";
+import type { MCPContent, MCPServerConnection, MCPToolCallParams, MCPToolCallResult, MCPToolDefinition } from "./types";
+
+/** Reconnect callback: tears down stale connection, returns new one or null. */
+export type MCPReconnect = () => Promise<MCPServerConnection | null>;
+
+/**
+ * Network-level and stale-session errors that warrant a reconnect + single retry.
+ * Conservative: only catches errors where the server is likely alive but the
+ * connection object is stale (dead SSE, expired session, refused after restart).
+ */
+const RETRIABLE_PATTERNS = [
+	"econnrefused",
+	"econnreset",
+	"epipe",
+	"enetunreach",
+	"ehostunreach",
+	"fetch failed",
+	"transport not connected",
+	"transport closed",
+	"network error",
+];
+
+export function isRetriableConnectionError(error: unknown): boolean {
+	if (!(error instanceof Error)) return false;
+	const msg = error.message.toLowerCase();
+	// Stale session (server restarted, old session ID is gone)
+	if (/^http (404|502|503):/.test(msg)) return true;
+	return RETRIABLE_PATTERNS.some(p => msg.includes(p));
+}
+
+type MCPToolArgs = NonNullable<MCPToolCallParams["arguments"]>;
+
+function normalizeToolArgs(value: unknown): MCPToolArgs {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		return {};
+	}
+	return value as MCPToolArgs;
+}
+
+/** Details included in MCP tool results for rendering */
+export interface MCPToolDetails {
+	/** Server name */
+	serverName: string;
+	/** Original MCP tool name */
+	mcpToolName: string;
+	/** Whether the call resulted in an error */
+	isError?: boolean;
+	/** Raw content from MCP response */
+	rawContent?: MCPContent[];
+	/** Provider ID (e.g., "xcsh", "mcp-json") */
+	provider?: string;
+	/** Provider display name (e.g., "xcsh", "MCP Config") */
+	providerName?: string;
+}
+/**
+ * Format MCP content for LLM consumption.
+ */
+function formatMCPContent(content: MCPContent[]): string {
+	const parts: string[] = [];
+
+	for (const item of content) {
+		switch (item.type) {
+			case "text":
+				parts.push(item.text);
+				break;
+			case "image":
+				parts.push(`[Image: ${item.mimeType}]`);
+				break;
+			case "resource":
+				if (item.resource.text) {
+					parts.push(`[Resource: ${item.resource.uri}]\n${item.resource.text}`);
+				} else {
+					parts.push(`[Resource: ${item.resource.uri}]`);
+				}
+				break;
+		}
+	}
+
+	return parts.join("\n\n");
+}
+
+/** Build a CustomToolResult from a callTool response. */
+function buildResult(
+	result: MCPToolCallResult,
+	serverName: string,
+	mcpToolName: string,
+	provider?: string,
+	providerName?: string,
+): CustomToolResult<MCPToolDetails> {
+	const text = formatMCPContent(result.content);
+	const details: MCPToolDetails = {
+		serverName,
+		mcpToolName,
+		isError: result.isError,
+		rawContent: result.content,
+		provider,
+		providerName,
+	};
+	if (result.isError) {
+		return { content: [{ type: "text", text: `Error: ${text}` }], details };
+	}
+	return { content: [{ type: "text", text }], details };
+}
+
+/** Build an error CustomToolResult from a caught exception. */
+function buildErrorResult(
+	error: unknown,
+	serverName: string,
+	mcpToolName: string,
+	provider?: string,
+	providerName?: string,
+): CustomToolResult<MCPToolDetails> {
+	const message = error instanceof Error ? error.message : String(error);
+	return {
+		content: [{ type: "text", text: `MCP error: ${message}` }],
+		details: { serverName, mcpToolName, isError: true, provider, providerName },
+	};
+}
+
+/** Re-throw abort-related errors so they bypass error-result handling. */
+function rethrowIfAborted(error: unknown, signal?: AbortSignal): void {
+	if (error instanceof ToolAbortError) throw error;
+	if (error instanceof Error && error.name === "AbortError") throw new ToolAbortError();
+	if (signal?.aborted) throw new ToolAbortError();
+}
+
+async function reconnectWithAbort(reconnect: MCPReconnect, signal?: AbortSignal): Promise<MCPServerConnection | null> {
+	try {
+		return await untilAborted(signal, reconnect);
+	} catch (error) {
+		rethrowIfAborted(error, signal);
+		return null;
+	}
+}
+
+/**
+ * Create a unique tool name for an MCP tool.
+ *
+ * Prefixes with server name to avoid conflicts. If the tool name already
+ * starts with the server name (e.g., server "puppeteer" with tool
+ * "puppeteer_screenshot"), strips the redundant prefix to produce
+ * "mcp_puppeteer_screenshot" instead of "mcp_puppeteer_puppeteer_screenshot".
+ */
+function sanitizeMCPToolNamePart(value: string, fallback: string): string {
+	const sanitized = value
+		.toLowerCase()
+		.replace(/[^a-z_]+/g, "_")
+		.replace(/_+/g, "_")
+		.replace(/^_+|_+$/g, "");
+
+	return sanitized.length > 0 ? sanitized : fallback;
+}
+
+export function createMCPToolName(serverName: string, toolName: string): string {
+	const sanitizedServerName = sanitizeMCPToolNamePart(serverName, "server");
+	const sanitizedToolName = sanitizeMCPToolNamePart(toolName, "tool");
+
+	// Strip redundant server name prefix from tool name if present
+	const prefixWithUnderscore = `${sanitizedServerName}_`;
+
+	let normalizedToolName = sanitizedToolName;
+	if (sanitizedToolName.startsWith(prefixWithUnderscore)) {
+		normalizedToolName = sanitizedToolName.slice(prefixWithUnderscore.length);
+	}
+
+	return `mcp_${sanitizedServerName}_${normalizedToolName}`;
+}
+
+/**
+ * Parse an MCP tool name back to server and tool components.
+ *
+ * Note: This returns the normalized tool name (with server prefix stripped).
+ * The original MCP tool name may have had the server name as a prefix.
+ */
+export function parseMCPToolName(name: string): { serverName: string; toolName: string } | null {
+	if (!name.startsWith("mcp_")) return null;
+
+	const rest = name.slice(4);
+	const underscoreIdx = rest.indexOf("_");
+	if (underscoreIdx === -1) return null;
+
+	return {
+		serverName: rest.slice(0, underscoreIdx),
+		toolName: rest.slice(underscoreIdx + 1),
+	};
+}
+
+/**
+ * CustomTool wrapping an MCP tool with an active connection.
+ */
+export class MCPTool implements CustomTool<TSchema, MCPToolDetails> {
+	readonly name: string;
+	readonly label: string;
+	readonly description: string;
+	readonly parameters: TSchema;
+	/** Original MCP tool name (before normalization) */
+	readonly mcpToolName: string;
+	/** Server name */
+	readonly mcpServerName: string;
+
+	/** Create MCPTool instances for all tools from an MCP server connection */
+	static fromTools(connection: MCPServerConnection, tools: MCPToolDefinition[], reconnect?: MCPReconnect): MCPTool[] {
+		return tools.map(tool => new MCPTool(connection, tool, reconnect));
+	}
+
+	constructor(
+		private connection: MCPServerConnection,
+		private readonly tool: MCPToolDefinition,
+		private readonly reconnect?: MCPReconnect,
+	) {
+		this.name = createMCPToolName(connection.name, tool.name);
+		this.label = `${connection.name}/${tool.name}`;
+		this.description = tool.description ?? `MCP tool from ${connection.name}`;
+		this.parameters = sanitizeSchemaForMCP(tool.inputSchema) as TSchema;
+		this.mcpToolName = tool.name;
+		this.mcpServerName = connection.name;
+	}
+
+	renderCall(args: unknown, _options: RenderResultOptions, theme: Theme) {
+		return renderMCPCall(normalizeToolArgs(args), theme, this.label);
+	}
+
+	renderResult(result: CustomToolResult<MCPToolDetails>, options: RenderResultOptions, theme: Theme, args?: unknown) {
+		return renderMCPResult(result, options, theme, normalizeToolArgs(args));
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: unknown,
+		_onUpdate: AgentToolUpdateCallback<MCPToolDetails> | undefined,
+		_ctx: CustomToolContext,
+		signal?: AbortSignal,
+	): Promise<CustomToolResult<MCPToolDetails>> {
+		throwIfAborted(signal);
+		const args = normalizeToolArgs(params);
+		const provider = this.connection._source?.provider;
+		const providerName = this.connection._source?.providerName;
+
+		try {
+			const result = await callTool(this.connection, this.tool.name, args, { signal });
+			return buildResult(result, this.connection.name, this.tool.name, provider, providerName);
+		} catch (error) {
+			rethrowIfAborted(error, signal);
+			if (this.reconnect && isRetriableConnectionError(error)) {
+				const newConn = await reconnectWithAbort(this.reconnect, signal);
+				if (newConn) {
+					// Rebind so subsequent calls on this instance use the fresh connection
+					this.connection = newConn;
+					const retryProvider = newConn._source?.provider ?? provider;
+					const retryProviderName = newConn._source?.providerName ?? providerName;
+					try {
+						const result = await callTool(newConn, this.tool.name, args, { signal });
+						return buildResult(result, newConn.name, this.tool.name, retryProvider, retryProviderName);
+					} catch (retryError) {
+						rethrowIfAborted(retryError, signal);
+						return buildErrorResult(
+							retryError,
+							this.connection.name,
+							this.tool.name,
+							retryProvider,
+							retryProviderName,
+						);
+					}
+				}
+			}
+			return buildErrorResult(error, this.connection.name, this.tool.name, provider, providerName);
+		}
+	}
+}
+
+/**
+ * CustomTool wrapping an MCP tool with deferred connection resolution.
+ */
+export class DeferredMCPTool implements CustomTool<TSchema, MCPToolDetails> {
+	readonly name: string;
+	readonly label: string;
+	readonly description: string;
+	readonly parameters: TSchema;
+	/** Original MCP tool name (before normalization) */
+	readonly mcpToolName: string;
+	/** Server name */
+	readonly mcpServerName: string;
+	readonly #fallbackProvider: string | undefined;
+	readonly #fallbackProviderName: string | undefined;
+
+	/** Create DeferredMCPTool instances for all tools from an MCP server */
+	static fromTools(
+		serverName: string,
+		tools: MCPToolDefinition[],
+		getConnection: () => Promise<MCPServerConnection>,
+		source?: SourceMeta,
+		reconnect?: MCPReconnect,
+	): DeferredMCPTool[] {
+		return tools.map(tool => new DeferredMCPTool(serverName, tool, getConnection, source, reconnect));
+	}
+
+	constructor(
+		private readonly serverName: string,
+		private readonly tool: MCPToolDefinition,
+		private readonly getConnection: () => Promise<MCPServerConnection>,
+		source?: SourceMeta,
+		private readonly reconnect?: MCPReconnect,
+	) {
+		this.name = createMCPToolName(serverName, tool.name);
+		this.label = `${serverName}/${tool.name}`;
+		this.description = tool.description ?? `MCP tool from ${serverName}`;
+		this.parameters = sanitizeSchemaForMCP(tool.inputSchema) as TSchema;
+		this.mcpToolName = tool.name;
+		this.mcpServerName = serverName;
+		this.#fallbackProvider = source?.provider;
+		this.#fallbackProviderName = source?.providerName;
+	}
+
+	renderCall(args: unknown, _options: RenderResultOptions, theme: Theme) {
+		return renderMCPCall(normalizeToolArgs(args), theme, this.label);
+	}
+
+	renderResult(result: CustomToolResult<MCPToolDetails>, options: RenderResultOptions, theme: Theme, args?: unknown) {
+		return renderMCPResult(result, options, theme, normalizeToolArgs(args));
+	}
+
+	async execute(
+		_toolCallId: string,
+		params: unknown,
+		_onUpdate: AgentToolUpdateCallback<MCPToolDetails> | undefined,
+		_ctx: CustomToolContext,
+		signal?: AbortSignal,
+	): Promise<CustomToolResult<MCPToolDetails>> {
+		throwIfAborted(signal);
+		const args = normalizeToolArgs(params);
+		const provider = this.#fallbackProvider;
+		const providerName = this.#fallbackProviderName;
+
+		try {
+			const connection = await untilAborted(signal, () => this.getConnection());
+			throwIfAborted(signal);
+			try {
+				const result = await callTool(connection, this.tool.name, args, { signal });
+				return buildResult(
+					result,
+					this.serverName,
+					this.tool.name,
+					connection._source?.provider ?? provider,
+					connection._source?.providerName ?? providerName,
+				);
+			} catch (callError) {
+				rethrowIfAborted(callError, signal);
+				if (this.reconnect && isRetriableConnectionError(callError)) {
+					const newConn = await reconnectWithAbort(this.reconnect, signal);
+					if (newConn) {
+						const retryProvider = newConn._source?.provider ?? provider;
+						const retryProviderName = newConn._source?.providerName ?? providerName;
+						try {
+							const result = await callTool(newConn, this.tool.name, args, { signal });
+							return buildResult(result, this.serverName, this.tool.name, retryProvider, retryProviderName);
+						} catch (retryError) {
+							rethrowIfAborted(retryError, signal);
+							return buildErrorResult(
+								retryError,
+								this.serverName,
+								this.tool.name,
+								retryProvider,
+								retryProviderName,
+							);
+						}
+					}
+				}
+				return buildErrorResult(callError, this.serverName, this.tool.name, provider, providerName);
+			}
+		} catch (connError) {
+			// getConnection() failed — server never connected or connection lost.
+			// This is always worth a reconnect attempt for deferred tools, since the
+			// error ("MCP server not connected") isn't a network error from callTool.
+			rethrowIfAborted(connError, signal);
+			if (this.reconnect) {
+				const newConn = await reconnectWithAbort(this.reconnect, signal);
+				if (newConn) {
+					try {
+						const result = await callTool(newConn, this.tool.name, args, { signal });
+						return buildResult(
+							result,
+							this.serverName,
+							this.tool.name,
+							newConn._source?.provider ?? provider,
+							newConn._source?.providerName ?? providerName,
+						);
+					} catch (retryError) {
+						rethrowIfAborted(retryError, signal);
+						return buildErrorResult(retryError, this.serverName, this.tool.name, provider, providerName);
+					}
+				}
+			}
+			return buildErrorResult(connError, this.serverName, this.tool.name, provider, providerName);
+		}
+	}
+}

package/src/mcp/tool-cache.ts

@@ -0,0 +1,117 @@
+/**
+ * MCP tool cache.
+ *
+ * Stores tool definitions per server in agent.db for fast startup.
+ */
+import { isRecord, logger } from "@f5xc-salesdemos/pi-utils";
+import type { AgentStorage } from "../session/agent-storage";
+import type { MCPServerConfig, MCPToolDefinition } from "./types";
+
+const CACHE_VERSION = 1;
+const CACHE_PREFIX = "mcp_tools:";
+const CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+type MCPToolCachePayload = {
+	version: number;
+	configHash: string;
+	tools: MCPToolDefinition[];
+};
+
+function stableClone(value: unknown): unknown {
+	if (Array.isArray(value)) {
+		return value.map(item => stableClone(item));
+	}
+	if (isRecord(value)) {
+		const sorted: Record<string, unknown> = {};
+		for (const key of Object.keys(value).sort()) {
+			sorted[key] = stableClone(value[key]);
+		}
+		return sorted;
+	}
+	return value;
+}
+
+function stableStringify(value: unknown): string {
+	return JSON.stringify(stableClone(value));
+}
+
+function toHex(buffer: ArrayBuffer): string {
+	const bytes = new Uint8Array(buffer);
+	let output = "";
+	for (const byte of bytes) {
+		output += byte.toString(16).padStart(2, "0");
+	}
+	return output;
+}
+
+async function hashConfig(config: MCPServerConfig): Promise<string> {
+	const stable = stableStringify(config);
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(stable));
+	return toHex(digest);
+}
+
+function cacheKey(serverName: string): string {
+	return `${CACHE_PREFIX}${serverName}`;
+}
+
+export class MCPToolCache {
+	constructor(private storage: AgentStorage) {}
+
+	async get(serverName: string, config: MCPServerConfig): Promise<MCPToolDefinition[] | null> {
+		const key = cacheKey(serverName);
+		const raw = this.storage.getCache(key);
+		if (!raw) return null;
+
+		let parsed: unknown;
+		try {
+			parsed = JSON.parse(raw);
+		} catch (error) {
+			logger.warn("MCP tool cache parse failed", { serverName, error: String(error) });
+			return null;
+		}
+
+		if (!isRecord(parsed)) return null;
+		if (parsed.version !== CACHE_VERSION) return null;
+		if (typeof parsed.configHash !== "string") return null;
+		if (!Array.isArray(parsed.tools)) return null;
+
+		let currentHash: string;
+		try {
+			currentHash = await hashConfig(config);
+		} catch (error) {
+			logger.warn("MCP tool cache hash failed", { serverName, error: String(error) });
+			return null;
+		}
+
+		if (parsed.configHash !== currentHash) return null;
+
+		return parsed.tools as MCPToolDefinition[];
+	}
+
+	async set(serverName: string, config: MCPServerConfig, tools: MCPToolDefinition[]): Promise<void> {
+		let configHash: string;
+		try {
+			configHash = await hashConfig(config);
+		} catch (error) {
+			logger.warn("MCP tool cache hash failed", { serverName, error: String(error) });
+			return;
+		}
+
+		const payload: MCPToolCachePayload = {
+			version: CACHE_VERSION,
+			configHash,
+			tools,
+		};
+
+		let serialized: string;
+		try {
+			serialized = JSON.stringify(payload);
+		} catch (error) {
+			logger.warn("MCP tool cache serialize failed", { serverName, error: String(error) });
+			return;
+		}
+
+		const expiresAtSec = Math.floor((Date.now() + CACHE_TTL_MS) / 1000);
+		this.storage.setCache(cacheKey(serverName), serialized, expiresAtSec);
+	}
+}