MCP API

Model Context Protocol tools for reading built design tokens and comparing Figma variables exports.

Interfaces

TokenSource

Token source for the MCP tools.

Properties

files

files: Record<string, DTCGDocument>

DTCG token documents keyed by slash-separated path relative to tokens.resolver.json.

resolver

resolver: ResolverDocument

The resolver describing contexts.

origin

origin: string

Source file or directory path.

variablesJson?

optional variablesJson?: unknown

Variables JSON from a Figma export.

Functions

createServer()

createServer(source): Promise<McpServer>

Create an MCP server bound to a token source.

The caller connects the returned server to an MCP transport.

Parameters

source

TokenSource

Returns

Promise<McpServer>

---

loadTokenSource()

loadTokenSource(sourcePath): Promise<TokenSource>

Load a Figma variables file or token directory.

The loader converts a Figma variables export (variables.json) in memory. For a directory, it reads tokens.resolver.json from the root or tokens/ and loads root-level and nested *.tokens.json files. Returned file keys use slash-separated paths relative to tokens.resolver.json.

A directory scan accepts up to 64 nested directory levels, 100,000 entries, and 1,000 token files. Each JSON file may contain up to 20 MiB, and all JSON files together may contain up to 256 MiB.

Parameters

sourcePath

string

Path to a Figma variables file or token directory.

Returns

Promise<TokenSource>

The loaded token source.

Throws

Error - The source is missing, uses a symbolic link, contains an unsupported file-system entry, or changes during loading.

Throws

Error - The loader cannot read or parse a JSON file, or the source exceeds a scan or size limit.

Throws

Error - A Figma variables document has an unsupported shape.

Throws

Error - A token directory contains unsafe or colliding token file paths.

---

listCollections()

listCollections(source): object

Return top-level token groups, their token counts, and the context axes the resolver declares.

Parameters

source

TokenSource

Returns

object

collections

collections: object[]

contexts

contexts: Record<string, string[]>

origin

origin: string

---

getToken()

getToken(source, path, contexts?): object

Return a token by dot path under a context selection.

Parameters

source

TokenSource

path

string

contexts?

Record<string, string>

Returns

object

path

path: string

found

found: boolean

token?

optional token?: DTCGToken

value?

optional value?: DTCGTokenValue

css?

optional css?: string | null

cssVar?

optional cssVar?: string

figma?

optional figma?: unknown

---

resolveContext()

resolveContext(source, contexts, limit?): object

Resolve tokens under a context selection.

Parameters

source

TokenSource

contexts

Record<string, string>

limit?

number = 500

Returns

object

contexts

contexts: Record<string, string>

total

total: number

truncated

truncated: boolean

tokens

tokens: object[]

---

searchTokens()

searchTokens(source, query, type?, contexts?, limit?): object

Search token paths and descriptions with an optional $type filter.

Parameters

source

TokenSource

query

string

type?

string

contexts?

Record<string, string>

limit?

number = 50

Returns

object

query

query: string

total

total: number

results

results: object[]

---

diffTokens()

diffTokens(oldJson, newJson): string

Compare two Figma variables exports and return a Markdown report.

Parameters

oldJson

unknown

newJson

unknown

Returns

string