feat: add support for using as a CLI via fetch subcommand to retrieve design data directly (#331)

* test: add result serialization behavior tests

Verify YAML and JSON serialization behavior matching the inline logic
in get-figma-data-tool.ts. Tests cover the performance-critical YAML
options (noRefs, lineWidth, noCompatMode, JSON_SCHEMA) and round-trip
correctness for both formats. These tests will anchor a future
extraction of serialization into a shared function.

* test(config): add unit tests for config resolution helpers

Export resolve, envStr, envInt, envBool (and Source, Resolved types)
from config.ts and add 13 unit tests covering the priority chain
and environment variable parsing. These are safety-net tests before
an upcoming config refactor.

* test: add process-level CLI startup tests

Pin current binary startup behavior before rewriting bin.ts:
- Verify NODE_ENV=cli triggers stdio mode without --stdio flag
- Verify HTTP mode starts via bin.ts and accepts MCP requests

* test: add edge case coverage for config resolution and YAML schema

Add falsy-value preservation test for resolve() (false, 0 must not fall
through to env/default). Add YAML schema quoting test verifying
JSON_SCHEMA skips unnecessary quoting of ambiguous strings like "yes"
and "2024-01-01".

* docs: update plan with Phase 1 completion and simplifications

* feat(utils): add Figma URL parser for fetch subcommand

Parses Figma URLs into fileKey and nodeId components, handling
/file/ and /design/ path formats and converting URL-style node IDs
(dashes) to API-style (colons).

* refactor(utils): extract serializeResult to shared utility

Move YAML/JSON serialization logic from get-figma-data-tool.ts into
utils/serialize.ts so it can be reused by the upcoming CLI fetch command.
Update serialization tests to import from the new module.

* refactor: restructure CLI as router with parameterized config

Move CLI parsing (cleye) from config.ts to bin.ts, making bin.ts the
entry-point router that dispatches to the server path or fetch
subcommand. config.ts becomes a toolkit of composable helpers:
getServerConfig(flags), resolveAuth(), loadEnvFile().

startServer() now accepts a ServerConfig object instead of calling
getServerConfig() internally, completing the separation of parsing
from execution.

* feat: implement CLI fetch subcommand

Add `figma-developer-mcp fetch` that performs a one-off Figma data
fetch to stdout. Supports positional URL argument or explicit
--file-key/--node-id flags, with flags overriding URL-derived values.

Pipeline: parse URL → load .env → resolve auth → FigmaService →
getRawNode/getRawFile → simplifyRawFigmaObject → serializeResult →
stdout.

* chore: address review feedback and mark plan complete

- Invert empty if-branch in bin.ts for clarity
- Narrow mcp-server.ts public API to only getServerConfig/ServerConfig
  (loadEnvFile, resolveAuth, ServerFlags are internal utilities)
- Mark Phase 2 done in plan document

* fix: handle malformed URL when file-key flag is provided

parseFigmaUrl() threw before flags could override URL-derived values.
Now URL parsing failures are non-fatal when --file-key is already set.

Also tighten hostname validation to reject lookalike domains like
notfigma.com (check exact match or .figma.com subdomain).

* chore: remove plan doc from branch

Author: GLips

CHANGELOG.md

@@ -2,75 +2,66 @@
 
 ## [0.8.1](https://github.com/GLips/Figma-Context-MCP/compare/v0.8.0...v0.8.1) (2026-04-07)
 
-
 ### Bug Fixes
 
-* disambiguate named styles with duplicate names ([#319](https://github.com/GLips/Figma-Context-MCP/issues/319)) ([a077ace](https://github.com/GLips/Figma-Context-MCP/commit/a077ace9809bf6b14c4e4a9906065fb3cea2d24f))
-* include BOOLEAN_OPERATION in SVG container collapse ([354679e](https://github.com/GLips/Figma-Context-MCP/commit/354679eab17389c551a435ca7c5224a250446301))
-* include BOOLEAN_OPERATION in SVG container collapse ([19c50b3](https://github.com/GLips/Figma-Context-MCP/commit/19c50b3ad3ecf12ce4b4bedc0aefff718b3b89f9))
-* replace jimp with selective @jimp/* imports to fix ESM crash ([#333](https://github.com/GLips/Figma-Context-MCP/issues/333)) ([dd47ebf](https://github.com/GLips/Figma-Context-MCP/commit/dd47ebf82520c6147b913415db99c3b4caaa40b2)), closes [#329](https://github.com/GLips/Figma-Context-MCP/issues/329)
+- disambiguate named styles with duplicate names ([#319](https://github.com/GLips/Figma-Context-MCP/issues/319)) ([a077ace](https://github.com/GLips/Figma-Context-MCP/commit/a077ace9809bf6b14c4e4a9906065fb3cea2d24f))
+- include BOOLEAN_OPERATION in SVG container collapse ([354679e](https://github.com/GLips/Figma-Context-MCP/commit/354679eab17389c551a435ca7c5224a250446301))
+- include BOOLEAN_OPERATION in SVG container collapse ([19c50b3](https://github.com/GLips/Figma-Context-MCP/commit/19c50b3ad3ecf12ce4b4bedc0aefff718b3b89f9))
+- replace jimp with selective @jimp/\* imports to fix ESM crash ([#333](https://github.com/GLips/Figma-Context-MCP/issues/333)) ([dd47ebf](https://github.com/GLips/Figma-Context-MCP/commit/dd47ebf82520c6147b913415db99c3b4caaa40b2)), closes [#329](https://github.com/GLips/Figma-Context-MCP/issues/329)
 
 ## [0.8.0](https://github.com/GLips/Figma-Context-MCP/compare/v0.7.1...v0.8.0) (2026-03-24)
 
-
 ### ⚠ BREAKING CHANGES
 
-* switch to stateless HTTP transport ([#304](https://github.com/GLips/Figma-Context-MCP/issues/304))
+- switch to stateless HTTP transport ([#304](https://github.com/GLips/Figma-Context-MCP/issues/304))
 
 ### Features
 
-* add progress notifications and async tree walker ([#305](https://github.com/GLips/Figma-Context-MCP/issues/305)) ([b5724ad](https://github.com/GLips/Figma-Context-MCP/commit/b5724ade8234e73fe94467c6bfad5e020552f0e2))
-
+- add progress notifications and async tree walker ([#305](https://github.com/GLips/Figma-Context-MCP/issues/305)) ([b5724ad](https://github.com/GLips/Figma-Context-MCP/commit/b5724ade8234e73fe94467c6bfad5e020552f0e2))
 
 ### Performance Improvements
 
-* fix O(n²) bottlenecks in simplification and YAML serialization ([#307](https://github.com/GLips/Figma-Context-MCP/issues/307)) ([29cff0c](https://github.com/GLips/Figma-Context-MCP/commit/29cff0cbd6d2fd0459900e9c3cbc49f64e47075d))
-
+- fix O(n²) bottlenecks in simplification and YAML serialization ([#307](https://github.com/GLips/Figma-Context-MCP/issues/307)) ([29cff0c](https://github.com/GLips/Figma-Context-MCP/commit/29cff0cbd6d2fd0459900e9c3cbc49f64e47075d))
 
 ### Code Refactoring
 
-* switch to stateless HTTP transport ([#304](https://github.com/GLips/Figma-Context-MCP/issues/304)) ([9dfb1cb](https://github.com/GLips/Figma-Context-MCP/commit/9dfb1cb65a081655d7dca5f076ab76f5d7e9edc0))
+- switch to stateless HTTP transport ([#304](https://github.com/GLips/Figma-Context-MCP/issues/304)) ([9dfb1cb](https://github.com/GLips/Figma-Context-MCP/commit/9dfb1cb65a081655d7dca5f076ab76f5d7e9edc0))
 
 ## [0.7.1](https://github.com/GLips/Figma-Context-MCP/compare/v0.7.0...v0.7.1) (2026-03-20)
 
-
 ### Bug Fixes
 
-* handle drive root paths in image directory security check ([#301](https://github.com/GLips/Figma-Context-MCP/issues/301)) ([9f32616](https://github.com/GLips/Figma-Context-MCP/commit/9f32616caa29b1dbdd5c5a9dcfafa3dd717070a3))
+- handle drive root paths in image directory security check ([#301](https://github.com/GLips/Figma-Context-MCP/issues/301)) ([9f32616](https://github.com/GLips/Figma-Context-MCP/commit/9f32616caa29b1dbdd5c5a9dcfafa3dd717070a3))
 
 ## [0.7.0](https://github.com/GLips/Figma-Context-MCP/compare/v0.6.6...v0.7.0) (2026-03-19)
 
-
 ### ⚠ BREAKING CHANGES
 
-* getServerConfig() no longer takes an isStdioMode parameter. It now detects stdio mode internally and returns it as part of ServerConfig.
+- getServerConfig() no longer takes an isStdioMode parameter. It now detects stdio mode internally and returns it as part of ServerConfig.
 
 ### Features
 
-* add --image-dir config for image download path control ([#297](https://github.com/GLips/Figma-Context-MCP/issues/297)) ([0417766](https://github.com/GLips/Figma-Context-MCP/commit/0417766eb5fc1e0b76e55da497961f9aee2f62f7))
-* replace yargs with cleye for CLI flag parsing ([#285](https://github.com/GLips/Figma-Context-MCP/issues/285)) ([0092ee7](https://github.com/GLips/Figma-Context-MCP/commit/0092ee789fce01b9ef1dab5e8f32c52e71107dbb))
-* support gifRef for downloading animated GIF embeds ([#286](https://github.com/GLips/Figma-Context-MCP/issues/286)) ([f1ec913](https://github.com/GLips/Figma-Context-MCP/commit/f1ec9133c31a351b55651126c20ea2f842c0a9ee))
-
+- add --image-dir config for image download path control ([#297](https://github.com/GLips/Figma-Context-MCP/issues/297)) ([0417766](https://github.com/GLips/Figma-Context-MCP/commit/0417766eb5fc1e0b76e55da497961f9aee2f62f7))
+- replace yargs with cleye for CLI flag parsing ([#285](https://github.com/GLips/Figma-Context-MCP/issues/285)) ([0092ee7](https://github.com/GLips/Figma-Context-MCP/commit/0092ee789fce01b9ef1dab5e8f32c52e71107dbb))
+- support gifRef for downloading animated GIF embeds ([#286](https://github.com/GLips/Figma-Context-MCP/issues/286)) ([f1ec913](https://github.com/GLips/Figma-Context-MCP/commit/f1ec9133c31a351b55651126c20ea2f842c0a9ee))
 
 ### Bug Fixes
 
-* remove inline release-type so release-please reads config file ([a03cd68](https://github.com/GLips/Figma-Context-MCP/commit/a03cd68826da1c1596273a223a612eb919832397))
-* replace sharp dependency with js-native jimp for image manipulation ([#289](https://github.com/GLips/Figma-Context-MCP/issues/289)) ([62b9f94](https://github.com/GLips/Figma-Context-MCP/commit/62b9f94b1607dd08daeaa90e8ace0a896fe6eb50))
-* skip jimp processing for SVGs and prevent image-fill collapse ([#298](https://github.com/GLips/Figma-Context-MCP/issues/298)) ([a4a4b13](https://github.com/GLips/Figma-Context-MCP/commit/a4a4b13ec7cae5d603022b1c8719cc717749195b))
+- remove inline release-type so release-please reads config file ([a03cd68](https://github.com/GLips/Figma-Context-MCP/commit/a03cd68826da1c1596273a223a612eb919832397))
+- replace sharp dependency with js-native jimp for image manipulation ([#289](https://github.com/GLips/Figma-Context-MCP/issues/289)) ([62b9f94](https://github.com/GLips/Figma-Context-MCP/commit/62b9f94b1607dd08daeaa90e8ace0a896fe6eb50))
+- skip jimp processing for SVGs and prevent image-fill collapse ([#298](https://github.com/GLips/Figma-Context-MCP/issues/298)) ([a4a4b13](https://github.com/GLips/Figma-Context-MCP/commit/a4a4b13ec7cae5d603022b1c8719cc717749195b))
 
 ## [0.6.6](https://github.com/GLips/Figma-Context-MCP/compare/v0.6.5...v0.6.6) (2026-03-04)
 
-
 ### Bug Fixes
 
-* use Node 24 in release workflow for npm OIDC support ([11ba7c6](https://github.com/GLips/Figma-Context-MCP/commit/11ba7c6a2e22910c483592ba7cdc1966fcdc9166))
+- use Node 24 in release workflow for npm OIDC support ([11ba7c6](https://github.com/GLips/Figma-Context-MCP/commit/11ba7c6a2e22910c483592ba7cdc1966fcdc9166))
 
 ## [0.6.5](https://github.com/GLips/Figma-Context-MCP/compare/v0.6.4...v0.6.5) (2026-03-04)
 
-
 ### Bug Fixes
 
-* upgrade MCP SDK to 1.27.1 and modernize tool registration ([#282](https://github.com/GLips/Figma-Context-MCP/issues/282)) ([4153e5f](https://github.com/GLips/Figma-Context-MCP/commit/4153e5f857aa708ee9ee10156e553c1289f03cf7))
+- upgrade MCP SDK to 1.27.1 and modernize tool registration ([#282](https://github.com/GLips/Figma-Context-MCP/issues/282)) ([4153e5f](https://github.com/GLips/Figma-Context-MCP/commit/4153e5f857aa708ee9ee10156e553c1289f03cf7))
 
 ## 0.6.4
 

src/bin.ts

@@ -1,8 +1,66 @@
 #!/usr/bin/env node
 
+import { cli } from "cleye";
+import { getServerConfig } from "./config.js";
 import { startServer } from "./server.js";
+import { fetchCommand } from "./commands/fetch.js";
 
-startServer().catch((error) => {
-  console.error("Failed to start server:", error);
-  process.exit(1);
+const argv = cli({
+  name: "figma-developer-mcp",
+  version: process.env.NPM_PACKAGE_VERSION ?? "unknown",
+  flags: {
+    figmaApiKey: {
+      type: String,
+      description: "Figma API key (Personal Access Token)",
+    },
+    figmaOauthToken: {
+      type: String,
+      description: "Figma OAuth Bearer token",
+    },
+    env: {
+      type: String,
+      description: "Path to custom .env file to load environment variables from",
+    },
+    port: {
+      type: Number,
+      description: "Port to run the server on",
+    },
+    host: {
+      type: String,
+      description: "Host to run the server on",
+    },
+    json: {
+      type: Boolean,
+      description: "Output data from tools in JSON format instead of YAML",
+    },
+    skipImageDownloads: {
+      type: Boolean,
+      description: "Do not register the download_figma_images tool (skip image downloads)",
+    },
+    imageDir: {
+      type: String,
+      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",
+    },
+  },
+  commands: [fetchCommand],
 });
+
+// Subcommand callbacks execute during cli() — only start the server when no subcommand ran.
+if (!argv.command) {
+  // NODE_ENV=cli is a legacy backdoor for stdio mode
+  const isStdio = argv.flags.stdio === true || process.env.NODE_ENV === "cli";
+  const config = getServerConfig({ ...argv.flags, stdio: isStdio });
+  startServer(config).catch((error) => {
+    console.error("Failed to start server:", error);
+    process.exit(1);
+  });
+}

src/commands/fetch.ts

@@ -0,0 +1,107 @@
+import { type Command, command } from "cleye";
+import { loadEnvFile, resolveAuth } from "~/config.js";
+import { FigmaService } from "~/services/figma.js";
+import {
+  simplifyRawFigmaObject,
+  allExtractors,
+  collapseSvgContainers,
+} from "~/extractors/index.js";
+import { serializeResult } from "~/utils/serialize.js";
+import { parseFigmaUrl } from "~/utils/figma-url.js";
+
+export const fetchCommand: Command = command(
+  {
+    name: "fetch",
+    description: "Fetch simplified Figma data and print to stdout",
+    parameters: ["[url]"],
+    flags: {
+      fileKey: {
+        type: String,
+        description: "Figma file key (overrides URL)",
+      },
+      nodeId: {
+        type: String,
+        description: "Node ID, format 1234:5678 (overrides URL)",
+      },
+      depth: {
+        type: Number,
+        description: "Tree traversal depth",
+      },
+      json: {
+        type: Boolean,
+        description: "Output JSON instead of YAML",
+      },
+      figmaApiKey: {
+        type: String,
+        description: "Figma API key",
+      },
+      figmaOauthToken: {
+        type: String,
+        description: "Figma OAuth token",
+      },
+      env: {
+        type: String,
+        description: "Path to .env file",
+      },
+    },
+  },
+  (argv) => {
+    run(argv.flags, argv._).catch((error) => {
+      console.error(error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    });
+  },
+);
+
+async function run(
+  flags: {
+    fileKey?: string;
+    nodeId?: string;
+    depth?: number;
+    json?: boolean;
+    figmaApiKey?: string;
+    figmaOauthToken?: string;
+    env?: string;
+  },
+  positionals: string[],
+) {
+  const url = positionals[0];
+  let fileKey = flags.fileKey;
+  let nodeId = flags.nodeId;
+
+  if (url) {
+    try {
+      const parsed = parseFigmaUrl(url);
+      fileKey ??= parsed.fileKey;
+      nodeId ??= parsed.nodeId;
+    } catch (error) {
+      if (!fileKey) throw error;
+      // fileKey provided via flag — malformed URL is non-fatal
+    }
+  }
+
+  if (!fileKey) {
+    console.error("Either a Figma URL or --file-key is required");
+    process.exit(1);
+  }
+
+  loadEnvFile(flags.env);
+  const auth = resolveAuth(flags);
+  const figmaService = new FigmaService(auth);
+
+  const depth = flags.depth;
+  const rawApiResponse = nodeId
+    ? await figmaService.getRawNode(fileKey, nodeId, depth)
+    : await figmaService.getRawFile(fileKey, depth);
+
+  const simplifiedDesign = await simplifyRawFigmaObject(rawApiResponse, allExtractors, {
+    maxDepth: depth,
+    afterChildren: collapseSvgContainers,
+  });
+
+  const { nodes, globalVars, ...metadata } = simplifiedDesign;
+  const result = { metadata, nodes, globalVars };
+
+  const outputFormat = flags.json ? "json" : "yaml";
+  console.log(serializeResult(result, outputFormat));
+}