Design System Server

Un servidor MCP para acceder y gestionar documentación de sistemas de diseño desde un repositorio de GitHub.

GitHub
12
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Design System

Este es un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona acceso a la documentación del sistema de diseño de Appian a través de repositorios de GitHub. Admite fuentes de documentación tanto públicas como internas, lo que permite que LLMs como Claude consulten y exploren componentes, diseños y patrones del sistema de diseño con controles de acceso apropiados.

🔗 Recursos Relacionados

⚡ Inicio Rápido

Para usuarios técnicos que quieran ponerse en marcha rápidamente:

  1. Clonar y configurar:

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

  2. Configurar acceso a GitHub:

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

  3. Compilar y configurar MCP:

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

  4. Probar la conexión:

    npm test

Para instrucciones detalladas de configuración, consulta la sección Instalación a continuación.

Características

  • Soporte de múltiples fuentes: Accede tanto a repositorios de documentación públicos como internos
  • Atribución de fuente: Indicación clara del origen del contenido (público/interno)
  • Fusión basada en prioridad: La documentación interna anula a la pública cuando ambas existen
  • Control de acceso: Acceso configurable a la documentación interna
  • Explorar categorías del sistema de diseño (componentes, diseños, patrones, marca, etc.)
  • Listar componentes dentro de una categoría con información de fuente
  • Obtener información detallada de componentes incluyendo guías y ejemplos de código
  • Buscar en todos los componentes por palabra clave con filtrado por fuente
  • Gestión de fuentes: Ver el estado de las fuentes y actualizar el contenido manualmente

Instalación

Solo Documentación Pública

