Galley MCP Server

Integra la API GraphQL de Galley con clientes MCP. Realiza una introspección automática del esquema GraphQL para un uso fluido con herramientas como Claude y VS Code.

Documentación

Galley MCP Server

Un servidor de Protocolo de Contexto de Modelo (MCP) para la integración con la API GraphQL de Galley, utilizando Apollo MCP Server con introspección automática de esquema obligatoria. El servidor realiza la introspección de su esquema GraphQL de Galley al iniciarse y proporciona una integración perfecta con clientes MCP como Claude, Cursor y VS Code.

🚀 Inicio Rápido

Requisitos Previos

  • Docker instalado en su sistema
  • Autenticación de la API de Galley (X-API-KEY o token Bearer)
  • Acceso de red a los endpoints GraphQL de Galley

Compilar y Ejecutar

# Option 1: Use pre-built image from public ECR (recommended)
docker run -i -e X_API_KEY="your_api_key_here" public.ecr.aws/o0r1r5q2/galley-mcp:latest

# Option 2: Build from source
# Clone the repository
git clone <your-repo-url>
cd galley-mcp

# Build the Docker image
docker build -t galley-mcp .

# Run with X-API-KEY authentication
docker run -i -e X_API_KEY="your_api_key_here" galley-mcp

# Or run with x-user-api-key authentication
docker run -i -e X_USER_API_KEY="your_user_api_key_here" galley-mcp

# Or run with Bearer token authentication
docker run -i -e GALLEY_AUTH_TOKEN="your_bearer_token_here" galley-mcp

Imágenes Precompiladas

Las imágenes Docker multiarquitectura precompiladas están disponibles en Amazon ECR Public Gallery:

  • Registro: public.ecr.aws/o0r1r5q2/galley-mcp
  • Última versión: public.ecr.aws/o0r1r5q2/galley-mcp:latest
  • Arquitecturas: linux/amd64, linux/arm64
  • Lanzamientos automáticos: Las imágenes se compilan y publican automáticamente en cada confirmación en la rama master

Etiquetas de versión disponibles:

  • latest - Última versión estable de la rama master
  • v1.0.0, v1.1.0, etc. - Etiquetas de versión semántica de los lanzamientos
  • 1.0.0, 1.1.0, etc. - Etiquetas de versión sin el prefijo 'v'
  • develop - Última versión de desarrollo de la rama develop

Qué Sucede al Iniciar

  1. Introspección de Esquema: Introspecta automáticamente el esquema GraphQL de Galley desde https://app.galleysolutions.com/graphql
  2. Validación de Esquema: Verifica que el esquema se haya recuperado correctamente (el inicio falla si la introspección falla)
  3. Inicio del Servidor MCP: Lanza Apollo MCP Server con el esquema introspectado y sus operaciones

Importante: Modo Interactivo Requerido

Los servidores MCP deben ejecutarse en modo interactivo (bandera -i) para comunicarse con los clientes MCP. Esto permite:

  • Comunicación bidireccional entre el cliente y el servidor
  • Manejo de solicitudes/respuestas en tiempo real para operaciones GraphQL
  • Gestión adecuada de flujos stdin/stdout para el protocolo MCP

Utilice siempre docker run -i al ejecutar el contenedor para la integración con clientes MCP.

📋 Instalación de Docker

Linux (Ubuntu/Debian)

# Update package index
sudo apt-get update

# Install required packages
sudo apt-get install ca-certificates curl gnupg lsb-release

# Add Docker's official GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Add Docker repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker Engine
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Add your user to docker group (optional, to run without sudo)
sudo usermod -aG docker $USER
newgrp docker

# Verify installation
docker --version

macOS

Opción 1: Docker Desktop (Recomendado)

  1. Descargue Docker Desktop desde https://www.docker.com/products/docker-desktop
  2. Instale el archivo .dmg
  3. Inicie Docker Desktop desde Aplicaciones
  4. Verifique la instalación: docker --version

Opción 2: Homebrew

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Docker
brew install --cask docker

# Launch Docker Desktop
open /Applications/Docker.app

