figmog: fold-backed local mirror of a Figma file

[hhff]

Hackathon submission

Note: this PR targets our own fork's main, not upstream — the template is filled in to prep the eventual upstream submission, but the acknowledgment box is deliberately left unchecked (that submission is a separate, explicit step).

category

pick one:

• agent support
• performance
• novel interface / gaming

team

• project name: figmog
• team / author name(s): hhff / sanctuary.computer
• contact (optional): hugh@sanctuary.computer

what you built

figmog turns one Figma file into a local, lightning-fast, agent-queryable database — and then becomes the only Figma MCP server an agent needs: a cached proxy in front of Figma's native tooling, backed by a fold mirror.

The mirror (v1). Figma has no delta API and its file endpoints are Tier-1 rate limited. figmog synthesizes the missing delta API from fold's KeyedStream upsert semantics: poll the cheap Tier-3 metadata endpoint, spend one Tier-1 fetch only when last_touched_at moves, flatten the document into deterministic per-node records, and upsert-diff them through one atomic transaction into 14 materialized sinks (node table, children multimap, BM25 text search, inverted indexes for instances/styles/variables/types, design-system tables, proxy cache). A byte-identical re-pull pushes zero deltas (delta-probe tested); one renamed layer costs exactly one retract/insert pair.

The MCP server (v2). figmog serve is an MCP stdio server with the sync loop built in — one process, always fresh. 17 figmog_* tools answer from the mirror at zero API cost, including whole-file structural queries nothing else offers: figmog_search (BM25), figmog_where (match any JSON pointer across every node), figmog_at (spatial hit-test), figmog_stats, figmog_path, figmog_instances, figmog_vars, and more.

The cached proxy (v3). With the Figma desktop app running (Dev/Full seat), figmog discovers the native Dev Mode MCP server's tools at startup and re-exposes them verbatim — get_design_context, get_screenshot, get_variable_defs, all of them, native output formats passed through untouched — with responses cached by (tool, args, file version), so a screenshot of an unchanged frame is fetched once, ever. Agents connect to figmog alone and get both worlds; the initialize instructions steer tool choice. CLI parity via figmog tools / figmog call <tool> --args '<json>'. Pull also opportunistically syncs Enterprise variables/local (silently skipped on other plans; plugin-export import + boundVariables inference remain as fallbacks).

Design docs: docs/superpowers/specs/2026-08-15-figmog-build-design.md (+ plans in docs/superpowers/plans/).

Upstream finding (not patched here): fold's Table<K, V> panics when K's postcard encoding is empty (e.g. K = ()) — lsm-tree forbids empty keys. figmog keys its singleton meta row by u8 instead. Also: fold's store-open panics on lock contention; figmog translates these to clean errors at its own layer.

how to run

# from repo root
export FIGMA_TOKEN=figd_…   # figma.com → settings → security → personal access tokens
cargo run -p figmog -- pull "https://www.figma.com/design/<key>/<name>"
cargo run -p figmog -- search "pricing card"
cargo run -p figmog -- stats

# as an MCP server for Claude Code (with built-in sync + native-tool proxy):
cargo build -p figmog
claude mcp add figmog -- $PWD/target/debug/figmog serve "https://www.figma.com/design/<key>/<name>"

Offline demo without a token: save any GET /v1/files/:key response as JSON, then figmog pull --from-file resp.json --db /tmp/demo and figmog serve --no-upstream --no-watch --db /tmp/demo.

demo / notes

• 112 tests: flatten determinism (byte-identical postcard), delta-probe churn arithmetic (exact push counts), mid-transaction rollback, watch/backoff state machine, MCP protocol contract (15 unit cases), upstream client incl. SSE parsing + session/protocol-version headers against an in-process HTTP fake, cache hit/miss/eviction/collision-guard, proxy routing + isError handling, serve e2e over real stdio incl. lock-contention behavior, variables import/inference/Enterprise-sync round trips.
• cargo test -p figmog, cargo test -p fold, cargo clippy -p figmog --no-deps -- -D warnings, cargo fmt -p figmog --check all green; zero diff to fold/ese/anny.
• Built via spec → plan → subagent-driven TDD with per-task review, two adversarial whole-branch review passes, and empirically-verified fix rounds.

checklist

• i forked bog-kit and built my project in this fork
• my project is runnable from this pr (crate name and run command above)
• i selected exactly one category
• this pr is my official hackathon submission acknowledgment