pi-figma-remote-auth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DianP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# pi-figma-remote-auth
+
+A Pi extension that handles **OAuth authentication and MCP config** for Figma's hosted Remote MCP server (`https://mcp.figma.com/mcp`), so that an existing [`pi-mcp-adapter`](https://github.com/nicobailon/pi-mcp-adapter) install can expose Figma tools inside Pi.
+
+## What this does
+
+In short, it does two things:
+
+1. **Writes the MCP server config** (`mcpServers.figma`) into Pi's MCP config file, pointing at Figma's remote endpoint with `auth: "oauth"`.
+2. **Runs the OAuth flow** against Figma and saves the resulting tokens in `pi-mcp-adapter`'s auth store, so the adapter can connect without re-prompting.
+
+The OAuth step uses a workaround for Figma's MCP client allowlist: the dynamic client registration registers as `client_name: "Codex"` (which Figma allows), then the credentials are stored in the format `pi-mcp-adapter` expects. Same idea as [`mcp-auth-helper`](https://github.com/sdaoudi/mcp-auth-helper), but writing into the Pi adapter's storage instead of OpenCode's.
+
+This is **not** the local Figma desktop MCP bridge — it only configures the remote endpoint.
+
+## Prerequisite
+
+Install `pi-mcp-adapter` first:
+
+```sh
+pi install npm:pi-mcp-adapter
+```
+
+Restart Pi.
+
+## Install this package
+
+From npm:
+
+```sh
+pi install npm:pi-figma-remote-auth
+```
+
+Or from a local checkout:
+
+```sh
+pi install /absolute/path/to/pi-figma-remote-auth
+```
+
+Or for one run, without installing:
+
+```sh
+pi -e npm:pi-figma-remote-auth
+```
+
+## Usage
+
+Inside Pi:
+
+```text
+/figma-remote-auth setup
+/figma-remote-auth login
+```
+
+During `login`, Pi prints the Figma authorization URL. Copy it from the notification and open it in your browser — the extension does **not** auto-open and Pi's TUI may not render the URL as clickable. After authorizing, restart Pi (or `/mcp reconnect figma`) so `pi-mcp-adapter` reloads MCP config.
+
+Use Figma tools through the adapter proxy:
+
+```ts
+mcp({ search: "figma" });
+mcp({ connect: "figma" });
+mcp({ tool: "figma_TOOL_NAME", args: "{}" });
+```
+
+## Commands
+
+```text
+/figma-remote-auth help
+/figma-remote-auth status [--server figma]
+/figma-remote-auth setup  [--global|--project|--shared] [--server figma] [--url https://mcp.figma.com/mcp] [--direct-tools] [--keep-alive]
+/figma-remote-auth login  [--server figma] [--url https://mcp.figma.com/mcp] [--client-name Codex] [--port <port>]
+/figma-remote-auth logout [--server figma]
+```
+
+`setup` and `login` first check that `pi-mcp-adapter` exists. If missing, install it before continuing.
+
+By default, `login` uses a random free localhost callback port so it does not collide with `pi-mcp-adapter`'s own OAuth callback server. Use `--port` only when you need a fixed callback URL.
+
+Config targets:
+
+- `--global` (default): writes `~/.pi/agent/mcp.json` or `$PI_CODING_AGENT_DIR/mcp.json`
+- `--project`: writes `.pi/mcp.json`
+- `--shared`: writes `.mcp.json`
+
+Token store (written by `login`, removed by `logout`):
+
+- `$MCP_OAUTH_DIR/figma/tokens.json` when `$MCP_OAUTH_DIR` is set
+- otherwise `~/.pi/agent/mcp-oauth/figma/tokens.json` or `$PI_CODING_AGENT_DIR/mcp-oauth/figma/tokens.json`
+
+## Security
+
+Tokens are written with file mode `0600`. Pi packages execute code with local system access; review before installing.

package/index.ts

