@clinebot/core 0.0.22 → 0.0.23

package/src/mcp/config-loader.test.ts

@@ -0,0 +1,238 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+	hasMcpSettingsFile,
+	loadMcpSettingsFile,
+	registerMcpServersFromSettingsFile,
+	resolveMcpServerRegistrations,
+} from "./config-loader";
+
+describe("mcp config loader", () => {
+	const tempRoots: string[] = [];
+
+	afterEach(async () => {
+		await Promise.all(
+			tempRoots.map((directory) =>
+				rm(directory, { recursive: true, force: true }),
+			),
+		);
+		tempRoots.length = 0;
+	});
+
+	it("loads and validates mcp server registrations from JSON", async () => {
+		const tempRoot = await mkdtemp(join(tmpdir(), "core-mcp-config-loader-"));
+		tempRoots.push(tempRoot);
+		const filePath = join(tempRoot, "cline_mcp_settings.json");
+		await writeFile(
+			filePath,
+			JSON.stringify(
+				{
+					mcpServers: {
+						docs: {
+							transport: {
+								type: "stdio",
+								command: "npx",
+								args: ["-y", "@modelcontextprotocol/server-filesystem"],
+							},
+						},
+						search: {
+							transport: {
+								type: "streamableHttp",
+								url: "https://mcp.example.com",
+							},
+							disabled: true,
+						},
+					},
+				},
+				null,
+				2,
+			),
+			"utf8",
+		);
+
+		expect(hasMcpSettingsFile({ filePath })).toBe(true);
+		expect(
+			loadMcpSettingsFile({ filePath }).mcpServers.docs.transport.type,
+		).toBe("stdio");
+
+		const registrations = resolveMcpServerRegistrations({ filePath });
+		expect(registrations).toEqual([
+			{
+				name: "docs",
+				transport: {
+					type: "stdio",
+					command: "npx",
+					args: ["-y", "@modelcontextprotocol/server-filesystem"],
+				},
+				disabled: undefined,
+				metadata: undefined,
+			},
+			{
+				name: "search",
+				transport: {
+					type: "streamableHttp",
+					url: "https://mcp.example.com",
+				},
+				disabled: true,
+				metadata: undefined,
+			},
+		]);
+	});
+
+	it("registers loaded servers with an mcp manager", async () => {
+		const tempRoot = await mkdtemp(join(tmpdir(), "core-mcp-config-loader-"));
+		tempRoots.push(tempRoot);
+		const filePath = join(tempRoot, "cline_mcp_settings.json");
+		await writeFile(
+			filePath,
+			JSON.stringify(
+				{
+					mcpServers: {
+						docs: {
+							transport: {
+								type: "stdio",
+								command: "node",
+							},
+						},
+					},
+				},
+				null,
+				2,
+			),
+			"utf8",
+		);
+
+		const registered: Array<{ name: string }> = [];
+		const manager = {
+			registerServer: async (registration: { name: string }) => {
+				registered.push(registration);
+			},
+		};
+
+		await registerMcpServersFromSettingsFile(manager, { filePath });
+		expect(registered).toEqual([
+			{
+				name: "docs",
+				transport: {
+					type: "stdio",
+					command: "node",
+				},
+				disabled: undefined,
+				metadata: undefined,
+			},
+		]);
+	});
+
+	it("throws a clear error for invalid config", async () => {
+		const tempRoot = await mkdtemp(join(tmpdir(), "core-mcp-config-loader-"));
+		tempRoots.push(tempRoot);
+		const filePath = join(tempRoot, "cline_mcp_settings.json");
+		await writeFile(
+			filePath,
+			JSON.stringify(
+				{
+					mcpServers: {
+						broken: {
+							transport: {
+								type: "stdio",
+								command: "",
+							},
+						},
+					},
+				},
+				null,
+				2,
+			),
+			"utf8",
+		);
+
+		expect(() => resolveMcpServerRegistrations({ filePath })).toThrow(
+			"Invalid MCP settings",
+		);
+	});
+
+	it("accepts legacy flat stdio format", async () => {
+		const tempRoot = await mkdtemp(join(tmpdir(), "core-mcp-config-loader-"));
+		tempRoots.push(tempRoot);
+		const filePath = join(tempRoot, "cline_mcp_settings.json");
+		await writeFile(
+			filePath,
+			JSON.stringify(
+				{
+					mcpServers: {
+						docs: {
+							command: "node",
+							args: ["server.js"],
+						},
+					},
+				},
+				null,
+				2,
+			),
+			"utf8",
+		);
+
+		const registrations = resolveMcpServerRegistrations({ filePath });
+		expect(registrations).toEqual([
+			{
+				name: "docs",
+				transport: {
+					type: "stdio",
+					command: "node",
+					args: ["server.js"],
+				},
+				disabled: undefined,
+				metadata: undefined,
+			},
+		]);
+	});
+
+	it("accepts legacy flat url format and preserves explicit transportType", async () => {
+		const tempRoot = await mkdtemp(join(tmpdir(), "core-mcp-config-loader-"));
+		tempRoots.push(tempRoot);
+		const filePath = join(tempRoot, "cline_mcp_settings.json");
+		await writeFile(
+			filePath,
+			JSON.stringify(
+				{
+					mcpServers: {
+						legacySse: {
+							url: "https://sse.example.com",
+						},
+						legacyHttp: {
+							url: "https://http.example.com",
+							transportType: "http",
+						},
+					},
+				},
+				null,
+				2,
+			),
+			"utf8",
+		);
+
+		const registrations = resolveMcpServerRegistrations({ filePath });
+		expect(registrations).toEqual([
+			{
+				name: "legacySse",
+				transport: {
+					type: "sse",
+					url: "https://sse.example.com",
+				},
+				disabled: undefined,
+				metadata: undefined,
+			},
+			{
+				name: "legacyHttp",
+				transport: {
+					type: "streamableHttp",
+					url: "https://http.example.com",
+				},
+				disabled: undefined,
+				metadata: undefined,
+			},
+		]);
+	});
+});

