pi-gitnexus-fork 0.7.0

package/src/mcp-client-stdio.ts

@@ -0,0 +1,217 @@
+import type { ChildProcess } from 'child_process';
+import spawn from 'cross-spawn';
+import { gitnexusCmd, MAX_OUTPUT_CHARS, spawnEnv } from './gitnexus';
+import type { McpClient } from './mcp-client';
+import { createMcpError } from './mcp-client';
+
+// ── JSON-RPC / MCP types ──────────────────────────────────────────────────────
+
+interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id?: number;
+  result?: unknown;
+  error?: { code: number; message: string };
+}
+
+interface McpContent {
+  type: string;
+  text?: string;
+  isError?: boolean;
+}
+
+interface McpToolResult {
+  content: McpContent[];
+  isError?: boolean;
+}
+
+// ── StdioMcpClient ────────────────────────────────────────────────────────────
+
+/**
+ * Thin stdio JSON-RPC 2.0 client for `gitnexus mcp`.
+ *
+ * Communication is exclusively over the spawned process's stdin/stdout pipe —
+ * no network socket, no port. Only our process can write to the pipe.
+ *
+ * The MCP process is started lazily on the first callTool() invocation and
+ * kept alive for the session lifetime. stop() terminates it; the next callTool()
+ * re-spawns with the new cwd.
+ */
+export class StdioMcpClient implements McpClient {
+  private proc: ChildProcess | null = null;
+  private buffer = '';
+  private pending = new Map<number, { resolve: (raw: string) => void; reject: (e: Error) => void }>();
+  private nextId = 2; // id 1 is reserved for the initialize handshake
+  private startPromise: Promise<void> | null = null;
+
+  /**
+   * Probe the local gitnexus binary. Returns true if it responds to --version.
+   * Static method for use by AutoMcpClient without instantiating.
+   */
+  static async probeLocalBinary(): Promise<boolean> {
+    return new Promise((resolve) => {
+      const [bin, ...baseArgs] = gitnexusCmd;
+      const proc = spawn(bin, [...baseArgs, '--version'], {
+        stdio: 'ignore',
+        env: spawnEnv,
+      });
+      proc.on('close', (code: number | null) => resolve(code === 0));
+      proc.on('error', () => resolve(false));
+    });
+  }
+
+  /**
+   * Lazily spawn `gitnexus mcp` and complete the MCP initialize handshake.
+   * Idempotent — concurrent calls await the same promise; only one process spawns.
+   */
+  private ensureStarted(cwd: string): Promise<void> {
+    if (this.proc) return Promise.resolve();
+    if (this.startPromise) return this.startPromise;
+
+    this.startPromise = new Promise<void>((resolve_, reject) => {
+      const [bin, ...baseArgs] = gitnexusCmd;
+      const proc = spawn(bin, [...baseArgs, 'mcp'], {
+        cwd,
+        stdio: ['pipe', 'pipe', 'ignore'],
+        env: spawnEnv,
+      });
+
+      proc.on('error', (err) => {
+        this.startPromise = null;
+        reject(err);
+      });
+
+      proc.stdout!.setEncoding('utf8');
+      proc.stdout!.on('data', (chunk: string) => {
+        this.buffer += chunk;
+        const lines = this.buffer.split('\n');
+        this.buffer = lines.pop() ?? '';
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const msg = JSON.parse(line) as JsonRpcResponse;
+            if (msg.id !== undefined) {
+              const p = this.pending.get(msg.id);
+              if (p) { this.pending.delete(msg.id); p.resolve(line); }
+            }
+          } catch { /* ignore malformed lines */ }
+        }
+      });
+
+      proc.on('close', () => {
+        this.proc = null;
+        this.startPromise = null;
+        for (const p of this.pending.values()) {
+          p.reject(new Error('gitnexus mcp process exited'));
+        }
+        this.pending.clear();
+      });
+
+      // MCP initialize handshake
+      const initMsg = JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2024-11-05',
+          capabilities: {},
+          clientInfo: { name: 'pi-gitnexus', version: '0.1.0' },
+        },
+      });
+
+      this.pending.set(1, {
+        resolve: () => {
+          proc.stdin!.write(
+            JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n'
+          );
+          this.proc = proc;
+          resolve_();
+        },
+        reject: (err) => {
+          this.startPromise = null;
+          reject(err);
+        },
+      });
+
+      proc.stdin!.write(initMsg + '\n');
+    });
+
+    return this.startPromise;
+  }
+
+  /**
+   * Call a gitnexus MCP tool and return its formatted text response.
+   * Starts the MCP process lazily if not already running.
+   */
+  async callTool(name: string, args: Record<string, unknown>, cwd: string): Promise<string> {
+    try {
+      await this.ensureStarted(cwd);
+    } catch (error) {
+      throw createMcpError(error, 'Failed to start gitnexus mcp');
+    }
+
+    if (!this.proc) throw createMcpError('GitNexus MCP is not running.');
+
+    const id = this.nextId++;
+    return new Promise<string>((resolve_, reject_) => {
+      this.pending.set(id, {
+        resolve: (raw: string) => {
+          try {
+            const msg = JSON.parse(raw) as JsonRpcResponse;
+            if (msg.error) {
+              reject_(createMcpError(msg.error.message));
+              return;
+            }
+            const result = msg.result as McpToolResult | undefined;
+            if (!result?.content) {
+              reject_(createMcpError('No response content returned from GitNexus MCP.'));
+              return;
+            }
+            const text = result.content
+              .filter((c) => c.type === 'text' && c.text)
+              .map((c) => c.text!)
+              .join('\n');
+            if (result.isError) {
+              reject_(createMcpError(text || 'GitNexus MCP reported an error with no text payload.'));
+              return;
+            }
+            if (!text) {
+              reject_(createMcpError('GitNexus MCP returned an empty response.'));
+              return;
+            }
+            resolve_('[GitNexus]\n' + text.slice(0, MAX_OUTPUT_CHARS));
+          } catch (error) {
+            reject_(createMcpError(error, 'Malformed response from GitNexus MCP.'));
+          }
+        },
+        reject: (error) => reject_(createMcpError(error)),
+      });
+
+      const msg = JSON.stringify({
+        jsonrpc: '2.0',
+        id,
+        method: 'tools/call',
+        params: { name, arguments: args },
+      });
+
+      try {
+        this.proc!.stdin!.write(msg + '\n');
+      } catch (error) {
+        this.pending.delete(id);
+        reject_(createMcpError(error, 'Failed to write request to GitNexus MCP.'));
+      }
+    });
+  }
+
+  /** Terminate the MCP process. Called on session_start so the next session gets a fresh process. */
+  stop(): void {
+    if (this.proc) {
+      this.proc.kill('SIGTERM');
+      this.proc = null;
+    }
+    this.startPromise = null;
+    for (const p of this.pending.values()) {
+      p.reject(new Error('MCP client stopped'));
+    }
+    this.pending.clear();
+  }
+}

