figjam-context-mcp

Ingest FigJam Board

ingest_board

Download a FigJam/Figma board and save a local snapshot for context summaries, Q&A, and diffs, with section highlights for next reads.

Instructions

Read a FigJam/Figma URL with the configured Figma token and persist a local snapshot for get_board_context, answer_from_board and diff_board; the summary names the largest sections to read next and how many excerpts lie outside sections. Leaves the Figma file unchanged. Every call downloads the board from Figma (one Tier 1 request); get_board_context and answer_from_board read the saved snapshot without a new request. Balanced/quality modes may send board text and images to the configured LLM provider and incur charges; max_speed skips vision. Re-ingest to refresh stale content and continue pending image interpretation; focusNodeIds with section IDs from the summary or the first page of get_board_context interprets their images first. Local history is bounded. Supports framework phases or customPhases.

Input Schema

Name	Required	Description	Default
`ingestMode`	No	How aggressively to use vision LLM calls during ingest	balanced
`customPhases`	No	Free-form phase names to map clusters onto (e.g. ["Ideen", "Feedback", "Offene Fragen"]); overrides docStructureHint
`figmaFileUrl`	Yes	URL of the FigJam/Figma file to ingest
`focusNodeIds`	No	IDs of pages, sections, frames, groups or single nodes whose image clusters are interpreted first, in list order; the rest of the board follows in the usual order. Section IDs come from the ingest_board summary or the first page of get_board_context. Only the order of image interpretation changes: the whole board is still read and cached, and later ingests without focusNodeIds reuse the interpretations. No effect in max_speed
`forceFullIngest`	No	Build the snapshot from the downloaded board again instead of the cached result for unchanged content, e.g. after turning credential redaction off. Image interpretations of unchanged clusters are kept, as without forceFullIngest; clusters still pending are interpreted as on any ingest. Model and prompt changes are detected automatically, so forceFullIngest is not needed for them. An unchanged board gives no new snapshot for diff_board. Default: false
`docStructureHint`	No	Built-in framework used to map clusters to phases	freeform
`figmaAccessToken`	No	Figma personal access token; falls back to FIGMA_ACCESS_TOKEN env var if omitted

Output Schema

Name	Required	Description
`boardId`	Yes
`summary`	Yes
`ingestMode`	No
`snapshotId`	No
`clusterCount`	Yes
`figmaVersion`	No
`qualityReport`	No
`relationCount`	No	Directed cluster-to-cluster relations derived from connector arrows
`ignoredArguments`	No	Unknown input keys that were ignored; their values are not echoed. Absent when none
`freshnessCheckedAt`	No
`persistenceWarning`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.12.0Nov 5, 2026

addedOutput schema / properties / ignoredArguments

