v2.0.0 — Figma watch: renamed, and agents can comment back

Figma listen is now Figma watch, published as @realmikekelly/figma-watch. Agents can now reply in Figma.

Commenting

• New watch_post_comment tool: post a comment pinned to a node (by ID or Figma URL) or reply to any comment in a thread. The official Figma MCP can't post comments.
• No self-echo: comments the agent posts are never delivered back to it as events, even if a poll sees them before Figma's response arrives. Replies from people still arrive normally.
• Scope detection: Figma has no scope-introspection endpoint. At startup the server makes requests a typical token can't make (GET /v2/webhooks, then an empty POST /v1/dev_resources that can't create anything) and reads the granted scopes from Figma's rejection. The tool is hidden without file_comments:write. If the scopes can't be determined, the tool is offered and then removed with tools/list_changed if Figma rejects a post for scope. doctor reports the detected scopes.

Breaking changes

Before	After
@realmikekelly/figma-listen	@realmikekelly/figma-watch
figma-listen command	figma-watch
listen_* tools	watch_* tools
FIGMA_LISTEN_STATE_DIR	FIGMA_WATCH_STATE_DIR (the old name still works)

Tokens saved by figma-listen auth are found and copied automatically. Update MCP configs and any prompts that name the old tools.

Validation: 62 automated tests (Node 20/22/24 CI), TypeScript checks, an installed-tarball CLI smoke test, and live scope detection against a read-only token, which correctly hides the tool. Posting a comment live hasn't been tested yet, because it needs a token with file_comments:write.

v1.3.0 — Scoped design changesets

Design edits now accumulate until the subscribed scope has been quiet for 120 seconds, then flush as a net changeset. Each additional in-scope design change restarts the timer. Comments and reactions remain prompt; edits outside the scope do not delay its batch.

• Detect edits even when Figma mutates a document under the same version ID. Design polling compares full document snapshots, with shared requests and existing queue pacing/backoff.
• Preserve pending changesets across restarts; require successful reads before flushing; suppress fully reverted changes and temporary deletions.
• Keep independent baselines/timers for overlapping subscriptions. Multi-file subscriptions flush one event per changed file after the scope is quiet.
• Add --design-quiet SECS (default 120, 0 for immediate observed deltas), changeset timing fields, and pending-batch status.

Validation: 47 automated tests, TypeScript checks, and installed-tarball CLI smoke test. Tests include same-version mutations, exact quiet boundaries, scope isolation, restarts, failures, and MCP push/replay.

The tarball is attached. npm publication remains pending account login. Automatic Codex wakeups remain unverified; delivery over the experimental MCP Events protocol requires a compatible host.

Figma listen v1.2.1 — current document version checks

Fix design-change detection when Figma's metadata endpoint lags behind the current document. Version checks now use a shallow document read (GET /files/:key?depth=1); full document snapshots are fetched only after the version/name changes or to establish a baseline.

Live testing found the metadata endpoint still returning an older version while the document endpoint already exposed an edit. The resulting design event contained 13 changed nodes. The fix uses the endpoint that exposed the current version in that test. Shallow checks use the Tier 1 file-content budget and no longer require file_metadata:read.

Validation: 39 automated tests, including a regression for stale metadata, TypeScript checks and packaged CLI startup passed. Codex CLI 0.160.0 successfully created a subscription and retrieved live comment creation/replies, edits, deletion, resolution/reopening, reaction additions/removals and a file-level design-change event. Native CLI event-stream delivery and automatic wakeups remain unverified.

The compiled @mikekelly/figma-listen tarball is attached. npm registry publication is still pending npm authentication.

Figma listen v1.2.0 — scoped activity events

Figma listen now follows design review activity beyond new comments. Subscribe to a file, page, section or frame to receive comment edits, deletions, resolutions and reopenings, emoji reaction additions/removals, and scoped design changes.

