@clinebot/core 0.0.28 → 0.0.29

package/src/extensions/mcp/client.ts

@@ -0,0 +1,420 @@
+import { type ChildProcessWithoutNullStreams, spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
+import type {
+	McpServerClient,
+	McpServerClientFactory,
+	McpServerRegistration,
+	McpToolCallResult,
+	McpToolDescriptor,
+} from "./types";
+
+type JsonRpcRequest = {
+	jsonrpc: "2.0";
+	id: number;
+	method: string;
+	params?: Record<string, unknown>;
+};
+
+type JsonRpcMessage = {
+	jsonrpc?: "2.0";
+	id?: number;
+	method?: string;
+	result?: unknown;
+	error?: {
+		code?: number;
+		message?: string;
+		data?: unknown;
+	};
+};
+
+type StdioProtocolMode = "newline" | "framed";
+
+const MCP_PROTOCOL_VERSION = "2024-11-05";
+const MCP_REQUEST_TIMEOUT_MS = 5_000;
+const MCP_CONNECT_TIMEOUT_MS = 1_500;
+
+function toErrorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function encodeFramedMessage(message: Record<string, unknown>): Buffer {
+	const body = Buffer.from(JSON.stringify(message), "utf8");
+	const header = Buffer.from(
+		`Content-Length: ${body.byteLength}\r\n\r\n`,
+		"utf8",
+	);
+	return Buffer.concat([header, body]);
+}
+
+function encodeNewlineMessage(message: Record<string, unknown>): Buffer {
+	return Buffer.from(`${JSON.stringify(message)}\n`, "utf8");
+}
+
+class FramedMessageParser {
+	private buffer = "";
+	private readonly decoder = new StringDecoder("utf8");
+
+	push(chunk: Buffer): string[] {
+		this.buffer += this.decoder.write(chunk);
+		const messages: string[] = [];
+
+		while (true) {
+			const separatorIndex = this.buffer.indexOf("\r\n\r\n");
+			if (separatorIndex < 0) {
+				break;
+			}
+
+			const headerText = this.buffer.slice(0, separatorIndex);
+			const contentLengthMatch = headerText.match(
+				/(?:^|\r\n)Content-Length:\s*(\d+)(?:\r\n|$)/i,
+			);
+			if (!contentLengthMatch) {
+				throw new Error(
+					"Invalid MCP stdio frame: missing Content-Length header.",
+				);
+			}
+
+			const contentLength = Number.parseInt(contentLengthMatch[1], 10);
+			const bodyStart = separatorIndex + 4;
+			const bodyEnd = bodyStart + contentLength;
+			if (this.buffer.length < bodyEnd) {
+				break;
+			}
+
+			messages.push(this.buffer.slice(bodyStart, bodyEnd));
+			this.buffer = this.buffer.slice(bodyEnd);
+		}
+
+		return messages;
+	}
+}
+
+class NewlineMessageParser {
+	private buffer = "";
+	private readonly decoder = new StringDecoder("utf8");
+
+	push(chunk: Buffer): string[] {
+		this.buffer += this.decoder.write(chunk);
+		const messages: string[] = [];
+
+		while (true) {
+			const newlineIndex = this.buffer.indexOf("\n");
+			if (newlineIndex < 0) {
+				break;
+			}
+			const line = this.buffer.slice(0, newlineIndex).trim();
+			this.buffer = this.buffer.slice(newlineIndex + 1);
+			if (line.length > 0) {
+				messages.push(line);
+			}
+		}
+
+		return messages;
+	}
+}
+
+class StdioMcpClient implements McpServerClient {
+	private readonly registration: McpServerRegistration;
+	private process?: ChildProcessWithoutNullStreams;
+	private nextRequestId = 1;
+	private readonly pending = new Map<
+		number,
+		{
+			resolve: (value: unknown) => void;
+			reject: (error: Error) => void;
+			timeout: ReturnType<typeof setTimeout>;
+		}
+	>();
+	private framedParser = new FramedMessageParser();
+	private newlineParser = new NewlineMessageParser();
+	private stderrBuffer = "";
+	private connected = false;
+	private protocolMode: StdioProtocolMode = "newline";
+
+	constructor(registration: McpServerRegistration) {
+		this.registration = registration;
+	}
+
+	async connect(): Promise<void> {
+		if (this.connected) {
+			return;
+		}
+		if (this.registration.transport.type !== "stdio") {
+			throw new Error(
+				`Unsupported MCP transport for "${this.registration.name}": ${this.registration.transport.type}`,
+			);
+		}
+
+		const attempts: StdioProtocolMode[] = ["newline", "framed"];
+		let lastError: Error | undefined;
+
+		for (const protocolMode of attempts) {
+			await this.disconnect().catch(() => {});
+			this.spawnProcess(protocolMode);
+			try {
+				await this.request(
+					"initialize",
+					{
+						protocolVersion: MCP_PROTOCOL_VERSION,
+						capabilities: {},
+						clientInfo: {
+							name: "@clinebot/core",
+							version: "0.0.0",
+						},
+					},
+					MCP_CONNECT_TIMEOUT_MS,
+				);
+				this.notify("notifications/initialized");
+				this.connected = true;
+				this.protocolMode = protocolMode;
+				return;
+			} catch (error) {
+				lastError = error instanceof Error ? error : new Error(String(error));
+			}
+		}
+
+		throw (
+			lastError ??
+			new Error(`Failed to connect to MCP server "${this.registration.name}".`)
+		);
+	}
+
+	async disconnect(): Promise<void> {
+		const child = this.process;
+		this.connected = false;
+		this.process = undefined;
+		this.failAllPending(
+			new Error(`Disconnected from MCP server "${this.registration.name}".`),
+		);
+		if (!child) {
+			return;
+		}
+		child.kill();
+	}
+
+	async listTools(): Promise<readonly McpToolDescriptor[]> {
+		const result = (await this.request("tools/list")) as {
+			tools?: Array<{
+				name?: string;
+				description?: string;
+				inputSchema?: Record<string, unknown>;
+			}>;
+		};
+		return (result.tools ?? [])
+			.filter(
+				(
+					tool,
+				): tool is {
+					name: string;
+					description?: string;
+					inputSchema: Record<string, unknown>;
+				} =>
+					typeof tool?.name === "string" &&
+					typeof tool.inputSchema === "object" &&
+					tool.inputSchema !== null,
+			)
+			.map((tool) => ({
+				name: tool.name,
+				description: tool.description,
+				inputSchema: tool.inputSchema,
+			}));
+	}
+
+	async callTool(request: {
+		name: string;
+		arguments?: Record<string, unknown>;
+	}): Promise<McpToolCallResult> {
+		return this.request("tools/call", {
+			name: request.name,
+			arguments: request.arguments ?? {},
+		});
+	}
+
+	private spawnProcess(protocolMode: StdioProtocolMode): void {
+		const transport = this.registration.transport;
+		if (transport.type !== "stdio") {
+			throw new Error(
+				`Unsupported MCP transport for "${this.registration.name}": ${transport.type}`,
+			);
+		}
+
+		this.framedParser = new FramedMessageParser();
+		this.newlineParser = new NewlineMessageParser();
+		this.stderrBuffer = "";
+		this.protocolMode = protocolMode;
+
+		const child = spawn(transport.command, transport.args ?? [], {
+			cwd: transport.cwd,
+			env: {
+				...process.env,
+				...(transport.env ?? {}),
+			},
+			stdio: ["pipe", "pipe", "pipe"],
+		});
+
+		this.process = child;
+		child.stdout.on("data", (chunk: Buffer) => this.handleStdout(chunk));
+		child.stderr.on("data", (chunk: Buffer) => {
+			if (this.process !== child) {
+				return;
+			}
+			this.stderrBuffer += chunk.toString("utf8");
+			if (this.stderrBuffer.length > 16_384) {
+				this.stderrBuffer = this.stderrBuffer.slice(-16_384);
+			}
+		});
+		child.once("error", (error) => {
+			if (this.process !== child) {
+				return;
+			}
+			this.failAllPending(
+				new Error(`MCP process error: ${toErrorMessage(error)}`),
+			);
+		});
+		child.once("exit", (code, signal) => {
+			if (this.process !== child) {
+				return;
+			}
+			this.connected = false;
+			this.process = undefined;
+			const suffix = this.stderrBuffer.trim()
+				? ` stderr: ${this.stderrBuffer.trim()}`
+				: "";
+			this.failAllPending(
+				new Error(
+					`MCP process exited for "${this.registration.name}" (code=${code ?? "null"}, signal=${signal ?? "null"}).${suffix}`,
+				),
+			);
+		});
+	}
+
+	private handleStdout(chunk: Buffer): void {
+		try {
+			const messages =
+				this.protocolMode === "framed"
+					? this.framedParser.push(chunk)
+					: this.newlineParser.push(chunk);
+
+			for (const messageText of messages) {
+				const message = JSON.parse(messageText) as JsonRpcMessage;
+				if (typeof message.id !== "number") {
+					continue;
+				}
+				const pending = this.pending.get(message.id);
+				if (!pending) {
+					continue;
+				}
+				this.pending.delete(message.id);
+				clearTimeout(pending.timeout);
+				if (message.error) {
+					const errorMessage =
+						message.error.message ||
+						`MCP request failed with code ${message.error.code ?? "unknown"}`;
+					pending.reject(new Error(errorMessage));
+					continue;
+				}
+				pending.resolve(message.result);
+			}
+		} catch (error) {
+			this.handleProtocolFailure(error);
+		}
+	}
+
+	private handleProtocolFailure(error: unknown): void {
+		const child = this.process;
+		if (!child) {
+			return;
+		}
+
+		this.connected = false;
+		this.process = undefined;
+		const stderrSuffix = this.stderrBuffer.trim()
+			? ` stderr: ${this.stderrBuffer.trim()}`
+			: "";
+		this.failAllPending(
+			new Error(
+				`Invalid MCP response from "${this.registration.name}": ${toErrorMessage(error)}.${stderrSuffix}`,
+			),
+		);
+		child.kill();
+	}
+
+	private async request(
+		method: string,
+		params?: Record<string, unknown>,
+		timeoutMs = MCP_REQUEST_TIMEOUT_MS,
+	): Promise<unknown> {
+		const child = this.process;
+		if (!child?.stdin.writable) {
+			throw new Error(
+				`MCP server "${this.registration.name}" is not connected.`,
+			);
+		}
+
+		const id = this.nextRequestId++;
+		const payload: JsonRpcRequest = {
+			jsonrpc: "2.0",
+			id,
+			method,
+			...(params ? { params } : {}),
+		};
+
+		const resultPromise = new Promise<unknown>((resolve, reject) => {
+			const timeout = setTimeout(() => {
+				this.pending.delete(id);
+				reject(
+					new Error(
+						`MCP request timed out for "${this.registration.name}" (${method}).`,
+					),
+				);
+			}, timeoutMs);
+			this.pending.set(id, { resolve, reject, timeout });
+		});
+
+		try {
+			child.stdin.write(
+				this.protocolMode === "framed"
+					? encodeFramedMessage(payload)
+					: encodeNewlineMessage(payload),
+			);
+		} catch (error) {
+			const pending = this.pending.get(id);
+			if (pending) {
+				clearTimeout(pending.timeout);
+				this.pending.delete(id);
+			}
+			throw error;
+		}
+
+		return resultPromise;
+	}
+
+	private notify(method: string, params?: Record<string, unknown>): void {
+		const child = this.process;
+		if (!child?.stdin.writable) {
+			return;
+		}
+		const payload = {
+			jsonrpc: "2.0" as const,
+			method,
+			...(params ? { params } : {}),
+		};
+		child.stdin.write(
+			this.protocolMode === "framed"
+				? encodeFramedMessage(payload)
+				: encodeNewlineMessage(payload),
+		);
+	}
+
+	private failAllPending(error: Error): void {
+		for (const [id, pending] of this.pending) {
+			clearTimeout(pending.timeout);
+			this.pending.delete(id);
+			pending.reject(error);
+		}
+	}
+}
+
+export function createDefaultMcpServerClientFactory(): McpServerClientFactory {
+	return (registration) => new StdioMcpClient(registration);
+}

package/src/{mcp → extensions/mcp}/index.ts

@@ -1,3 +1,4 @@
+export { createDefaultMcpServerClientFactory } from "./client";
 export type {
 	LoadMcpSettingsOptions,
 	McpSettingsFile,
@@ -12,6 +13,16 @@ export {
 } from "./config-loader";
 export { InMemoryMcpManager } from "./manager";
 export type {
+	CreateDisabledMcpToolPoliciesOptions,
+	CreateDisabledMcpToolPolicyOptions,
+} from "./policies";
+export {
+	createDisabledMcpToolPolicies,
+	createDisabledMcpToolPolicy,
+} from "./policies";
+export { createMcpTools } from "./tools";
+export type {
+	CreateMcpToolsOptions,
 	McpConnectionStatus,
 	McpManager,
 	McpManagerOptions,
@@ -23,4 +34,9 @@ export type {
 	McpSseTransportConfig,
 	McpStdioTransportConfig,
 	McpStreamableHttpTransportConfig,
+	McpToolCallRequest,
+	McpToolCallResult,
+	McpToolDescriptor,
+	McpToolNameTransform,
+	McpToolProvider,
 } from "./types";

package/src/{mcp → extensions/mcp}/manager.test.ts

@@ -1,7 +1,6 @@
-import type { McpToolDescriptor } from "@clinebot/agents";
 import { describe, expect, it, vi } from "vitest";
 import { InMemoryMcpManager } from "./manager";
-import type { McpServerClient } from "./types";
+import type { McpServerClient, McpToolDescriptor } from "./types";
 
 function createClient(overrides?: Partial<McpServerClient>): McpServerClient {
 	return {

package/src/{mcp → extensions/mcp}/manager.ts

@@ -1,8 +1,3 @@
-import type {
-	McpToolCallRequest,
-	McpToolCallResult,
-	McpToolDescriptor,
-} from "@clinebot/agents";
 import type {
 	McpConnectionStatus,
 	McpManager,
@@ -10,6 +5,9 @@ import type {
 	McpServerClient,
 	McpServerRegistration,
 	McpServerSnapshot,
+	McpToolCallRequest,
+	McpToolCallResult,
+	McpToolDescriptor,
 } from "./types";
 
 const DEFAULT_TOOLS_CACHE_TTL_MS = 5000;

package/src/extensions/mcp/name-transform.ts

@@ -0,0 +1,33 @@
+import { createHash } from "node:crypto";
+import type { McpToolNameTransform } from "./types";
+
+const MAX_MCP_TOOL_NAME_LENGTH = 128;
+const INVALID_MCP_TOOL_NAME_CHARACTERS = /[^a-zA-Z0-9_-]+/g;
+const HASH_LENGTH = 8;
+const HASH_SEPARATOR_LENGTH = 1;
+const FALLBACK_BASE_NAME = "mcp_tool";
+
+function buildMcpToolNameHash(value: string): string {
+	return createHash("sha1").update(value).digest("hex").slice(0, HASH_LENGTH);
+}
+
+function sanitizeMcpToolNameCandidate(value: string): string {
+	return value.replace(INVALID_MCP_TOOL_NAME_CHARACTERS, "_");
+}
+
+export const defaultMcpToolNameTransform: McpToolNameTransform = ({
+	serverName,
+	toolName,
+}): string => {
+	const rawName = `${serverName}__${toolName}`;
+	const sanitizedName = sanitizeMcpToolNameCandidate(rawName);
+	if (sanitizedName === rawName && rawName.length <= MAX_MCP_TOOL_NAME_LENGTH) {
+		return rawName;
+	}
+
+	const hash = buildMcpToolNameHash(rawName);
+	const maxBaseLength =
+		MAX_MCP_TOOL_NAME_LENGTH - HASH_SEPARATOR_LENGTH - HASH_LENGTH;
+	const baseName = sanitizedName.slice(0, maxBaseLength) || FALLBACK_BASE_NAME;
+	return `${baseName}_${hash}`;
+};

package/src/extensions/mcp/policies.ts

@@ -0,0 +1,47 @@
+import type { ToolPolicy } from "@clinebot/shared";
+import { defaultMcpToolNameTransform } from "./name-transform";
+import type { McpToolNameTransform } from "./types";
+
+export interface CreateDisabledMcpToolPolicyOptions {
+	serverName: string;
+	toolName: string;
+	nameTransform?: McpToolNameTransform;
+}
+
+export interface CreateDisabledMcpToolPoliciesOptions {
+	serverName: string;
+	toolNames: readonly string[];
+	nameTransform?: McpToolNameTransform;
+}
+
+export function createDisabledMcpToolPolicy(
+	options: CreateDisabledMcpToolPolicyOptions,
+): Record<string, ToolPolicy> {
+	const nameTransform = options.nameTransform ?? defaultMcpToolNameTransform;
+	const name = nameTransform({
+		serverName: options.serverName,
+		toolName: options.toolName,
+	});
+	return {
+		[name]: {
+			enabled: false,
+		},
+	};
+}
+
+export function createDisabledMcpToolPolicies(
+	options: CreateDisabledMcpToolPoliciesOptions,
+): Record<string, ToolPolicy> {
+	const policies: Record<string, ToolPolicy> = {};
+	for (const toolName of options.toolNames) {
+		Object.assign(
+			policies,
+			createDisabledMcpToolPolicy({
+				serverName: options.serverName,
+				toolName,
+				nameTransform: options.nameTransform,
+			}),
+		);
+	}
+	return policies;
+}

package/src/extensions/mcp/tools.ts

@@ -0,0 +1,47 @@
+import { createTool, type Tool } from "@clinebot/shared";
+import { defaultMcpToolNameTransform } from "./name-transform";
+import type { CreateMcpToolsOptions, McpToolDescriptor } from "./types";
+
+function defaultMcpDescription(
+	serverName: string,
+	tool: McpToolDescriptor,
+): string {
+	const base = tool.description?.trim();
+	if (base) {
+		return base;
+	}
+	return `Execute MCP tool "${tool.name}" from server "${serverName}".`;
+}
+
+export async function createMcpTools(
+	options: CreateMcpToolsOptions,
+): Promise<Tool[]> {
+	const descriptors = await options.provider.listTools(options.serverName);
+	const nameTransform = options.nameTransform ?? defaultMcpToolNameTransform;
+
+	return descriptors.map((descriptor) => {
+		const agentToolName = nameTransform({
+			serverName: options.serverName,
+			toolName: descriptor.name,
+		});
+
+		return createTool({
+			name: agentToolName,
+			description: defaultMcpDescription(options.serverName, descriptor),
+			inputSchema: descriptor.inputSchema,
+			timeoutMs: options.timeoutMs,
+			retryable: options.retryable,
+			maxRetries: options.maxRetries,
+			execute: async (input: unknown, context) =>
+				options.provider.callTool({
+					serverName: options.serverName,
+					toolName: descriptor.name,
+					arguments:
+						input && typeof input === "object" && !Array.isArray(input)
+							? (input as Record<string, unknown>)
+							: undefined,
+					context,
+				}),
+		});
+	});
+}

package/src/{mcp → extensions/mcp}/types.ts

@@ -1,10 +1,38 @@
-import type {
-	McpToolCallRequest,
-	McpToolCallResult,
-	McpToolDescriptor,
-	McpToolProvider,
-	ToolContext,
-} from "@clinebot/agents";
+import type { ToolContext } from "@clinebot/shared";
+
+export interface McpToolDescriptor {
+	name: string;
+	description?: string;
+	inputSchema: Record<string, unknown>;
+}
+
+export interface McpToolCallRequest {
+	serverName: string;
+	toolName: string;
+	arguments?: Record<string, unknown>;
+	context?: ToolContext;
+}
+
+export type McpToolCallResult = unknown;
+
+export interface McpToolProvider {
+	listTools(serverName: string): Promise<readonly McpToolDescriptor[]>;
+	callTool(request: McpToolCallRequest): Promise<McpToolCallResult>;
+}
+
+export type McpToolNameTransform = (input: {
+	serverName: string;
+	toolName: string;
+}) => string;
+
+export interface CreateMcpToolsOptions {
+	serverName: string;
+	provider: McpToolProvider;
+	nameTransform?: McpToolNameTransform;
+	timeoutMs?: number;
+	retryable?: boolean;
+	maxRetries?: number;
+}
 
 export type McpConnectionStatus = "disconnected" | "connecting" | "connected";