figjam-context-mcp 0.0.0-stage → 0.4.1

package/.env.example

@@ -0,0 +1,70 @@
+# Figma personal access token
+# figma.com → Settings → Security → Personal access tokens
+# Scope: file_content:read. The token must have access to the requested board.
+# Prefer environment credentials; tool arguments can appear in client logs.
+FIGMA_ACCESS_TOKEN=
+
+# --- LLM (vision interpretation + answer synthesis) ---------------------
+# OpenAI-compatible chat completions endpoint. Model quotas/prices can change.
+# Board text/images are sent to this provider for vision and Q&A; use max_speed
+# and get_board_context for deterministic context without model calls.
+#
+# 1) OpenRouter (default): create a key at https://openrouter.ai/keys.
+#    The student-free preset uses nvidia/nemotron-3-super-120b-a12b:free for
+#    text, then the openrouter/free router, and the router alone for vision.
+#    Free models and their limits change; run diagnose_llm_config to check.
+#
+# 2) GitHub Models: free with any GitHub account
+#    (https://github.com/marketplace/models) — set
+#    LLM_BASE_URL=https://models.github.ai/inference and use a GitHub PAT
+#    as LLM_API_KEY, with a vision-capable model id.
+LLM_BASE_URL=https://openrouter.ai/api/v1
+LLM_API_KEY=
+# Supported presets: student-free
+LLM_MODEL_PRESET=student-free
+# Optional role-specific overrides. Legacy LLM_VISION_MODEL / LLM_TEXT_MODEL
+# still work and become the first candidate in each list.
+# LLM_VISION_MODELS=openrouter/free
+# LLM_TEXT_MODELS=nvidia/nemotron-3-super-120b-a12b:free,openrouter/free
+# LLM_FAST_TEXT_MODELS=nvidia/nemotron-3-super-120b-a12b:free,openrouter/free
+# LLM_PROVIDER_REQUIRE_PARAMETERS=true
+# Optional answer-only reasoning effort: none, low, medium or high.
+# Omit to retain provider defaults; support depends on the configured model.
+# LLM_ANSWER_REASONING_EFFORT=none
+
+# --- Timeout controls ----------------------------------------------------
+# Defaults are tuned so MCP UI clients do not wait forever on slow providers.
+# Increase these only if your MCP client/request timeout is also higher.
+# FIGMA_REQUEST_TIMEOUT_MS=15000
+# FIGMA_FILE_REQUEST_TIMEOUT_MS=60000
+# Global LLM request timeout; when set, it applies to roles without their own value.
+# LLM_REQUEST_TIMEOUT_MS=20000
+# Answers and text diagnostics: explicit role value > explicit global value > 40000 ms.
+# answer_from_board stops after 50000 ms across all model candidates (or this value, if larger).
+# LLM_ANSWER_REQUEST_TIMEOUT_MS=40000
+# Vision: explicit role value > explicit global value > 60000 ms.
+# LLM_VISION_REQUEST_TIMEOUT_MS=60000
+# LLM_SDK_MAX_RETRIES=0
+# LLM_RATE_LIMIT_RETRIES=1
+# LLM_RATE_LIMIT_MAX_BACKOFF_MS=5000
+# LLM_ANSWER_MAX_OUTPUT_TOKENS=2048
+# LLM_VISION_MAX_OUTPUT_TOKENS=4096
+# LLM_ANSWER_TOP_K=6
+# LLM_ANSWER_PROMPT_MAX_CHARS=24000
+# INGEST_BOARD_VISION_BUDGET_MS=40000
+# INGEST_BOARD_MIN_VISION_SLOT_MS=10000
+# INGEST_BOARD_VISION_CONCURRENCY=3
+# FIGMA_SCREENSHOT_DOWNLOAD_CONCURRENCY=3
+
+# --- Cache controls ------------------------------------------------------
+# Maximum full boards retained in process memory. Older entries remain on
+# disk and are restored on demand.
+# FIGJAM_MCP_MEMORY_CACHE_MAX_BOARDS=10
+
+# Private cache root (v4/ is created beneath it). Omit for the per-user OS default.
+# macOS: ~/Library/Caches/figjam-context-mcp
+# Windows: %LOCALAPPDATA%/figjam-context-mcp
+# Linux: $XDG_CACHE_HOME/figjam-context-mcp or ~/.cache/figjam-context-mcp
+# Use an absolute dedicated directory, not a shared project directory.
+# FIGJAM_MCP_CACHE_DIR=/absolute/private/path/figjam-context-mcp
+# Legacy v3 data is preserved; re-ingest boards to populate v4.

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## 0.4.1 — 2026-10-19
+
+- `answer_from_board` waits up to 40 s per model request (`LLM_ANSWER_REQUEST_TIMEOUT_MS`)
+  instead of 20 s and stops after 50 s across all model candidates, so large prompts
+  on free reasoning models finish inside a 60-second client timeout. The text checks of
+  `diagnose_llm_config` use the same timeout, and timeout errors name the setting to change.
+- Tool descriptions point overviews and whole-board summaries to `get_board_context`;
+  `answer_from_board` is for one specific question.
+- `ingest_board` renders screenshots of several clusters per Figma request (up to
+  18 nodes) instead of one request per cluster, saving Tier 1 Figma requests.
+- Vision summaries keep table values and statistical notation literally and name
+  a statistic such as a confidence interval only when a legend identifies it.
+- Releases are published from CI with npm provenance.
+- Dependency updates: `openai` 7.34, `dotenv` 18.0.8.
+
+## 0.4.0 — 2026-10-18
+
+- New `student-free` defaults: text uses `nvidia/nemotron-3-super-120b-a12b:free`,
+  then `openrouter/free`; vision uses `openrouter/free`. OpenRouter's
+  `provider.require_parameters` is no longer sent to other providers.
+- `ingest_board` fits a 60-second client timeout: the vision phase defaults to
+  40 s (`INGEST_BOARD_VISION_BUDGET_MS`). Unfinished clusters continue on the
+  next ingest, and the summary says so.
+- `diagnose_llm_config` runs its checks in parallel with the same output budgets
+  as the real calls and answers within 45 s.
+- Stable MCP TypeScript SDK v2 and Zod 4 with unchanged tool names and required
+  fields; cancellation, ingest progress and tool annotations. Requires Node.js 22.12+.
+- Answers cite source nodes with exact quotes and Figma links, and report
+  insufficient evidence instead of guessing.
+- Answers keep confirmed statuses, explicit negatives, open tasks, proposals and
+  conflicting sources apart. Optional `LLM_ANSWER_REASONING_EFFORT` for answers.
+- `get_board_context` adds pagination, character budgets, exact node lookups and
+  local BM25 search over original text, table cells and names. Topics without
+  matches return empty results.
+- Tables, pages, sections and arrow direction are preserved. Arrows anchored to
+  the page canvas no longer create connections.
+- `diff_board` compares the latest snapshot with an earlier one (20 are kept),
+  including table-cell, visual and connector changes.
+- Re-ingests reuse unchanged clusters and skip the download when Figma reports
+  the same version. Model or prompt changes invalidate interpretations automatically.
+- Ingest results report why vision is incomplete (time budget, timeout, rate
+  limit, configuration, access) and when to retry; Retry-After is respected.
+- Private v4 cache with atomic writes and a write lock. Legacy v3 caches are kept;
+  re-ingest once after upgrading.
+- Bounded work: 64 MiB per file, 100,000 nodes, 8 MiB per image, 64 MiB of
+  screenshots per ingest, and per-request timeouts for Figma and the LLM.
+- Vision summaries keep visible facts and diagram direction and are marked as
+  model-derived.
+- Offline retrieval and diff evaluation with 20 synthetic cases
+  (`npm run eval:retrieval`); MIT license and CI on Linux, macOS and Windows.
+
+## 0.3.0 — Development history
+
+Added board snapshot diffs, incremental interpretation, bounded concurrent vision,
+connector relations and an npm tarball startup smoke test. No published release
+date is asserted for this development version.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ecestnrkl
+
+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