@@ -0,0 +1,197 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { existsSync } from "node:fs";
+import {
+	assertMcpAdapterExists,
+	hasMcpAdapter,
+	hasMcpAdapterExecutable,
+} from "./src/adapter.js";
+import {
+	type Command,
+	DEFAULT_FIGMA_MCP_URL,
+	completionsFor,
+	parseArgs,
+} from "./src/args.js";
+import {
+	configContainsServer,
+	getKnownConfigPaths,
+	writeMcpConfig,
+} from "./src/config.js";
+import {
+	getAuthFilePath,
+	readAuthEntry,
+	removeAuthFile,
+} from "./src/auth-store.js";
+import { runOAuthFlow } from "./src/oauth.js";
+import { formatUserError } from "./src/util.js";
+
+const COMMAND_NAME = "figma-remote-auth";
+
+export default function figmaRemoteAuthExtension(pi: ExtensionAPI) {
+	pi.registerCommand(COMMAND_NAME, {
+		description: "Setup/auth Figma Remote MCP for pi-mcp-adapter",
+		getArgumentCompletions: (prefix) => completionsFor(prefix),
+		handler: async (args, ctx) => {
+			let command: Command;
+			try {
+				command = parseArgs(args);
+			} catch (error) {
+				ctx.ui.notify(formatUserError(error), "error");
+				return;
+			}
+
+			try {
+				await dispatch(pi, ctx, command);
+			} catch (error) {
+				ctx.ui.notify(formatUserError(error), "error");
+			}
+		},
+	});
+}
+
+type CommandContext = Parameters<
+	NonNullable<Parameters<ExtensionAPI["registerCommand"]>[1]["handler"]>
+>[1];
+
+async function dispatch(
+	pi: ExtensionAPI,
+	ctx: CommandContext,
+	command: Command,
+): Promise<void> {
+	switch (command.kind) {
+		case "help":
+			ctx.ui.notify(helpText(), "info");
+			return;
+
+		case "status":
+			ctx.ui.notify(buildStatus(pi, command.serverName, ctx.cwd), "info");
+			return;
+
+		case "setup": {
+			assertMcpAdapterExists(pi);
+			const path = writeMcpConfig(command, ctx.cwd);
+			ctx.ui.notify(
+				[
+					`Figma Remote MCP config written: ${path}`,
+					`Restart Pi, then use: mcp({ connect: "${command.serverName}" })`,
+				].join("\n"),
+				"info",
+			);
+			return;
+		}
+
+		case "login": {
+			assertMcpAdapterExists(pi);
+			const confirmed = await ctx.ui.confirm(
+				"Figma Remote MCP OAuth",
+				[
+					`Start OAuth for "${command.serverName}" at ${command.url}?`,
+					"",
+					"Pi will show a copyable/clickable authorization URL.",
+					"Browser will not auto-open.",
+					"",
+					`Client name:  ${command.clientName}`,
+					`Token store:  ${getAuthFilePath(command.serverName)}`,
+				].join("\n"),
+			);
+			if (!confirmed) return;
+
+			ctx.ui.notify("Starting Figma OAuth flow…", "info");
+			ctx.ui.setStatus(COMMAND_NAME, "Waiting for Figma OAuth callback…");
+			try {
+				const authPath = await runOAuthFlow({
+					serverName: command.serverName,
+					url: command.url,
+					clientName: command.clientName,
+					callbackPort: command.callbackPort,
+					signal: ctx.signal,
+					onAuthorizationUrl: (authorizationUrl, callbackUrl) => {
+						ctx.ui.notify(
+							[
+								"Open this URL in your browser to authorize Figma:",
+								authorizationUrl,
+								"",
+								`Waiting for callback on ${callbackUrl}`,
+							].join("\n"),
+							"info",
+						);
+						console.log(
+							`\nFigma MCP authorization URL:\n${authorizationUrl}\n\nCallback URL: ${callbackUrl}\n`,
+						);
+					},
+				});
+				ctx.ui.notify(
+					[
+						`Figma OAuth credentials saved: ${authPath}`,
+						`Restart Pi or run /mcp reconnect ${command.serverName}.`,
+					].join("\n"),
+					"info",
+				);
+			} finally {
+				ctx.ui.setStatus(COMMAND_NAME, undefined);
+			}
+			return;
+		}
+
+		case "logout": {
+			const removed = removeAuthFile(command.serverName);
+			ctx.ui.notify(
+				removed
+					? `Cleared Figma OAuth credentials for "${command.serverName}".`
+					: `No Figma OAuth credentials found for "${command.serverName}".`,
+				"info",
+			);
+			return;
+		}
+	}
+}
+
+function helpText(): string {
+	return [
+		"Figma Remote MCP for pi-mcp-adapter",
+		"",
+		`/${COMMAND_NAME} status [--server <name>]`,
+		`/${COMMAND_NAME} setup  [--global|--project|--shared] [--direct-tools] [--keep-alive]`,
+		`/${COMMAND_NAME} login  [--client-name Codex] [--port <port>]`,
+		`/${COMMAND_NAME} logout [--server <name>]`,
+		"",
+		`Default endpoint:      ${DEFAULT_FIGMA_MCP_URL}`,
+		"Default config target: --global (<Pi agent dir>/mcp.json)",
+	].join("\n");
+}
+
+function buildStatus(
+	pi: ExtensionAPI,
+	serverName: string,
+	cwd: string,
+): string {
+	const configHits = getKnownConfigPaths(cwd).filter((path) =>
+		configContainsServer(path, serverName),
+	);
+	const authPath = getAuthFilePath(serverName);
+	const auth = readAuthEntry(authPath);
+	const adapterPresent = hasMcpAdapter(pi);
+	const adapterInstalled = adapterPresent || hasMcpAdapterExecutable();
+
+	const lines = [
+		`Figma Remote MCP status (server: "${serverName}")`,
+		`pi-mcp-adapter installed:    ${adapterInstalled ? "yes" : "no"}`,
+		`pi-mcp-adapter loaded now:   ${adapterPresent ? "yes" : "no"}`,
+		`config entries:              ${configHits.length ? configHits.join(", ") : "none"}`,
+		`auth file:                   ${existsSync(authPath) ? authPath : "missing"}`,
+	];
+
+	if (auth?.tokens?.expiresAt) {
+		const expires = new Date(auth.tokens.expiresAt * 1000).toISOString();
+		const valid = auth.tokens.expiresAt > Math.floor(Date.now() / 1000) + 60;
+		lines.push(
+			`token expires:               ${expires} (${valid ? "valid" : "expired/near expiry"})`,
+		);
+	} else if (auth?.tokens?.accessToken) {
+		lines.push("token expires:               unknown (no expires_in)");
+	}
+	if (auth?.serverUrl) {
+		lines.push(`auth server URL:             ${auth.serverUrl}`);
+	}
+
+	return lines.join("\n");
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "pi-figma-remote-auth",
+  "version": "0.1.0",
+  "description": "Pi extension that authenticates and configures Figma Remote MCP for pi-mcp-adapter.",
+  "type": "module",
+  "license": "MIT",
+  "author": "DianP",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "figma",
+    "mcp",
+    "remote-mcp",
+    "pi-mcp-adapter",
+    "oauth"
+  ],
+  "homepage": "https://github.com/dianp/pi-figma-remote-auth#readme",
+  "bugs": {
+    "url": "https://github.com/dianp/pi-figma-remote-auth/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dianp/pi-figma-remote-auth.git"
+  },
+  "engines": {
+    "node": ">=22.6.0"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "pretest": "node --experimental-strip-types tests/ensure-symlinks.ts",
+    "test": "tsc --noEmit",
+    "prepublishOnly": "npm test"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "pi-mcp-adapter": ">=2.5.4"
+  },
+  "peerDependenciesMeta": {
+    "pi-mcp-adapter": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "latest",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,38 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { existsSync } from "node:fs";
+import { delimiter, join } from "node:path";
+
+export function hasMcpAdapter(pi: ExtensionAPI): boolean {
+	try {
+		if (pi.getAllTools().some((tool) => tool.name === "mcp")) return true;
+		return pi
+			.getCommands()
+			.some((command) => command.name === "mcp" || command.name === "mcp-auth");
+	} catch {
+		return false;
+	}
+}
+
+export function hasMcpAdapterExecutable(): boolean {
+	const pathValue = process.env.PATH ?? "";
+	const executableNames =
+		process.platform === "win32"
+			? ["pi-mcp-adapter.cmd", "pi-mcp-adapter.exe", "pi-mcp-adapter"]
+			: ["pi-mcp-adapter"];
+
+	for (const dir of pathValue.split(delimiter)) {
+		if (!dir) continue;
+		for (const name of executableNames) {
+			if (existsSync(join(dir, name))) return true;
+		}
+	}
+
+	return false;
+}
+
+export function assertMcpAdapterExists(pi: ExtensionAPI): void {
+	if (hasMcpAdapter(pi) || hasMcpAdapterExecutable()) return;
+	throw new Error(
+		"pi-mcp-adapter not found. Install it first with `pi install npm:pi-mcp-adapter`, restart Pi, then retry.",
+	);
+}

package/src/args.ts

@@ -0,0 +1,272 @@
+export type ConfigTarget = "global" | "project" | "shared";
+
+export type Command =
+	| { kind: "help" }
+	| { kind: "status"; serverName: string }
+	| {
+			kind: "setup";
+			serverName: string;
+			url: string;
+			target: ConfigTarget;
+			directTools: boolean;
+			keepAlive: boolean;
+	  }
+	| {
+			kind: "login";
+			serverName: string;
+			url: string;
+			clientName: string;
+			callbackPort: number;
+	  }
+	| { kind: "logout"; serverName: string };
+
+export type CommandKind = Command["kind"];
+
+const SUBCOMMANDS = ["help", "status", "setup", "login", "logout"] as const;
+type SubcommandLiteral = (typeof SUBCOMMANDS)[number];
+
+export const DEFAULT_SERVER_NAME = "figma";
+export const DEFAULT_FIGMA_MCP_URL = "https://mcp.figma.com/mcp";
+export const DEFAULT_CLIENT_NAME = "Codex";
+export const DEFAULT_CALLBACK_PORT = 0;
+
+const FLAG_DESCRIPTIONS: Record<string, string> = {
+	"--global": "Write config to <Pi agent dir>/mcp.json (default)",
+	"--project": "Write config to .pi/mcp.json (project-local)",
+	"--shared": "Write config to .mcp.json (shared/checked-in)",
+	"--server": "Server name in mcpServers (default: figma)",
+	"--url": "Remote MCP endpoint (default: https://mcp.figma.com/mcp)",
+	"--client-name": "OAuth client_name to register (default: Codex)",
+	"--port": "Fixed callback port (default: random free)",
+	"--direct-tools": "Expose tools directly instead of via the proxy",
+	"--keep-alive": "Keep the MCP connection open instead of lazy",
+};
+
+const SUBCOMMAND_DESCRIPTIONS: Record<SubcommandLiteral, string> = {
+	help: "Show help",
+	status: "Show current install/config/auth status",
+	setup: "Write Figma Remote MCP entry into Pi's mcp.json",
+	login: "Run OAuth and save tokens for pi-mcp-adapter",
+	logout: "Remove the saved OAuth tokens",
+};
+
+const FLAGS_BY_SUBCOMMAND: Record<SubcommandLiteral, readonly string[]> = {
+	help: [],
+	status: ["--server"],
+	setup: [
+		"--global",
+		"--project",
+		"--shared",
+		"--server",
+		"--url",
+		"--direct-tools",
+		"--keep-alive",
+	],
+	login: ["--server", "--url", "--client-name", "--port"],
+	logout: ["--server"],
+};
+
+export interface CompletionItem {
+	value: string;
+	label: string;
+	description?: string;
+}
+
+export function parseArgs(input: string): Command {
+	const tokens = tokenize(input.trim());
+	const subcommandToken = (tokens.shift() ?? "help") as string;
+
+	if (!isSubcommand(subcommandToken)) {
+		throw new Error(
+			`Unknown subcommand: "${subcommandToken}". Try: ${SUBCOMMANDS.join(", ")}`,
+		);
+	}
+
+	const flags = collectFlags(tokens, subcommandToken);
+
+	switch (subcommandToken) {
+		case "help":
+			return { kind: "help" };
+		case "status":
+			return {
+				kind: "status",
+				serverName: flags.serverName ?? DEFAULT_SERVER_NAME,
+			};
+		case "setup":
+			return {
+				kind: "setup",
+				serverName: flags.serverName ?? DEFAULT_SERVER_NAME,
+				url: validateUrl(flags.url ?? DEFAULT_FIGMA_MCP_URL),
+				target: flags.target ?? "global",
+				directTools: flags.directTools ?? false,
+				keepAlive: flags.keepAlive ?? false,
+			};
+		case "login":
+			return {
+				kind: "login",
+				serverName: flags.serverName ?? DEFAULT_SERVER_NAME,
+				url: validateUrl(flags.url ?? DEFAULT_FIGMA_MCP_URL),
+				clientName: flags.clientName ?? DEFAULT_CLIENT_NAME,
+				callbackPort: flags.callbackPort ?? DEFAULT_CALLBACK_PORT,
+			};
+		case "logout":
+			return {
+				kind: "logout",
+				serverName: flags.serverName ?? DEFAULT_SERVER_NAME,
+			};
+	}
+}
+
+export function completionsFor(prefix: string): CompletionItem[] | null {
+	const tokens = tokenize(prefix.replace(/\s+$/, ""));
+	const trailingSpace = /\s$/.test(prefix);
+	const subcommandToken = tokens[0];
+	const subcommand = isSubcommand(subcommandToken) ? subcommandToken : null;
+	const last = trailingSpace ? "" : (tokens.at(-1) ?? "");
+
+	const completingSubcommand = tokens.length <= 1 && !trailingSpace;
+	const candidates = completingSubcommand
+		? [...SUBCOMMANDS]
+		: subcommand
+			? [...FLAGS_BY_SUBCOMMAND[subcommand]]
+			: [];
+
+	const items: CompletionItem[] = candidates
+		.filter((value) => value.startsWith(last))
+		.map((value) => ({
+			value,
+			label: value,
+			description: completingSubcommand
+				? SUBCOMMAND_DESCRIPTIONS[value as SubcommandLiteral]
+				: FLAG_DESCRIPTIONS[value],
+		}));
+
+	return items.length > 0 ? items : null;
+}
+
+interface CollectedFlags {
+	serverName?: string;
+	url?: string;
+	clientName?: string;
+	callbackPort?: number;
+	target?: ConfigTarget;
+	directTools?: boolean;
+	keepAlive?: boolean;
+}
+
+function collectFlags(
+	tokens: string[],
+	subcommand: SubcommandLiteral,
+): CollectedFlags {
+	const allowed = new Set(FLAGS_BY_SUBCOMMAND[subcommand]);
+	const flags: CollectedFlags = {};
+
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (!token.startsWith("--")) {
+			throw new Error(`Unexpected argument: ${token}`);
+		}
+		if (!allowed.has(token)) {
+			throw new Error(rejectFlagMessage(token, subcommand));
+		}
+
+		switch (token) {
+			case "--global":
+				flags.target = "global";
+				break;
+			case "--project":
+				flags.target = "project";
+				break;
+			case "--shared":
+				flags.target = "shared";
+				break;
+			case "--direct-tools":
+				flags.directTools = true;
+				break;
+			case "--keep-alive":
+				flags.keepAlive = true;
+				break;
+			case "--server":
+				flags.serverName = validateServerName(
+					requireValue(tokens, ++i, token),
+				);
+				break;
+			case "--url":
+				flags.url = requireValue(tokens, ++i, token);
+				break;
+			case "--client-name":
+				flags.clientName = requireValue(tokens, ++i, token);
+				break;
+			case "--port":
+				flags.callbackPort = parsePort(requireValue(tokens, ++i, token));
+				break;
+			default:
+				throw new Error(`Unknown option: ${token}`);
+		}
+	}
+
+	return flags;
+}
+
+function rejectFlagMessage(
+	flag: string,
+	subcommand: SubcommandLiteral,
+): string {
+	const allowed = FLAGS_BY_SUBCOMMAND[subcommand];
+	if (!allowed.length)
+		return `${flag} is not valid for "${subcommand}" (no options accepted)`;
+	return `${flag} is not valid for "${subcommand}". Allowed: ${allowed.join(", ")}`;
+}
+
+function isSubcommand(value: string | undefined): value is SubcommandLiteral {
+	return !!value && (SUBCOMMANDS as readonly string[]).includes(value);
+}
+
+function tokenize(input: string): string[] {
+	const result: string[] = [];
+	const pattern =
+		/"([^"\\]*(?:\\.[^"\\]*)*)"|'([^'\\]*(?:\\.[^'\\]*)*)'|(\S+)/g;
+	let match: RegExpExecArray | null;
+	while ((match = pattern.exec(input)) !== null) {
+		result.push(
+			(match[1] ?? match[2] ?? match[3]).replace(/\\(["'\\])/g, "$1"),
+		);
+	}
+	return result;
+}
+
+function requireValue(tokens: string[], index: number, option: string): string {
+	const value = tokens[index];
+	if (!value || value.startsWith("--"))
+		throw new Error(`${option} requires a value`);
+	return value;
+}
+
+function parsePort(value: string): number {
+	const port = Number.parseInt(value, 10);
+	if (!Number.isInteger(port) || port < 0 || port > 65535)
+		throw new Error(`Invalid port: ${value}`);
+	return port;
+}
+
+function validateServerName(serverName: string): string {
+	if (!/^[A-Za-z0-9_.-]+$/.test(serverName)) {
+		throw new Error(
+			"Server name may contain only letters, numbers, dot, underscore, and dash",
+		);
+	}
+	return serverName;
+}
+
+function validateUrl(value: string): string {
+	let parsed: URL;
+	try {
+		parsed = new URL(value);
+	} catch {
+		throw new Error(`Invalid --url: ${value}`);
+	}
+	if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+		throw new Error(`--url must be http(s): ${value}`);
+	}
+	return parsed.href;
+}

package/src/auth-store.ts

@@ -0,0 +1,91 @@
+import {
+	chmodSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { expandHome, getAgentPath } from "./paths.js";
+
+export interface RegisteredClient {
+	clientId: string;
+	clientSecret?: string;
+	clientIdIssuedAt?: number;
+	clientSecretExpiresAt?: number;
+}
+
+export interface TokenResponse {
+	access_token: string;
+	refresh_token?: string;
+	expires_in?: number;
+	scope?: string;
+	token_type?: string;
+}
+
+export interface AdapterAuthEntry {
+	tokens?: {
+		accessToken: string;
+		refreshToken?: string;
+		expiresAt?: number;
+		scope?: string;
+	};
+	clientInfo?: RegisteredClient;
+	codeVerifier?: string;
+	oauthState?: string;
+	serverUrl?: string;
+}
+
+export function getAuthFilePath(serverName: string): string {
+	const base = process.env.MCP_OAUTH_DIR?.trim() || getAgentPath("mcp-oauth");
+	return join(expandHome(base), serverName, "tokens.json");
+}
+
+export function saveAdapterAuth(
+	serverName: string,
+	serverUrl: string,
+	client: RegisteredClient,
+	tokens: TokenResponse,
+): string {
+	const now = Math.floor(Date.now() / 1000);
+	const entry: AdapterAuthEntry = {
+		tokens: {
+			accessToken: tokens.access_token,
+			refreshToken: tokens.refresh_token,
+			expiresAt: tokens.expires_in ? now + tokens.expires_in : undefined,
+			scope: tokens.scope,
+		},
+		clientInfo: client,
+		serverUrl,
+	};
+
+	const authPath = getAuthFilePath(serverName);
+	mkdirSync(dirname(authPath), { recursive: true, mode: 0o700 });
+	writeFileSync(authPath, `${JSON.stringify(entry, null, 2)}\n`, {
+		encoding: "utf8",
+		mode: 0o600,
+	});
+	try {
+		chmodSync(authPath, 0o600);
+	} catch {
+		// Best effort on platforms without POSIX chmod.
+	}
+	return authPath;
+}
+
+export function readAuthEntry(path: string): AdapterAuthEntry | undefined {
+	if (!existsSync(path)) return undefined;
+	try {
+		return JSON.parse(readFileSync(path, "utf8")) as AdapterAuthEntry;
+	} catch {
+		return undefined;
+	}
+}
+
+export function removeAuthFile(serverName: string): boolean {
+	const authPath = getAuthFilePath(serverName);
+	if (!existsSync(authPath)) return false;
+	rmSync(authPath, { force: true });
+	return true;
+}

package/src/config.ts

@@ -0,0 +1,71 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { ConfigTarget } from "./args.js";
+import { getAgentPath } from "./paths.js";
+import { asRecord, readJsonObject } from "./util.js";
+
+export interface WriteMcpConfigOptions {
+	serverName: string;
+	url: string;
+	target: ConfigTarget;
+	directTools: boolean;
+	keepAlive: boolean;
+}
+
+export function writeMcpConfig(
+	options: WriteMcpConfigOptions,
+	cwd: string,
+): string {
+	const configPath = getMcpConfigPath(options.target, cwd);
+	const config = readJsonObject(configPath);
+	const mcpServers = asRecord(config.mcpServers);
+	const server = {
+		url: options.url,
+		auth: "oauth",
+		lifecycle: options.keepAlive ? "keep-alive" : "lazy",
+		exposeResources: true,
+		directTools: options.directTools,
+	};
+
+	mcpServers[options.serverName] = server;
+	config.mcpServers = mcpServers;
+
+	mkdirSync(dirname(configPath), { recursive: true, mode: 0o700 });
+	writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+	return configPath;
+}
+
+export function getMcpConfigPath(target: ConfigTarget, cwd: string): string {
+	switch (target) {
+		case "global":
+			return getAgentPath("mcp.json");
+		case "project":
+			return join(cwd, ".pi", "mcp.json");
+		case "shared":
+			return join(cwd, ".mcp.json");
+	}
+}
+
+export function getKnownConfigPaths(cwd: string): string[] {
+	return [
+		getAgentPath("mcp.json"),
+		join(cwd, ".pi", "mcp.json"),
+		join(cwd, ".mcp.json"),
+	];
+}
+
+export function configContainsServer(
+	path: string,
+	serverName: string,
+): boolean {
+	if (!existsSync(path)) return false;
+	try {
+		const config = JSON.parse(readFileSync(path, "utf8")) as Record<
+			string,
+			unknown
+		>;
+		return Boolean(asRecord(config.mcpServers)[serverName]);
+	} catch {
+		return false;
+	}
+}

package/src/oauth.ts

@@ -0,0 +1,342 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import {
+	type RegisteredClient,
+	type TokenResponse,
+	saveAdapterAuth,
+} from "./auth-store.js";
+import {
+	base64Url,
+	fetchJson,
+	optionalNumberField,
+	optionalStringField,
+	stringField,
+} from "./util.js";
+
+const CALLBACK_PATH = "/callback";
+const AUTH_TIMEOUT_MS = 10 * 60 * 1000;
+
+export interface OAuthFlowOptions {
+	serverName: string;
+	url: string;
+	clientName: string;
+	callbackPort: number;
+	signal?: AbortSignal;
+	onAuthorizationUrl: (authorizationUrl: string, callbackUrl: string) => void;
+}
+
+export async function runOAuthFlow(options: OAuthFlowOptions): Promise<string> {
+	const { codeVerifier, codeChallenge } = generatePkce();
+	const state = base64Url(randomBytes(32));
+	const callbackListener = await waitForCallback(
+		options.callbackPort,
+		state,
+		options.signal,
+	);
+	const redirectUri = callbackListener.callbackUrl;
+
+	try {
+		const endpoints = await discoverOAuthEndpoints(options.url, options.signal);
+		if (!endpoints.registrationEndpoint) {
+			throw new Error("OAuth metadata did not include a registration_endpoint");
+		}
+
+		const client = await registerClient(
+			endpoints.registrationEndpoint,
+			redirectUri,
+			options.clientName,
+			options.signal,
+		);
+		const authorizationUrl = buildAuthorizationUrl(
+			endpoints.authorizationEndpoint,
+			client.clientId,
+			redirectUri,
+			codeChallenge,
+			state,
+		);
+
+		options.onAuthorizationUrl(authorizationUrl, redirectUri);
+
+		const callback = await callbackListener.result;
+		const tokens = await exchangeCodeForTokens(
+			endpoints.tokenEndpoint,
+			client,
+			redirectUri,
+			callback.code,
+			codeVerifier,
+			options.signal,
+		);
+		return saveAdapterAuth(options.serverName, options.url, client, tokens);
+	} finally {
+		callbackListener.close();
+	}
+}
+
+interface OAuthEndpoints {
+	authorizationEndpoint: string;
+	tokenEndpoint: string;
+	registrationEndpoint?: string;
+}
+
+async function discoverOAuthEndpoints(
+	serverUrl: string,
+	signal?: AbortSignal,
+): Promise<OAuthEndpoints> {
+	const base = new URL(serverUrl);
+	const wellKnownUrl = new URL(
+		"/.well-known/oauth-authorization-server",
+		base.origin,
+	).href;
+	const metadata = await fetchJson<Record<string, unknown>>(wellKnownUrl, { signal });
+	const authorizationEndpoint = stringField(metadata, "authorization_endpoint");
+	const tokenEndpoint = stringField(metadata, "token_endpoint");
+	const registrationEndpoint = optionalStringField(
+		metadata,
+		"registration_endpoint",
+	);
+
+	if (!authorizationEndpoint || !tokenEndpoint) {
+		throw new Error(`Invalid OAuth metadata from ${wellKnownUrl}`);
+	}
+
+	return { authorizationEndpoint, tokenEndpoint, registrationEndpoint };
+}
+
+async function registerClient(
+	registrationEndpoint: string,
+	redirectUri: string,
+	clientName: string,
+	signal?: AbortSignal,
+): Promise<RegisteredClient> {
+	const body = {
+		redirect_uris: [redirectUri],
+		client_name: clientName,
+		grant_types: ["authorization_code", "refresh_token"],
+		response_types: ["code"],
+		token_endpoint_auth_method: "none",
+	};
+
+	const result = await fetchJson<Record<string, unknown>>(
+		registrationEndpoint,
+		{
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify(body),
+			signal,
+		},
+	);
+
+	const clientId = stringField(result, "client_id");
+	if (!clientId)
+		throw new Error("OAuth registration response missing client_id");
+
+	return {
+		clientId,
+		clientSecret: optionalStringField(result, "client_secret"),
+		clientIdIssuedAt: optionalNumberField(result, "client_id_issued_at"),
+		clientSecretExpiresAt: optionalNumberField(
+			result,
+			"client_secret_expires_at",
+		),
+	};
+}
+
+function generatePkce(): { codeVerifier: string; codeChallenge: string } {
+	const codeVerifier = base64Url(randomBytes(32));
+	const codeChallenge = base64Url(
+		createHash("sha256").update(codeVerifier).digest(),
+	);
+	return { codeVerifier, codeChallenge };
+}
+
+function buildAuthorizationUrl(
+	authorizationEndpoint: string,
+	clientId: string,
+	redirectUri: string,
+	codeChallenge: string,
+	state: string,
+): string {
+	const url = new URL(authorizationEndpoint);
+	url.searchParams.set("response_type", "code");
+	url.searchParams.set("client_id", clientId);
+	url.searchParams.set("redirect_uri", redirectUri);
+	url.searchParams.set("code_challenge", codeChallenge);
+	url.searchParams.set("code_challenge_method", "S256");
+	url.searchParams.set("state", state);
+	return url.href;
+}
+
+async function exchangeCodeForTokens(
+	tokenEndpoint: string,
+	client: RegisteredClient,
+	redirectUri: string,
+	code: string,
+	codeVerifier: string,
+	signal?: AbortSignal,
+): Promise<TokenResponse> {
+	const params = new URLSearchParams();
+	params.set("grant_type", "authorization_code");
+	params.set("code", code);
+	params.set("redirect_uri", redirectUri);
+	params.set("client_id", client.clientId);
+	params.set("code_verifier", codeVerifier);
+	if (client.clientSecret) params.set("client_secret", client.clientSecret);
+
+	const result = await fetchJson<Record<string, unknown>>(tokenEndpoint, {
+		method: "POST",
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+		body: params.toString(),
+		signal,
+	});
+
+	const accessToken = stringField(result, "access_token");
+	if (!accessToken) throw new Error("Token response missing access_token");
+
+	return {
+		access_token: accessToken,
+		refresh_token: optionalStringField(result, "refresh_token"),
+		expires_in: optionalNumberField(result, "expires_in"),
+		scope: optionalStringField(result, "scope"),
+		token_type: optionalStringField(result, "token_type") ?? "Bearer",
+	};
+}
+
+interface CallbackListener {
+	callbackUrl: string;
+	result: Promise<{ code: string; state: string }>;
+	close: () => void;
+}
+
+async function waitForCallback(
+	port: number,
+	expectedState: string,
+	signal: AbortSignal | undefined,
+): Promise<CallbackListener> {
+	let resolveResult!: (result: { code: string; state: string }) => void;
+	let rejectResult!: (error: unknown) => void;
+	const result = new Promise<{ code: string; state: string }>(
+		(resolve, reject) => {
+			resolveResult = resolve;
+			rejectResult = reject;
+		},
+	);
+
+	let closed = false;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	let abortHandler: (() => void) | undefined;
+
+	const close = () => {
+		if (closed) return;
+		closed = true;
+		if (timer) clearTimeout(timer);
+		if (abortHandler) signal?.removeEventListener("abort", abortHandler);
+		try {
+			server.close();
+		} catch {
+			// Server may not be listening yet when a bind error fires.
+		}
+	};
+
+	const fail = (error: unknown) => {
+		rejectResult(error);
+		close();
+	};
+
+	const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+		let url: URL;
+		try {
+			const host = req.headers.host ?? `localhost:${port}`;
+			url = new URL(req.url ?? "/", `http://${host}`);
+		} catch {
+			res.writeHead(400, { "Content-Type": "text/plain" });
+			res.end("Bad request");
+			return;
+		}
+
+		if (url.pathname !== CALLBACK_PATH) {
+			res.writeHead(404, { "Content-Type": "text/plain" });
+			res.end("Not found");
+			return;
+		}
+
+		const oauthError = url.searchParams.get("error");
+		if (oauthError) {
+			const description =
+				url.searchParams.get("error_description") ?? "OAuth error";
+			res.writeHead(400, { "Content-Type": "text/plain" });
+			res.end(`${oauthError}: ${description}`);
+			fail(new Error(`${oauthError}: ${description}`));
+			return;
+		}
+
+		const code = url.searchParams.get("code");
+		const state = url.searchParams.get("state");
+		if (!code || !state) {
+			res.writeHead(400, { "Content-Type": "text/plain" });
+			res.end("OAuth callback missing code or state");
+			return;
+		}
+
+		if (state !== expectedState) {
+			res.writeHead(400, { "Content-Type": "text/plain" });
+			res.end("OAuth state mismatch");
+			return;
+		}
+
+		res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+		res.end(successHtml());
+		resolveResult({ code, state });
+		close();
+	});
+
+	await new Promise<void>((resolve, reject) => {
+		const onBindError = (error: unknown) => {
+			close();
+			reject(error);
+		};
+		server.once("error", onBindError);
+		server.listen(port, () => {
+			server.off("error", onBindError);
+			server.on("error", fail);
+			resolve();
+		});
+	});
+
+	timer = setTimeout(() => {
+		fail(new Error("Timed out waiting for OAuth callback"));
+	}, AUTH_TIMEOUT_MS);
+
+	if (signal) {
+		if (signal.aborted) {
+			fail(new Error("Aborted"));
+		} else {
+			abortHandler = () => fail(new Error("Aborted"));
+			signal.addEventListener("abort", abortHandler, { once: true });
+		}
+	}
+
+	const address = server.address();
+	const actualPort =
+		typeof address === "object" && address ? address.port : port;
+	return {
+		callbackUrl: `http://localhost:${actualPort}${CALLBACK_PATH}`,
+		result,
+		close,
+	};
+}
+
+function successHtml(): string {
+	return `<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<title>Figma MCP authorized</title>
+	</head>
+	<body style="font-family:system-ui,sans-serif;margin:3rem;max-width:32rem">
+		<h1>Figma MCP authorized</h1>
+		<p>You can close this tab and return to Pi.</p>
+	</body>
+</html>
+`;
+}

package/src/paths.ts

@@ -0,0 +1,18 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+export function getAgentDir(): string {
+	const configured = process.env.PI_CODING_AGENT_DIR?.trim();
+	if (!configured) return join(homedir(), ".pi", "agent");
+	return expandHome(configured);
+}
+
+export function getAgentPath(...segments: string[]): string {
+	return join(getAgentDir(), ...segments);
+}
+
+export function expandHome(path: string): string {
+	if (path === "~") return homedir();
+	if (path.startsWith("~/")) return resolve(homedir(), path.slice(2));
+	return resolve(path);
+}

package/src/util.ts

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from "node:fs";
+
+export function asRecord(value: unknown): Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+	return value as Record<string, unknown>;
+}
+
+export function stringField(
+	record: Record<string, unknown>,
+	key: string,
+): string {
+	const value = record[key];
+	return typeof value === "string" ? value : "";
+}
+
+export function optionalStringField(
+	record: Record<string, unknown>,
+	key: string,
+): string | undefined {
+	const value = record[key];
+	return typeof value === "string" ? value : undefined;
+}
+
+export function optionalNumberField(
+	record: Record<string, unknown>,
+	key: string,
+): number | undefined {
+	const value = record[key];
+	return typeof value === "number" ? value : undefined;
+}
+
+export function base64Url(buffer: Buffer): string {
+	return buffer
+		.toString("base64")
+		.replace(/=/g, "")
+		.replace(/\+/g, "-")
+		.replace(/\//g, "_");
+}
+
+export function formatUserError(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export function readJsonObject(path: string): Record<string, unknown> {
+	if (!existsSync(path)) return {};
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (error) {
+		throw new Error(`Failed to read ${path}: ${formatUserError(error)}`);
+	}
+	try {
+		return asRecord(JSON.parse(raw));
+	} catch (error) {
+		throw new Error(`Invalid JSON in ${path}: ${formatUserError(error)}`);
+	}
+}
+
+export async function fetchJson<T>(url: string, init?: RequestInit, timeoutMs = 30_000): Promise<T> {
+	const method = init?.method ?? "GET";
+	const timeoutSignal = AbortSignal.timeout(timeoutMs);
+	const signal = init?.signal
+		? AbortSignal.any([init.signal, timeoutSignal])
+		: timeoutSignal;
+	const response = await fetch(url, { ...init, signal });
+	if (!response.ok) {
+		const text = await response.text().catch(() => "");
+		throw new Error(
+			`${method} ${url} failed: ${response.status} ${response.statusText}${
+				text ? ` - ${text.slice(0, 500)}` : ""
+			}`,
+		);
+	}
+	try {
+		return (await response.json()) as T;
+	} catch {
+		throw new Error(`${method} ${url} returned non-JSON body`);
+	}
+}