@aigentic/ruflo 3.7.0-alpha.69

package/src/ruvocal/src/lib/server/mcp/clientPool.spec.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+// We mock the MCP SDK transports + Client so we can drive the connection
+// outcomes deterministically. The point of these tests is to verify that
+// clientPool.ts:
+//   1. Skips the SSE fallback when the first transport returns 4xx/5xx (e.g. 429)
+//      because retrying via SSE will hit the same upstream and produce the
+//      same rate-limit response.
+//   2. Surfaces a typed McpRateLimitedError on 429 with retryAfterMs derived
+//      from the upstream Retry-After header when present.
+//   3. Memoizes the failure for a cooldown window so subsequent getClient
+//      calls don't pound the upstream.
+//   4. Still falls back to SSE for transport-level / network errors that
+//      have no HTTP status (the "Streamable HTTP server is not running" path).
+
+const httpConnectMock = vi.fn();
+const sseConnectMock = vi.fn();
+
+vi.mock("@modelcontextprotocol/sdk/client", () => {
+	class MockClient {
+		private nextTransportIsHttp = true;
+		async connect(transport: unknown) {
+			// The transport instances are tagged below in the streamableHttp/sse mocks.
+			const isHttp = (transport as { __kind?: string }).__kind === "http";
+			if (isHttp) {
+				return httpConnectMock();
+			}
+			return sseConnectMock();
+		}
+		async close() {}
+		async callTool() {
+			return { content: [] };
+		}
+	}
+	return { Client: MockClient };
+});
+
+vi.mock("@modelcontextprotocol/sdk/client/streamableHttp.js", () => {
+	class StreamableHTTPError extends Error {
+		code: number;
+		constructor(code: number, message: string) {
+			super(`Streamable HTTP error: ${message}`);
+			this.code = code;
+			this.name = "StreamableHTTPError";
+		}
+	}
+	class StreamableHTTPClientTransport {
+		__kind = "http";
+		constructor(_url: URL, _opts: unknown) {}
+	}
+	return { StreamableHTTPError, StreamableHTTPClientTransport };
+});
+
+vi.mock("@modelcontextprotocol/sdk/client/sse.js", () => {
+	class SSEClientTransport {
+		__kind = "sse";
+		constructor(_url: URL, _opts: unknown) {}
+	}
+	return { SSEClientTransport };
+});
+
+// Import AFTER vi.mock declarations.
+import { getClient, drainPool, McpRateLimitedError } from "./clientPool";
+
+const server = { name: "test-server", url: "https://example.test/mcp", headers: {} };
+
+describe("clientPool — rate-limit and HTTP error handling", () => {
+	beforeEach(async () => {
+		await drainPool();
+		httpConnectMock.mockReset();
+		sseConnectMock.mockReset();
+	});
+
+	afterEach(async () => {
+		await drainPool();
+	});
+
+	it("skips SSE fallback on 429 and throws McpRateLimitedError", async () => {
+		httpConnectMock.mockRejectedValue(
+			new StreamableHTTPError(
+				429,
+				"Error POSTing to endpoint: Rate exceeded. Retry-After: 7"
+			)
+		);
+
+		await expect(getClient(server)).rejects.toBeInstanceOf(McpRateLimitedError);
+		// Critical: SSE was NOT attempted — would just hit the same upstream.
+		expect(sseConnectMock).not.toHaveBeenCalled();
+		expect(httpConnectMock).toHaveBeenCalledTimes(1);
+	});
+
+	it("honors Retry-After when present in the error message", async () => {
+		httpConnectMock.mockRejectedValue(
+			new StreamableHTTPError(
+				429,
+				"Error POSTing to endpoint: Rate exceeded. Retry-After: 12"
+			)
+		);
+
+		try {
+			await getClient(server);
+			throw new Error("should have thrown");
+		} catch (err) {
+			expect(err).toBeInstanceOf(McpRateLimitedError);
+			expect((err as McpRateLimitedError).retryAfterMs).toBe(12_000);
+			expect((err as McpRateLimitedError).status).toBe(429);
+			expect((err as McpRateLimitedError).serverName).toBe("test-server");
+		}
+	});
+
+	it("memoizes the 429 failure and skips network on subsequent calls during cooldown", async () => {
+		httpConnectMock.mockRejectedValue(
+			new StreamableHTTPError(429, "Error POSTing to endpoint: Rate exceeded. Retry-After: 5")
+		);
+
+		await expect(getClient(server)).rejects.toBeInstanceOf(McpRateLimitedError);
+		// Second call within the cooldown window: must NOT touch the upstream again.
+		await expect(getClient(server)).rejects.toBeInstanceOf(McpRateLimitedError);
+		expect(httpConnectMock).toHaveBeenCalledTimes(1);
+		expect(sseConnectMock).not.toHaveBeenCalled();
+	});
+
+	it("skips SSE fallback on 4xx (e.g. 401)", async () => {
+		httpConnectMock.mockRejectedValue(
+			new StreamableHTTPError(401, "Unauthorized")
+		);
+		await expect(getClient(server)).rejects.toThrow(/HTTP 401/);
+		expect(sseConnectMock).not.toHaveBeenCalled();
+	});
+
+	it("skips SSE fallback on 5xx (e.g. 503)", async () => {
+		httpConnectMock.mockRejectedValue(
+			new StreamableHTTPError(503, "Service Unavailable")
+		);
+		await expect(getClient(server)).rejects.toThrow(/HTTP 503/);
+		expect(sseConnectMock).not.toHaveBeenCalled();
+	});
+
+	it("falls back to SSE on transport-level / network errors with no HTTP status", async () => {
+		httpConnectMock.mockRejectedValue(new Error("ECONNREFUSED"));
+		sseConnectMock.mockResolvedValue(undefined);
+
+		const client = await getClient(server);
+		expect(client).toBeDefined();
+		expect(httpConnectMock).toHaveBeenCalledTimes(1);
+		expect(sseConnectMock).toHaveBeenCalledTimes(1);
+	});
+
+	it("falls back to SSE on 408 Request Timeout (recoverable)", async () => {
+		httpConnectMock.mockRejectedValue(
+			new StreamableHTTPError(408, "Request Timeout")
+		);
+		sseConnectMock.mockResolvedValue(undefined);
+
+		const client = await getClient(server);
+		expect(client).toBeDefined();
+		expect(sseConnectMock).toHaveBeenCalledTimes(1);
+	});
+
+	it("surfaces 429 even when the SSE fallback also reports 429", async () => {
+		httpConnectMock.mockRejectedValue(new Error("transport mismatch")); // forces SSE attempt
+		sseConnectMock.mockRejectedValue(
+			new Error("SSE error: Non-200 status code (429)")
+		);
+
+		try {
+			await getClient(server);
+			throw new Error("should have thrown");
+		} catch (err) {
+			expect(err).toBeInstanceOf(McpRateLimitedError);
+			expect((err as McpRateLimitedError).status).toBe(429);
+		}
+	});
+});

