Skip to content

A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.

TypeScript
21.7 KB
Raw Blame
// The daemon's MCP proxy (S25.4): the engine talks to `/mcp/<connector>` with a per-launch key, and
// the daemon talks to the real server. Exercised through HTTP with pi-mcp's own client (as the engine
// connects), against in-memory, stdio, and HTTP upstreams.
import { readFileSync } from "node:fs";
import { createServer, type IncomingMessage, type Server } from "node:http";
import type { AddressInfo } from "node:net";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import {
	type JsonRpcMessage,
	McpClient,
	McpError,
	type McpTransport,
	StreamableHttpTransport,
	type Tool,
} from "@earendil-works/pi-mcp";
import { createInMemoryTransportPair } from "@earendil-works/pi-mcp/testing";
import { afterEach, describe, expect, it } from "vitest";
import {
	type ApprovalPreview,
	McpProxy,
	type ProxiedConnector,
	type UpstreamCredentials,
} from "../src/mcp-proxy.ts";
import { SecretsUnavailableError } from "../src/secret-source.ts";
import { tempDir, waitFor } from "./helpers.ts";

const FAKE_SERVER = fileURLToPath(new URL("./fixtures/fake-mcp-server.ts", import.meta.url));

const TOOLS: Tool[] = [
	{ name: "search", inputSchema: { type: "object" }, annotations: { readOnlyHint: true } },
	// Curated, but the server does not say it only reads: it is not read-only.
	{ name: "fetch", inputSchema: { type: "object" } },
	// Says it only reads, but nobody curated it.
	{ name: "peek", inputSchema: { type: "object" }, annotations: { readOnlyHint: true } },
	{ name: "send", inputSchema: { type: "object" }, annotations: { readOnlyHint: false } },
	{ name: "explode", inputSchema: { type: "object" }, annotations: { readOnlyHint: true } },
];

type Rec = Record<string, unknown>;

/** An MCP server behind an in-memory transport: every request it got, and how often it was closed. */
function memoryUpstream() {
	const requests: { method: string; params: Rec }[] = [];
	const state = { closed: 0, connects: 0, dropNext: false };
	const answer = (method: string, params: Rec): { result?: unknown; error?: Rec } => {
		switch (method) {
			case "initialize":
				return {
					result: {
						protocolVersion: params.protocolVersion,
						capabilities: { tools: {}, resources: {}, prompts: {} },
						serverInfo: { name: "upstream", version: "1" },
					},
				};
			case "tools/list":
				return { result: { tools: TOOLS } };
			case "tools/call":
				if (params.name === "explode") return { error: { code: -32042, message: "the upstream exploded" } };
				return { result: { content: [{ type: "text", text: `ran ${String(params.name)}` }] } };
			case "resources/list":
				return { result: { resources: [{ uri: "file:///a", name: "a" }] } };
			case "resources/templates/list":
				return { result: { resourceTemplates: [{ uriTemplate: "file:///{x}", name: "x" }] } };
			case "resources/read":
				return { result: { contents: [{ uri: params.uri, text: "contents" }] } };
			case "prompts/list":
				return { result: { prompts: [{ name: "summary" }] } };
			case "prompts/get":
				return { result: { messages: [{ role: "user", content: { type: "text", text: "hi" } }] } };
			default:
				return { result: {} };
		}
	};
	const transport = (): McpTransport => {
		state.connects++;
		const { client, server } = createInMemoryTransportPair();
		server.onClose(() => {
			state.closed++;
		});
		server.onMessage((message: JsonRpcMessage) => {
			if (!("method" in message) || !("id" in message)) return;
			const params = (message.params ?? {}) as Rec;
			requests.push({ method: message.method, params });
			if (state.dropNext && message.method === "tools/call") {
				state.dropNext = false;
				void server.close();
				return;
			}
			void server.send({
				jsonrpc: "2.0",
				id: message.id,
				...answer(message.method, params),
			} as JsonRpcMessage);
		});
		void server.start();
		return client;
	};
	const called = () => requests.filter((r) => r.method === "tools/call").map((r) => r.params.name);
	return { transport, requests, called, state };
}

function connector(overrides: Partial<ProxiedConnector> = {}): ProxiedConnector {
	return {
		id: "notes",
		name: "Notes",
		enabled: true,
		mode: "read_only",
		readOnlyTools: ["search", "fetch", "explode"],
		server: { url: "https://notes.example.com/mcp" },
		revision: "r1",
		...overrides,
	};
}

