Skip to main content
Glama
Soma Nexus MCP

Soma Nexus MCP

by pablostefan

Soma Nexus MCP

MCP server em TypeScript para VS Code, focado em leitura de dados do Figma e contexto para design-to-code.

O que faz

  • Busca árvore de arquivo do Figma

  • Busca nós específicos por ID

  • Resolve URL completa do Figma (fileKey + node-id)

  • Busca nó direto a partir de URL

  • Retorna saída normalizada para design-to-code

  • Busca imagens exportadas

  • Busca components, styles e variables

  • Valida contrato federado de mapeamento Figma -> Design System

Related MCP server: Figma MCP

Arquitetura (simples e prática)

Aplicamos SOLID + Clean Architecture sem excesso de abstração:

  • src/index.ts: composition root

  • src/presentation/register-tools.ts: camada de entrada (tools MCP)

  • src/infrastructure/figma-api-client.ts: integração com API Figma

  • src/domain/figma-url.ts: regras de URL e IDs

  • src/application/node-normalizer.ts: normalização para design-to-code

  • src/core/errors.ts e src/core/responses.ts: erros e contrato de resposta

Regras usadas:

  • Responsabilidade única por módulo

  • Dependências apontando para dentro (presentation -> application/domain/infrastructure)

  • Infra isolada (troca de API client sem mexer em tools)

  • Erro e resposta padronizados para todas as tools

Requisitos

  • Node.js 18+

  • FIGMA_TOKEN definido no ambiente do cliente MCP

  • Opcional: FIGMA_NODES_CACHE_TTL_MS (default: 90000)

Desenvolvimento local

npm install
npm run build
npm run dev
npm test

Tools disponíveis

  • get_figma_file: payload bruto do arquivo inteiro (debug pesado)

  • parse_figma_url: extrai fileKey e nodeId de URL

  • get_figma_nodes: busca nós por IDs

  • get_figma_node_from_url: busca nó direto com URL completa

  • get_figma_node_normalized: metadata + estilos/tokens/assets normalizados

  • get_figma_images: URLs de renderização de nós

  • get_figma_components: componentes publicados

  • get_figma_styles: estilos publicados

  • get_figma_variables: variáveis locais

  • validate_figma_to_code_index: valida índice global e docs por componente

  • preview_figma_component_mapping: mostra melhor match de componente DS para um node Figma

  • generate_flutter_component_from_figma: gera snippet Flutter mínimo via mapping federado

  • generate_flutter_page_from_figma: gera estrutura Flutter de página inteira com DS quando houver match

Economia de tokens (recomendado)

Use estes parâmetros em tools de leitura/mapping/geração:

  • responseMode: compact | standard

  • debugTelemetry: true | false

Sugestão para uso normal:

  • responseMode: "compact"

  • debugTelemetry: false

Quando quiser medir custo real de payload:

  • debugTelemetry: true retorna meta.payloadSizeBytes e meta.responseSizeBytes.

Observações:

  • Tools com depth usam default conservador 1 quando não informado.

  • Preview de matching limita candidatos por padrão para reduzir resposta (compact: 3, standard: 10).

Modelo federado Figma -> Code

Cada componente do Design System deve manter seu próprio arquivo:

  • {component}/docs/figma-to-code.md

E todos os componentes devem ser registrados em:

  • docs/figma-to-code-index.yaml

Documentação de suporte:

  • docs/specs/figma-to-code-component-doc-spec.md

  • docs/figma-to-code-authoring-guide.md

  • docs/templates/component-figma-to-code.template.md

Configuração no VS Code

No workspace, use .vscode/mcp.json:

{
	"inputs": [
		{
			"id": "figma-token",
			"type": "promptString",
			"description": "FIGMA_TOKEN for Soma Nexus MCP",
			"password": true
		}
	],
	"servers": {
		"soma-nexus-figma-mcp": {
			"type": "stdio",
			"command": "npm",
			"args": ["run", "dev"],
			"env": {
				"FIGMA_TOKEN": "${input:figma-token}"
			}
		}
	}
}

Na primeira vez, VS Code pergunta token e guarda valor localmente.

Fluxo recomendado (design-to-code)

  1. validate_figma_to_code_index

  2. parse_figma_url

  3. preview_figma_component_mapping

  4. generate_flutter_component_from_figma (quando URL aponta para componente)

  5. generate_flutter_page_from_figma (quando URL aponta para frame/página)

  6. get_figma_node_normalized (debug/inspeção)

  7. get_figma_images (se precisar assets)