# Verify installation
docker --version

Windows

Opción 1: Docker Desktop (Recomendado)

  1. Descargue Docker Desktop desde https://www.docker.com/products/docker-desktop
  2. Ejecute el instalador
  3. Reinicie su computadora cuando se le solicite
  4. Inicie Docker Desktop
  5. Verifique la instalación: docker --version

Opción 2: WSL2 + Docker (Avanzado)

# Enable WSL2
wsl --install

# Install Docker in WSL2
# Follow Linux installation steps inside WSL2

⚙️ Configuración

Variables de Entorno

VariableDescripciónPredeterminadoRequerido
X_API_KEYAutenticación X-API-KEY de Galley-*
X_USER_API_KEYAutenticación x-user-api-key de Galley-*
GALLEY_AUTH_TOKENAutenticación de token Bearer de Galley-*
STAGINGUsar endpoints de entorno de stagingfalseNo
ENDPOINTURL del endpoint GraphQL para operaciones MCPhttps://app.galleysolutions.com/graphql (prod) o https://staging-app.galleysolutions.com/graphql (staging)No
INTROSPECT_ENDPOINTEndpoint de introspección de esquemaIgual que ENDPOINTNo
USER_DIRECTORYDirectorio adicional de operaciones para montar-No
APOLLOGRAPHQL_CLIENT_NAMEEncabezado de identificación del clientegalley-mcp-server@{hostname}No
SCHEMA_OUTPUTRuta del archivo de salida del esquema/app/schema.graphqlNo
MCP_DEBUGHabilitar modo de depuración con registro detalladofalseNo
DISABLE_INTROSPECTIONDeshabilitar capacidad de introspección en el servidor MCPfalseNo
ALLOW_MUTATIONSControlar permisos de mutaciones: none, explicit, o allnoneNo

Prioridad de Autenticación: X_API_KEY tiene prioridad sobre X_USER_API_KEY, que tiene prioridad sobre GALLEY_AUTH_TOKEN si se proporcionan múltiples.

Modos de Entorno

El servidor admite entornos de producción y staging:

Modo de Producción (Predeterminado)

# Uses production endpoints by default
docker run -i -e X_API_KEY="your_key" public.ecr.aws/o0r1r5q2/galley-mcp:latest
  • Endpoint: https://app.galleysolutions.com/graphql
  • Introspección: https://app.galleysolutions.com/graphql

Modo de Staging

# Enable staging mode
docker run -i -e X_API_KEY="your_key" -e STAGING=true public.ecr.aws/o0r1r5q2/galley-mcp:latest
  • Endpoint: https://staging-app.galleysolutions.com/graphql
  • Introspección: https://staging-app.galleysolutions.com/graphql

Endpoints Personalizados

# Override specific endpoints (takes precedence over STAGING flag)
docker run -i \
  -e X_API_KEY="your_key" \
  -e ENDPOINT="https://custom.galleysolutions.com/graphql" \
  -e INTROSPECT_ENDPOINT="https://custom-introspect.galleysolutions.com/graphql" \
  public.ecr.aws/o0r1r5q2/galley-mcp:latest

Modo de Depuración

Establezca MCP_DEBUG=true para habilitar el registro detallado y la salida detallada:

  • Introspección de Esquema: Muestra la salida detallada de Rover y estadísticas del esquema
  • Apollo MCP Server: Habilita el registro de depuración con --log DEBUG
  • Configuración: Muestra todas las variables de entorno y configuraciones
  • Modo Silencioso: Cuando MCP_DEBUG=false (predeterminado), salida mínima para uso en producción
# Enable debug mode
docker run -i -e X_API_KEY="your_key" -e MCP_DEBUG=true public.ecr.aws/o0r1r5q2/galley-mcp:latest

# Silent mode (default)
docker run -i -e X_API_KEY="your_key" public.ecr.aws/o0r1r5q2/galley-mcp:latest