package/src/mcp/config-loader.ts

@@ -0,0 +1,219 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolveMcpSettingsPath } from "@clinebot/shared/storage";
+import { z } from "zod";
+import type { McpManager, McpServerRegistration } from "./types";
+
+const stringRecordSchema = z.record(z.string(), z.string());
+const metadataSchema = z.record(z.string(), z.unknown());
+
+const stdioTransportSchema = z.object({
+	type: z.literal("stdio"),
+	command: z.string().min(1),
+	args: z.array(z.string()).optional(),
+	cwd: z.string().min(1).optional(),
+	env: stringRecordSchema.optional(),
+});
+
+const sseTransportSchema = z.object({
+	type: z.literal("sse"),
+	url: z.string().url(),
+	headers: stringRecordSchema.optional(),
+});
+
+const streamableHttpTransportSchema = z.object({
+	type: z.literal("streamableHttp"),
+	url: z.string().url(),
+	headers: stringRecordSchema.optional(),
+});
+
+const mcpTransportSchema = z.discriminatedUnion("type", [
+	stdioTransportSchema,
+	sseTransportSchema,
+	streamableHttpTransportSchema,
+]);
+
+const nestedRegistrationBodySchema = z.object({
+	transport: mcpTransportSchema,
+	disabled: z.boolean().optional(),
+	metadata: metadataSchema.optional(),
+});
+
+const legacyTransportTypeSchema = z
+	.enum(["stdio", "sse", "http", "streamableHttp"])
+	.optional();
+
+const legacyRegistrationBaseSchema = z.object({
+	type: z.enum(["stdio", "sse", "streamableHttp"]).optional(),
+	transportType: legacyTransportTypeSchema,
+	disabled: z.boolean().optional(),
+	metadata: metadataSchema.optional(),
+});
+
+function mapLegacyTransportType(
+	transportType: z.infer<typeof legacyTransportTypeSchema>,
+): "stdio" | "sse" | "streamableHttp" | undefined {
+	if (!transportType) {
+		return undefined;
+	}
+	if (transportType === "http") {
+		return "streamableHttp";
+	}
+	return transportType;
+}
+
+const legacyStdioRegistrationSchema = legacyRegistrationBaseSchema
+	.extend({
+		command: z.string().min(1),
+		args: z.array(z.string()).optional(),
+		cwd: z.string().min(1).optional(),
+		env: stringRecordSchema.optional(),
+	})
+	.superRefine((value, ctx) => {
+		const resolvedType =
+			value.type ?? mapLegacyTransportType(value.transportType);
+		if (resolvedType && resolvedType !== "stdio") {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				message: 'Expected type "stdio" for command-based MCP server',
+				path: ["type"],
+			});
+		}
+	})
+	.transform((value) => ({
+		transport: {
+			type: "stdio" as const,
+			command: value.command,
+			args: value.args,
+			cwd: value.cwd,
+			env: value.env,
+		},
+		disabled: value.disabled,
+		metadata: value.metadata,
+	}));
+
+const legacyUrlRegistrationSchema = legacyRegistrationBaseSchema
+	.extend({
+		url: z.string().url(),
+		headers: stringRecordSchema.optional(),
+	})
+	.superRefine((value, ctx) => {
+		const resolvedType =
+			value.type ?? mapLegacyTransportType(value.transportType) ?? "sse";
+		if (resolvedType !== "sse" && resolvedType !== "streamableHttp") {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				message:
+					'Expected type "sse" or "streamableHttp" for URL-based MCP server',
+				path: ["type"],
+			});
+		}
+	})
+	.transform((value) => {
+		const resolvedType =
+			value.type ?? mapLegacyTransportType(value.transportType) ?? "sse";
+		if (resolvedType === "streamableHttp") {
+			return {
+				transport: {
+					type: "streamableHttp" as const,
+					url: value.url,
+					headers: value.headers,
+				},
+				disabled: value.disabled,
+				metadata: value.metadata,
+			};
+		}
+		return {
+			transport: {
+				type: "sse" as const,
+				url: value.url,
+				headers: value.headers,
+			},
+			disabled: value.disabled,
+			metadata: value.metadata,
+		};
+	});
+
+const mcpRegistrationBodySchema = z.union([
+	nestedRegistrationBodySchema,
+	legacyStdioRegistrationSchema,
+	legacyUrlRegistrationSchema,
+]);
+
+const mcpSettingsSchema = z
+	.object({
+		mcpServers: z.record(z.string(), mcpRegistrationBodySchema),
+	})
+	.strict();
+
+export interface McpSettingsFile {
+	mcpServers: Record<string, Omit<McpServerRegistration, "name">>;
+}
+
+export interface LoadMcpSettingsOptions {
+	filePath?: string;
+}
+
+export interface RegisterMcpServersFromSettingsOptions {
+	filePath?: string;
+}
+
+export function resolveDefaultMcpSettingsPath(): string {
+	return resolveMcpSettingsPath();
+}
+
+export function loadMcpSettingsFile(
+	options: LoadMcpSettingsOptions = {},
+): McpSettingsFile {
+	const filePath = options.filePath ?? resolveDefaultMcpSettingsPath();
+	const raw = readFileSync(filePath, "utf8");
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (error) {
+		const details = error instanceof Error ? error.message : String(error);
+		throw new Error(
+			`Failed to parse MCP settings JSON at "${filePath}": ${details}`,
+		);
+	}
+	const result = mcpSettingsSchema.safeParse(parsed);
+	if (!result.success) {
+		const details = result.error.issues
+			.map((issue) => {
+				const path = issue.path.join(".");
+				return path ? `${path}: ${issue.message}` : issue.message;
+			})
+			.join("; ");
+		throw new Error(`Invalid MCP settings at "${filePath}": ${details}`);
+	}
+	return result.data;
+}
+
+export function hasMcpSettingsFile(
+	options: LoadMcpSettingsOptions = {},
+): boolean {
+	const filePath = options.filePath ?? resolveDefaultMcpSettingsPath();
+	return existsSync(filePath);
+}
+
+export function resolveMcpServerRegistrations(
+	options: LoadMcpSettingsOptions = {},
+): McpServerRegistration[] {
+	const config = loadMcpSettingsFile(options);
+	return Object.entries(config.mcpServers).map(([name, value]) => ({
+		name,
+		transport: value.transport,
+		disabled: value.disabled,
+		metadata: value.metadata,
+	}));
+}
+
+export async function registerMcpServersFromSettingsFile(
+	manager: Pick<McpManager, "registerServer">,
+	options: RegisterMcpServersFromSettingsOptions = {},
+): Promise<McpServerRegistration[]> {
+	const registrations = resolveMcpServerRegistrations(options);
+	for (const registration of registrations) {
+		await manager.registerServer(registration);
+	}
+	return registrations;
+}

