@njuptlzf/mcp-adapter 2.29.0-0.0.1

package/abort.ts

@@ -0,0 +1,34 @@
+export function throwIfAborted(signal?: AbortSignal): void {
+  if (!signal?.aborted) return;
+  throw signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason ?? "MCP request aborted"));
+}
+
+export async function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return promise;
+  throwIfAborted(signal);
+  return await new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const cleanup = () => signal.removeEventListener("abort", onAbort);
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason ?? "MCP request aborted")));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      value => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve(value);
+      },
+      error => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(error);
+      },
+    );
+  });
+}

package/adapters/pi-renderer.ts

@@ -0,0 +1,7 @@
+import { Text } from "@earendil-works/pi-tui";
+
+export type RenderOutput = string;
+
+export function piRenderWrapper<T extends (...args: unknown[]) => RenderOutput>(fn: T) {
+  return (...args: Parameters<T>) => new Text(fn(...args), 0, 0);
+}

package/adapters/protocol-elicitation-forwarder.ts

@@ -0,0 +1,164 @@
+/**
+ * ProtocolElicitationForwarder — forwards MCP elicitation requests from
+ * downstream servers to the Agent Client via the MCP Server→Client
+ * `elicitation/create` reverse call.
+ *
+ * D-07: implements the `UISystem.form` interface.
+ *
+ * Threat model:
+ *   T-12-02 (Information Disclosure): `form()` must NEVER log
+ *   `result.content` — it may contain user PII. Only `result.action`
+ *   ("accept"/"decline"/"cancel") may be logged.
+ *
+ * Note: This causes a double conversion (MCP → FormConfig → MCP → Agent →
+ *   MCP → FormResult → ElicitResult) because `elicitation-handler.ts`
+ *   already converts MCP schema to FormConfig. This is an accepted
+ *   trade-off for architectural consistency. See RESEARCH Pitfall 3.
+ */
+
+import type {
+	FormConfig,
+	FormField,
+	FormResult,
+} from "../interfaces/host-types.ts";
+import type {
+	ElicitRequestFormParams,
+	ElicitResult,
+} from "@modelcontextprotocol/client";
+
+/** Minimal Server→Client reverse-call surface the forwarder needs. */
+type ElicitationForwardTarget = {
+	elicitInput(params: ElicitRequestFormParams): Promise<ElicitResult>;
+};
+
+/**
+ * Convert a `FormField` to a JSON Schema property definition.
+ *
+ * This is the reverse of `elicitation-handler.ts`'s
+ * `convertMcpSchemaToPiForm()`. It maps each FormField type to the
+ * corresponding JSON Schema property for `elicitInput`'s
+ * `requestedSchema`.
+ *
+ * Supported types:
+ *   - text        → { type: "string", minLength?, maxLength? }
+ *   - number      → { type: "number", minimum?, maximum? }
+ *   - integer     → { type: "integer", minimum?, maximum? }
+ *   - boolean     → { type: "boolean" }
+ *   - select      → { type: "string", enum: [...] }
+ *   - multiSelect → { type: "array", items: { type: "string", enum: [...] } }
+ *
+ * `title` (from `field.label`) is always included when present.
+ * `description` (from `field.description`) is included when present.
+ */
+export function convertFieldToSchema(field: FormField): Record<string, unknown> {
+	const type = field.type;
+	const label = field.label;
+	const description = (field as { description?: string }).description;
+
+	// Build the base object with optional title/description.
+	const buildBase = (): Record<string, unknown> => {
+		const base: Record<string, unknown> = {};
+		if (label !== undefined) base.title = label;
+		if (description !== undefined) base.description = description;
+		return base;
+	};
+
+	if (type === "select" || type === "multiSelect") {
+		const options = (field as { options?: Array<{ value: string; label?: string }> }).options ?? [];
+		if (type === "multiSelect") {
+			return {
+				type: "array",
+				items: { type: "string", enum: options.map((o) => o.value) },
+				...buildBase(),
+			};
+		}
+		return {
+			type: "string",
+			enum: options.map((o) => o.value),
+			...buildBase(),
+		};
+	}
+
+	if (type === "number" || type === "integer") {
+		const schema: Record<string, unknown> = { type, ...buildBase() };
+		const minimum = (field as { minimum?: number }).minimum;
+		const maximum = (field as { maximum?: number }).maximum;
+		if (minimum !== undefined) schema.minimum = minimum;
+		if (maximum !== undefined) schema.maximum = maximum;
+		return schema;
+	}
+
+	if (type === "boolean") {
+		return { type: "boolean", ...buildBase() };
+	}
+
+	// Default: text → string with optional minLength/maxLength
+	const schema: Record<string, unknown> = { type: "string", ...buildBase() };
+	const minLength = (field as { minLength?: number }).minLength;
+	const maxLength = (field as { maxLength?: number }).maxLength;
+	if (minLength !== undefined) schema.minLength = minLength;
+	if (maxLength !== undefined) schema.maxLength = maxLength;
+	return schema;
+}
+
+/**
+ * Forwards MCP elicitation requests to the Agent Client via
+ * `server.elicitInput()`.
+ *
+ * The forwarder is used when the connecting Agent Client declares
+ * `elicitation.form` capability. It implements the `UISystem.form`
+ * interface, converting `FormConfig` → `elicitInput` params and
+ * `ElicitResult` → `FormResult`.
+ *
+ * Action mapping:
+ *   ElicitResult.action "accept"  → FormResult.action "submit"  (with values)
+ *   ElicitResult.action "decline" → FormResult.action "secondary"
+ *   ElicitResult.action "cancel"  → FormResult.action "cancel"
+ */
+export class ProtocolElicitationForwarder {
+	constructor(private readonly server: ElicitationForwardTarget) {}
+
+	/**
+	 * Convert `FormConfig` to `ElicitRequestFormParams` and forward to
+	 * the Agent Client via `server.elicitInput()`.
+	 *
+	 * T-12-02: does NOT log `result.content` (may contain user PII).
+	 */
+	async form(config: FormConfig): Promise<FormResult> {
+		// Convert FormConfig fields back to JSON Schema for requestedSchema
+		const properties: Record<string, unknown> = {};
+		const required: string[] = [];
+
+		for (const field of config.fields) {
+			const schema = convertFieldToSchema(field);
+			properties[field.name] = schema;
+			if ((field as { required?: boolean }).required) {
+				required.push(field.name);
+			}
+		}
+
+		const result: ElicitResult = await this.server.elicitInput({
+			mode: "form",
+			message: config.message ?? "",
+			requestedSchema: {
+				type: "object" as const,
+				properties,
+				required: required.length > 0 ? required : undefined,
+			},
+		} as ElicitRequestFormParams);
+
+		// Map ElicitResult → FormResult
+		// T-12-02: only result.action is used for control flow — result.content
+		// is passed through as values without logging.
+		if (result.action === "accept") {
+			return {
+				action: "submit",
+				values: result.content as Record<string, unknown> | undefined,
+			};
+		}
+		if (result.action === "decline") {
+			return { action: "secondary" };
+		}
+		return { action: "cancel" };
+	}
+}

