@f5-sales-demo/xcsh 19.51.2

package/src/mcp/config.ts

@@ -0,0 +1,365 @@
+/**
+ * MCP configuration loader.
+ *
+ * Uses the capability system to load MCP servers from multiple sources.
+ */
+
+import { getMCPConfigPath } from "@f5xc-salesdemos/pi-utils";
+import { mcpCapability } from "../capability/mcp";
+import type { SourceMeta } from "../capability/types";
+import type { MCPServer } from "../discovery";
+import { loadCapability } from "../discovery";
+import { readDisabledServers } from "./config-writer";
+import type { MCPServerConfig } from "./types";
+
+/** Options for loading MCP configs */
+export interface LoadMCPConfigsOptions {
+	/** Whether to load project-level config (default: true) */
+	enableProjectConfig?: boolean;
+	/** Whether to filter out Exa MCP servers (default: true) */
+	filterExa?: boolean;
+	/** Whether to filter out browser MCP servers when builtin browser tool is enabled (default: false) */
+	filterBrowser?: boolean;
+}
+
+/** Result of loading MCP configs */
+export interface LoadMCPConfigsResult {
+	/** Loaded server configs */
+	configs: Record<string, MCPServerConfig>;
+	/** Extracted Exa API keys (if any were filtered) */
+	exaApiKeys: string[];
+	/** Source metadata for each server */
+	sources: Record<string, SourceMeta>;
+}
+
+/**
+ * Convert canonical MCPServer to legacy MCPServerConfig.
+ */
+function convertToLegacyConfig(server: MCPServer): MCPServerConfig {
+	// Determine transport type
+	const transport = server.transport ?? (server.command ? "stdio" : server.url ? "http" : "stdio");
+	const shared = {
+		enabled: server.enabled,
+		timeout: server.timeout,
+		auth: server.auth,
+		oauth: server.oauth,
+	};
+
+	if (transport === "stdio") {
+		const config: MCPServerConfig = {
+			...shared,
+			type: "stdio" as const,
+			command: server.command ?? "",
+		};
+		if (server.args) config.args = server.args;
+		if (server.env) config.env = server.env;
+		if (server.cwd) config.cwd = server.cwd;
+		return config;
+	}
+
+	if (transport === "http") {
+		const config: MCPServerConfig = {
+			...shared,
+			type: "http" as const,
+			url: server.url ?? "",
+		};
+		if (server.headers) config.headers = server.headers;
+		return config;
+	}
+
+	if (transport === "sse") {
+		const config: MCPServerConfig = {
+			...shared,
+			type: "sse" as const,
+			url: server.url ?? "",
+		};
+		if (server.headers) config.headers = server.headers;
+		return config;
+	}
+
+	// Fallback to stdio
+	return {
+		...shared,
+		type: "stdio" as const,
+		command: server.command ?? "",
+	};
+}
+
+/**
+ * Load all MCP server configs from standard locations.
+ * Uses the capability system for multi-source discovery.
+ *
+ * @param cwd Working directory (project root)
+ * @param options Load options
+ */
+export async function loadAllMCPConfigs(cwd: string, options?: LoadMCPConfigsOptions): Promise<LoadMCPConfigsResult> {
+	const enableProjectConfig = options?.enableProjectConfig ?? true;
+	const filterExa = options?.filterExa ?? true;
+	const filterBrowser = options?.filterBrowser ?? false;
+
+	// Load MCP servers via capability system
+	const result = await loadCapability<MCPServer>(mcpCapability.id, { cwd });
+
+	// Filter out project-level configs if disabled
+	const servers = enableProjectConfig
+		? result.items
+		: result.items.filter(server => server._source.level !== "project");
+
+	// Load user-level disabled servers list
+	const disabledServers = new Set(await readDisabledServers(getMCPConfigPath("user", cwd)));
+	// Convert to legacy format and preserve source metadata
+	let configs: Record<string, MCPServerConfig> = {};
+	let sources: Record<string, SourceMeta> = {};
+	for (const server of servers) {
+		const config = convertToLegacyConfig(server);
+		if (config.enabled === false || disabledServers.has(server.name)) {
+			continue;
+		}
+		configs[server.name] = config;
+		sources[server.name] = server._source;
+	}
+
+	let exaApiKeys: string[] = [];
+
+	if (filterExa) {
+		const exaResult = filterExaMCPServers(configs, sources);
+		configs = exaResult.configs;
+		sources = exaResult.sources;
+		exaApiKeys = exaResult.exaApiKeys;
+	}
+
+	if (filterBrowser) {
+		const browserResult = filterBrowserMCPServers(configs, sources);
+		configs = browserResult.configs;
+		sources = browserResult.sources;
+	}
+
+	return { configs, exaApiKeys, sources };
+}
+
+/** Pattern to match Exa MCP servers */
+const EXA_MCP_URL_PATTERN = /mcp\.exa\.ai/i;
+const EXA_API_KEY_PATTERN = /exaApiKey=([^&\s]+)/i;
+
+/**
+ * Check if a server config is an Exa MCP server.
+ */
+export function isExaMCPServer(name: string, config: MCPServerConfig): boolean {
+	// Check by server name
+	if (name.toLowerCase() === "exa") {
+		return true;
+	}
+
+	// Check by URL for HTTP/SSE servers
+	if (config.type === "http" || config.type === "sse") {
+		const httpConfig = config as { url?: string };
+		if (httpConfig.url && EXA_MCP_URL_PATTERN.test(httpConfig.url)) {
+			return true;
+		}
+	}
+
+	// Check by args for stdio servers (e.g., mcp-remote to exa)
+	if (!config.type || config.type === "stdio") {
+		const stdioConfig = config as { args?: string[] };
+		if (stdioConfig.args?.some(arg => EXA_MCP_URL_PATTERN.test(arg))) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+/**
+ * Extract Exa API key from an MCP server config.
+ */
+export function extractExaApiKey(config: MCPServerConfig): string | undefined {
+	// Check URL for HTTP/SSE servers
+	if (config.type === "http" || config.type === "sse") {
+		const httpConfig = config as { url?: string };
+		if (httpConfig.url) {
+			const match = EXA_API_KEY_PATTERN.exec(httpConfig.url);
+			if (match) return match[1];
+		}
+	}
+
+	// Check args for stdio servers
+	if (!config.type || config.type === "stdio") {
+		const stdioConfig = config as { args?: string[] };
+		if (stdioConfig.args) {
+			for (const arg of stdioConfig.args) {
+				const match = EXA_API_KEY_PATTERN.exec(arg);
+				if (match) return match[1];
+			}
+		}
+	}
+
+	// Check env vars
+	if ("env" in config && config.env) {
+		const envConfig = config as { env: Record<string, string> };
+		if (envConfig.env.EXA_API_KEY) {
+			return envConfig.env.EXA_API_KEY;
+		}
+	}
+
+	return undefined;
+}
+
+/** Result of filtering Exa MCP servers */
+export interface ExaFilterResult {
+	/** Configs with Exa servers removed */
+	configs: Record<string, MCPServerConfig>;
+	/** Extracted Exa API keys (if any) */
+	exaApiKeys: string[];
+	/** Source metadata for remaining servers */
+	sources: Record<string, SourceMeta>;
+}
+
+/**
+ * Filter out Exa MCP servers and extract their API keys.
+ * Since we have native Exa integration, we don't need the MCP server.
+ */
+export function filterExaMCPServers(
+	configs: Record<string, MCPServerConfig>,
+	sources: Record<string, SourceMeta>,
+): ExaFilterResult {
+	const filtered: Record<string, MCPServerConfig> = {};
+	const filteredSources: Record<string, SourceMeta> = {};
+	const exaApiKeys: string[] = [];
+
+	for (const [name, config] of Object.entries(configs)) {
+		if (isExaMCPServer(name, config)) {
+			// Extract API key before filtering
+			const apiKey = extractExaApiKey(config);
+			if (apiKey) {
+				exaApiKeys.push(apiKey);
+			}
+		} else {
+			filtered[name] = config;
+			if (sources[name]) {
+				filteredSources[name] = sources[name];
+			}
+		}
+	}
+
+	return { configs: filtered, exaApiKeys, sources: filteredSources };
+}
+
+/**
+ * Validate server config has required fields.
+ */
+export function validateServerConfig(name: string, config: MCPServerConfig): string[] {
+	const errors: string[] = [];
+
+	const serverType = config.type ?? "stdio";
+
+	// Check for conflicting transport fields
+	const hasCommand = "command" in config && config.command;
+	const hasUrl = "url" in config && (config as { url?: string }).url;
+	if (hasCommand && hasUrl) {
+		errors.push(
+			`Server "${name}": both "command" and "url" are set - server should be either stdio (command) OR http/sse (url), not both`,
+		);
+	}
+
+	if (serverType === "stdio") {
+		const stdioConfig = config as { command?: string };
+		if (!stdioConfig.command) {
+			errors.push(`Server "${name}": stdio server requires "command" field`);
+		}
+	} else if (serverType === "http" || serverType === "sse") {
+		const httpConfig = config as { url?: string };
+		if (!httpConfig.url) {
+			errors.push(`Server "${name}": ${serverType} server requires "url" field`);
+		}
+	} else {
+		errors.push(`Server "${name}": unknown server type "${serverType}"`);
+	}
+
+	return errors;
+}
+
+/** Known browser automation MCP server names (lowercase) */
+const BROWSER_MCP_NAMES = new Set([
+	"puppeteer",
+	"playwright",
+	"browserbase",
+	"browser-tools",
+	"browser-use",
+	"browser",
+]);
+
+/** Patterns matching browser MCP package names in command/args */
+const BROWSER_MCP_PKG_PATTERN =
+	// Official packages
+	// - @modelcontextprotocol/server-puppeteer
+	// - @playwright/mcp
+	// - @browserbasehq/mcp-server-browserbase
+	// - @agentdeskai/browser-tools-mcp
+	// - @agent-infra/mcp-server-browser
+	// Community packages: puppeteer-mcp-server, playwright-mcp, pptr-mcp, etc.
+	/(?:@modelcontextprotocol\/server-puppeteer|@playwright\/mcp|@browserbasehq\/mcp-server-browserbase|@agentdeskai\/browser-tools-mcp|@agent-infra\/mcp-server-browser|puppeteer-mcp|playwright-mcp|pptr-mcp|browser-use-mcp|mcp-browser-use)/i;
+
+/** URL patterns for hosted browser MCP services */
+const BROWSER_MCP_URL_PATTERN = /browserbase\.com|browser-use\.com/i;
+
+/**
+ * Check if a server config is a browser automation MCP server.
+ */
+export function isBrowserMCPServer(name: string, config: MCPServerConfig): boolean {
+	// Check by server name
+	if (BROWSER_MCP_NAMES.has(name.toLowerCase())) {
+		return true;
+	}
+
+	// Check by URL for HTTP/SSE servers
+	if (config.type === "http" || config.type === "sse") {
+		const httpConfig = config as { url?: string };
+		if (httpConfig.url && BROWSER_MCP_URL_PATTERN.test(httpConfig.url)) {
+			return true;
+		}
+	}
+
+	// Check by command/args for stdio servers
+	if (!config.type || config.type === "stdio") {
+		const stdioConfig = config as { command?: string; args?: string[] };
+		if (stdioConfig.command && BROWSER_MCP_PKG_PATTERN.test(stdioConfig.command)) {
+			return true;
+		}
+		if (stdioConfig.args?.some(arg => BROWSER_MCP_PKG_PATTERN.test(arg))) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+/** Result of filtering browser MCP servers */
+export interface BrowserFilterResult {
+	/** Configs with browser servers removed */
+	configs: Record<string, MCPServerConfig>;
+	/** Source metadata for remaining servers */
+	sources: Record<string, SourceMeta>;
+}
+
+/**
+ * Filter out browser automation MCP servers.
+ * Since we have a native browser tool, we don't need these MCP servers.
+ */
+export function filterBrowserMCPServers(
+	configs: Record<string, MCPServerConfig>,
+	sources: Record<string, SourceMeta>,
+): BrowserFilterResult {
+	const filtered: Record<string, MCPServerConfig> = {};
+	const filteredSources: Record<string, SourceMeta> = {};
+
+	for (const [name, config] of Object.entries(configs)) {
+		if (!isBrowserMCPServer(name, config)) {
+			filtered[name] = config;
+			if (sources[name]) {
+				filteredSources[name] = sources[name];
+			}
+		}
+	}
+
+	return { configs: filtered, sources: filteredSources };
+}

package/src/mcp/discoverable-tool-metadata.ts

@@ -0,0 +1,202 @@
+import type { AgentTool } from "@f5xc-salesdemos/pi-agent-core";
+
+export interface DiscoverableMCPTool {
+	name: string;
+	label: string;
+	description: string;
+	serverName?: string;
+	mcpToolName?: string;
+	schemaKeys: string[];
+}
+
+export interface DiscoverableMCPToolServerSummary {
+	name: string;
+	toolCount: number;
+}
+
+export interface DiscoverableMCPToolSummary {
+	servers: DiscoverableMCPToolServerSummary[];
+	toolCount: number;
+}
+
+export function formatDiscoverableMCPToolServerSummary(server: DiscoverableMCPToolServerSummary): string {
+	const toolLabel = server.toolCount === 1 ? "tool" : "tools";
+	return `${server.name} (${server.toolCount} ${toolLabel})`;
+}
+
+export interface DiscoverableMCPSearchDocument {
+	tool: DiscoverableMCPTool;
+	termFrequencies: Map<string, number>;
+	length: number;
+}
+
+export interface DiscoverableMCPSearchIndex {
+	documents: DiscoverableMCPSearchDocument[];
+	averageLength: number;
+	documentFrequencies: Map<string, number>;
+}
+
+export interface DiscoverableMCPSearchResult {
+	tool: DiscoverableMCPTool;
+	score: number;
+}
+
+const BM25_K1 = 1.2;
+const BM25_B = 0.75;
+const FIELD_WEIGHTS = {
+	name: 6,
+	label: 4,
+	serverName: 2,
+	mcpToolName: 4,
+	description: 2,
+	schemaKey: 1,
+} as const;
+
+export function isMCPToolName(name: string): boolean {
+	return name.startsWith("mcp_");
+}
+
+function getSchemaPropertyKeys(parameters: unknown): string[] {
+	if (!parameters || typeof parameters !== "object" || Array.isArray(parameters)) return [];
+	const properties = (parameters as { properties?: unknown }).properties;
+	if (!properties || typeof properties !== "object" || Array.isArray(properties)) return [];
+	return Object.keys(properties as Record<string, unknown>).sort();
+}
+
+function tokenize(value: string): string[] {
+	return value
+		.replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+		.replace(/[^a-zA-Z0-9]+/g, " ")
+		.toLowerCase()
+		.trim()
+		.split(/\s+/)
+		.filter(token => token.length > 0);
+}
+
+function addWeightedTokens(termFrequencies: Map<string, number>, value: string | undefined, weight: number): void {
+	if (!value) return;
+	for (const token of tokenize(value)) {
+		termFrequencies.set(token, (termFrequencies.get(token) ?? 0) + weight);
+	}
+}
+
+function buildSearchDocument(tool: DiscoverableMCPTool): DiscoverableMCPSearchDocument {
+	const termFrequencies = new Map<string, number>();
+	addWeightedTokens(termFrequencies, tool.name, FIELD_WEIGHTS.name);
+	addWeightedTokens(termFrequencies, tool.label, FIELD_WEIGHTS.label);
+	addWeightedTokens(termFrequencies, tool.serverName, FIELD_WEIGHTS.serverName);
+	addWeightedTokens(termFrequencies, tool.mcpToolName, FIELD_WEIGHTS.mcpToolName);
+	addWeightedTokens(termFrequencies, tool.description, FIELD_WEIGHTS.description);
+	for (const schemaKey of tool.schemaKeys) {
+		addWeightedTokens(termFrequencies, schemaKey, FIELD_WEIGHTS.schemaKey);
+	}
+	const length = Array.from(termFrequencies.values()).reduce((sum, value) => sum + value, 0);
+	return { tool, termFrequencies, length };
+}
+
+export function getDiscoverableMCPTool(tool: AgentTool): DiscoverableMCPTool | null {
+	if (!isMCPToolName(tool.name)) return null;
+	const toolRecord = tool as AgentTool & {
+		label?: string;
+		description?: string;
+		mcpServerName?: string;
+		mcpToolName?: string;
+		parameters?: unknown;
+	};
+	return {
+		name: tool.name,
+		label: typeof toolRecord.label === "string" ? toolRecord.label : tool.name,
+		description: typeof toolRecord.description === "string" ? toolRecord.description : "",
+		serverName: typeof toolRecord.mcpServerName === "string" ? toolRecord.mcpServerName : undefined,
+		mcpToolName: typeof toolRecord.mcpToolName === "string" ? toolRecord.mcpToolName : undefined,
+		schemaKeys: getSchemaPropertyKeys(toolRecord.parameters),
+	};
+}
+
+export function collectDiscoverableMCPTools(tools: Iterable<AgentTool>): DiscoverableMCPTool[] {
+	const discoverable: DiscoverableMCPTool[] = [];
+	for (const tool of tools) {
+		const metadata = getDiscoverableMCPTool(tool);
+		if (metadata) {
+			discoverable.push(metadata);
+		}
+	}
+	return discoverable;
+}
+
+export function selectDiscoverableMCPToolNamesByServer(
+	tools: Iterable<DiscoverableMCPTool>,
+	serverNames: ReadonlySet<string>,
+): string[] {
+	if (serverNames.size === 0) return [];
+	return Array.from(tools)
+		.filter(tool => tool.serverName !== undefined && serverNames.has(tool.serverName))
+		.map(tool => tool.name);
+}
+
+export function summarizeDiscoverableMCPTools(tools: DiscoverableMCPTool[]): DiscoverableMCPToolSummary {
+	const serverToolCounts = new Map<string, number>();
+	for (const tool of tools) {
+		if (!tool.serverName) continue;
+		serverToolCounts.set(tool.serverName, (serverToolCounts.get(tool.serverName) ?? 0) + 1);
+	}
+	const servers = Array.from(serverToolCounts.entries())
+		.sort(([left], [right]) => left.localeCompare(right))
+		.map(([name, toolCount]) => ({ name, toolCount }));
+	return {
+		servers,
+		toolCount: tools.length,
+	};
+}
+
+export function buildDiscoverableMCPSearchIndex(tools: Iterable<DiscoverableMCPTool>): DiscoverableMCPSearchIndex {
+	const documents = Array.from(tools, buildSearchDocument);
+	const averageLength = documents.reduce((sum, document) => sum + document.length, 0) / documents.length || 1;
+	const documentFrequencies = new Map<string, number>();
+	for (const document of documents) {
+		for (const token of new Set(document.termFrequencies.keys())) {
+			documentFrequencies.set(token, (documentFrequencies.get(token) ?? 0) + 1);
+		}
+	}
+	return {
+		documents,
+		averageLength,
+		documentFrequencies,
+	};
+}
+
+export function searchDiscoverableMCPTools(
+	index: DiscoverableMCPSearchIndex,
+	query: string,
+	limit: number,
+): DiscoverableMCPSearchResult[] {
+	const queryTokens = tokenize(query);
+	if (queryTokens.length === 0) {
+		throw new Error("Query must contain at least one letter or number.");
+	}
+	if (index.documents.length === 0) {
+		return [];
+	}
+
+	const queryTermCounts = new Map<string, number>();
+	for (const token of queryTokens) {
+		queryTermCounts.set(token, (queryTermCounts.get(token) ?? 0) + 1);
+	}
+
+	return index.documents
+		.map(document => {
+			let score = 0;
+			for (const [token, queryTermCount] of queryTermCounts) {
+				const termFrequency = document.termFrequencies.get(token) ?? 0;
+				if (termFrequency === 0) continue;
+				const documentFrequency = index.documentFrequencies.get(token) ?? 0;
+				const idf = Math.log(1 + (index.documents.length - documentFrequency + 0.5) / (documentFrequency + 0.5));
+				const normalization = BM25_K1 * (1 - BM25_B + BM25_B * (document.length / index.averageLength));
+				score += queryTermCount * idf * ((termFrequency * (BM25_K1 + 1)) / (termFrequency + normalization));
+			}
+			return { tool: document.tool, score };
+		})
+		.filter(result => result.score > 0)
+		.sort((left, right) => right.score - left.score || left.tool.name.localeCompare(right.tool.name))
+		.slice(0, limit);
+}

package/src/mcp/index.ts

@@ -0,0 +1,29 @@
+/**
+ * MCP (Model Context Protocol) support.
+ *
+ * Provides per-project .mcp.json configuration for connecting to
+ * MCP servers via stdio or HTTP transports.
+ */
+
+// Client
+export * from "./client";
+// Config
+export * from "./config";
+export * from "./config-writer";
+// JSON-RPC (lightweight HTTP-based MCP calls)
+export { callMCP, parseSSE } from "./json-rpc";
+// Loader (for SDK integration)
+export * from "./loader";
+// Manager
+export * from "./manager";
+// OAuth Discovery
+export * from "./oauth-discovery";
+// Tool bridge
+export * from "./tool-bridge";
+// Tool cache
+export * from "./tool-cache";
+// Transports
+export * from "./transports/http";
+export * from "./transports/stdio";
+// Types
+export * from "./types";

package/src/mcp/json-rpc.ts

@@ -0,0 +1,84 @@
+/**
+ * MCP JSON-RPC 2.0 over HTTPS.
+ *
+ * Lightweight utilities for calling MCP servers directly via HTTP
+ * without maintaining persistent connections.
+ */
+import { logger } from "@f5xc-salesdemos/pi-utils";
+
+/** Parse SSE response format (lines starting with "data: ") */
+export function parseSSE(text: string): unknown {
+	const lines = text.split("\n");
+	for (const line of lines) {
+		if (line.startsWith("data: ")) {
+			const data = line.slice(6).trim();
+			if (data === "[DONE]") continue;
+			const result = JSON.parse(data) as unknown;
+			if (result) return result;
+		}
+	}
+	// Fallback: try parsing entire response as JSON
+	try {
+		return JSON.parse(text);
+	} catch {
+		return null;
+	}
+}
+
+/** JSON-RPC 2.0 response structure */
+export interface JsonRpcResponse<T = unknown> {
+	jsonrpc: "2.0";
+	id: string | number;
+	result?: T;
+	error?: {
+		code: number;
+		message: string;
+		data?: unknown;
+	};
+}
+
+/**
+ * Call an MCP server with JSON-RPC 2.0 over HTTPS.
+ *
+ * @param url - Full MCP server URL (including any query parameters)
+ * @param method - JSON-RPC method name (e.g., "tools/list", "tools/call")
+ * @param params - Method parameters
+ * @returns Parsed JSON-RPC response
+ */
+export async function callMCP<T = unknown>(
+	url: string,
+	method: string,
+	params?: Record<string, unknown>,
+): Promise<JsonRpcResponse<T>> {
+	const body = {
+		jsonrpc: "2.0",
+		id: Math.random().toString(36).slice(2),
+		method,
+		params: params ?? {},
+	};
+
+	const response = await fetch(url, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Accept: "application/json, text/event-stream",
+		},
+		body: JSON.stringify(body),
+	});
+
+	if (!response.ok) {
+		const errorMsg = `MCP request failed: ${response.status} ${response.statusText}`;
+		logger.error(errorMsg, { url, method, params });
+		throw new Error(errorMsg);
+	}
+
+	const text = await response.text();
+	const result = parseSSE(text) as JsonRpcResponse<T> | null;
+
+	if (!result) {
+		logger.error("Failed to parse MCP response", { url, method, responseText: text.slice(0, 500) });
+		throw new Error("Failed to parse MCP response");
+	}
+
+	return result;
+}