Added value: +{
+  "description": "Unknown input keys that were ignored; their values are not echoed. Absent when none",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed3 schema fields changedv0.10.2Oct 21, 2026

addedInput schema / properties / focusNodeIds

Added value: +{
+  "description": "IDs of pages, sections, frames, groups or single nodes whose image clusters are interpreted first, in list order; the rest of the board follows in the usual order. Section IDs come from the ingest_board summary or the first page of get_board_context. Only the order of image interpretation changes: the whole board is still read and cached, and later ingests without focusNodeIds reuse the interpretations. No effect in max_speed",
+  "items": {
+    "maxLength": 200,
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 50,
+  "minItems": 1,
+  "type": "array"
+}

changedInput schema / properties / forceFullIngest / description

Previous value: -"Download and extract the board again, skipping the unchanged-board check and cache, and redo the image interpretation of the chosen ingestMode. Interpretations this mode does not redo (all in max_speed; in balanced those of clusters without image or drawing) are kept while a cluster's content is unchanged. The vision time budget still applies, so balanced and max_quality may need several ingests until every image is interpreted again. An unchanged board gives no new snapshot for diff_board, even with forceFullIngest. Model/configuration changes are detected automatically. Default: false"New value: +"Build the snapshot from the downloaded board again instead of the cached result for unchanged content, e.g. after turning credential redaction off. Image interpretations of unchanged clusters are kept, as without forceFullIngest; clusters still pending are interpreted as on any ingest. Model and prompt changes are detected automatically, so forceFullIngest is not needed for them. An unchanged board gives no new snapshot for diff_board. Default: false"

addedOutput schema / properties / qualityReport / properties / focus

Added value: +{
+  "additionalProperties": false,
+  "description": "Only with focusNodeIds: the IDs found on the board and the clusters in focus this ingestMode interprets, of them interpreted and pending",
+  "properties": {
+    "foundIds": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "imageClusters": {
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "interpreted": {
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "pending": {
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "requestedIds": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "requestedIds",
+    "foundIds",
+    "imageClusters",
+    "interpreted",
+    "pending"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedv0.8.0Oct 20, 2026

changedInput schema / properties / forceFullIngest / description

Previous value: -"Deliberately skip all caching and incremental reuse, including successful interpretations. The vision time budget still applies. Model/configuration changes are detected automatically. Default: false"New value: +"Download and extract the board again, skipping the unchanged-board check and cache, and redo the image interpretation of the chosen ingestMode. Interpretations this mode does not redo (all in max_speed; in balanced those of clusters without image or drawing) are kept while a cluster's content is unchanged. The vision time budget still applies, so balanced and max_quality may need several ingests until every image is interpreted again. An unchanged board gives no new snapshot for diff_board, even with forceFullIngest. Model/configuration changes are detected automatically. Default: false"

addedOutput schema / properties / qualityReport / properties / figmaRequests

Added value: +{
+  "additionalProperties": false,
+  "description": "Figma requests of this ingest for images: image fills (Tier 2) and renders (Tier 1)",
+  "properties": {
+    "imageFills": {
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "renders": {
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "imageFills",
+    "renders"
+  ],
+  "type": "object"
+}

Changed22 schema fields changedv0.4.0Oct 18, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

removedInput schema / additionalProperties
```
Removed value: -false
```

addedInput schema / properties / customPhases

Added value: +{
+  "description": "Free-form phase names to map clusters onto (e.g. [\"Ideen\", \"Feedback\", \"Offene Fragen\"]); overrides docStructureHint",
+  "items": {
+    "maxLength": 80,
+    "minLength": 1,
+    "type": "string"
+  },
+  "maxItems": 12,
+  "minItems": 1,
+  "type": "array"
+}

changedInput schema / properties / docStructureHint / description

Previous value: -"How to interpret the board's structure when mapping clusters to phases"New value: +"Built-in framework used to map clusters to phases"

changedInput schema / properties / docStructureHint / enum

Previous value: -[
-  "double_diamond",
-  "freeform"
-]New value: +[
+  "freeform",
+  "double_diamond",
+  "lean_canvas",
+  "retro",
+  "user_journey"
+]

addedInput schema / properties / figmaAccessToken / maxLength
```
Added value: +512
```
addedInput schema / properties / figmaAccessToken / minLength
```
Added value: +1
```
addedInput schema / properties / figmaFileUrl / maxLength
```
Added value: +2048
```

addedInput schema / properties / forceFullIngest

Added value: +{
+  "description": "Deliberately skip all caching and incremental reuse, including successful interpretations. The vision time budget still applies. Model/configuration changes are detected automatically. Default: false",
+  "type": "boolean"
+}

addedInput schema / properties / ingestMode

Added value: +{
+  "default": "balanced",
+  "description": "How aggressively to use vision LLM calls during ingest",
+  "enum": [
+    "balanced",
+    "max_quality",
+    "max_speed"
+  ],
+  "type": "string"
+}

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / properties / boardId / maxLength
```
Added value: +128
```
addedOutput schema / properties / boardId / minLength
```
Added value: +6
```
addedOutput schema / properties / boardId / pattern
```
Added value: +"^[A-Za-z0-9]+$"
```
addedOutput schema / properties / clusterCount / maximum
```
Added value: +9007199254740991
```
addedOutput schema / properties / figmaVersion
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / freshnessCheckedAt
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / ingestMode

Added value: +{
+  "enum": [
+    "balanced",
+    "max_quality",
+    "max_speed"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / persistenceWarning
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / qualityReport

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "cachedClusters": {
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "deterministicClusters": {
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "fallbackCount": {
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "fallbackReasons": {
+      "additionalProperties": {
+        "maximum": 9007199254740991,
+        "minimum": 0,
+        "type": "integer"
+      },
+      "propertyNames": {
+        "type": "string"
+      },
+      "type": "object"
+    },
+    "incompleteClusters": {
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "modelsUsed": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "nextRetryAt": {
+      "type": "number"
+    },
+    "reusedClusters": {
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    },
+    "visionClusters": {
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "modelsUsed",
+    "cachedClusters",
+    "deterministicClusters",
+    "visionClusters",
+    "fallbackCount"
+  ],
+  "type": "object"
+}

addedOutput schema / properties / relationCount

Added value: +{
+  "description": "Directed cluster-to-cluster relations derived from connector arrows",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

addedOutput schema / properties / snapshotId
```
Added value: +{
+  "type": "string"
+}
```

First observedv0.1.0Jul 4, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial behavior beyond the annotations: the Figma file is left unchanged, every call costs exactly one Tier 1 Figma request, balanced/quality modes may incur LLM charges while max_speed skips vision, and local history is bounded. These are exactly the cost, side-effect and safety facts an agent needs before invoking an open-world, non-idempotent tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose is front-loaded in the first clause, but the body is a single dense run-on block mixing cost, caching, vision ordering and phase mapping. It also restates focusNodeIds semantics already fully documented in the schema, so several clauses do not earn their place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter ingest tool with an output schema, the description covers cost model, caching/idempotency behavior, staleness, refresh path and downstream consumers. Nothing an agent needs to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining the cost/vision tradeoff behind ingestMode and the resolution path for focusNodeIds section IDs. It adds little on figmaAccessToken and docStructureHint beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb+resource (read a FigJam/Figma URL, persist a local snapshot) and immediately ties the result to the three sibling tools that consume it. An agent can distinguish this ingest step from get_board_context/answer_from_board/diff_board without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit refresh guidance ("Re-ingest to refresh stale content and continue pending image interpretation") and clarifies that siblings read the saved snapshot with no new request, which implicitly tells the agent when not to call this tool. It stops short of an explicit "use X instead when the snapshot is fresh" routing rule, so 4 rather than 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server