Design System Server

Um servidor MCP para acessar e gerenciar documentação de sistema de design a partir de um repositório GitHub.

GitHub
12
Experimente este MCPPatrocinado

Documentação

Servidor MCP do Design System

Este é um servidor Model Context Protocol (MCP) que fornece acesso à documentação do design system da Appian por meio de repositórios GitHub. Ele suporta fontes de documentação públicas e internas, permitindo que LLMs como o Claude consultem e explorem componentes, layouts e padrões do design system com controles de acesso apropriados.

🔗 Recursos Relacionados

⚡ Início Rápido

Para usuários técnicos que desejam começar rapidamente:

  1. Clone e configure:

    git clone https://github.com/appian-design/aurora-mcp.git
cd aurora-mcp
npm install

  2. Configure o acesso ao GitHub:

    cp .env.example .env
# Edit .env with your GitHub token and repository details

  3. Compile e configure o MCP:

    npm run build
# Add to ~/.aws/amazonq/mcp.json or Claude Desktop config

  4. Teste a conexão:

    npm test

Para instruções detalhadas de configuração, consulte a seção Instalação abaixo.

Recursos

  • Suporte a múltiplas fontes: Acesse repositórios de documentação públicos e internos
  • Atribuição de fonte: Indicação clara da origem do conteúdo (público/interno)
  • Mesclagem baseada em prioridade: A documentação interna substitui a pública quando ambas existem
  • Controle de acesso: Acesso configurável à documentação interna
  • Navegue pelas categorias do design system (componentes, layouts, padrões, branding, etc.)
  • Liste componentes dentro de uma categoria com informações da fonte
  • Obtenha informações detalhadas de componentes, incluindo orientações e exemplos de código
  • Pesquise em todos os componentes por palavra-chave com filtro por fonte
  • Gerenciamento de fontes: Visualize o status das fontes e atualize o conteúdo manualmente

Instalação

Somente Documentação Pública

