How do I use Design System MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Design System MCP Server find related components for card" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP Server (HTTP) para Design System

Microsserviço HTTP em NodeJS (Express) que implementa o protocolo MCP via JSON‑RPC para expor recursos de um Design System. A fonte de dados é Markdown (mock local) ou S3.

Stack

NodeJS + Express
@modelcontextprotocol/sdk + zod
@aws-sdk/client-s3
gray-matter

Configuração

Copie .env.example para .env e ajuste:

PORT=3000
MOCK_S3=true
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=changeme
AWS_SECRET_ACCESS_KEY=changeme
S3_BUCKET=meu-bucket-design-system
S3_PREFIX=components/

MOCK_S3=true usa mock-data/components/*.md.
Para S3 real: MOCK_S3=false + credenciais e bucket.

Execução

Dev: npm run dev
Prod/local: npm start
Base: http://localhost:3000

Endpoints

GET /health → { status, service, mock }
POST /mcp → JSON‑RPC 2.0 (MCP via SDK)
GET /mcp → abre SSE (servidor→cliente) para uma sessão
DELETE /mcp → encerra a sessão atual

Observação: As rotas REST de componentes (/components, /components/:id) foram removidas. O acesso aos componentes acontece exclusivamente via MCP.

MCP (SDK oficial)

Servidor: McpServer com StreamableHTTPServerTransport.
Recursos: ResourceTemplate('component://{id}') com listagem dinâmica e leitura de markdown.
Ferramentas (schemas zod): search_components, related_components.
Prompt: component_usage.

Requisitos de chamada HTTP

Header Accept deve incluir application/json e text/event-stream.
initialize deve ser enviado com protocolVersion (ex.: 2025-03-26).
Após initialize, inclua Mcp-Session-Id e Mcp-Protocol-Version em todas as chamadas subsequentes.

CURLs (SDK)

Initialize (captura sessão)

curl -s -i -X POST http://localhost:3000/mcp \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json, text/event-stream' \
 -d '{
   "jsonrpc":"2.0",
   "id":"init",
   "method":"initialize",
   "params":{
     "clientInfo":{"name":"cli","version":"1.0.0"},
     "capabilities":{"jsonResponse":true},
     "protocolVersion":"2025-03-26"
   }
 }'
# Observe o header mcp-session-id na resposta e exporte:
# SID=... (valor do header)

Listar recursos (reutiliza sessão)

curl -s -i -X POST http://localhost:3000/mcp \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json, text/event-stream' \
 -H "Mcp-Session-Id: $SID" \
 -H 'Mcp-Protocol-Version: 2025-03-26' \
 -d '{"jsonrpc":"2.0","id":"lr","method":"resources/list","params":{}}'

Ler recurso (por URI)

curl -s -i -X POST http://localhost:3000/mcp \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json, text/event-stream' \
 -H "Mcp-Session-Id: $SID" \
 -H 'Mcp-Protocol-Version: 2025-03-26' \
 -d '{"jsonrpc":"2.0","id":"rr","method":"resources/read","params":{"uri":"component://button"}}'

Listar ferramentas

curl -s -i -X POST http://localhost:3000/mcp \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json, text/event-stream' \
 -H "Mcp-Session-Id: $SID" \
 -H 'Mcp-Protocol-Version: 2025-03-26' \
 -d '{"jsonrpc":"2.0","id":"lt","method":"tools/list","params":{}}'

Executar ferramenta search_components

curl -s -i -X POST http://localhost:3000/mcp \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json, text/event-stream' \
 -H "Mcp-Session-Id: $SID" \
 -H 'Mcp-Protocol-Version: 2025-03-26' \
 -d '{"jsonrpc":"2.0","id":"ct1","method":"tools/call","params":{"name":"search_components","arguments":{"query":"input"}}}'

Executar ferramenta related_components

curl -s -i -X POST http://localhost:3000/mcp \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json, text/event-stream' \
 -H "Mcp-Session-Id: $SID" \
 -H 'Mcp-Protocol-Version: 2025-03-26' \
 -d '{"jsonrpc":"2.0","id":"ct2","method":"tools/call","params":{"name":"related_components","arguments":{"id":"button"}}}'

SSE dedicado (opcional)

curl -s -N -X GET http://localhost:3000/mcp \
 -H 'Accept: text/event-stream' \
 -H "Mcp-Session-Id: $SID" \
 -H 'Mcp-Protocol-Version: 2025-03-26'

Encerrar sessão

curl -s -X DELETE http://localhost:3000/mcp \
 -H "Mcp-Session-Id: $SID" \
 -H 'Mcp-Protocol-Version: 2025-03-26' -i

Estrutura

src/
  index.js       # Express + transporte MCP
  mcp-setup.js   # Registro de recursos, ferramentas e prompt via SDK
  datasource.js  # S3 + mock
mock-data/
  components/
.env.example
README.md

Debug com MCP Inspector

Instale e conecte:

npx @modelcontextprotocol/inspector

Na UI, conecte usando a URL: http://localhost:3000/mcp.

Conexão com clientes MCP

Claude Code:

claude mcp add --transport http design-system http://localhost:3000/mcp

VS Code (exemplo JSON):

code --add-mcp '{"name":"design-system","type":"http","url":"http://localhost:3000/mcp"}'

Coleção Insomnia

Importação:
- Abra o Insomnia → Application → Import Data → From File.
- Selecione o arquivo insomnia_mcp_collection.json na raiz do projeto.
Ambiente:
- A coleção já define base_url (http://localhost:3000) e protocol_version (2025-03-26).
Encadeamento de sessão:
- A requisição Initialize (capture session) captura o header mcp-session-id.
- As demais requisições usam esse valor automaticamente com o template {% response 'req_init', 'header', 'mcp-session-id' %}.
Ordem sugerida:
- Health → Initialize (capture session) → resources/list → resources/read (button) → tools/list → tools/call search_components → tools/call related_components → prompts/list → prompts/get component_usage (id=button) → GET SSE /mcp (opcional) → DELETE /mcp.
Observações:
- Certifique-se de que o servidor esteja rodando (PORT=3000 MOCK_S3=true node src/index.js).
- O SSE é contínuo; interrompa manualmente quando terminar.

Design System MCP Server