package/adapters/protocol-sampling-forwarder.ts

@@ -0,0 +1,108 @@
+/**
+ * ProtocolSamplingForwarder — forwards MCP sampling requests from downstream
+ * servers to the Agent Client via the MCP Server→Client `sampling/createMessage`
+ * reverse call.
+ *
+ * D-06: implements the `SamplingProvider` interface.
+ * D-11: pure forwarding — no config check, no local approval. If the Agent
+ *   Client declares `sampling` capability, mcp-adapter unconditionally
+ *   forwards. The Agent handles user approval, LLM call, and result.
+ *
+ * Threat model:
+ *   T-12-01 (Information Disclosure): `complete()` must NEVER log
+ *   `request.messages` or `request.systemPrompt` — they may contain tokens
+ *   or user content. Error paths only include the event name + error
+ *   message, following the T-10-01 pattern from StoreAgentAdapter.
+ */
+
+import type {
+	SamplingModel,
+	SamplingProvider,
+	SamplingRequest,
+	SamplingResponse,
+} from "../interfaces/sampling.ts";
+import type {
+	CreateMessageRequestParams,
+	CreateMessageResult,
+	ModelPreferences,
+} from "@modelcontextprotocol/client";
+
+/** Minimal Server→Client reverse-call surface the forwarder needs. */
+type SamplingForwardTarget = {
+	createMessage(params: CreateMessageRequestParams): Promise<CreateMessageResult>;
+};
+
+/**
+ * Forwards MCP sampling requests to the Agent Client via
+ * `server.createMessage()`.
+ *
+ * The forwarder is injected into `McpServerManager.setSamplingConfig()`
+ * when the connecting Agent Client declares `sampling` capability.
+ */
+export class ProtocolSamplingForwarder implements SamplingProvider {
+	constructor(private readonly server: SamplingForwardTarget) {}
+
+	/**
+	 * Returns a placeholder model. In pure forwarding mode (D-11), the Agent
+	 * Client handles actual model selection. The model returned here is not
+	 * used for the LLM call — it's only passed to `complete()` which ignores it.
+	 */
+	async resolveModel(_prefs?: ModelPreferences): Promise<SamplingModel | undefined> {
+		return { provider: "mcp-protocol", id: "forwarded" };
+	}
+
+	/**
+	 * Forward the sampling request to the Agent Client via
+	 * `server.createMessage()`.
+	 *
+	 * Converts `SamplingRequest.messages` to MCP `CreateMessageRequestParam`
+	 * messages (string content → text content block), calls
+	 * `server.createMessage()`, and maps `CreateMessageResult` to
+	 * `SamplingResponse`.
+	 *
+	 * T-12-01: does NOT log `request.messages` or `request.systemPrompt`.
+	 */
+	async complete(_model: SamplingModel, request: SamplingRequest): Promise<SamplingResponse> {
+		try {
+			// Convert SamplingRequest messages to MCP createMessage params.
+			// String content is wrapped as { type: "text", text }; array content
+			// (SamplingTextContent[]) is passed through.
+			const messages = request.messages.map((m) => ({
+				role: m.role,
+				content: typeof m.content === "string"
+					? { type: "text" as const, text: m.content }
+					: m.content,
+			}));
+
+			const result: CreateMessageResult = await this.server.createMessage({
+				messages,
+				systemPrompt: request.systemPrompt,
+				// maxTokens is required by the MCP protocol; SamplingRequest.maxTokens
+				// is optional at the interface level but always present at runtime
+				// (the downstream server's createMessage request includes it).
+				maxTokens: request.maxTokens ?? 0,
+			});
+
+			// Map CreateMessageResult → SamplingResponse
+			const text = result.content.type === "text" ? result.content.text : "";
+			return {
+				text,
+				model: result.model,
+				stopReason: result.stopReason ?? "endTurn",
+			};
+		} catch (err) {
+			// T-12-01: only log event name + error message — never request payload.
+			throw new Error(
+				`[ProtocolSamplingForwarder] complete failed: ${(err as Error).message}`,
+			);
+		}
+	}
+
+	/**
+	 * D-11: No local approval — the Agent Client handles user approval.
+	 * Always returns `true` unconditionally.
+	 */
+	async confirm(_title: string, _message: string): Promise<boolean> {
+		return true;
+	}
+}