package/src/ruvocal/src/lib/server/mcp/hf.ts

@@ -0,0 +1,32 @@
+// Minimal shared helpers for HF MCP token forwarding
+
+export const hasAuthHeader = (h?: Record<string, string>) =>
+	!!h && Object.keys(h).some((k) => k.toLowerCase() === "authorization");
+
+export const isStrictHfMcpLogin = (urlString: string) => {
+	try {
+		const u = new URL(urlString);
+		const host = u.hostname.toLowerCase();
+		const allowedHosts = new Set(["hf.co", "huggingface.co"]);
+		return (
+			u.protocol === "https:" &&
+			allowedHosts.has(host) &&
+			u.pathname === "/mcp" &&
+			u.search === "?login"
+		);
+	} catch {
+		return false;
+	}
+};
+
+export const hasNonEmptyToken = (tok: unknown): tok is string =>
+	typeof tok === "string" && tok.trim().length > 0;
+
+export const isExaMcpServer = (urlString: string): boolean => {
+	try {
+		const u = new URL(urlString);
+		return u.protocol === "https:" && u.hostname.toLowerCase() === "mcp.exa.ai";
+	} catch {
+		return false;
+	}
+};

package/src/ruvocal/src/lib/server/mcp/httpClient.ts

@@ -0,0 +1,122 @@
+import { Client } from "@modelcontextprotocol/sdk/client";
+import { getClient, evictFromPool } from "./clientPool";
+import { config } from "$lib/server/config";
+
+function isConnectionClosedError(err: unknown): boolean {
+	const message = err instanceof Error ? err.message : String(err);
+	return message.includes("-32000") || message.toLowerCase().includes("connection closed");
+}
+
+export interface McpServerConfig {
+	name: string;
+	url: string;
+	headers?: Record<string, string>;
+}
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+export function getMcpToolTimeoutMs(): number {
+	const envValue = config.MCP_TOOL_TIMEOUT_MS;
+	if (envValue) {
+		const parsed = parseInt(envValue, 10);
+		if (!isNaN(parsed) && parsed > 0) {
+			return parsed;
+		}
+	}
+	return DEFAULT_TIMEOUT_MS;
+}
+
+export type McpToolTextResponse = {
+	text: string;
+	/** If the server returned structuredContent, include it raw */
+	structured?: unknown;
+	/** Raw content blocks returned by the server, if any */
+	content?: unknown[];
+};
+
+export type McpToolProgress = {
+	progress: number;
+	total?: number;
+	message?: string;
+};
+
+export async function callMcpTool(
+	server: McpServerConfig,
+	tool: string,
+	args: unknown = {},
+	{
+		timeoutMs = DEFAULT_TIMEOUT_MS,
+		signal,
+		client,
+		onProgress,
+	}: {
+		timeoutMs?: number;
+		signal?: AbortSignal;
+		client?: Client;
+		onProgress?: (progress: McpToolProgress) => void;
+	} = {}
+): Promise<McpToolTextResponse> {
+	const normalizedArgs =
+		typeof args === "object" && args !== null && !Array.isArray(args)
+			? (args as Record<string, unknown>)
+			: undefined;
+
+	// Get a (possibly pooled) client. The client itself was connected with a signal
+	// that already composes outer cancellation. We still enforce a per-call timeout here.
+	let activeClient = client ?? (await getClient(server, signal));
+
+	const callToolOptions = {
+		signal,
+		timeout: timeoutMs,
+		// Enable progress tokens so long-running tools keep extending the timeout.
+		onprogress: (progress: McpToolProgress) => {
+			onProgress?.({
+				progress: progress.progress,
+				total: progress.total,
+				message: progress.message,
+			});
+		},
+		resetTimeoutOnProgress: true,
+	};
+
+	let response;
+	try {
+		response = await activeClient.callTool(
+			{ name: tool, arguments: normalizedArgs },
+			undefined,
+			callToolOptions
+		);
+	} catch (err) {
+		if (!isConnectionClosedError(err)) {
+			throw err;
+		}
+
+		// Evict stale client and close it
+		const stale = evictFromPool(server);
+		stale?.close?.().catch(() => {});
+
+		// Retry with fresh client
+		activeClient = await getClient(server, signal);
+		response = await activeClient.callTool(
+			{ name: tool, arguments: normalizedArgs },
+			undefined,
+			callToolOptions
+		);
+	}
+
+	const parts = Array.isArray(response?.content) ? (response.content as Array<unknown>) : [];
+	const textParts = parts
+		.filter((part): part is { type: "text"; text: string } => {
+			if (typeof part !== "object" || part === null) return false;
+			const obj = part as Record<string, unknown>;
+			return obj["type"] === "text" && typeof obj["text"] === "string";
+		})
+		.map((p) => p.text);
+
+	const text = textParts.join("\n");
+	const structured = (response as unknown as { structuredContent?: unknown })?.structuredContent;
+	const contentBlocks = Array.isArray(response?.content)
+		? (response.content as unknown[])
+		: undefined;
+	return { text, structured, content: contentBlocks };
+}