• Nine event types, selectable with event_types; omitted means all supported events.
• Figma URL scopes or explicit IDs, with subscriptions following node identity through renames and moves. Changes crossing a scope boundary are classified as entered/left; deleting the watched target emits figma.scope.deleted.
• Design version polling gates shared document snapshots. Events identify affected nodes, changed property names and previous/current hierarchy; large diffs explicitly report truncation.
• Separate comment, reaction and design jobs retain the nonblocking FIFO scheduler, coalescing, global request pacing and rate-limit backoff.
• Persistent snapshots support replay and detecting differences across restart. Existing v1.1 subscriptions remain new-comments-only when migrated.
• npm package name: @mikekelly/figma-listen. The compiled tarball is attached; registry publication is pending npm authentication.

Validation: 38 automated tests, TypeScript checks, packaged CLI startup, npm publish dry-run, and live Figma authentication/MCP startup passed. Live activity deltas and Codex automatic wakeups remain unverified. Polling reports differences between observed API snapshots, not every editor action.

Figma listen v1.1 — rapid concurrent polling

Figma listen now targets three-second polling with nonblocking FIFO dispatch. Slow Figma responses no longer serialize all resources or stretch the scheduling timer.

• Independent three-second producer (configurable down to one second).
• One pending or in-flight polling job per file or discovery scope; repeated ticks coalesce duplicates.
• Shared upstream HTTP dispatcher: FIFO starts, configurable request-start spacing (default two seconds), and at most four concurrent requests.
• HTTP 429 pauses the shared request queue for Retry-After, preserving pending work and FIFO order. Already sent requests may finish.
• Failed resources use exponential retry backoff independently; successful polls reset their backoff.
• Network waits happen outside the state mutation lock, keeping subscription and cancellation tools responsive.
• Overlapping subscriptions share file polling and discovery. listen_status exposes queue, concurrency, and backoff state.

The desired interval is independent of response time. Effective per-resource polling remains subject to global request capacity, rate-limit pauses, and the rule preventing duplicate work for an already in-flight resource. Two subscriptions to the same file require one poll, not two.

Figma publishes PAT rate limits, shared per user and resource plan rather than independently per token. Comments are Tier 2. The request-spacing safeguard is our configurable limit, not a Figma-mandated two-second rule. See Figma rate limits.

npx -y github:mikekelly/figma-listen#v1.1.0 doctor

Update any pinned MCP config from #v1.0.1 to #v1.1.0. Existing subscription state and credentials remain compatible. The compiled npm tarball is attached; the npm registry package is not yet published.

Validated with 21 tests covering FIFO ordering, duplicate suppression, slow-request concurrency, bounded workers, independent timer scheduling, global Retry-After, exponential backoff, and existing event/persistence/protocol behavior. Also checked live authentication and MCP status. No live comment activity or Codex automatic wakeups were tested.

Figma listen v1

Figma listen is a local TypeScript MCP companion for subscribing to Figma comments and replies. It polls Figma REST directly and delivers events over stdio, with no webhook or hosted service.

• File, page, frame, folder, team, and explicitly configured organization scopes.
• Exact hashtag filters, including #bot, with optional replies to tagged root threads.
• Persistent subscriptions, deduplicated events, cursor replay, retention gap reporting, and rate-limit backoff.
• Environment token authentication and an interactive system-keyring authentication command.
• Five standard MCP tools, plus experimental MCP Events events/list, events/poll, and events/stream with correlated stdio notifications.
• No Figma writes, reactions, or agent execution.

Run with Node.js 20.19+:

npx -y github:mikekelly/figma-listen#v1.0.1 doctor

Use your exported FIGMA_ACCESS_TOKEN, or replace doctor with auth to save a token in your system credential store. See the README for Codex configuration and subscription examples. The attached tarball contains compiled JavaScript and can be installed with npm; the package has not yet been published to the npm registry.

Validation: 13 automated tests, TypeScript checks, compiled tarball startup, and a live read-only authentication/MCP status check. GitHub Actions checks Node 20, 22, and 24.

Compatibility: automatic Codex push/wakeup support has not been established. Retrieval tools work during an active session; push requires a host implementing the experimental Events extension. Live comment activity was not tested. Organization coverage is limited to supplied team IDs, and page/frame filtering excludes comments without usable node anchors.

This release includes a packaging-stage correction to project REST author metadata to the advertised event schema and deduplicate repeated IDs within a snapshot.