Introspección de Esquema

  • Obligatoria: La introspección de esquema se ejecuta en cada inicio y no se puede omitir
  • Fallo Rápido: El servidor no se iniciará si la introspección de esquema falla
  • Autenticación: Utiliza el mismo método de autenticación (X-API-KEY o token Bearer) para la introspección
  • Salida: El esquema se guarda en /app/schema.graphql y lo utiliza Apollo MCP Server

Control de Introspección

El servidor MCP admite capacidades de introspección que permiten a los clientes explorar el esquema GraphQL dinámicamente. Puede controlar este comportamiento con la variable de entorno DISABLE_INTROSPECTION:

  • Comportamiento predeterminado: La introspección está habilitada (DISABLE_INTROSPECTION=false)
  • Consideración de seguridad: Deshabilite la introspección en entornos de producción por seguridad
  • Impacto en el cliente: Cuando está deshabilitada, los clientes MCP no pueden explorar el esquema dinámicamente
# Enable introspection (default)
docker run -i -e X_API_KEY="your_key" public.ecr.aws/o0r1r5q2/galley-mcp:latest

# Disable introspection for production
docker run -i -e X_API_KEY="your_key" -e DISABLE_INTROSPECTION=true public.ecr.aws/o0r1r5q2/galley-mcp:latest

Control de Mutaciones

El servidor MCP proporciona control granular sobre las mutaciones GraphQL a través de la variable de entorno ALLOW_MUTATIONS. Esto ayuda a mantener la seguridad de los datos y controlar qué operaciones pueden realizar los clientes MCP:

  • none (predeterminado): No permitir ninguna mutación - acceso de solo lectura
  • explicit: Permitir solo mutaciones predefinidas de archivos de operaciones, pero no permitir que el LLM construya nuevas mutaciones dinámicamente
  • all: Permitir que el LLM construya y ejecute mutaciones dinámicamente (mayor riesgo)
# Read-only mode (default)
docker run -i -e X_API_KEY="your_key" public.ecr.aws/o0r1r5q2/galley-mcp:latest

# Allow only explicit mutations from operation files
docker run -i -e X_API_KEY="your_key" -e ALLOW_MUTATIONS=explicit public.ecr.aws/o0r1r5q2/galley-mcp:latest

# Allow LLM to build mutations (use with caution)
docker run -i -e X_API_KEY="your_key" -e ALLOW_MUTATIONS=all public.ecr.aws/o0r1r5q2/galley-mcp:latest

Recomendación de Seguridad: Utilice none o explicit en entornos de producción para prevenir modificaciones no intencionadas de datos.

Ejemplos de Configuración

Configuración de Producción (Solo Lectura)

docker run -i \
  -e X_API_KEY="prod_api_key_here" \
  -e ENDPOINT="https://app.galleysolutions.com/graphql" \
  -e INTROSPECT_ENDPOINT="https://app.galleysolutions.com/graphql" \
  -e APOLLOGRAPHQL_CLIENT_NAME="production-server@prod-host" \
  -e DISABLE_INTROSPECTION=true \
  -e ALLOW_MUTATIONS=none \
  public.ecr.aws/o0r1r5q2/galley-mcp:latest

Configuración de Producción (Solo Mutaciones Explícitas)

docker run -i \
  -e X_API_KEY="prod_api_key_here" \
  -e ENDPOINT="https://app.galleysolutions.com/graphql" \
  -e INTROSPECT_ENDPOINT="https://app.galleysolutions.com/graphql" \
  -e APOLLOGRAPHQL_CLIENT_NAME="production-server@prod-host" \
  -e DISABLE_INTROSPECTION=true \
  -e ALLOW_MUTATIONS=explicit \
  public.ecr.aws/o0r1r5q2/galley-mcp:latest

Desarrollo con Operaciones Personalizadas y Depuración

docker run -i \
  -e X_API_KEY="dev_api_key_here" \
  -e USER_DIRECTORY="/custom/operations" \
  -e MCP_DEBUG=true \
  -e ALLOW_MUTATIONS=all \
  -v ./custom-operations:/custom/operations \
  public.ecr.aws/o0r1r5q2/galley-mcp:latest

Entorno de Staging