package/adapters/universal-host.ts

@@ -0,0 +1,213 @@
+/**
+ * adapters/universal-host.ts — Universal MCP stdio host disguised as a Pi
+ * `ExtensionAPI`.
+ *
+ * Stage 2 (fork-host, not fork-engine): instead of the fork's parallel engine
+ * (`adapters/entry.ts`) driving registration through the fork `AgentAPI`
+ * abstraction, this class implements the *Pi* `ExtensionAPI` surface so the
+ * upstream `index.ts` engine (`installMcpAdapter`) can run unchanged against a
+ * non-Pi, MCP-stdio host.
+ *
+ * It is deliberately NOT declared as `implements ExtensionAPI` — the npm
+ * `@earendil-works/pi-coding-agent` types degrade `ExtensionAPI` to `any`, so
+ * the precise surface below is the fork-owned contract. The caller
+ * (`bin/mcp-server.ts`) casts to `ExtensionAPI` at the boundary.
+ *
+ * Surface implemented (evidence in upstream `index.ts`/`init.ts`/`utils.ts`):
+ *   registerTool / registerCommand / registerFlag / getFlag / on / events /
+ *   getAllTools / setActiveTools / getActiveTools / unregisterTool /
+ *   sendMessage / exec (+ `tools`/`activeTools` stores for MCP ListTools
+ *   filtering).
+ */
+
+import { EventEmitter } from "node:events";
+import type {
+	AgentChannel,
+	CommandConfig,
+	FlagConfig,
+	ToolInfo,
+	ToolRegistration,
+} from "../interfaces/host-types.ts";
+
+type EventHandler = (...args: unknown[]) => void | Promise<void>;
+
+/** Shape of an MCP-status event bus; satisfies upstream's `McpStatusEventBus`. */
+export type UniversalStatusEventBus = Pick<EventEmitter, "emit" | "on" | "removeAllListeners">;
+
+/** The fork-owned `ExtensionAPI` contract that upstream `installMcpAdapter` needs. */
+export interface UniversalHostSurface {
+	registerTool(tool: ToolRegistration): void;
+	registerCommand(name: string, config: CommandConfig): void;
+	registerFlag(name: string, config: FlagConfig): void;
+	getFlag(name: string): string | undefined;
+	on(event: string, handler: EventHandler): void;
+	getAllTools(): ToolInfo[];
+	setActiveTools(names: string[]): void;
+	getActiveTools(): string[];
+	unregisterTool(name: string): boolean;
+	sendMessage(message: unknown, options?: unknown): void;
+	exec(command: string, args: string[], options?: unknown): Promise<unknown>;
+}
+
+/**
+ * A host that presents the Pi `ExtensionAPI` surface backed by in-memory
+ * stores, so `index.ts`'s engine can register tools/commands/flags and wire
+ * session lifecycle events without a real Pi runtime.
+ */
+export class UniversalMcpHost implements UniversalHostSurface {
+	/** Registered tools by name. Public so MCP `ListTools`/`CallTool` handlers can enumerate. */
+	readonly tools = new Map<string, ToolRegistration>();
+	/** Registered tools that are currently "active" (surface-visible). */
+	private activeTools = new Set<string>();
+	/** Registered commands by name (no-op surface for MCP stdio). */
+	readonly commands = new Map<string, CommandConfig>();
+	/** Registered flags by name. Value mutable so `getFlag` reflects later updates. */
+	readonly flags = new Map<string, FlagConfig & { value?: string }>();
+	/** Event handlers keyed by event name. */
+	private readonly handlers = new Map<string, Set<EventHandler>>();
+	/** Status event bus (upstream sets `state.statusEvents = pi.events`). */
+	readonly events: UniversalStatusEventBus = new EventEmitter();
+
+	private channel: AgentChannel | undefined;
+	private static readonly PREFIX = "[mcp-adapter]";
+
+	// ------------------------------------------------------------------
+	// ExtensionAPI surface
+	// ------------------------------------------------------------------
+
+	registerTool(tool: ToolRegistration): void {
+		this.tools.set(tool.name, tool);
+		// Pi auto-activates a registered tool; mirror that so `getActiveTools()`
+		// returns the full registered surface unless the engine explicitly
+		// `setActiveTools`/`unregisterTool` narrows it.
+		this.activeTools.add(tool.name);
+	}
+
+	registerCommand(name: string, config: CommandConfig): void {
+		this.commands.set(name, config);
+	}
+
+	registerFlag(name: string, config: FlagConfig): void {
+		this.flags.set(name, { ...config });
+	}
+
+	getFlag(name: string): string | undefined {
+		return this.flags.get(name)?.value;
+	}
+
+	on(event: string, handler: EventHandler): void {
+		let set = this.handlers.get(event);
+		if (!set) {
+			set = new Set();
+			this.handlers.set(event, set);
+		}
+		set.add(handler);
+	}
+
+	getAllTools(): ToolInfo[] {
+		return [...this.tools.values()].map((t) => ({ name: t.name }));
+	}
+
+	setActiveTools(names: string[]): void {
+		this.activeTools = new Set(names);
+	}
+
+	getActiveTools(): string[] {
+		return [...this.activeTools];
+	}
+
+	unregisterTool(name: string): boolean {
+		this.activeTools.delete(name);
+		return this.tools.delete(name);
+	}
+
+	sendMessage(message: unknown, _options?: unknown): void {
+		if (this.channel) {
+			void this.channel.send(message);
+		}
+		// No channel — no-op. stderr routing is handled by the channel in main().
+	}
+
+	/**
+	 * Spawn a child process via node:child_process.spawn.
+	 * Used by upstream `openUrl` (OAuth browser launch) and panels.
+	 * No path from an untrusted MCP tool result to exec.
+	 */
+	async exec(command: string, args: string[], _options?: unknown): Promise<unknown> {
+		const cp = (await import("node:child_process")) as typeof import("node:child_process");
+		return await new Promise<{
+			code: number | null;
+			stdout: string;
+			stderr: string;
+		}>((resolvePromise, reject) => {
+			const child = cp.spawn(command, args, { stdio: ["ignore", "pipe", "pipe"] });
+			const stdoutChunks: Buffer[] = [];
+			const stderrChunks: Buffer[] = [];
+			child.stdout?.on("data", (chunk: Buffer) => stdoutChunks.push(chunk));
+			child.stderr?.on("data", (chunk: Buffer) => stderrChunks.push(chunk));
+			child.once("error", reject);
+			child.once("close", (code) => {
+				resolvePromise({
+					code,
+					stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+					stderr: Buffer.concat(stderrChunks).toString("utf8"),
+				});
+			});
+		});
+	}
+
+	// ------------------------------------------------------------------
+	// Companion methods (not part of ExtensionAPI)
+	// ------------------------------------------------------------------
+
+	/** Attach a universal AgentChannel for bidirectional communication. */
+	attachChannel(channel: AgentChannel): void {
+		this.channel = channel;
+	}
+
+	/** Drive a simulated `session_start` event with the supplied runtime context. */
+	async fireSessionStart(ctx: unknown): Promise<void> {
+		await this.fire("session_start", "session_start", ctx);
+	}
+
+	/** Drive a simulated `session_shutdown` event. */
+	async fireSessionShutdown(): Promise<void> {
+		await this.fire("session_shutdown");
+	}
+
+	/** Drive a simulated `input` event (keep-alive convergence hook). */
+	async fireInput(): Promise<void> {
+		await this.fire("input");
+	}
+
+	/** Drive a simulated `tool_result` event with the result details. */
+	async fireToolResult(details: unknown): Promise<void> {
+		await this.fire("tool_result", { details });
+	}
+
+	// ------------------------------------------------------------------
+	// Private helpers
+	// ------------------------------------------------------------------
+
+	/**
+	 * Invoke every handler registered for `event`, catching handler errors so
+	 * a single failing listener cannot break the host. Logs error prefix +
+	 * event name + handler count only — never the event args.
+	 */
+	private async fire(event: string, ...args: unknown[]): Promise<void> {
+		const set = this.handlers.get(event);
+		if (!set || set.size === 0) return;
+		const handlers = [...set];
+		await Promise.all(
+			handlers.map(async (h) => {
+				try {
+					await Promise.resolve(h(...args));
+				} catch (err) {
+					console.error(
+						`${UniversalMcpHost.PREFIX} handler error for event '${event}' (${set.size} handlers): ${(err as Error).message}`,
+					);
+				}
+			}),
+		);
+	}
+}