package/src/mcp-client.ts

@@ -0,0 +1,208 @@
+// ── JSON-RPC / MCP types ──────────────────────────────────────────────────────
+
+interface JsonRpcResponse {
+	jsonrpc: "2.0";
+	id?: number;
+	result?: unknown;
+	error?: { code: number; message: string };
+}
+
+interface McpContent {
+	type: string;
+	text?: string;
+	isError?: boolean;
+}
+
+interface McpToolResult {
+	content: McpContent[];
+	isError?: boolean;
+}
+
+// ── McpClient interface ───────────────────────────────────────────────────────
+
+/**
+ * Abstraction over MCP transport mechanisms (stdio, remote HTTP).
+ * Implementations must be safe for concurrent `callTool()` invocations.
+ */
+export interface McpClient {
+	/** Call a named MCP tool with the given arguments, scoped to `cwd`. Returns formatted text. */
+	callTool(
+		name: string,
+		args: Record<string, unknown>,
+		cwd: string,
+	): Promise<string>;
+	/** Terminate any open connections / processes. Idempotent. */
+	stop(): void;
+}
+
+// ── Error helper ──────────────────────────────────────────────────────────────
+
+/** Create a consistently-prefixed error from an unknown value. */
+export function createMcpError(
+	error: unknown,
+	fallback = "GitNexus MCP request failed.",
+): Error {
+	const message =
+		error instanceof Error
+			? error.message
+			: typeof error === "string"
+				? error
+				: fallback;
+	return new Error(`[GitNexus] ${message || fallback}`);
+}
+
+// ── Re-exports (lazy — avoids circular dependency) ─────────────────────────────
+export { StdioMcpClient } from "./mcp-client-stdio";
+
+// ── AutoMcpClient ─────────────────────────────────────────────────────────────
+
+import type { McpMode } from "./gitnexus";
+import { RemoteMcpClient } from "./remote-mcp-client";
+
+/**
+ * Auto-detecting MCP client that probes the local binary on first use.
+ * Falls back to remote HTTP if the local binary fails.
+ * Once selected, the chosen transport is cached for the session.
+ */
+export class AutoMcpClient implements McpClient {
+	private delegate: McpClient | null = null;
+	private probePromise: Promise<McpClient> | null = null;
+
+	/**
+	 * Probe the local gitnexus binary. Returns true if it responds to --version.
+	 */
+	static async probeLocalBinary(): Promise<boolean> {
+		const { StdioMcpClient } = await import("./mcp-client-stdio");
+		return StdioMcpClient.probeLocalBinary();
+	}
+
+	/** Resolve the transport. Probes local binary once, then caches the result. */
+	private async resolveClient(): Promise<McpClient> {
+		if (this.delegate) return this.delegate;
+		if (this.probePromise) return this.probePromise;
+
+		this.probePromise = (async () => {
+			const { McpClientFactory } = await import("./mcp-client-factory");
+			const { serverUrl } = McpClientFactory.loadConfig();
+
+			const localWorks = await AutoMcpClient.probeLocalBinary();
+			const client = localWorks
+				? await McpClientFactory.createClient({ mode: "local" })
+				: new RemoteMcpClient({ serverUrl: serverUrl! });
+			this.delegate = client;
+			return client;
+		})();
+
+		return this.probePromise;
+	}
+
+	async callTool(
+		name: string,
+		args: Record<string, unknown>,
+		cwd: string,
+	): Promise<string> {
+		const client = await this.resolveClient();
+		return client.callTool(name, args, cwd);
+	}
+
+	stop(): void {
+		if (this.delegate) {
+			this.delegate.stop();
+			this.delegate = null;
+		}
+		this.probePromise = null;
+	}
+}
+
+// ── Factory ───────────────────────────────────────────────────────────────────
+
+/**
+ * Create an McpClient based on the configured mode.
+ *
+ * @param mode     - Transport mode from config.
+ * @param serverUrl - Remote server URL (required for 'remote', optional for 'auto').
+ */
+export function createMcpClient(mode: McpMode, serverUrl: string): McpClient {
+	switch (mode) {
+		case "remote":
+			return new RemoteMcpClient({ serverUrl });
+		case "auto":
+			return new AutoMcpClient();
+		default:
+			// Return a lazy proxy that defers StdioMcpClient instantiation.
+			// This avoids circular dependency: mcp-client-stdio imports from this module,
+			// so we can't eagerly import it here.
+			return createLazyStdioClient();
+	}
+}
+
+/**
+ * Create a lazy proxy McpClient that defers StdioMcpClient instantiation
+ * until the first method call. Avoids circular dependency issues.
+ */
+function createLazyStdioClient(): McpClient {
+	let _instance: McpClient | null = null;
+	let _pending: Promise<McpClient> | null = null;
+
+	const getInstance = async (): Promise<McpClient> => {
+		if (_instance) return _instance;
+		if (_pending) return _pending;
+		_pending = import("./mcp-client-stdio").then((mod) => {
+			_instance = new mod.StdioMcpClient();
+			return _instance;
+		});
+		return _pending;
+	};
+
+	return new Proxy({} as McpClient, {
+		get(_, prop) {
+			if (prop === "stop") {
+				return () => {
+					_instance?.stop();
+				};
+			}
+			if (prop === "callTool") {
+				return (name: string, args: Record<string, unknown>, cwd: string) =>
+					getInstance().then((c) => c.callTool(name, args, cwd));
+			}
+			return undefined;
+		},
+	});
+}
+
+// ── Singleton (config-aware, lazy) ─────────────────────────────────────────────
+
+/**
+ * Singleton MCP client. Reads config on first use and selects transport:
+ * - mode=remote → RemoteMcpClient
+ * - mode=auto → AutoMcpClient (probe local, fallback remote)
+ * - mode=local (or missing) → StdioMcpClient
+ */
+export const mcpClient: McpClient = new Proxy({} as McpClient, {
+	get(_, prop) {
+		if (prop === "stop") {
+			return () => {
+				_singletonInstance?.stop();
+			};
+		}
+		if (prop === "callTool") {
+			return (name: string, args: Record<string, unknown>, cwd: string) =>
+				getSingletonClient().then((c) => c.callTool(name, args, cwd));
+		}
+		return undefined;
+	},
+});
+
+let _singletonInstance: McpClient | null = null;
+let _singletonPending: Promise<McpClient> | null = null;
+
+function getSingletonClient(): Promise<McpClient> {
+	if (_singletonInstance) return Promise.resolve(_singletonInstance);
+	if (_singletonPending) return _singletonPending;
+	_singletonPending = import("./mcp-client-factory").then((mod) => {
+		const { mode, serverUrl } = mod.McpClientFactory.loadConfig();
+		_singletonInstance = createMcpClient(mode, serverUrl ?? "");
+		return _singletonInstance;
+	});
+	return _singletonPending;
+}