const servers: Server[] = [];
const proxies: McpProxy[] = [];
const clients: McpClient[] = [];
afterEach(async () => {
	await Promise.all(clients.splice(0).map((c) => c.close().catch(() => undefined)));
	await Promise.all(proxies.splice(0).map((p) => p.close()));
	await Promise.all(servers.splice(0).map((s) => new Promise((done) => s.close(done))));
});

async function listen(handler: (req: IncomingMessage, res: import("node:http").ServerResponse) => void) {
	const server = createServer(handler);
	servers.push(server);
	await new Promise<void>((done) => server.listen(0, "127.0.0.1", done));
	return `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
}

async function setup(
	options: {
		connectors?: ProxiedConnector[];
		approve?: (preview: ApprovalPreview) => Promise<boolean>;
		credentials?: (id: string) => Promise<UpstreamCredentials>;
		upstream?: ReturnType<typeof memoryUpstream>;
		inMemory?: boolean;
	} = {},
) {
	const views = new Map((options.connectors ?? [connector()]).map((c) => [c.id, c]));
	const upstream = options.upstream ?? memoryUpstream();
	const previews: ApprovalPreview[] = [];
	const logs: string[] = [];
	const proxy = new McpProxy({
		connector: (id) => views.get(id),
		credentials: options.credentials ?? (async () => ({})),
		approve: async (preview) => {
			previews.push(preview);
			return options.approve ? options.approve(preview) : true;
		},
		...(options.inMemory === false ? {} : { transport: upstream.transport }),
		env: process.env,
		cwd: tempDir(),
		log: (line) => logs.push(line),
	});
	proxies.push(proxy);
	const base = await listen((req, res) => proxy.handle(req, res));
	const key = proxy.rotateKey();
	/** A client like the engine's: plain streamable HTTP with the key in a header. */
	const open = async (id = "notes", withKey = key) => {
		const client = new McpClient({ name: "engine", version: "1" });
		clients.push(client);
		await client.connect(
			new StreamableHttpTransport({
				url: `${base}/mcp/${id}`,
				headers: { Authorization: `Bearer ${withKey}` },
			}),
		);
		return client;
	};
	const post = (path: string, body: unknown, headers: Record<string, string> = {}) =>
		fetch(`${base}${path}`, {
			method: "POST",
			headers: { "content-type": "application/json", accept: "application/json", ...headers },
			body: JSON.stringify(body),
		});
	return { proxy, views, upstream, previews, logs, base, key, open, post };
}

const rpc = (method: string, params: Rec = {}) => ({ jsonrpc: "2.0", id: 1, method, params });

async function rpcError(promise: Promise<unknown>): Promise<McpError> {
	const error = await promise.then(
		() => undefined,
		(e: unknown) => e,
	);
	expect(error).toBeInstanceOf(McpError);
	return error as McpError;
}

describe("MCP proxy: the engine's side (S25.4)", () => {
	it("answers only requests carrying this launch's key in the Authorization header", async () => {
		const { post, key, proxy, upstream } = await setup();
		const noKey = await post("/mcp/notes", rpc("ping"));
		expect(noKey.status).toBe(401);
		expect(noKey.headers.get("content-type")).toMatch(/^application\/json/);
		expect((await noKey.json()) as Rec).toMatchObject({ error: { code: -32001 } });
		expect((await post("/mcp/notes", rpc("ping"), { authorization: "Bearer nope" })).status).toBe(401);
		// The key is never taken from the address.
		expect((await post(`/mcp/notes?token=${key}&key=${key}`, rpc("ping"))).status).toBe(401);
		const ok = await post("/mcp/notes", rpc("ping"), { authorization: `Bearer ${key}` });
		expect(ok.status).toBe(200);
		expect(ok.headers.get("content-type")).toMatch(/^application\/json/);
		expect(await ok.json()).toEqual({ jsonrpc: "2.0", id: 1, result: {} });
		// A new engine launch gets a new key; the old one stops working.
		const next = proxy.rotateKey();
		expect(next).not.toBe(key);
		expect(next.length).toBeGreaterThanOrEqual(40);
		expect((await post("/mcp/notes", rpc("ping"), { authorization: `Bearer ${key}` })).status).toBe(401);
		expect((await post("/mcp/notes", rpc("ping"), { authorization: `Bearer ${next}` })).status).toBe(200);
		expect(upstream.state.connects).toBe(0);
	});

	it("speaks plain JSON: GET is 405, notifications are 202, unknown connectors and methods are errors", async () => {
		const { post, key, base } = await setup();
		const auth = { authorization: `Bearer ${key}` };
		expect((await fetch(`${base}/mcp/notes`, { headers: auth })).status).toBe(405);
		const note = await post("/mcp/notes", { jsonrpc: "2.0", method: "notifications/initialized" }, auth);
		expect(note.status).toBe(202);
		expect(await note.text()).toBe("");
		expect(((await (await post("/mcp/notes", rpc("nope/nothing"), auth)).json()) as Rec).error).toMatchObject(
			{
				code: -32601,
			},
		);
		const unknown = await post("/mcp/other", rpc("ping"), auth);
		expect(unknown.status).toBe(404);
		expect(((await unknown.json()) as Rec).error).toMatchObject({ code: -32000 });
		const broken = await fetch(`${base}/mcp/notes`, { method: "POST", headers: auth, body: "{oops" });
		expect(((await broken.json()) as Rec).error).toMatchObject({ code: -32700 });
		// A page in a browser cannot use it, even with the key.
		expect((await post("/mcp/notes", rpc("ping"), { ...auth, origin: "https://evil.example" })).status).toBe(
			403,
		);
	});

	it("is accepted by pi-mcp's client, as the engine connects, and connects upstream only when needed", async () => {
		const { open, upstream } = await setup();
		const client = await open();
		expect(client.serverCapabilities?.tools).toBeDefined();
		expect(upstream.state.connects).toBe(0);
		await client.listTools();
		expect(upstream.state.connects).toBe(1);
		await client.listTools();
		expect(upstream.state.connects).toBe(1);
	});
});

describe("MCP proxy: policy from the live connector state", () => {
	it("lists only curated tools the server marks read-only in read only, and every tool in read and send", async () => {
		const { open, views } = await setup();
		const client = await open();
		expect((await client.listTools()).map((t) => t.name)).toEqual(["search", "explode"]);
		views.set("notes", connector({ mode: "read_write" }));
		// The same connection sees the change: no engine restart.
		expect((await client.listTools()).map((t) => t.name)).toEqual([
			"search",
			"fetch",
			"peek",
			"send",
			"explode",
		]);
		views.set("notes", connector({ mode: "read_only" }));
		expect((await client.listTools()).map((t) => t.name)).toEqual(["search", "explode"]);
	});

	it("refuses hidden and unknown tools even when called directly, and forwards nothing", async () => {
		const { open, upstream, previews } = await setup();
		const client = await open();
		for (const name of ["send", "peek", "fetch"]) {
			const error = await rpcError(client.callTool(name, { to: "x" }));
			expect(error.code).toBe(-32602);
			expect(error.message).toContain("read only");
		}
		const unknown = await rpcError(client.callTool("format_disk", {}));
		expect(unknown.code).toBe(-32602);
		expect(unknown.message).toContain("format_disk");
		expect(upstream.called()).toEqual([]);
		expect(previews).toEqual([]);
		// A read-only call runs without asking.
		expect(await client.callTool("search", { q: "x" })).toEqual({
			content: [{ type: "text", text: "ran search" }],
		});
		expect(upstream.called()).toEqual(["search"]);
		expect(previews).toEqual([]);
	});

	it("asks once with the full preview before a sending action, and forwards nothing when declined", async () => {
		let allow = false;
		const { open, upstream, previews } = await setup({
			connectors: [connector({ mode: "read_write" })],
			approve: async () => allow,
		});
		const client = await open();
		const long = "x".repeat(10_000);
		const args = { to: "[email protected]", body: long, nested: { list: [1, 2, 3] } };
		const declined = await rpcError(client.callTool("send", args));
		expect(declined.message).toMatch(/did not allow/);
		expect(previews).toEqual([{ connectorId: "notes", connector: "Notes", tool: "send", arguments: args }]);
		expect(upstream.called()).toEqual([]);
		allow = true;
		expect(await client.callTool("send", args)).toEqual({ content: [{ type: "text", text: "ran send" }] });
		expect(previews).toHaveLength(2);
		expect(upstream.requests.find((r) => r.method === "tools/call")?.params).toEqual({
			name: "send",
			arguments: args,
		});
		// Read-only tools never ask, in either mode.
		await client.callTool("search", {});
		expect(previews).toHaveLength(2);
	});

	it("refuses when asking fails, and when the connector changed while the user was asked", async () => {
		const state: { fail: boolean; views?: Map<string, ProxiedConnector> } = { fail: true };
		const { open, upstream, views } = await setup({
			connectors: [connector({ mode: "read_write" })],
			approve: async () => {
				if (state.fail) throw new Error("no window");
				state.views?.set("notes", connector({ mode: "read_only" }));
				return true;
			},
		});
		state.views = views;
		const client = await open();
		expect((await rpcError(client.callTool("send", {}))).message).toMatch(/could not be asked|approval/i);
		state.fail = false;
		// Approved, but the user switched the connector to read only meanwhile.
		expect((await rpcError(client.callTool("send", {}))).message).toContain("read only");
		expect(upstream.called()).toEqual([]);
	});

	it("shows resources and prompts in read and send, and in read only only for a connector with a curated list", async () => {
		const { open, views, upstream } = await setup();
		const client = await open();
		expect(client.serverCapabilities?.resources).toBeDefined();
		expect(await client.listResources()).toEqual([{ uri: "file:///a", name: "a" }]);
		expect(await client.listResourceTemplates()).toHaveLength(1);
		expect((await client.readResource("file:///a")).contents).toHaveLength(1);
		expect(await client.request("prompts/list")).toEqual({ prompts: [{ name: "summary" }] });
		expect(await client.request("prompts/get", { name: "summary" })).toMatchObject({
			messages: [{ role: "user" }],
		});
		// A server of the user's own (no curated list) in read only exposes nothing.
		views.set("notes", connector({ readOnlyTools: [] }));
		const before = upstream.requests.length;
		expect(await client.listResources()).toEqual([]);
		expect(await client.listResourceTemplates()).toEqual([]);
		expect(await client.request("prompts/list")).toEqual({ prompts: [] });
		expect((await rpcError(client.readResource("file:///a"))).code).toBe(-32602);
		expect((await rpcError(client.request("prompts/get", { name: "summary" }))).code).toBe(-32602);
		expect(await client.listTools()).toEqual([]);
		expect(upstream.requests.slice(before).filter((r) => r.method !== "tools/list")).toEqual([]);
		views.set("notes", connector({ readOnlyTools: [], mode: "read_write" }));
		expect(await client.listResources()).toHaveLength(1);
	});

	it("refuses everything for a connector that is turned off", async () => {
		const { open, views, upstream } = await setup();
		const client = await open();
		views.set("notes", connector({ enabled: false }));
		const error = await rpcError(client.listTools());
		expect(error.message).toContain("turned off");
		expect(upstream.state.connects).toBe(0);
	});
});

describe("MCP proxy: upstream connections", () => {
	it("passes the upstream's errors on, and reconnects after the upstream dropped", async () => {
		const { open, upstream, logs } = await setup();
		const client = await open();
		const failed = await rpcError(client.callTool("explode", {}));
		expect([failed.code, failed.message]).toEqual([-32042, "the upstream exploded"]);
		upstream.state.dropNext = true;
		const dropped = await rpcError(client.callTool("search", {}));
		expect(dropped.message).toMatch(/could not reach notes|Notes/i);
		expect(upstream.state.connects).toBe(1);
		expect(await client.callTool("search", {})).toMatchObject({ content: [{ text: "ran search" }] });
		expect(upstream.state.connects).toBe(2);
		expect(logs.join("\n")).not.toContain("Bearer");
	});

	it("tells the model why the secret store is unavailable and keeps the reason in the log", async () => {
		const { open, upstream, logs } = await setup({
			credentials: async () => {
				throw new SecretsUnavailableError(
					"The secret store is unavailable: no Secret Service in this desktop session (bus); install and unlock a keyring such as GNOME Keyring or KWallet",
				);
			},
		});
		const client = await open();
		const failed = await rpcError(client.callTool("search", {}));
		expect(failed.message).toBe(
			"The secret store is unavailable: no Secret Service in this desktop session (bus); install and unlock a keyring such as GNOME Keyring or KWallet",
		);
		expect(upstream.state.connects).toBe(0);
		expect(logs).toContain(
			"connector notes cannot get its secrets: The secret store is unavailable: no Secret Service in this desktop session (bus); install and unlock a keyring such as GNOME Keyring or KWallet",
		);
	});

	it("closes a connector's upstream when it is removed, turned off, or its server changed, and all of them on close", async () => {
		const { open, views, upstream, proxy } = await setup();
		const client = await open();
		await client.listTools();
		proxy.sync();
		expect(upstream.state.closed).toBe(0);
		views.set("notes", connector({ mode: "read_write" }));
		proxy.sync();
		// A mode change keeps the connection.
		expect(upstream.state.closed).toBe(0);
		views.set("notes", connector({ revision: "r2" }));
		proxy.sync();
		await waitFor(() => upstream.state.closed === 1);
		await client.listTools();
		views.set("notes", connector({ enabled: false }));
		proxy.sync();
		await waitFor(() => upstream.state.closed === 2);
		views.set("notes", connector());
		await client.listTools();
		views.delete("notes");
		proxy.sync();
		await waitFor(() => upstream.state.closed === 3);
		views.set("notes", connector());
		await client.listTools();
		await proxy.close();
		await waitFor(() => upstream.state.closed === 4);
	});

	it("runs a stdio server itself, with the environment from the credentials, and stops it when removed", async () => {
		const dir = tempDir();
		const calls = join(dir, "calls.jsonl");
		const pidFile = join(dir, "pid");
		const stdio = connector({
			id: "chat",
			name: "Chat",
			mode: "read_write",
			readOnlyTools: ["list_messages"],
			server: { command: process.execPath, args: [FAKE_SERVER] },
		});
		const { open, views, proxy, previews } = await setup({
			connectors: [stdio],
			inMemory: false,
			credentials: async (id) => {
				expect(id).toBe("chat");
				return { env: { FAKE_MCP_SERVER_CALLS: calls, FAKE_MCP_SERVER_PID_FILE: pidFile } };
			},
		});
		const client = await open("chat");
		expect((await client.listTools()).map((t) => t.name)).toEqual([
			"list_messages",
			"notion-search",
			"send_message",
		]);
		expect(await client.callTool("list_messages", {})).toMatchObject({
			content: [{ text: "ran list_messages" }],
		});
		await client.callTool("send_message", { to: "a", body: "b" });
		expect(previews.map((p) => p.tool)).toEqual(["send_message"]);
		expect(
			readFileSync(calls, "utf8")
				.trim()
				.split("\n")
				.map((l) => JSON.parse(l).name),
		).toEqual(["list_messages", "send_message"]);
		const pid = Number(readFileSync(pidFile, "utf8"));
		const alive = () => {
			try {
				process.kill(pid, 0);
				return true;
			} catch {
				return false;
			}
		};
		expect(alive()).toBe(true);
		views.delete("chat");
		proxy.sync();
		await waitFor(() => !alive());
	});

	it("talks to a remote server over HTTP with the headers and token from the credentials", async () => {
		const seen: { authorization?: string; team?: string; method: string }[] = [];
		const upstreamUrl = await listen((req, res) => {
			let body = "";
			req.on("data", (chunk: Buffer) => {
				body += chunk.toString("utf8");
			});
			req.on("end", () => {
				if (req.method !== "POST") {
					res.writeHead(405).end();
					return;
				}
				const message = JSON.parse(body) as { id?: number; method: string; params?: Rec };
				seen.push({
					authorization: req.headers.authorization,
					team: req.headers["x-team"] as string | undefined,
					method: message.method,
				});
				if (message.id === undefined) {
					res.writeHead(202).end();
					return;
				}
				const result =
					message.method === "initialize"
						? {
								protocolVersion: message.params?.protocolVersion,
								capabilities: { tools: {} },
								serverInfo: { name: "remote", version: "1" },
							}
						: message.method === "tools/list"
							? { tools: TOOLS }
							: { content: [{ type: "text", text: "remote ran" }] };
				res.writeHead(200, { "content-type": "application/json" });
				res.end(JSON.stringify({ jsonrpc: "2.0", id: message.id, result }));
			});
		});
		const { open } = await setup({
			connectors: [connector({ server: { url: `${upstreamUrl}/mcp` } })],
			inMemory: false,
			credentials: async () => ({
				headers: { "X-Team": "blue" },
				authProvider: { token: async () => "upstream-access-token" },
			}),
		});
		const client = await open();
		expect(await client.callTool("search", {})).toMatchObject({ content: [{ text: "remote ran" }] });
		expect(seen.length).toBeGreaterThan(0);
		for (const request of seen) {
			expect(request.authorization).toBe("Bearer upstream-access-token");
			expect(request.team).toBe("blue");
		}
		expect(seen.map((r) => r.method)).toContain("tools/call");
	});

	it("says the user must sign in again when the upstream refuses the credentials", async () => {
		const upstreamUrl = await listen((req, res) => {
			req.resume();
			res.writeHead(401, { "content-type": "application/json" }).end("{}");
		});
		const { open } = await setup({
			connectors: [connector({ server: { url: `${upstreamUrl}/mcp` } })],
			inMemory: false,
		});
		const client = await open();
		const error = await rpcError(client.listTools());
		expect(error.message).toMatch(/sign in/i);
	});
});