package/src/ruvocal/src/lib/server/mcp/registry.ts

@@ -0,0 +1,76 @@
+import { config } from "$lib/server/config";
+import { logger } from "$lib/server/logger";
+import type { McpServerConfig } from "./httpClient";
+import { resetMcpToolsCache } from "./tools";
+
+let cachedRaw: string | null = null;
+let cachedServers: McpServerConfig[] = [];
+
+function parseServers(raw: string): McpServerConfig[] {
+	if (!raw) return [];
+
+	try {
+		const parsed = JSON.parse(raw);
+		if (!Array.isArray(parsed)) return [];
+
+		return parsed
+			.map((entry) => {
+				if (!entry || typeof entry !== "object") return undefined;
+				const name = (entry as Record<string, unknown>).name;
+				const url = (entry as Record<string, unknown>).url;
+				if (typeof name !== "string" || !name.trim()) return undefined;
+				if (typeof url !== "string" || !url.trim()) return undefined;
+
+				const headersRaw = (entry as Record<string, unknown>).headers;
+				let headers: Record<string, string> | undefined;
+				if (headersRaw && typeof headersRaw === "object" && !Array.isArray(headersRaw)) {
+					const headerEntries = Object.entries(headersRaw as Record<string, unknown>).filter(
+						(entry): entry is [string, string] => typeof entry[1] === "string"
+					);
+					headers = Object.fromEntries(headerEntries);
+				}
+
+				return headers ? { name, url, headers } : { name, url };
+			})
+			.filter((server): server is McpServerConfig => Boolean(server));
+	} catch (error) {
+		logger.warn({ err: error }, "[mcp] failed to parse MCP_SERVERS env");
+		return [];
+	}
+}
+
+function setServers(raw: string) {
+	cachedServers = parseServers(raw);
+	cachedRaw = raw;
+	resetMcpToolsCache();
+	logger.debug({ count: cachedServers.length }, "[mcp] loaded server configuration");
+	console.log(
+		`[MCP] Loaded ${cachedServers.length} server(s):`,
+		cachedServers.map((s) => s.name).join(", ") || "none"
+	);
+}
+
+export function loadMcpServersOnStartup(): McpServerConfig[] {
+	const raw = config.MCP_SERVERS || "[]";
+	setServers(raw);
+	return cachedServers;
+}
+
+export function refreshMcpServersIfChanged(): void {
+	const currentRaw = config.MCP_SERVERS || "[]";
+	if (cachedRaw === null) {
+		setServers(currentRaw);
+		return;
+	}
+
+	if (currentRaw !== cachedRaw) {
+		setServers(currentRaw);
+	}
+}
+
+export function getMcpServers(): McpServerConfig[] {
+	if (cachedRaw === null) {
+		loadMcpServersOnStartup();
+	}
+	return cachedServers;
+}

