one-code-extension 0.1.0

package/extensions/mcp/client.ts

@@ -0,0 +1,205 @@
+/**
+ * MCP connection management. The official SDK carries the protocol; this owns
+ * lifecycle, timeouts, and failure reporting.
+ */
+
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { McpServer } from "./config.ts";
+
+/**
+ * The MCP SDK costs ~70-80ms to load (findings §15), so it is imported on the
+ * first connect rather than at startup — a session with no configured servers
+ * never pays for it. The promise is cached: concurrent connects share one load.
+ */
+let sdkPromise:
+	| Promise<{
+			Client: typeof import("@modelcontextprotocol/sdk/client/index.js").Client;
+			StdioClientTransport: typeof import("@modelcontextprotocol/sdk/client/stdio.js").StdioClientTransport;
+			StreamableHTTPClientTransport: typeof import("@modelcontextprotocol/sdk/client/streamableHttp.js").StreamableHTTPClientTransport;
+	  }>
+	| undefined;
+
+function loadSdk() {
+	sdkPromise ??= Promise.all([
+		import("@modelcontextprotocol/sdk/client/index.js"),
+		import("@modelcontextprotocol/sdk/client/stdio.js"),
+		import("@modelcontextprotocol/sdk/client/streamableHttp.js"),
+	]).then(([client, stdio, http]) => ({
+		Client: client.Client,
+		StdioClientTransport: stdio.StdioClientTransport,
+		StreamableHTTPClientTransport: http.StreamableHTTPClientTransport,
+	}));
+	return sdkPromise;
+}
+
+const CONNECT_TIMEOUT_MS = 20_000;
+const CALL_TIMEOUT_MS = 120_000;
+
+export interface McpTool {
+	name: string;
+	description?: string;
+	inputSchema?: Record<string, unknown>;
+}
+
+export interface McpResource {
+	uri: string;
+	name?: string;
+	description?: string;
+	mimeType?: string;
+}
+
+export interface Connection {
+	server: McpServer;
+	client: Client;
+	tools: McpTool[];
+	resources: McpResource[];
+	/** The server's own usage instructions from its initialize result, if any. */
+	instructions?: string;
+	/** Non-fatal problems after a successful connect (e.g. listTools failed). */
+	warnings: string[];
+}
+
+export interface FailedConnection {
+	server: McpServer;
+	error: string;
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number, what: string): Promise<T> {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => reject(new Error(`${what} timed out after ${ms}ms`)), ms);
+		timer.unref?.();
+		promise.then(
+			(value) => {
+				clearTimeout(timer);
+				resolve(value);
+			},
+			(error) => {
+				clearTimeout(timer);
+				reject(error);
+			},
+		);
+	});
+}
+
+export async function connect(server: McpServer): Promise<Connection> {
+	const { Client, StdioClientTransport, StreamableHTTPClientTransport } = await loadSdk();
+	const client = new Client({ name: "one-code", version: "0.1.0" }, { capabilities: {} });
+
+	const transport =
+		server.kind === "stdio"
+			? new StdioClientTransport({
+					command: server.command,
+					args: server.args,
+					env: { ...(process.env as Record<string, string>), ...(server.env ?? {}) },
+					stderr: "pipe",
+				})
+			: new StreamableHTTPClientTransport(new URL(server.url), {
+					requestInit: server.headers ? { headers: server.headers } : undefined,
+				});
+
+	await withTimeout(client.connect(transport), CONNECT_TIMEOUT_MS, `connecting to "${server.name}"`);
+
+	const warnings: string[] = [];
+
+	// Each list call can take up to CONNECT_TIMEOUT_MS on a slow server; run
+	// them concurrently instead of stacking their worst-case latencies.
+	const [toolsResult, resourcesResult] = await Promise.allSettled([
+		withTimeout(client.listTools(), CONNECT_TIMEOUT_MS, `listing tools of "${server.name}"`),
+		withTimeout(client.listResources(), CONNECT_TIMEOUT_MS, `listing resources of "${server.name}"`),
+	]);
+
+	let tools: McpTool[] = [];
+	if (toolsResult.status === "fulfilled") {
+		tools = (toolsResult.value.tools ?? []) as McpTool[];
+	} else {
+		// A server that connects but fails listTools would otherwise register
+		// zero tools with no signal anywhere — surface it as a warning.
+		warnings.push(`connected, but listing tools failed: ${(toolsResult.reason as Error).message}`);
+	}
+
+	let resources: McpResource[] = [];
+	if (resourcesResult.status === "fulfilled") {
+		resources = (resourcesResult.value.resources ?? []) as McpResource[];
+	} else {
+		// Resources are optional in MCP; "method not found" is normal. Anything
+		// else (a timeout, a protocol error) is worth a warning.
+		const message = (resourcesResult.reason as Error).message;
+		if (!/method not found|-32601/i.test(message)) {
+			warnings.push(`connected, but listing resources failed: ${message}`);
+		}
+	}
+
+	const instructions = client.getInstructions()?.trim() || undefined;
+
+	return { server, client, tools, resources, instructions, warnings };
+}
+
+const INSTRUCTIONS_CAP = 3000;
+
+/**
+ * The reminder carrying servers' own usage instructions, formatted the way
+ * Claude Code injects them (findings §14). Servers without instructions are
+ * skipped; returns undefined when none have any.
+ */
+export function mcpInstructionsReminder(
+	connections: Array<{ server: { name: string }; instructions?: string }>,
+): string | undefined {
+	const withInstructions = connections.filter((c) => c.instructions);
+	if (withInstructions.length === 0) return undefined;
+	const sections = withInstructions.map((c) => {
+		const text =
+			c.instructions!.length > INSTRUCTIONS_CAP ? `${c.instructions!.slice(0, INSTRUCTIONS_CAP)}… [truncated]` : c.instructions!;
+		return `## ${c.server.name}\n${text}`;
+	});
+	return [
+		"# MCP Server Instructions",
+		"",
+		"The following MCP servers have provided instructions for how to use their tools and resources:",
+		"",
+		sections.join("\n\n"),
+	].join("\n");
+}
+
+export async function callTool(
+	connection: Connection,
+	toolName: string,
+	args: Record<string, unknown>,
+): Promise<{ content?: unknown[]; isError?: boolean }> {
+	const result = await withTimeout(
+		connection.client.callTool({ name: toolName, arguments: args }),
+		CALL_TIMEOUT_MS,
+		`calling "${toolName}"`,
+	);
+	return result as { content?: unknown[]; isError?: boolean };
+}
+
+export async function readResource(connection: Connection, uri: string): Promise<{ contents?: unknown[] }> {
+	return (await withTimeout(
+		connection.client.readResource({ uri }),
+		CALL_TIMEOUT_MS,
+		`reading resource "${uri}"`,
+	)) as { contents?: unknown[] };
+}
+
+/**
+ * `resources/directory/read` — directory listing for resources. Not in the SDK's
+ * typed surface (servers opt in), so it goes through the generic request path.
+ * The SDK only calls `safeParse` on the result schema, and the response shape is
+ * server-defined, so a passthrough schema beats pinning one the spec hasn't settled.
+ */
+export async function readResourceDir(connection: Connection, uri: string): Promise<Record<string, unknown>> {
+	const passthrough = { safeParse: (data: unknown) => ({ success: true as const, data }) };
+	return (await withTimeout(
+		connection.client.request({ method: "resources/directory/read", params: { uri } }, passthrough as never),
+		CALL_TIMEOUT_MS,
+		`listing directory "${uri}"`,
+	)) as Record<string, unknown>;
+}
+
+export async function close(connection: Connection): Promise<void> {
+	try {
+		await withTimeout(connection.client.close(), 3000, "closing connection");
+	} catch {
+		// A server that won't close cleanly should not block shutdown.
+	}
+}