@@ -1,3 +1,151 @@
-# Temporary Holding Version
+# figjam-context-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A local MCP server that turns FigJam boards into source-cited context for LLMs.
+It reads a board through the Figma REST API, groups stickies, tables, images and
+arrows into clusters, and answers questions with links back to the original nodes.
+
+![Pipeline: a FigJam board is read through the Figma API, clustered by geometry, refined with vision and turned into LLM-ready context](https://raw.githubusercontent.com/ecestnrkl/figjam-mcp/main/docs/pipeline.gif)
+
+## Why
+
+Workshop boards hold research notes, decisions and open questions, but an LLM
+cannot read a canvas. Screenshots and PDF exports lose tables, arrow direction
+and the link to the source. This server keeps the board's structure and cites
+every answer to the nodes it came from.
+
+## Tools
+
+| Tool | What it does | LLM call |
+| --- | --- | --- |
+| `ingest_board` | Reads a board, clusters it and saves a local snapshot. Re-ingests reuse unchanged clusters. | In `balanced` (default) and `max_quality` mode |
+| `get_board_context` | Returns paginated, source-linked context, optionally for a topic or exact node IDs. Use it for overviews, summaries and documentation. | No |
+| `answer_from_board` | Answers one specific question (a number, status or decision) from the most relevant excerpts, with node-level citations or an insufficient-evidence result. Not meant for whole-board summaries. | Yes |
+| `diff_board` | Compares two snapshots: new, removed and changed clusters, nodes, table cells and arrows. | No |
+| `diagnose_llm_config` | Tests the configured models with small text and image JSON checks. | Yes |
+
+## Quick start
+
+Requires Node.js 22.12 or later.
+
+1. Create a Figma personal access token under **Settings → Security → Personal
+   access tokens** with the scope `file_content:read`. Add `file_metadata:read`
+   so re-ingests of an unchanged board skip the download. The token's account
+   needs access to the board.
+2. Optional: create an OpenRouter key at
+   [openrouter.ai/keys](https://openrouter.ai/keys). It enables image
+   interpretation, `answer_from_board` and `diagnose_llm_config`. Without it, use
+   `ingestMode: "max_speed"` with `get_board_context` and `diff_board`.
+3. Add the server to your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "figjam-context": {
+      "command": "npx",
+      "args": ["-y", "figjam-context-mcp"],
+      "env": {
+        "FIGMA_ACCESS_TOKEN": "your-figma-token",
+        "LLM_BASE_URL": "https://openrouter.ai/api/v1",
+        "LLM_API_KEY": "your-openrouter-key"
+      }
+    }
+  }
+}
+```
+
+For Claude Code:
+
+```bash
+claude mcp add figjam-context -e FIGMA_ACCESS_TOKEN=your-figma-token -e LLM_BASE_URL=https://openrouter.ai/api/v1 -e LLM_API_KEY=your-openrouter-key -- npx -y figjam-context-mcp
+```
+
+Then ask your assistant to ingest a board URL, for example *"Ingest
+https://www.figma.com/board/FILE_KEY/Name and list the open questions."*
+The `boardId` of every later call is the file key from that URL.
+
+All settings: [configuration](https://github.com/ecestnrkl/figjam-mcp/blob/main/docs/configuration.md).
+Problems: [troubleshooting](https://github.com/ecestnrkl/figjam-mcp/blob/main/docs/troubleshooting.md).
+
+## How it works
+
+1. **Read.** `ingest_board` downloads the board through the Figma REST API. If
+   Figma reports the same version as the last ingest, the download is skipped.
+2. **Normalize.** Nodes become text, table cells, images and connectors, with
+   their pages and sections.
+3. **Cluster.** Nearby nodes are grouped by rotation-aware distance. Arrows
+   between groups become directed relations.
+4. **Interpret.** In `balanced` mode, clusters with images or little text get a
+   vision-model summary within a 40-second budget; the rest keep their extracted
+   text. Unfinished clusters continue on the next ingest.
+5. **Serve.** The snapshot is saved to a private local cache.
+   `get_board_context` searches it (BM25 over original text, table cells and
+   names), `answer_from_board` answers with citations and `diff_board` compares
+   snapshots.
+
+## Models and cost
+
+The default preset `student-free` uses free OpenRouter models: text goes to
+`nvidia/nemotron-3-super-120b-a12b:free` and then `openrouter/free`; images go to
+`openrouter/free`, which picks a free model that accepts images and structured
+outputs. The free default is best effort: free models change, hit rate limits
+and time out.
+
+- OpenRouter allows free models 20 requests per minute and 50 requests per day,
+  or 1,000 per day once you have bought at least 10 credits
+  ([limits](https://openrouter.ai/docs/api-reference/limits)).
+- Figma limits file downloads and image renders by seat and plan: Dev and Full
+  seats on paid plans get 10–20 requests per minute, View and Collab seats and
+  files in Starter plans at most 20 per month
+  ([rate limits](https://developers.figma.com/docs/rest-api/rate-limits/)).
+  One render request covers up to 18 screenshots (about three clusters), so a
+  default ingest usually needs at most four; `max_speed` needs none.
+- For a team, configure your own model: `LLM_BASE_URL` takes any
+  OpenAI-compatible endpoint, and `LLM_TEXT_MODELS` / `LLM_VISION_MODELS` set
+  the model lists.
+- Run `diagnose_llm_config` after every model change. It checks JSON replies
+  and image understanding with synthetic inputs.
+
+## Privacy
+
+- The server reads from Figma and never changes a board.
+- `balanced` and `max_quality` ingests send board text and screenshots to the
+  configured LLM provider. `answer_from_board` sends the question and selected
+  excerpts. `max_speed` with `get_board_context` and `diff_board` sends nothing
+  to an LLM provider.
+- Snapshots stay in a private per-user cache on your machine. Delete the cache
+  directory to remove them.
+- Keep tokens in the client's environment. A token passed as a tool argument can
+  appear in client logs.
+
+## Limitations
+
+- Image interpretation gets 40 seconds per ingest by default; large boards need
+  several ingests to interpret every image cluster.
+- A client that cancels an ingest, for example after a 60-second timeout, gets
+  no partial result.
+- Free models are best effort. Citations show where an answer comes from, not
+  that its conclusion is right.
+- Search is lexical; synonyms without shared words do not match.
+- Local stdio only; no hosted or multi-user mode.
+
+Measured results: [evaluation](https://github.com/ecestnrkl/figjam-mcp/blob/main/docs/evaluation.md).
+
+## Development
+
+```bash
+git clone https://github.com/ecestnrkl/figjam-mcp.git
+cd figjam-mcp
+npm ci
+cp .env.example .env    # add your tokens
+npm run check           # typecheck, tests, build, package validation
+npm run package:smoke   # install the packed package and exercise all tools
+npm run eval:retrieval  # offline retrieval and diff evaluation
+npx @modelcontextprotocol/inspector --config inspector.config.json
+```
+
+See [CONTRIBUTING.md](https://github.com/ecestnrkl/figjam-mcp/blob/main/CONTRIBUTING.md)
+and the [changelog](https://github.com/ecestnrkl/figjam-mcp/blob/main/CHANGELOG.md).
+
+## License
+
+[MIT](https://github.com/ecestnrkl/figjam-mcp/blob/main/LICENSE) © 2026 ecestnrkl

package/SECURITY.md

@@ -0,0 +1,26 @@
+# Security policy
+
+Security fixes target the latest release on the current development line.
+Use supported Node.js LTS versions and apply dependency updates promptly.
+
+## Reporting
+
+Use GitHub's **Report a vulnerability** option on the repository Security tab
+when private reporting is enabled. If that option is unavailable, open an issue
+requesting a private reporting channel without including exploit details or
+secrets. Do not attach Figma tokens, provider keys, private board content or cache
+files to public issues. There is no guaranteed response-time SLA.
+
+## Data boundary
+
+This is a local stdio server intended for one user's trusted MCP client. It does
+not expose an HTTP endpoint or implement multi-user access control. Figma tokens
+belong in the environment. Board text/screenshots and questions can be sent to the
+configured LLM provider; provider retention and costs depend on that provider.
+Use max_speed ingest and get_board_context to avoid model calls.
+
+Local snapshots contain board content and are stored in a private per-user cache.
+Only connect clients trusted to read that data. Re-ingest after upgrading from
+legacy cache formats. Stop the server before removing its cache directory.
+Board content is untrusted input; source citations and prompt boundaries reduce
+risk but do not make model output authoritative. Review cited source nodes.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "dotenv/config";

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { createServer, packageMetadata } from "./server.js";
+async function main() {
+    if (process.argv.includes("--version") || process.argv.includes("-v")) {
+        process.stdout.write(`${packageMetadata.version}\n`);
+        return;
+    }
+    const handle = serveStdio(() => createServer());
+    const shutdown = () => { void handle.close(); };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+    console.error(`${packageMetadata.name} running on stdio`);
+}
+main().catch((error) => {
+    console.error(`Fatal error starting ${packageMetadata.name}:`, error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,eAAe,CAAC;AACvB,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE5D,KAAK,UAAU,IAAI;IACjB,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACtE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,eAAe,CAAC,OAAO,IAAI,CAAC,CAAC;QACrD,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,YAAY,EAAE,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,GAAG,EAAE,GAAG,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IAChD,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACjC,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAClC,OAAO,CAAC,KAAK,CAAC,GAAG,eAAe,CAAC,IAAI,mBAAmB,CAAC,CAAC;AAC5D,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,KAAK,CAAC,wBAAwB,eAAe,CAAC,IAAI,GAAG,EAAE,KAAK,CAAC,CAAC;IACtE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/lib/boardDiff.d.ts

@@ -0,0 +1,55 @@
+import type { BoardData } from "../types.js";
+/**
+ * Compares two ingest snapshots of the same board — "what changed since the
+ * last workshop?". Works on three levels:
+ *  - nodes: added / removed / edited content nodes (structural containers
+ *    and connectors excluded — connectors are diffed separately),
+ *  - clusters: matched across snapshots by member overlap, then classified
+ *    as unchanged (same content hash), modified, new, or removed,
+ *  - connections: connector arrows diffed as (from, to, label) edges and
+ *    rendered with the owning clusters' labels.
+ */
+export interface ClusterSummaryRef {
+    label: string;
+    summary: string;
+}
+export interface ModifiedClusterDiff {
+    label: string;
+    previousLabel: string;
+    addedNodeCount: number;
+    removedNodeCount: number;
+    editedNodeCount: number;
+}
+export interface BoardDiffStats {
+    addedNodes: number;
+    removedNodes: number;
+    editedNodes: number;
+    newClusters: number;
+    removedClusters: number;
+    modifiedClusters: number;
+    unchangedClusters: number;
+    addedConnections: number;
+    removedConnections: number;
+}
+export interface BoardDiffResult {
+    stats: BoardDiffStats;
+    newClusters: ClusterSummaryRef[];
+    removedClusters: ClusterSummaryRef[];
+    modifiedClusters: ModifiedClusterDiff[];
+    addedConnections: string[];
+    removedConnections: string[];
+    summaryText: string;
+    tableCellChanges: TableCellChange[];
+}
+export interface TableCellChange {
+    tableNodeId: string;
+    cellId: string;
+    changeType: "added" | "removed" | "modified";
+    previousText?: string;
+    currentText?: string;
+    previousRow?: number;
+    previousColumn?: number;
+    currentRow?: number;
+    currentColumn?: number;
+}
+export declare function diffBoards(baseline: BoardData, current: BoardData): BoardDiffResult;