package/src/mcp/index.ts

@@ -0,0 +1,26 @@
+export type {
+	LoadMcpSettingsOptions,
+	McpSettingsFile,
+	RegisterMcpServersFromSettingsOptions,
+} from "./config-loader";
+export {
+	hasMcpSettingsFile,
+	loadMcpSettingsFile,
+	registerMcpServersFromSettingsFile,
+	resolveDefaultMcpSettingsPath,
+	resolveMcpServerRegistrations,
+} from "./config-loader";
+export { InMemoryMcpManager } from "./manager";
+export type {
+	McpConnectionStatus,
+	McpManager,
+	McpManagerOptions,
+	McpServerClient,
+	McpServerClientFactory,
+	McpServerRegistration,
+	McpServerSnapshot,
+	McpServerTransportConfig,
+	McpSseTransportConfig,
+	McpStdioTransportConfig,
+	McpStreamableHttpTransportConfig,
+} from "./types";

package/src/mcp/manager.test.ts

@@ -0,0 +1,106 @@
+import type { McpToolDescriptor } from "@clinebot/agents";
+import { describe, expect, it, vi } from "vitest";
+import { InMemoryMcpManager } from "./manager";
+import type { McpServerClient } from "./types";
+
+function createClient(overrides?: Partial<McpServerClient>): McpServerClient {
+	return {
+		connect: vi.fn(async () => {}),
+		disconnect: vi.fn(async () => {}),
+		listTools: vi.fn(async () => []),
+		callTool: vi.fn(async () => ({ ok: true })),
+		...overrides,
+	};
+}
+
+describe("InMemoryMcpManager", () => {
+	it("registers servers, connects on demand, and calls tools", async () => {
+		const toolDescriptors: readonly McpToolDescriptor[] = [
+			{
+				name: "search",
+				inputSchema: {
+					type: "object",
+					properties: { q: { type: "string" } },
+					required: ["q"],
+				},
+			},
+		];
+		const client = createClient({
+			listTools: vi.fn(async () => toolDescriptors),
+		});
+		const manager = new InMemoryMcpManager({
+			clientFactory: vi.fn(async () => client),
+		});
+
+		await manager.registerServer({
+			name: "docs",
+			transport: {
+				type: "streamableHttp",
+				url: "https://mcp.example.test",
+			},
+		});
+
+		const tools = await manager.listTools("docs");
+		expect(tools).toHaveLength(1);
+
+		await manager.callTool({
+			serverName: "docs",
+			toolName: "search",
+			arguments: { q: "oauth flow" },
+		});
+
+		expect(client.connect).toHaveBeenCalledTimes(1);
+		expect(client.callTool).toHaveBeenCalledWith({
+			name: "search",
+			arguments: { q: "oauth flow" },
+			context: undefined,
+		});
+	});
+
+	it("uses tool list cache to avoid repeated listTools round trips", async () => {
+		const toolDescriptors: readonly McpToolDescriptor[] = [
+			{
+				name: "echo",
+				inputSchema: { type: "object", properties: {} },
+			},
+		];
+		const client = createClient({
+			listTools: vi.fn(async () => toolDescriptors),
+		});
+		const manager = new InMemoryMcpManager({
+			clientFactory: async () => client,
+			toolsCacheTtlMs: 60_000,
+		});
+
+		await manager.registerServer({
+			name: "cache-test",
+			transport: {
+				type: "stdio",
+				command: "node",
+				args: ["./mcp.js"],
+			},
+		});
+
+		await manager.listTools("cache-test");
+		await manager.listTools("cache-test");
+		expect(client.listTools).toHaveBeenCalledTimes(1);
+	});
+
+	it("prevents tool calls on disabled servers", async () => {
+		const manager = new InMemoryMcpManager({
+			clientFactory: async () => createClient(),
+		});
+		await manager.registerServer({
+			name: "disabled",
+			transport: { type: "sse", url: "https://example.test/sse" },
+			disabled: true,
+		});
+
+		await expect(
+			manager.callTool({
+				serverName: "disabled",
+				toolName: "anything",
+			}),
+		).rejects.toThrow(/disabled/i);
+	});
+});