Esse fluxo evita payload gigante e melhora estabilidade da geração de código.

Contrato de resposta

Sucesso:

{
	"ok": true,
	"data": {}
}

Erro:

{
	"ok": false,
	"error": {
		"code": "FIGMA_UNAUTHORIZED",
		"message": "Figma token unauthorized.",
		"details": {}
	}
}

Available Tools

13 tools
generate_flutter_component_from_figmaB
Read-only

Generate a minimal Flutter widget snippet from a Figma node using federated docs mapping.

Inputs: figmaUrl (required), depth, version, responseMode, +1 more.

generate_flutter_page_from_figmaB
Read-only

Generate Flutter page scaffold from a Figma page/frame URL, using DS components when matched.

Inputs: figmaUrl (required), depth, version, maxNodes, +2 more.

get_figma_componentsA
Read-only

Fetch published components found in a Figma file.

Inputs: fileKey (required), responseMode, debugTelemetry.

get_figma_fileB
Read-only

Fetch a Figma file. Prefer compact mode to avoid large payloads.

Inputs: fileKey (required), version, responseMode, debugTelemetry.

get_figma_imagesB
Read-only

Render Figma nodes to image URLs for assets and previews.

Inputs: fileKey (required), nodeIds (required), scale, format, +3 more.

get_figma_node_from_urlA
Read-only

Fetch a specific Figma node directly from a full Figma URL.

Inputs: figmaUrl (required), depth, version, geometry, +2 more.

get_figma_node_normalizedA
Read-only

Fetch a Figma node from URL and return normalized metadata, tokens, styles, and asset refs.

Inputs: figmaUrl (required), depth, version, responseMode, +2 more.

get_figma_nodesB
Read-only

Fetch specific Figma nodes, their subtrees, and optional geometry.

Inputs: fileKey (required), nodeIds (required), depth, version, +3 more.

get_figma_stylesC
Read-only

Fetch published styles found in a Figma file.

Inputs: fileKey (required), responseMode, debugTelemetry.

get_figma_variablesB
Read-only

Fetch local variables and collections from a Figma file.

Inputs: fileKey (required), responseMode, debugTelemetry.

parse_figma_urlA
Read-only

Parse a Figma URL and extract fileKey and nodeId.

Inputs: figmaUrl (required).

preview_figma_component_mappingB
Read-only

Preview how a Figma node matches a Design System component via federated docs.

Inputs: figmaUrl (required), depth, version, responseMode, +2 more.

validate_figma_to_code_indexA
Read-only

Validate the global figma-to-code index and all per-component docs before generation.

Inputs: responseMode, debugTelemetry.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 13 tools

    Disambiguation2/5

    Multiple tools have overlapping boundaries, especially the node-fetching trio: get_figma_nodes, get_figma_node_from_url, and get_figma_node_normalized all retrieve node data with subtle differences. get_figma_node_from_url and get_figma_node_normalized are particularly confusing since both take a URL and return node information, with the latter adding normalization. This overlap makes it difficult for an agent to reliably select the right tool.

    Naming Consistency3/5

    Most tools follow a verb_noun pattern (get_figma_file, generate_flutter_component_from_figma), but there are inconsistencies in granularity and style. For example, get_figma_nodes (plural) coexists with get_figma_node_from_url and get_figma_node_normalized (singular), and the latter two are not parallel to each other. The mix of 'from_url' and 'normalized' suffixes adds unpredictability, so while the convention is readable, it is not consistently applied.

    Tool Count5/5

    With 13 tools, the server is well-scoped for a Figma-to-Flutter generation workflow. Each tool addresses a distinct step in the pipeline (fetching, parsing, mapping, validating, generating) without unnecessary bloat. The count fits comfortably within the ideal 3-15 range and each tool appears to serve a concrete purpose.

    Completeness4/5

    The tool set covers the core lifecycle of Figma-to-Flutter generation: fetching files/nodes/styles/variables, parsing URLs, validating index, previewing component mappings, and generating both component and page code. Minor gaps exist, such as no explicit tool to manage or update the component index or design system docs, but agents can work around these with the existing validation and mapping tools.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Read-only Figma MCP server that enables design-to-code workflows by talking to the Figma REST API with a personal access token, for use with Claude Code and GitHub Copilot.
      2,146 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Read-only MCP server that wraps the Figma REST API, providing tools like get file metadata, list frames, and export node image URLs for AI SDLC agents.
      -