package/extensions/mcp/config.ts

@@ -0,0 +1,199 @@
+/**
+ * MCP server configuration in Claude Code's format (pure).
+ *
+ * Sources, lowest to highest precedence:
+ *   ~/.claude.json                    (user, global)
+ *   <cwd>/.mcp.json                   (project, checked in — walked up to the repo root)
+ *   <cwd>/.claude/settings.local.json (project, personal)
+ *
+ * Every file holds an `mcpServers` object. A stdio server has `command` (plus
+ * optional `args`, `env`); a remote one has `url` and optional `type`/`headers`.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface StdioServer {
+	kind: "stdio";
+	name: string;
+	command: string;
+	args: string[];
+	env?: Record<string, string>;
+	source: string;
+	/** Config referenced these environment variables and they are not set. */
+	missingEnv?: string[];
+}
+
+export interface HttpServer {
+	kind: "http";
+	name: string;
+	url: string;
+	headers?: Record<string, string>;
+	source: string;
+	/** Config referenced these environment variables and they are not set. */
+	missingEnv?: string[];
+}
+
+export type McpServer = StdioServer | HttpServer;
+
+interface RawServer {
+	command?: unknown;
+	args?: unknown;
+	env?: unknown;
+	url?: unknown;
+	type?: unknown;
+	headers?: unknown;
+	disabled?: unknown;
+}
+
+function readJson(path: string): Record<string, unknown> | undefined {
+	if (!existsSync(path)) return undefined;
+	try {
+		return JSON.parse(readFileSync(path, "utf-8")) as Record<string, unknown>;
+	} catch {
+		return undefined;
+	}
+}
+
+function asStringRecord(value: unknown): Record<string, string> | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const out: Record<string, string> = {};
+	for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+		if (typeof item === "string") out[key] = item;
+	}
+	return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/** Expands $VAR and ${VAR} in a config string, as Claude Code does. */
+export function expandEnv(value: string, env: Record<string, string | undefined>): string {
+	return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, braced, bare) => {
+		return env[braced ?? bare] ?? "";
+	});
+}
+
+/**
+ * Variables a value references that are not set. Expanding them to "" produces
+ * configuration that looks valid and fails confusingly at the server — a real
+ * example being `Authorization: "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"`
+ * becoming `"Bearer "`, which the endpoint rejects as a badly formatted header.
+ */
+export function missingEnvVars(value: string, env: Record<string, string | undefined>): string[] {
+	const missing: string[] = [];
+	const pattern = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+	let match = pattern.exec(value);
+	while (match) {
+		const name = match[1] ?? match[2];
+		if (!env[name]) missing.push(name);
+		match = pattern.exec(value);
+	}
+	return [...new Set(missing)];
+}
+
+export function parseServer(
+	name: string,
+	raw: RawServer,
+	source: string,
+	env: Record<string, string | undefined>,
+): McpServer | undefined {
+	if (raw.disabled === true) return undefined;
+
+	if (typeof raw.url === "string" && raw.url.trim()) {
+		const headers = asStringRecord(raw.headers);
+		const missing = [
+			...missingEnvVars(raw.url, env),
+			...Object.values(headers ?? {}).flatMap((value) => missingEnvVars(value, env)),
+		];
+		return {
+			kind: "http",
+			name,
+			url: expandEnv(raw.url, env),
+			headers: headers
+				? Object.fromEntries(Object.entries(headers).map(([k, v]) => [k, expandEnv(v, env)]))
+				: undefined,
+			source,
+			missingEnv: missing.length > 0 ? [...new Set(missing)] : undefined,
+		};
+	}
+
+	if (typeof raw.command === "string" && raw.command.trim()) {
+		const args = Array.isArray(raw.args)
+			? raw.args.filter((a): a is string => typeof a === "string").map((a) => expandEnv(a, env))
+			: [];
+		const rawEnv = asStringRecord(raw.env);
+		const missing = [
+			...missingEnvVars(raw.command, env),
+			...(Array.isArray(raw.args) ? raw.args : [])
+				.filter((a): a is string => typeof a === "string")
+				.flatMap((a) => missingEnvVars(a, env)),
+			...Object.values(rawEnv ?? {}).flatMap((value) => missingEnvVars(value, env)),
+		];
+		return {
+			kind: "stdio",
+			name,
+			command: expandEnv(raw.command, env),
+			args,
+			env: rawEnv ? Object.fromEntries(Object.entries(rawEnv).map(([k, v]) => [k, expandEnv(v, env)])) : undefined,
+			source,
+			missingEnv: missing.length > 0 ? [...new Set(missing)] : undefined,
+		};
+	}
+
+	return undefined;
+}
+
+/** `.mcp.json` from cwd upward, so a repo-root config applies in subdirectories. */
+export function findProjectConfigs(cwd: string): string[] {
+	const found: string[] = [];
+	let dir = cwd;
+	while (true) {
+		const candidate = join(dir, ".mcp.json");
+		if (existsSync(candidate)) found.push(candidate);
+		if (existsSync(join(dir, ".git"))) break;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	// Nearest last, so it overrides ancestors.
+	return found.reverse();
+}
+
+export function configPaths(cwd: string, home: string): string[] {
+	return [join(home, ".claude.json"), ...findProjectConfigs(cwd), join(cwd, ".claude", "settings.local.json")];
+}
+
+/**
+ * A plugin's `.mcp.json` is a **bare** server map with no `mcpServers` wrapper,
+ * unlike a project's. Accept either shape.
+ */
+function serverMapOf(file: Record<string, unknown> | undefined): Record<string, RawServer> | undefined {
+	if (!file || typeof file !== "object") return undefined;
+	const wrapped = (file as { mcpServers?: unknown }).mcpServers;
+	if (wrapped && typeof wrapped === "object" && !Array.isArray(wrapped)) {
+		return wrapped as Record<string, RawServer>;
+	}
+	const looksLikeServerMap = Object.values(file).every(
+		(value) => value && typeof value === "object" && !Array.isArray(value),
+	);
+	return looksLikeServerMap ? (file as Record<string, RawServer>) : undefined;
+}
+
+export function loadServers(
+	cwd: string,
+	home: string,
+	env: Record<string, string | undefined> = process.env,
+	extraPaths: string[] = [],
+): McpServer[] {
+	const byName = new Map<string, McpServer>();
+	// Plugin configs come first so project and user files can override them.
+	for (const path of [...extraPaths, ...configPaths(cwd, home)]) {
+		const file = readJson(path) as Record<string, unknown> | undefined;
+		const servers = serverMapOf(file);
+		if (!servers) continue;
+		for (const [name, raw] of Object.entries(servers)) {
+			const server = parseServer(name, raw ?? {}, path, env);
+			if (server) byName.set(name, server);
+			else byName.delete(name); // an explicit `disabled` entry removes an inherited one
+		}
+	}
+	return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}