docker run -i \
  -e X_API_KEY="staging_api_key_here" \
  -e STAGING=true \
  -e APOLLOGRAPHQL_CLIENT_NAME="staging-server@staging-host" \
  public.ecr.aws/o0r1r5q2/galley-mcp:latest

🔌 Integración con Clientes MCP

Claude Desktop

  1. Instale Claude Desktop desde https://claude.ai/download

  2. Configure el Servidor MCP en la configuración de Claude:

    Configuración de solo lectura (recomendada):

    {
      "mcpServers": {
        "galley": {
          "command": "docker",
          "args": [
            "run",
            "--rm",
            "-i",
            "-e", "X_API_KEY=your_api_key_here",
            "-e", "DISABLE_INTROSPECTION=true",
            "-e", "ALLOW_MUTATIONS=none",
            "public.ecr.aws/o0r1r5q2/galley-mcp:latest"
          ],
          "env": {}
        }
      }
    }
    

    Permitir mutaciones explícitas:

    {
      "mcpServers": {
        "galley": {
          "command": "docker",
          "args": [
            "run",
            "--rm",
            "-i",
            "-e", "X_API_KEY=your_api_key_here",
            "-e", "ALLOW_MUTATIONS=explicit",
            "public.ecr.aws/o0r1r5q2/galley-mcp:latest"
          ],
          "env": {}
        }
      }
    }
    
  3. Reinicie Claude Desktop para cargar el servidor MCP

Cursor IDE

  1. Instale Cursor desde https://cursor.sh

  2. Agregue la Configuración MCP en la configuración de Cursor:

    • Abra Configuración → Extensiones → MCP
    • Agregue una nueva configuración de servidor:
    {
      "name": "galley",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "X_API_KEY=your_api_key_here",
        "public.ecr.aws/o0r1r5q2/galley-mcp:latest"
      ]
    }
    
  3. Habilite el servidor MCP en el panel MCP de Cursor

VS Code

  1. Instale VS Code desde https://code.visualstudio.com

  2. Instale la Extensión MCP:

    • Abra el panel de Extensiones (Ctrl+Shift+X)
    • Busque "Model Context Protocol"
    • Instale la extensión MCP
  3. Configure el Servidor MCP:

    • Abra la configuración de VS Code (Ctrl+,)
    • Busque "MCP"
    • Agregue la configuración del servidor:
    {
      "mcp.servers": {
        "galley": {
          "command": "docker",
          "args": [
            "run", "--rm", "-i",
            "-e", "X_API_KEY=your_api_key_here",
            "public.ecr.aws/o0r1r5q2/galley-mcp:latest"
          ]
        }
      }
    }
    

🛠️ Desarrollo

Operaciones Personalizadas

Agregue sus propias operaciones GraphQL montando un directorio personalizado:

# Create custom operations directory
mkdir -p ./my-operations

# Add your .graphql files
echo 'query MyCustomQuery { viewer { id } }' > ./my-operations/MyQuery.graphql

# Run with custom operations
docker run -i \
  -e X_API_KEY="your_api_key" \
  -e USER_DIRECTORY="/custom" \
  -v ./my-operations:/custom \
  public.ecr.aws/o0r1r5q2/galley-mcp:latest

Introspección de Esquema

El servidor introspecta automáticamente el esquema GraphQL de Galley al iniciarse. El esquema se guarda en /app/schema.graphql y lo utiliza Apollo MCP Server.

Características Clave:

  • Ejecución obligatoria: No se puede omitir ni deshabilitar
  • Comportamiento de fallo rápido: El servidor se detiene si la introspección falla
  • Autenticación: Utiliza las mismas credenciales que las operaciones MCP
  • Esquema en tiempo real: Siempre obtiene el esquema más reciente al iniciarse
  • Identificación del cliente: Envía el encabezado apollographql-client-name para seguimiento

Herramientas Integradas

La imagen Docker incluye:

  • Apollo MCP Server: Última versión instalada en /usr/local/bin
  • Rover: Herramienta CLI de GraphQL de Apollo para introspección de esquema
  • Debian Bookworm Slim: Imagen base ligera con soporte glibc