package/src/remote-mcp-client.ts

@@ -0,0 +1,250 @@
+import { MAX_OUTPUT_CHARS } from "./gitnexus";
+
+const PREFIX = "[GitNexus]\n";
+
+export interface RemoteMcpClientConfig {
+	serverUrl: string;
+	timeout?: number;
+}
+
+interface JsonRpcResponse {
+	jsonrpc: "2.0";
+	id?: number;
+	result?: unknown;
+	error?: { code: number; message: string };
+}
+
+interface McpContent {
+	type: string;
+	text?: string;
+	isError?: boolean;
+}
+
+interface McpToolResult {
+	content: McpContent[];
+	isError?: boolean;
+}
+
+/** Default timeout for a single MCP request (ms). */
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * RemoteMcpClient — StreamableHTTP transport to a GitNexus MCP server.
+ *
+ * Uses native fetch() for all communication. Completes the MCP initialize
+ * handshake on the first callTool() invocation and reuses the session.
+ */
+export class RemoteMcpClient {
+	private serverUrl: string;
+	private initialized = false;
+	private stopped = false;
+	private timeoutMs: number;
+	private initPromise: Promise<void> | null = null;
+	private sessionId: string | null = null;
+
+	/**
+	 * @param configOrUrl - Either a config object `{ serverUrl, timeout? }` or a plain URL string.
+	 */
+	constructor(configOrUrl: RemoteMcpClientConfig | string) {
+		if (typeof configOrUrl === "string") {
+			this.serverUrl = configOrUrl.replace(/\/+$/, "");
+			this.timeoutMs = DEFAULT_TIMEOUT_MS;
+		} else {
+			this.serverUrl = (configOrUrl.serverUrl ?? "").replace(/\/+$/, "");
+			this.timeoutMs = configOrUrl.timeout ?? DEFAULT_TIMEOUT_MS;
+		}
+	}
+
+	/** Returns the configured server URL. */
+	getServerUrl(): string {
+		return this.serverUrl;
+	}
+
+	/** Returns whether the MCP initialize handshake has been completed. */
+	isInitialized(): boolean {
+		return this.initialized;
+	}
+
+	/**
+	 * POST a JSON-RPC message and return the parsed response.
+	 * Throws on network errors, timeouts, or MCP-level errors.
+	 */
+	private async rpcSend(
+		method: string,
+		params?: Record<string, unknown>,
+	): Promise<JsonRpcResponse> {
+		if (this.stopped)
+			throw new Error("[GitNexus] Remote MCP client is stopped.");
+
+		const body = {
+			jsonrpc: "2.0" as const,
+			id: 1,
+			method,
+			...(params !== undefined ? { params } : {}),
+		};
+
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+		try {
+			const headers: Record<string, string> = {
+				"Content-Type": "application/json",
+				Accept: "application/json, text/event-stream",
+			};
+			if (this.sessionId) headers["Mcp-Session-Id"] = this.sessionId;
+
+			const res = await Promise.race([
+				fetch(this.serverUrl, {
+					method: "POST",
+					headers,
+					body: JSON.stringify(body),
+					signal: controller.signal,
+				}),
+				new Promise<never>((_, reject) =>
+					setTimeout(() => {
+						controller.abort();
+						reject(
+							new Error(
+								`[GitNexus] Remote MCP request timed out after ${this.timeoutMs}ms`,
+							),
+						);
+					}, this.timeoutMs),
+				),
+			]);
+
+			if (!res.ok) {
+				throw new Error(`[GitNexus] HTTP ${res.status}`);
+			}
+
+			// Capture session ID for StreamableHTTP session stickiness
+			const sid = res.headers.get("mcp-session-id");
+			if (sid) this.sessionId = sid;
+
+			let data: JsonRpcResponse;
+			try {
+				data = (await res.json()) as JsonRpcResponse;
+			} catch {
+				throw new Error("[GitNexus] Malformed JSON response from remote MCP.");
+			}
+
+			if (data.error) {
+				throw new Error(
+					`[GitNexus] ${data.error.message || `MCP error ${data.error.code}`}`,
+				);
+			}
+
+			return data;
+		} catch (err) {
+			if (err instanceof Error && err.message.includes("timed out")) throw err;
+			if (err instanceof Error && err.message.startsWith("[GitNexus]"))
+				throw err;
+			throw new Error(
+				`[GitNexus] ${err instanceof Error ? err.message : String(err)}`,
+			);
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+
+	/**
+	 * Complete MCP initialize handshake (idempotent for concurrent callers).
+	 * Only runs once per client lifetime until stop() is called.
+	 */
+	private ensureInitialized(): Promise<void> {
+		if (this.initialized) return Promise.resolve();
+		if (this.stopped)
+			return Promise.reject(
+				new Error("[GitNexus] Remote MCP client is stopped."),
+			);
+
+		if (this.initPromise) return this.initPromise;
+
+		this.initPromise = (async () => {
+			try {
+				await this.rpcSend("initialize", {
+					protocolVersion: "2024-11-05",
+					capabilities: {},
+					clientInfo: { name: "pi-gitnexus", version: "0.1.0" },
+				});
+
+				// Send initialized notification (fire-and-forget)
+				try {
+					await fetch(this.serverUrl, {
+						method: "POST",
+						headers: { "Content-Type": "application/json" },
+						body: JSON.stringify({
+							jsonrpc: "2.0",
+							method: "notifications/initialized",
+						}),
+					});
+				} catch {
+					/* best-effort */
+				}
+
+				this.initialized = true;
+			} catch (err) {
+				this.initPromise = null;
+				throw new Error(
+					`[GitNexus] Remote MCP initialization failed: ${err instanceof Error ? err.message : String(err)}`,
+				);
+			}
+		})();
+
+		return this.initPromise;
+	}
+
+	/**
+	 * Call an MCP tool by name and return its formatted text response.
+	 * Handles text content extraction, truncation, and error mapping.
+	 */
+	async callTool(
+		name: string,
+		args: Record<string, unknown>,
+		_cwd?: string,
+	): Promise<string> {
+		await this.ensureInitialized();
+
+		if (this.stopped)
+			throw new Error("[GitNexus] Remote MCP client is stopped.");
+
+		const response = await this.rpcSend("tools/call", {
+			name,
+			arguments: args,
+		});
+
+		const result = response.result as McpToolResult | undefined;
+
+		if (!result?.content) {
+			throw new Error(
+				"[GitNexus] No response content returned from remote MCP.",
+			);
+		}
+
+		const text = result.content
+			.filter((c) => c.type === "text" && c.text)
+			.map((c) => c.text!)
+			.join("\n");
+
+		if (result.isError) {
+			throw new Error(
+				`[GitNexus] ${text || "Remote MCP reported an error with no text payload."}`,
+			);
+		}
+
+		if (!text) {
+			throw new Error("[GitNexus] Remote MCP returned an empty response.");
+		}
+
+		// Truncate including the prefix so total stays within MAX_OUTPUT_CHARS
+		const available = MAX_OUTPUT_CHARS - PREFIX.length;
+		return PREFIX + text.slice(0, Math.max(0, available));
+	}
+
+	/** Mark as stopped. Resets initialization state so next call re-initializes. */
+	stop(): void {
+		this.stopped = false; // Allow re-use after stop
+		this.initialized = false;
+		this.initPromise = null;
+		this.sessionId = null;
+	}
+}