package/src/ruvocal/src/lib/server/mcp/tools.ts

@@ -0,0 +1,196 @@
+import { Client } from "@modelcontextprotocol/sdk/client";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import type { McpServerConfig } from "./httpClient";
+import { logger } from "$lib/server/logger";
+// use console.* for lightweight diagnostics in production logs
+
+export type OpenAiTool = {
+	type: "function";
+	function: { name: string; description?: string; parameters?: Record<string, unknown> };
+};
+
+export interface McpToolMapping {
+	fnName: string;
+	server: string;
+	tool: string;
+}
+
+interface CacheEntry {
+	fetchedAt: number;
+	ttlMs: number;
+	tools: OpenAiTool[];
+	mapping: Record<string, McpToolMapping>;
+}
+
+const DEFAULT_TTL_MS = 60_000;
+const cache = new Map<string, CacheEntry>();
+
+// Per OpenAI tool/function name guidelines most providers enforce:
+//   ^[a-zA-Z0-9_-]{1,64}$
+// Dots are not universally accepted (e.g., MiniMax via HF router rejects them).
+// Normalize any disallowed characters (including ".") to underscore and trim to 64 chars.
+function sanitizeName(name: string) {
+	return name.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64);
+}
+
+function buildCacheKey(servers: McpServerConfig[]): string {
+	const normalized = servers
+		.map((server) => ({
+			name: server.name,
+			url: server.url,
+			headers: server.headers
+				? Object.entries(server.headers)
+						.sort(([a], [b]) => a.localeCompare(b))
+						.map(([key, value]) => [key, value])
+				: [],
+		}))
+		.sort((a, b) => {
+			const byName = a.name.localeCompare(b.name);
+			if (byName !== 0) return byName;
+			return a.url.localeCompare(b.url);
+		});
+
+	return JSON.stringify(normalized);
+}
+
+type ListedTool = {
+	name?: string;
+	inputSchema?: Record<string, unknown>;
+	description?: string;
+	annotations?: { title?: string };
+};
+
+async function listServerTools(
+	server: McpServerConfig,
+	opts: { signal?: AbortSignal } = {}
+): Promise<ListedTool[]> {
+	const url = new URL(server.url);
+	const client = new Client({ name: "chat-ui-mcp", version: "0.1.0" });
+	try {
+		try {
+			const transport = new StreamableHTTPClientTransport(url, {
+				requestInit: { headers: server.headers, signal: opts.signal },
+			});
+			await client.connect(transport);
+		} catch {
+			const transport = new SSEClientTransport(url, {
+				requestInit: { headers: server.headers, signal: opts.signal },
+			});
+			await client.connect(transport);
+		}
+
+		const response = await client.listTools({});
+		const tools = Array.isArray(response?.tools) ? (response.tools as ListedTool[]) : [];
+		try {
+			logger.debug(
+				{
+					server: server.name,
+					url: server.url,
+					count: tools.length,
+					toolNames: tools.map((t) => t?.name).filter(Boolean),
+				},
+				"[mcp] listed tools from server"
+			);
+		} catch {}
+		return tools;
+	} finally {
+		try {
+			await client.close?.();
+		} catch {
+			// ignore close errors
+		}
+	}
+}
+
+export async function getOpenAiToolsForMcp(
+	servers: McpServerConfig[],
+	{ ttlMs = DEFAULT_TTL_MS, signal }: { ttlMs?: number; signal?: AbortSignal } = {}
+): Promise<{ tools: OpenAiTool[]; mapping: Record<string, McpToolMapping> }> {
+	const now = Date.now();
+	const cacheKey = buildCacheKey(servers);
+	const cached = cache.get(cacheKey);
+	if (cached && now - cached.fetchedAt < cached.ttlMs) {
+		return { tools: cached.tools, mapping: cached.mapping };
+	}
+
+	const tools: OpenAiTool[] = [];
+	const mapping: Record<string, McpToolMapping> = {};
+
+	const seenNames = new Set<string>();
+
+	const pushToolDefinition = (
+		name: string,
+		description: string | undefined,
+		parameters: Record<string, unknown> | undefined
+	) => {
+		if (seenNames.has(name)) return;
+		tools.push({
+			type: "function",
+			function: {
+				name,
+				description,
+				parameters,
+			},
+		});
+		seenNames.add(name);
+	};
+
+	// Fetch tools in parallel; tolerate individual failures
+	const tasks = servers.map((server) => listServerTools(server, { signal }));
+	const results = await Promise.allSettled(tasks);
+
+	for (let i = 0; i < results.length; i++) {
+		const server = servers[i];
+		const r = results[i];
+		if (r.status === "fulfilled") {
+			const serverTools = r.value;
+			for (const tool of serverTools) {
+				if (typeof tool.name !== "string" || tool.name.trim().length === 0) {
+					continue;
+				}
+
+				const parameters =
+					tool.inputSchema && typeof tool.inputSchema === "object" ? tool.inputSchema : undefined;
+				const description = tool.description ?? tool.annotations?.title;
+				const toolName = tool.name;
+
+				// Emit a collision-aware function name.
+				// Prefer the plain tool name; on conflict, suffix with server name.
+				let plainName = sanitizeName(toolName);
+				if (plainName in mapping) {
+					const suffix = sanitizeName(server.name);
+					const candidate = `${plainName}_${suffix}`.slice(0, 64);
+					if (!(candidate in mapping)) {
+						plainName = candidate;
+					} else {
+						let i = 2;
+						let next = `${candidate}_${i}`;
+						while (i < 10 && next in mapping) {
+							i += 1;
+							next = `${candidate}_${i}`;
+						}
+						plainName = next.slice(0, 64);
+					}
+				}
+
+				pushToolDefinition(plainName, description, parameters);
+				mapping[plainName] = {
+					fnName: plainName,
+					server: server.name,
+					tool: toolName,
+				};
+			}
+		} else {
+			// ignore failure for this server
+			continue;
+		}
+	}
+
+	cache.set(cacheKey, { fetchedAt: now, ttlMs, tools, mapping });
+	return { tools, mapping };
+}
+
+export function resetMcpToolsCache() {
+	cache.clear();
+}