Para acesso apenas à documentação pública do design system:

  1. Clone este repositório (ou faça um fork para sua própria conta do GitHub)
  2. Copie o arquivo de ambiente e configure-o: 
    cp .env.example .env
  3. Edite .env e atualize os valores:
    • GITHUB_TOKEN: Seu token de acesso pessoal do GitHub (gere em https://github.com/settings/tokens)
    • GITHUB_OWNER: Seu nome de usuário do GitHub (o proprietário do repositório)
    • GITHUB_REPO: O nome do seu repositório (ex.: "aurora")
  4. Instale as dependências: 
    npm install
  5. Compile o servidor: 
    npm run build

Acesso à Documentação Interna

Para acesso à documentação pública e interna:

  1. Siga a configuração da documentação pública acima
  2. Configure o acesso à documentação interna no seu arquivo .env: 
    # Enable internal documentation
ENABLE_INTERNAL_DOCS=true

# GitHub token for internal repository (must have access to private repo)
INTERNAL_DOCS_TOKEN=your_github_token_for_private_repo

# Optional: Internal repository owner (defaults to GITHUB_OWNER)
INTERNAL_GITHUB_OWNER=your_internal_repo_owner

# Optional: Internal repository name (defaults to design-system-docs-internal)
INTERNAL_GITHUB_REPO=your_internal_repo_name
  3. Certifique-se de que seu repositório interno siga a mesma estrutura do público:
    • Coloque os arquivos de documentação em uma pasta /docs
    • Use a mesma estrutura de categorias (components, layouts, patterns, etc.)

Configuração Avançada

Para opções de configuração detalhadas, consulte o Guia de Configuração.

Uso com Amazon Q (específico da Appian)

Esta seção ajudará você a configurar o Servidor MCP do Design System para funcionar com o chat do Amazon Q. Esta ferramenta permite consultar componentes, padrões e layouts do design system diretamente por meio de IA conversacional, com suporte para fontes de documentação públicas e internas.

O Que Você Vai Precisar

  • Acesso à nossa conta AWS
  • VS Code (recomendado)
  • Node.js instalado na sua máquina

Mais sobre Node.js

Verifique se está instalado abrindo o aplicativo Terminal e executando este comando para ver a versão: node -v.

Se você receber uma mensagem de "comando não encontrado", acesse a página de download do Node.js para obtê-lo. Você pode usar a ferramenta de seleção para executar a instalação pela linha de comando ou baixar o binário e executá-lo na sua máquina.

Escolha a versão LTS (suporte de longo prazo) atual do Node.

A ferramenta de linha de comando fará você escolher um gerenciador de versão do node e um gerenciador de pacotes do node. A menos que você tenha preferência por outra coisa, use nvm e npm.

Etapa 1: Instalar o Amazon Q Chat

[!IMPORTANT] Durante a instalação, faça login com a opção Use with Pro license. Você precisará localizar a URL inicial na nossa documentação interna.

  1. Visite a página de instalação do chat do Amazon Q: Amazon Q Developer (linha de comando)
    • Queremos usar a versão de linha de comando (CLI) porque é mais confiável e tem acesso às ferramentas MCP.
  2. Clique em "Get Started" e siga as instruções de instalação para o seu sistema operacional
  3. Após a instalação, você pode acessar o Amazon Q pelo terminal digitando q chat
    • Ao iniciar o Q, recomendamos mudar o modelo para Claude 4 digitando /model e escolhendo essa opção.

Etapa 2: Baixar Este Projeto

Você tem duas opções para obter os arquivos do projeto:

Opção A: Baixar ZIP (mais fácil)

  1. Acesse a página do projeto no GitHub
  2. Clique no botão verde "Code"
  3. Selecione "Download ZIP"
  4. Extraia o arquivo ZIP para sua Área de Trabalho ou local de preferência
    • Ele será baixado e extraído como aurora-mcp-main. Você pode remover o -main ou deixar como está, mas o restante das instruções pressupõe que ele não esteja lá.

Opção B: Clonar com Git (se você estiver confortável com Git)

  1. Abra o Terminal (Mac) ou Prompt de Comando (Windows)
  2. Navegue até onde deseja colocar o projeto, ex.: ~/repo/
  3. Execute: git clone [repository-url]

Etapa 3: Instalar o Projeto

  1. Abra o Terminal (Mac) ou Prompt de Comando (Windows)
  2. Navegue até a pasta do projeto, por exemplo: 
    cd Desktop/aurora
  3. Instale as dependências necessárias: 
    npm install
  4. Compile o projeto: 
    npm run build

Etapa 4: Configurar o Acesso ao GitHub

O servidor MCP precisa de acesso à API do GitHub para buscar a documentação do design system. Você pode configurar o acesso apenas para documentação pública ou para documentação pública e interna.

Somente Documentação Pública (Configuração Padrão)

Em um nível geral, aqui está o que você precisa fazer:

  • Crie um Personal Access Token (PAT) para permitir acesso à API de todos os repositórios públicos (mais fácil)
    • Alternativamente, você pode criar um fork do repositório e criar um PAT para ele (mais voltado para desenvolvimento)
  • Copie o PAT para um arquivo .env na pasta da sua cópia local do repositório aurora-mcp

Acesso à Documentação Interna (Opcional)

Se você precisar de acesso à documentação interna, também precisará de:

  • Acesso ao repositório de documentação interna
  • Um token GitHub separado para o repositório privado
  • Configuração adicional de ambiente

Etapas Detalhadas

  1. Crie um Personal Access Token do GitHub:

  2. Crie um arquivo .env:

    • Na pasta aurora-mcp da sua máquina, execute este comando no Terminal para copiar o arquivo de ambiente de exemplo:

      cp .env.example .env

    • Abra o arquivo .env em um editor de texto

      open -e .env

    • Somente para documentação pública, atualize estes valores:

      • GITHUB_TOKEN: Substitua pelo seu token real da etapa anterior
      • GITHUB_OWNER: Deve ser definido como appian-design (a menos que você tenha criado um fork)
      • GITHUB_REPO: Deve ser definido como aurora (a menos que você tenha renomeado seu fork)

    • Para acesso à documentação interna, adicione também:

      • ENABLE_INTERNAL_DOCS=true
      • INTERNAL_DOCS_TOKEN=your_internal_docs_token_here

    • Salve e feche o arquivo

  3. Recompile o projeto:

    npm run build

Etapa 5: Configurar o Amazon Q

Agora você precisa informar ao Amazon Q onde encontrar este servidor do design system.

  1. Configure o arquivo de configuração:

    • Execute este comando no Terminal para criar o arquivo vazio no local correto e abri-lo com o TextEdit: 
      mkdir -p ~/.aws/amazonq && touch ~/.aws/amazonq/mcp.json && open -e ~/.aws/amazonq/mcp.json

  2. Obtenha o caminho completo do seu projeto:

    • No Terminal/Prompt de Comando, dentro da pasta do projeto aurora-mcp, execute: 
      pwd
    • Copie o caminho completo que aparecer e cole-o em algum lugar prático por enquanto (será algo como /Users/first.last/Desktop/aurora-mcp)

  3. Edite o arquivo de configuração:

    • Abra o arquivo mcp.json no VS Code ou em qualquer editor de texto (se ainda não estiver aberto no TextEdit)
    • Adicione esta configuração (substitua YOUR_FULL_PATH_HERE pelo caminho que você copiou e deixe o /build/index.js após o caminho):
    {
    "mcpServers": {
        "design-system": {
            "command": "node",
            "args": [
                "YOUR_FULL_PATH_HERE/build/index.js"
            ]
        }
    }
}

  4. Salve o arquivo e reinicie o Amazon Q

  5. Confirme a configuração do MCP

    • Em uma nova janela do Terminal, digite este comando: qchat mcp list
    • Você deve ver uma referência ao arquivo que acabou de editar (em global:) com um item design-system listado

Etapa 6: Configurar Seu Projeto de Trabalho

Agora que o servidor MCP está configurado, você vai querer criar um espaço de trabalho separado para o seu trabalho com o design system. É aqui que você vai gerar e organizar arquivos antes de copiá-los para o Interface Designer.

  1. Crie uma nova pasta de projeto:

    • Crie uma nova pasta na sua Área de Trabalho com um nome como design-system-work ou my-design-project
    • Esta pasta será separada da pasta do servidor MCP que você baixou anteriormente

  2. Abra sua pasta de trabalho no VS Code:

    • Inicie o VS Code
    • Vá em File → Open Folder
    • Selecione sua nova pasta de projeto de trabalho
    • Isso lhe dá um espaço de trabalho limpo para seus arquivos do design system

  3. Entendendo o fluxo de trabalho:

    • Você usará o chat do Amazon Q para consultar o design system e gerar código de componentes
    • O Amazon Q fornecerá trechos de código SAIL
    • Você pode salvar esses trechos como arquivos no seu projeto do VS Code para referência
    • Quando estiver pronto, você copiará e colará o código final no Interface Designer

  4. Organize seu espaço de trabalho:

    • Considere criar pastas como:
      • components/ - para arquivos de componentes individuais
      • layouts/ - para padrões de layout
      • examples/ - para exemplos de código e variações
      • notes/ - para decisões de design e documentação

Etapa 7: Teste

  1. Abra o chat do Amazon Q (digite q chat no Terminal)
  2. Tente fazer perguntas como:
    • "Quais categorias do design system estão disponíveis?"
    • "Mostre-me todos os componentes da categoria de componentes"
    • "Pesquise no design system por cards"
    • "Verifique o status das fontes de documentação" (para ver se a documentação interna está habilitada)
    • "Obtenha detalhes sobre o componente de cards incluindo documentação interna" (se você tiver acesso interno)

Etapa 8: Configuração da Documentação Interna (Opcional)

Se você precisar de acesso à documentação interna, siga estas etapas adicionais:

Pré-requisitos

  • Acesso ao repositório de documentação interna
  • Permissão para criar Personal Access Tokens do GitHub para repositórios privados

Etapas de Configuração

  1. Obtenha acesso ao repositório interno:

    • Entre em contato com o líder da sua equipe para obter acesso ao repositório de documentação interna
    • O repositório geralmente tem um nome como aurora-internal

  2. Crie o token da documentação interna:

  3. Atualize seu arquivo .env:

    # Add these lines to your existing .env file
ENABLE_INTERNAL_DOCS=true
INTERNAL_DOCS_TOKEN=your_internal_token_here

  4. Recompile e teste:

    npm run build

    Teste com o Amazon Q:

    • "Verifique o status das fontes de documentação"
    • Você deve ver as fontes PUBLIC e INTERNAL listadas

Usando a Documentação Interna

Após a configuração, você pode acessar a documentação interna:

  • Adicionando "incluindo documentação interna" às suas consultas
  • Usando nomes específicos de componentes internos
  • Pesquisando apenas na documentação interna

Exemplos de consultas:

  • "Obtenha detalhes sobre o componente admin-panel incluindo documentação interna"
  • "Pesquise por componentes 'internos' apenas na documentação interna"

Solução de Problemas

Se o Amazon Q não conseguir encontrar o servidor:

  • Verifique novamente se o caminho no seu arquivo de configuração está correto e é absoluto (começa com / no Mac ou C:\ no Windows)
  • Certifique-se de que você executou npm run build com sucesso
  • Reinicie o Amazon Q completamente

Se os comandos npm não funcionarem:

  • Instale o Node.js a partir de nodejs.org
  • Reinicie seu Terminal/Command Prompt após a instalação

Se a documentação interna não estiver funcionando:

  • Verifique se ENABLE_INTERNAL_DOCS=true está definido no seu arquivo .env
  • Verifique se INTERNAL_DOCS_TOKEN tem as permissões corretas
  • Teste o token manualmente visitando o repositório no seu navegador
  • Use "Verificar o status das fontes de documentação" para confirmar que ambas as fontes estão habilitadas

Se você vir erros de "Autenticação necessária":

  • Seu token de documentação interna pode ter expirado
  • Verifique se o token tem acesso ao repositório correto
  • Tente regenerar o token com as mesmas permissões

Precisa de ajuda?

  • Consulte o arquivo README.md principal para solução de problemas mais detalhada
  • Consulte o Guia de Migração para atualizar a partir da configuração de fonte única
  • Consulte o Guia de Configuração para opções avançadas de configuração
  • O caminho do arquivo de configuração deve ser o caminho completo e absoluto para funcionar corretamente

O que vem a seguir?

Depois de configurado, você pode usar o Amazon Q para explorar seu design system fazendo perguntas em linguagem natural sobre componentes, padrões e layouts. A IA ajudará você a encontrar o que precisa sem ter que navegar manualmente pela documentação.

Uso com o Claude Desktop

  1. Certifique-se de ter o Claude Desktop instalado e atualizado

  2. Edite o arquivo de configuração do Claude Desktop:

    MacOS:

    ~/Library/Application Support/Claude/claude_desktop_config.json

    Windows:

    %AppData%\Claude\claude_desktop_config.json

  3. Adicione a configuração do servidor:

    {
    "mcpServers": {
        "design-system": {
            "command": "node",
            "args": [
                "/ABSOLUTE/PATH/TO/aurora-mcp/build/index.js"
            ]
        }
    }
}

    (Substitua /ABSOLUTE/PATH/TO pelo caminho real para este diretório)

  4. Reinicie o Claude Desktop

Solução de problemas

Se você encontrar problemas:

  1. Verifique os logs do Claude Desktop: 
    tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
  2. Verifique se o seu servidor compila e executa sem erros
  3. Certifique-se de que o caminho de configuração seja absoluto e correto
  4. Reinicie o Claude Desktop completamente

Ferramentas

O servidor fornece as seguintes ferramentas com suporte a fontes duplas:

Gerenciamento de Fontes

  1. get-content-sources: Visualiza as fontes de documentação disponíveis e seu status
  2. refresh-sources: Atualiza manualmente as fontes de documentação e limpa o cache

Acesso ao Conteúdo

  1. list-categories: Lista todas as categorias disponíveis do design system
  2. list-components: Lista todos os componentes em uma categoria específica
  3. get-component-details: Obtém informações detalhadas sobre um componente específico com atribuição de fonte
    • includeInternal: Acessar documentação interna (padrão: false)
    • sourceOnly: Filtrar por fonte específica ("public", "internal", "all")
  4. search-design-system: Pesquisa em todos os componentes por palavra-chave com filtragem de fonte
    • includeInternal: Incluir documentação interna na pesquisa
    • sourceOnly: Filtrar resultados por fonte específica

Para documentação detalhada da API, consulte o Guia da API.

Exemplos de Consultas

Uso Básico (Documentação Pública)

  • "Quais categorias de design system estão disponíveis?"
  • "Mostre-me todos os componentes na categoria 'layouts'"
  • "Obtenha detalhes sobre o componente 'cards'"
  • "Pesquise no design system por 'navigation'"

Uso com Fontes Duplas (Pública + Interna)

  • "Verifique o status das fontes de documentação"
  • "Obtenha detalhes sobre o componente 'cards' incluindo documentação interna"
  • "Pesquise por componentes 'internos' apenas na documentação interna"
  • "Mostre-me todos os componentes, incluindo os internos"
  • "Atualize as fontes de documentação"

Filtragem Avançada

// Public users - default behavior
"Get details about the cards component"

// Internal users - access internal documentation
"Get details about the cards component with internal documentation included"

// Search only internal documentation
"Search for 'widget' in internal documentation only"

// Check what sources are available
"What documentation sources are available?"