Depuración

Habilite el modo de depuración para obtener salida detallada y solución de problemas:

# Enable debug mode for verbose logging
docker run -i -e X_API_KEY="your_api_key" -e MCP_DEBUG=true public.ecr.aws/o0r1r5q2/galley-mcp:latest

# View container logs
docker logs <container_id>

# Run interactively to see all output
docker run -it -e X_API_KEY="your_api_key" -e MCP_DEBUG=true public.ecr.aws/o0r1r5q2/galley-mcp:latest

# Test with different endpoints in debug mode
docker run -i \
  -e X_API_KEY="your_api_key" \
  -e MCP_DEBUG=true \
  -e INTROSPECT_ENDPOINT="https://staging-app.galleysolutions.com/graphql" \
  public.ecr.aws/o0r1r5q2/galley-mcp:latest

Características del Modo de Depuración:

  • Muestra todos los valores de configuración
  • Muestra el comando de introspección de Rover y su salida
  • Muestra estadísticas del esquema (líneas, tamaño del archivo)
  • Habilita el registro de depuración de Apollo MCP Server
  • Muestra el método de autenticación que se está utilizando

📁 Estructura del Proyecto

galley-mcp/
├── Dockerfile                 # Docker container with Apollo MCP Server + Rover
├── entrypoint.sh             # Main startup script with mandatory introspection
├── introspect-schema.sh      # Schema introspection script using Rover
├── operations/               # GraphQL operations directory
│   └── GetRecipesByName.graphql  # Example Galley recipe query
└── README.md                # This comprehensive guide

Componentes Clave

  • entrypoint.sh: Orquesta la introspección de esquema y el inicio del servidor
  • introspect-schema.sh: Utiliza Rover para obtener el esquema GraphQL más reciente de Galley
  • operations/: Contiene sus operaciones GraphQL (consultas, mutaciones, suscripciones)
  • Dockerfile: Compilación de múltiples etapas con Apollo MCP Server y Rover preinstalados

🔄 Pipeline CI/CD

El proyecto incluye CI/CD automatizado utilizando GitHub Actions con dos flujos de trabajo especializados:

🚀 Flujo de Trabajo de Lanzamiento (release.yml)

Disparadores: Push a la rama master

Qué hace:

  • Versión automática: Incrementa automáticamente la versión de parche desde la última etiqueta
  • Lanzamientos de GitHub: Crea un lanzamiento con notas generadas automáticamente
  • Compilaciones multiarquitectura: Compila para linux/amd64 y linux/arm64
  • Múltiples etiquetas Docker: Publica etiquetas latest, v1.0.1 y 1.0.1
  • Documentación del lanzamiento: Incluye URLs de imágenes Docker e información de confirmación

Ejemplo: Push a master → Crea el lanzamiento v1.0.1 + publica imágenes Docker

🔧 Flujo de Trabajo de Compilación (build-and-push.yml)

Disparadores:

  • Push a la rama develop
  • Solicitudes de extracción a master

Qué hace:

  • Compilaciones de desarrollo: Publica la etiqueta develop para la rama de desarrollo
  • Validación de PR: Compila (pero no publica) para solicitudes de extracción
  • Multiarquitectura: Admite tanto linux/amd64 como linux/arm64
  • Caché: Utiliza caché de GitHub Actions para compilaciones más rápidas

Etiquetas Docker Disponibles

  • latest - Última versión estable de la rama master
  • v1.0.1, 1.0.1 - Etiquetas de versión semántica de los lanzamientos
  • develop - Última versión de desarrollo de la rama develop

Configuración del Repositorio

Para configurar el pipeline CI/CD, configure estos secretos del repositorio de GitHub:

  • AWS_ACCESS_KEY_ID: Clave de acceso de AWS para permisos de push a ECR
  • AWS_SECRET_ACCESS_KEY: Clave secreta de AWS para permisos de push a ECR

Permisos: El flujo de trabajo de lanzamiento necesita el permiso contents: write (configurado automáticamente).