package/agent-dir.ts

@@ -0,0 +1,68 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export function getConfigDirName(): string {
+  const configDir = readPiConfig()?.configDir;
+  return typeof configDir === "string" && configDir.trim() ? configDir.trim() : ".pi";
+}
+
+export function getAgentDir(): string {
+  const piConfig = readPiConfig();
+  const name = piConfig?.name;
+  const appName = typeof name === "string" && name.trim() ? name.trim() : "pi";
+  const configured = process.env[`${appName.toUpperCase()}_CODING_AGENT_DIR`]?.trim();
+  if (!configured) {
+    return join(homedir(), getConfigDirName(), "agent");
+  }
+  if (configured === "~") {
+    return homedir();
+  }
+  if (configured.startsWith("~/")) {
+    return resolve(homedir(), configured.slice(2));
+  }
+  return resolve(configured);
+}
+
+export function getAgentPath(...segments: string[]): string {
+  return join(getAgentDir(), ...segments);
+}
+
+/**
+ * What the host calls itself.
+ *
+ * pi supports rebranding through `piConfig.name` in the package.json that its
+ * `getPackageDir()` resolves, and distributions built on pi (arc, tau, …) point
+ * `PI_PACKAGE_DIR` at their own manifest. Read that manifest directly rather
+ * than importing pi: this package deliberately depends on pi-ai and pi-tui
+ * only, and `getAgentDir()` above reads its env var the same self-contained way.
+ *
+ * Falls back to "pi", which is what pi's own APP_NAME resolves to.
+ */
+function readPiConfig(): { name?: unknown; configDir?: unknown; clientUri?: unknown } | undefined {
+  const dir = process.env.PI_PACKAGE_DIR?.trim()
+  if (!dir) return undefined
+  try {
+    const manifest = JSON.parse(readFileSync(join(resolve(dir), "package.json"), "utf8")) as {
+      piConfig?: { name?: unknown; configDir?: unknown; clientUri?: unknown }
+    }
+    return manifest.piConfig
+  } catch {
+    return undefined
+  }
+}
+
+export function getAppName(): string {
+  const name = readPiConfig()?.name
+  return typeof name === "string" && name.trim() ? name.trim() : "pi"
+}
+
+/**
+ * Home page the host declares for itself, via `piConfig.clientUri` in the same
+ * manifest that carries `piConfig.name`. Only the distribution knows its own
+ * URL, so this is the one place it can come from without guessing.
+ */
+export function getAppClientUri(): string | undefined {
+  const uri = readPiConfig()?.clientUri
+  return typeof uri === "string" && uri.trim() ? uri.trim() : undefined
+}