Para acceso solo a la documentación pública del sistema de diseño:

  1. Clona este repositorio (o haz un fork en tu cuenta de GitHub)
  2. Copia el archivo de entorno y configúralo: 
    cp .env.example .env
  3. Edita .env y actualiza los valores:
    • GITHUB_TOKEN: Tu token de acceso personal de GitHub (genéralo en https://github.com/settings/tokens)
    • GITHUB_OWNER: Tu nombre de usuario de GitHub (el propietario del repositorio)
    • GITHUB_REPO: El nombre de tu repositorio (por ejemplo, "aurora")
  4. Instala las dependencias: 
    npm install
  5. Compila el servidor: 
    npm run build

Acceso a Documentación Interna

Para acceso tanto a documentación pública como interna:

  1. Sigue la configuración de documentación pública anterior
  2. Configura el acceso a la documentación interna en tu archivo .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. Asegúrate de que tu repositorio interno siga la misma estructura que el público:
    • Coloca los archivos de documentación en una carpeta /docs
    • Usa la misma estructura de categorías (componentes, diseños, patrones, etc.)

Configuración Avanzada

Para opciones de configuración detalladas, consulta Guía de Configuración.

Uso con Amazon Q (específico de Appian)

Esta sección te ayudará a configurar el Servidor MCP de Design System para trabajar con el chat de Amazon Q. Esta herramienta te permite consultar componentes, patrones y diseños del sistema de diseño directamente a través de IA conversacional, con soporte para fuentes de documentación tanto públicas como internas.

Lo Que Necesitarás

  • Acceso a nuestra cuenta de AWS
  • VS Code (recomendado)
  • Node.js instalado en tu máquina

Más sobre Node.js

Verifica si está instalado abriendo la aplicación Terminal y ejecutando este comando para ver la versión: node -v.

Si recibes un mensaje de "comando no encontrado", ve a la página de descarga de Node.js para obtenerlo. Puedes usar la herramienta de selección para ejecutar la instalación desde la línea de comandos o descargar el binario y ejecutarlo desde tu máquina.

Elige la versión LTS (soporte a largo plazo) actual de Node.

La herramienta de línea de comandos te pedirá que elijas un administrador de versiones de node y un administrador de paquetes de node. A menos que tengas preferencia por otra cosa, usa nvm y npm.

Paso 1: Instalar Amazon Q Chat

[!IMPORTANTE] Durante la instalación, inicia sesión con la opción Use with Pro license. Necesitarás localizar la URL de inicio en nuestra documentación interna.

  1. Visita la página de instalación del chat de Amazon Q: Amazon Q Developer (Línea de comandos)
    • Queremos usar la versión de línea de comandos (CLI) porque es más confiable y tiene acceso a las herramientas MCP.
  2. Haz clic en "Comenzar" y sigue las instrucciones de instalación para tu sistema operativo
  3. Una vez instalado, puedes acceder a Amazon Q a través de la línea de comandos de la terminal escribiendo q chat
    • Una vez que inicies Q, recomendamos cambiar el modelo a Claude 4 escribiendo /model y eligiendo esa opción.

Paso 2: Descargar Este Proyecto

Tienes dos opciones para obtener los archivos del proyecto:

Opción A: Descargar ZIP (Más fácil)

  1. Ve a la página de GitHub del proyecto
  2. Haz clic en el botón verde "Code"
  3. Selecciona "Download ZIP"
  4. Extrae el archivo ZIP en tu Escritorio o ubicación preferida
    • Se descargará y extraerá como aurora-mcp-main. Puedes eliminar el -main o dejarlo como está, pero el resto de las instrucciones asumen que no está ahí.

Opción B: Clonar con Git (Si te sientes cómodo con Git)

  1. Abre Terminal (Mac) o Símbolo del sistema (Windows)
  2. Navega a donde quieras el proyecto, por ejemplo, ~/repo/
  3. Ejecuta: git clone [repository-url]

Paso 3: Instalar el Proyecto

  1. Abre Terminal (Mac) o Símbolo del sistema (Windows)
  2. Navega a la carpeta del proyecto, por ejemplo: 
    cd Desktop/aurora
  3. Instala las dependencias requeridas: 
    npm install
  4. Compila el proyecto: 
    npm run build

Paso 4: Configurar Acceso a GitHub

El servidor MCP necesita acceso API a GitHub para obtener la documentación del sistema de diseño. Puedes configurar acceso solo para documentación pública, o para documentación pública e interna.

Solo Documentación Pública (Configuración Predeterminada)

A alto nivel, esto es lo que necesitas hacer:

  • Crear un Token de Acceso Personal (PAT) para permitir acceso API a todos los repositorios públicos (más fácil)
    • Alternativamente, puedes hacer un fork de tu propia copia del repositorio y crear un PAT para ese (más para desarrollo)
  • Copia el PAT a un archivo .env en la carpeta de tu copia local del repositorio aurora-mcp

Acceso a Documentación Interna (Opcional)

Si necesitas acceso a documentación interna, también necesitarás:

  • Acceso al repositorio de documentación interna
  • Un token de GitHub separado para el repositorio privado
  • Configuración adicional de entorno

Pasos Detallados

  1. Crear un Token de Acceso Personal de GitHub:

    • Ve a Configuración de GitHub > Configuración de desarrollador > Tokens de acceso personal > Tokens de grano fino
    • Haz clic en "Generar nuevo token"
    • Dale un nombre descriptivo como "Acceso a Documentación de Appian Aurora"
    • Establece la expiración según tu preferencia
    • Bajo Acceso a Repositorios, confirma que esté configurado en Public repositories
    • Haz clic en "Generar token"
    • Importante: Copia el token inmediatamente: ¡no podrás verlo de nuevo! (Puede que quieras pegarlo en una ubicación temporal hasta que completes la configuración).

  2. Crear un archivo .env:

    • En la carpeta aurora-mcp en tu máquina, ejecuta este comando en Terminal para copiar el archivo de entorno de ejemplo:

      cp .env.example .env

    • Abre el archivo .env en un editor de texto

      open -e .env

    • Solo para documentación pública, actualiza estos valores:

      • GITHUB_TOKEN: Reemplázalo con tu token real del paso anterior
      • GITHUB_OWNER: Debe configurarse como appian-design (a menos que hayas creado un fork)
      • GITHUB_REPO: Debe configurarse como aurora (a menos que hayas renombrado tu fork)

    • Para acceso a documentación interna, también agrega:

      • ENABLE_INTERNAL_DOCS=true
      • INTERNAL_DOCS_TOKEN=your_internal_docs_token_here

    • Guarda y cierra el archivo

  3. Recompilar el proyecto:

    npm run build

Paso 5: Configurar Amazon Q

Ahora necesitas indicarle a Amazon Q dónde encontrar este servidor de sistema de diseño.

  1. Configurar archivo de configuración:

    • Ejecuta este comando en Terminal para crear el archivo vacío en el lugar correcto y abrirlo con TextEdit: 
      mkdir -p ~/.aws/amazonq && touch ~/.aws/amazonq/mcp.json && open -e ~/.aws/amazonq/mcp.json

  2. Obtener la ruta completa de tu proyecto:

    • En Terminal/Símbolo del sistema, mientras estás en la carpeta del proyecto aurora-mcp, ejecuta: 
      pwd
    • Copia la ruta completa que aparece y pégala en algún lugar práctico por ahora (se verá algo como /Users/first.last/Desktop/aurora-mcp)

  3. Editar el archivo de configuración:

    • Abre el archivo mcp.json en VS Code o cualquier editor de texto (si no está ya abierto en TextEdit)
    • Agrega esta configuración (reemplaza YOUR_FULL_PATH_HERE con la ruta que copiaste y deja el /build/index.js después de la ruta):
    {
    "mcpServers": {
        "design-system": {
            "command": "node",
            "args": [
                "YOUR_FULL_PATH_HERE/build/index.js"
            ]
        }
    }
}

  4. Guarda el archivo y reinicia Amazon Q

  5. Confirmar configuración de MCP

    • En una nueva ventana de Terminal, escribe este comando: qchat mcp list
    • Deberías ver una referencia al archivo que acabas de editar (bajo global:) con un elemento design-system listado

Paso 6: Configurar Tu Proyecto de Trabajo

Ahora que el servidor MCP está configurado, querrás crear un espacio de trabajo separado para tu trabajo del sistema de diseño. Aquí es donde generarás y organizarás archivos antes de copiarlos en Interface Designer.

  1. Crear una nueva carpeta de proyecto:

    • Crea una nueva carpeta en tu Escritorio llamada algo como design-system-work o my-design-project
    • Esta carpeta estará separada de la carpeta del servidor MCP que descargaste anteriormente

  2. Abrir tu carpeta de trabajo en VS Code:

    • Inicia VS Code
    • Ve a Archivo → Abrir Carpeta
    • Selecciona tu nueva carpeta de proyecto de trabajo
    • Esto te da un espacio de trabajo limpio para tus archivos del sistema de diseño

  3. Entender el flujo de trabajo:

    • Usarás el chat de Amazon Q para consultar el sistema de diseño y generar código de componentes
    • Amazon Q te proporcionará fragmentos de código SAIL
    • Puedes guardar estos fragmentos como archivos en tu proyecto de VS Code para referencia
    • Cuando estés listo, copiarás y pegarás el código final en Interface Designer

  4. Organizar tu espacio de trabajo:

    • Considera crear carpetas como:
      • components/ - para archivos de componentes individuales
      • layouts/ - para patrones de diseño
      • examples/ - para ejemplos de código y variaciones
      • notes/ - para decisiones de diseño y documentación

Paso 7: Probarlo

  1. Abre el chat de Amazon Q (escribe q chat en Terminal)
  2. Intenta hacer preguntas como:
    • "¿Qué categorías del sistema de diseño están disponibles?"
    • "Muéstrame todos los componentes en la categoría de componentes"
    • "Busca en el sistema de diseño tarjetas"
    • "Verifica el estado de las fuentes de documentación" (para ver si la documentación interna está habilitada)
    • "Obtén detalles sobre el componente de tarjetas incluyendo documentación interna" (si tienes acceso interno)

Paso 8: Configuración de Documentación Interna (Opcional)

Si necesitas acceso a documentación interna, sigue estos pasos adicionales:

Requisitos Previos

  • Acceso al repositorio de documentación interna
  • Permiso para crear Tokens de Acceso Personal de GitHub para repositorios privados

Pasos de Configuración

  1. Obtener acceso al repositorio interno:

    • Contacta al líder de tu equipo para obtener acceso al repositorio de documentación interna
    • El repositorio típicamente se llama algo como aurora-internal

  2. Crear token de documentación interna:

  3. Actualizar tu archivo .env:

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

  4. Recompilar y probar:

    npm run build

    Prueba con Amazon Q:

    • "Verifica el estado de las fuentes de documentación"
    • Deberías ver tanto fuentes PÚBLICAS como INTERNAS listadas

Uso de Documentación Interna

Una vez configurado, puedes acceder a la documentación interna:

  • Agregando "incluyendo documentación interna" a tus consultas
  • Usando nombres específicos de componentes internos
  • Buscando solo dentro de la documentación interna

Ejemplos de consultas:

  • "Obtén detalles sobre el componente admin-panel incluyendo documentación interna"
  • "Busca componentes 'internos' solo en documentación interna"

Solución de Problemas

Si Amazon Q no puede encontrar el servidor:

  • Vuelve a verificar que la ruta en tu archivo de configuración sea correcta y absoluta (comienza con / en Mac o C:\ en Windows)
  • Asegúrate de haber ejecutado npm run build correctamente
  • Reinicia Amazon Q por completo

Si los comandos de npm no funcionan:

  • Instala Node.js desde nodejs.org
  • Reinicia tu Terminal/Símbolo del sistema después de la instalación

Si la documentación interna no funciona:

  • Verifica que ENABLE_INTERNAL_DOCS=true esté configurado en tu archivo .env
  • Comprueba que INTERNAL_DOCS_TOKEN tenga los permisos correctos
  • Prueba el token manualmente visitando el repositorio en tu navegador
  • Usa "Verificar el estado de las fuentes de documentación" para confirmar que ambas fuentes estén habilitadas

Si ves errores de "Autenticación requerida":

  • Tu token de documentación interna puede haber expirado
  • Verifica que el token tenga acceso al repositorio correcto
  • Intenta regenerar el token con los mismos permisos

¿Necesitas ayuda?

  • Consulta el archivo README.md principal para obtener una solución de problemas más detallada
  • Consulta la Guía de migración para actualizar desde una configuración de fuente única
  • Consulta la Guía de configuración para opciones de configuración avanzadas
  • La ruta del archivo de configuración debe ser la ruta absoluta completa para que funcione correctamente

¿Qué sigue?

Una vez configurado, puedes usar Amazon Q para explorar tu sistema de diseño haciendo preguntas en lenguaje natural sobre componentes, patrones y diseños. La IA te ayudará a encontrar lo que necesitas sin tener que navegar manualmente por la documentación.

Uso con Claude Desktop

  1. Asegúrate de tener Claude Desktop instalado y actualizado

  2. Edita el archivo de configuración de Claude Desktop:

    MacOS:

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

    Windows:

    %AppData%\Claude\claude_desktop_config.json

  3. Agrega la configuración del servidor:

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

    (Reemplaza /ABSOLUTE/PATH/TO con la ruta real a este directorio)

  4. Reinicia Claude Desktop

Solución de problemas

Si encuentras problemas:

  1. Revisa los registros de Claude Desktop: 
    tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
  2. Verifica que tu servidor se compile y ejecute sin errores
  3. Asegúrate de que la ruta de configuración sea absoluta y correcta
  4. Reinicia Claude Desktop por completo

Herramientas

El servidor proporciona las siguientes herramientas con soporte de doble fuente:

Gestión de fuentes

  1. get-content-sources: Ver las fuentes de documentación disponibles y su estado
  2. refresh-sources: Actualizar manualmente las fuentes de documentación y limpiar la caché

Acceso al contenido

  1. list-categories: Lista todas las categorías disponibles del sistema de diseño
  2. list-components: Lista todos los componentes en una categoría específica
  3. get-component-details: Obtiene información detallada sobre un componente específico con atribución de fuente
    • includeInternal: Acceder a documentación interna (predeterminado: false)
    • sourceOnly: Filtrar por fuente específica ("public", "internal", "all")
  4. search-design-system: Busca en todos los componentes por palabra clave con filtrado de fuente
    • includeInternal: Incluir documentación interna en la búsqueda
    • sourceOnly: Filtrar resultados por fuente específica

Para obtener documentación detallada de la API, consulta la Guía de API.

Consultas de ejemplo

Uso básico (documentación pública)

  • "¿Qué categorías del sistema de diseño están disponibles?"
  • "Muéstrame todos los componentes de la categoría 'layouts'"
  • "Obtén detalles sobre el componente 'cards'"
  • "Busca 'navigation' en el sistema de diseño"

Uso de doble fuente (pública + interna)

  • "Verifica el estado de las fuentes de documentación"
  • "Obtén detalles sobre el componente 'cards' incluyendo documentación interna"
  • "Busca componentes 'internos' solo en documentación interna"
  • "Muéstrame todos los componentes, incluidos los internos"
  • "Actualiza las fuentes de documentación"

Filtrado avanzado

// 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?"