El repositorio ECR debe crearse como un repositorio público en la región us-east-1 con el nombre galley-mcp.

🔧 Solución de Problemas

Problemas Comunes

Errores de Autenticación

# Verify your API key is correct
docker run -i -e X_API_KEY="your_key" public.ecr.aws/o0r1r5q2/galley-mcp:latest

# Check if endpoint is accessible
curl -H "X-API-KEY: your_key" https://app.galleysolutions.com/graphql

La Introspección de Esquema Falla

# Check network connectivity to introspection endpoint
docker run --rm -e X_API_KEY="your_key" public.ecr.aws/o0r1r5q2/galley-mcp:latest ping -c 3 app.galleysolutions.com

# Test GraphQL endpoint manually
curl -X POST -H "Content-Type: application/json" \
  -H "X-API-KEY: your_key" \
  -d '{"query": "{ __schema { types { name } } }"}' \
  https://app.galleysolutions.com/graphql

# Check if introspection endpoint is different from operation endpoint
docker run -i \
  -e X_API_KEY="your_key" \
  -e INTROSPECT_ENDPOINT="https://staging-app.galleysolutions.com/graphql" \
  public.ecr.aws/o0r1r5q2/galley-mcp:latest

# Verify authentication method
# Try with Bearer token instead of X-API-KEY
docker run -i -e GALLEY_AUTH_TOKEN="your_token" public.ecr.aws/o0r1r5q2/galley-mcp:latest

Problemas con Apollo MCP Server

# Verify Apollo MCP Server is installed correctly
docker run --rm public.ecr.aws/o0r1r5q2/galley-mcp:latest which apollo-mcp-server
docker run --rm public.ecr.aws/o0r1r5q2/galley-mcp:latest apollo-mcp-server --version

# Check if schema file exists after introspection
docker run --rm -e X_API_KEY="your_key" public.ecr.aws/o0r1r5q2/galley-mcp:latest ls -la /app/schema.graphql

Problemas con Docker

# Check Docker is running
docker --version

# Pull latest base image
docker pull debian:bookworm-slim

# Rebuild without cache
docker build --no-cache -t galley-mcp .

Obtener Ayuda

  1. Revise los registros de inicio: docker logs <container_id> - Muestra la introspección y el proceso de inicio
  2. Verifique la autenticación: Asegúrese de que su X-API-KEY o token Bearer sea válido
  3. Pruebe los endpoints: Confirme que tanto los endpoints de introspección como los de operaciones sean accesibles
  4. Revise Docker: Asegúrese de estar utilizando la versión más reciente de Docker
  5. Recompile la imagen: Intente docker build --no-cache -t galley-mcp . para forzar una compilación nueva

Indicadores Comunes de Éxito

Cuando todo funciona correctamente, debería ver:

Modo Silencioso (MCP_DEBUG=false, predeterminado):

Error: Schema introspection failed. Server cannot start without valid schema.
(Only errors are shown)

Modo de Depuración (MCP_DEBUG=true):

Starting Apollo MCP Server with Galley configuration...
Endpoint: https://staging-app.galleysolutions.com/graphql
Operations directory: /app/operations
Graph reference: Galley-dtd1yd@current
Client name: galley-mcp-server@hostname
Debug mode: true
Running mandatory schema introspection...
Rover is available
Introspecting schema from: https://app.galleysolutions.com/graphql
Using X-API-KEY for introspection
Running: rover graph introspect https://app.galleysolutions.com/graphql --output /app/schema.graphql --log DEBUG --header X-API-KEY:your_key --header apollographql-client-name:galley-mcp-introspect@hostname
Schema introspection completed successfully!
Schema saved to: /app/schema.graphql
Schema file: XXXX lines, XXXkB
Schema introspection completed successfully, starting server...
Using X-API-KEY authentication

📄 Licencia

[Su Licencia Aquí]

🤝 Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Realice sus cambios
  4. Pruebe a fondo
  5. Envíe una solicitud de extracción

Para obtener más información sobre el Model Context Protocol, visita https://modelcontextprotocol.io