feat: add proxy support for managed networks (#338)

* feat(config): add undici dependency and --proxy config option

Add `undici` as a production dependency (needed for proxy-aware fetch
dispatcher in a follow-up change). Add `--proxy` CLI flag and support
for FIGMA_PROXY, HTTPS_PROXY, and HTTP_PROXY env vars with a
4-source fallback chain. The proxy URL is included in startup config
logging.

* feat(proxy): set global fetch dispatcher at startup

Route all fetch() calls through the configured proxy by setting
undici's global dispatcher after config resolution. Uses ProxyAgent
for explicit --proxy values and EnvHttpProxyAgent as the default to
automatically respect HTTP_PROXY/HTTPS_PROXY/NO_PROXY env vars.

* refactor: replace curl fallback with proxy-aware error messaging

Remove the curl subprocess fallback from fetchWithRetry and replace it
with connection error detection that guides users toward proxy
configuration when they encounter network failures.

* refactor: address review findings

- Rename fetchWithRetry → fetchJSON (and file) since it no longer retries
- Narrow proxy config to only --proxy/FIGMA_PROXY; let EnvHttpProxyAgent
  handle HTTPS_PROXY/HTTP_PROXY/NO_PROXY correctly at the dispatcher level
- Mask proxy URL in startup logs (show "configured" vs "none")

* fix: downgrade undici to 6.x for Node 18+ compatibility

undici 8.x requires Node >= 22.19, but the project supports Node >= 18.
undici 6.x supports Node 18+, is actively maintained through the Node
20/22 LTS cycle, and provides all the APIs we need (ProxyAgent,
EnvHttpProxyAgent, setGlobalDispatcher).

* fix: use 'network proxy' wording instead of 'corporate'

Author: GLips

package.json

@@ -63,6 +63,7 @@
     "express": "^5.2.1",
     "js-yaml": "^4.1.1",
     "remeda": "^2.20.1",
+    "undici": "^6.24.1",
     "zod": "^3.25.76"
   },
   "devDependencies": {

pnpm-lock.yaml

@@ -14,6 +14,7 @@ interface ServerConfig {
   auth: FigmaAuthOptions;
   port: number;
   host: string;
+  proxy: string | undefined;
   outputFormat: "yaml" | "json";
   skipImageDownloads: boolean;
   imageDir: string;
@@ -90,6 +91,10 @@ export function getServerConfig(): ServerConfig {
         description:
           "Base directory for image downloads. The download tool will only write files within this directory. Defaults to the current working directory.",
       },
+      proxy: {
+        type: String,
+        description: "HTTP proxy URL for networks that require a proxy (e.g. http://proxy:8080)",
+      },
       stdio: {
         type: Boolean,
         description: "Run in stdio transport mode for MCP clients",
@@ -121,6 +126,11 @@ export function getServerConfig(): ServerConfig {
     process.cwd(),
   );
 
+  // Only resolve explicit proxy config here. Standard env vars (HTTPS_PROXY, HTTP_PROXY,
+  // NO_PROXY) are handled by undici's EnvHttpProxyAgent at the dispatcher level, which
+  // correctly respects NO_PROXY exclusions.
+  const proxy = resolve(argv.flags.proxy, envStr("FIGMA_PROXY"), undefined);
+
   // These two don't fit the simple pattern: --json maps to a string enum,
   // and --stdio has a NODE_ENV backdoor.
   const outputFormat = resolve<"yaml" | "json">(
@@ -151,6 +161,7 @@ export function getServerConfig(): ServerConfig {
     figmaOauthToken: figmaOauthToken.source,
     port: port.source,
     host: host.source,
+    proxy: proxy.source,
     outputFormat: outputFormat.source,
     skipImageDownloads: skipImageDownloads.source,
     imageDir: imageDir.source,
@@ -172,6 +183,7 @@ export function getServerConfig(): ServerConfig {
     }
     console.log(`- FRAMELINK_PORT: ${port.value} (source: ${configSources.port})`);
     console.log(`- FRAMELINK_HOST: ${host.value} (source: ${configSources.host})`);
+    console.log(`- PROXY: ${proxy.value ? "configured" : "none"} (source: ${configSources.proxy})`);
     console.log(`- OUTPUT_FORMAT: ${outputFormat.value} (source: ${configSources.outputFormat})`);
     console.log(
       `- SKIP_IMAGE_DOWNLOADS: ${skipImageDownloads.value} (source: ${configSources.skipImageDownloads})`,
@@ -184,6 +196,7 @@ export function getServerConfig(): ServerConfig {
     auth,
     port: port.value,
     host: host.value,
+    proxy: proxy.value,
     outputFormat: outputFormat.value,
     skipImageDownloads: skipImageDownloads.value,
     imageDir: imageDir.value,

src/config.ts

@@ -3,6 +3,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
 import { Server } from "http";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ProxyAgent, EnvHttpProxyAgent, setGlobalDispatcher } from "undici";
 import { Logger } from "./utils/logger.js";
 import { createServer } from "./mcp/index.js";
 import { getServerConfig } from "./config.js";
@@ -23,6 +24,14 @@ const activeConnections = new Set<ActiveConnection>();
 export async function startServer(): Promise<void> {
   const config = getServerConfig();
 
+  if (config.proxy) {
+    setGlobalDispatcher(new ProxyAgent(config.proxy));
+  } else {
+    // EnvHttpProxyAgent automatically respects HTTP_PROXY/HTTPS_PROXY/NO_PROXY
+    // env vars when present, and falls through to direct connections when absent.
+    setGlobalDispatcher(new EnvHttpProxyAgent());
+  }
+
   const serverOptions = {
     isHTTP: !config.isStdioMode,
     outputFormat: config.outputFormat as "yaml" | "json",

src/server.ts

@@ -7,7 +7,7 @@ import type {
 } from "@figma/rest-api-spec";
 import { downloadAndProcessImage, type ImageProcessingResult } from "~/utils/image-processing.js";
 import { Logger, writeLogs } from "~/utils/logger.js";
-import { fetchWithRetry } from "~/utils/fetch-with-retry.js";
+import { fetchJSON } from "~/utils/fetch-json.js";
 
 export type FigmaAuthOptions = {
   figmaApiKey: string;
@@ -61,7 +61,7 @@ export class FigmaService {
       Logger.log(`Calling ${this.baseUrl}${endpoint}`);
       const headers = this.getAuthHeaders();
 
-      return await fetchWithRetry<T & { status?: number }>(`${this.baseUrl}${endpoint}`, {
+      return await fetchJSON<T & { status?: number }>(`${this.baseUrl}${endpoint}`, {
         headers,
       });
     } catch (error) {

src/services/figma.ts

@@ -0,0 +1,46 @@
+type RequestOptions = RequestInit & {
+  /**
+   * Force format of headers to be a record of strings, e.g. { "Authorization": "Bearer 123" }
+   *
+   * Avoids complexity of needing to deal with `instanceof Headers`, which is not supported in some environments.
+   */
+  headers?: Record<string, string>;
+};
+
+const CONNECTION_ERROR_CODES = new Set([
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ETIMEDOUT",
+  "ENOTFOUND",
+  "UND_ERR_CONNECT_TIMEOUT",
+]);
+
+export async function fetchJSON<T extends { status?: number }>(
+  url: string,
+  options: RequestOptions = {},
+): Promise<T> {
+  try {
+    const response = await fetch(url, options);
+
+    if (!response.ok) {
+      throw new Error(`Fetch failed with status ${response.status}: ${response.statusText}`);
+    }
+    return (await response.json()) as T;
+  } catch (error: unknown) {
+    if (isConnectionError(error)) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `${message}\n\nCould not connect to the Figma API. If your network requires a proxy, ` +
+          `set the --proxy flag in your MCP server config or the FIGMA_PROXY environment variable ` +
+          `to your proxy URL (e.g. http://proxy:8080).`,
+      );
+    }
+    throw error;
+  }
+}
+
+function isConnectionError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const cause = (error as { cause?: { code?: string } }).cause;
+  return cause?.code !== undefined && CONNECTION_ERROR_CODES.has(cause.code);
+}