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 masterv1.0.0,v1.1.0, etc. - Etiquetas de versión semántica de los lanzamientos1.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
- Introspección de Esquema: Introspecta automáticamente el esquema GraphQL de Galley desde
https://app.galleysolutions.com/graphql - Validación de Esquema: Verifica que el esquema se haya recuperado correctamente (el inicio falla si la introspección falla)
- 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)
- Descargue Docker Desktop desde https://www.docker.com/products/docker-desktop
- Instale el archivo
.dmg - Inicie Docker Desktop desde Aplicaciones
- 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)
- Descargue Docker Desktop desde https://www.docker.com/products/docker-desktop
- Ejecute el instalador
- Reinicie su computadora cuando se le solicite
- Inicie Docker Desktop
- 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
| Variable | Descripción | Predeterminado | Requerido |
|---|---|---|---|
X_API_KEY | Autenticación X-API-KEY de Galley | - | * |
X_USER_API_KEY | Autenticación x-user-api-key de Galley | - | * |
GALLEY_AUTH_TOKEN | Autenticación de token Bearer de Galley | - | * |
STAGING | Usar endpoints de entorno de staging | false | No |
ENDPOINT | URL del endpoint GraphQL para operaciones MCP | https://app.galleysolutions.com/graphql (prod) o https://staging-app.galleysolutions.com/graphql (staging) | No |
INTROSPECT_ENDPOINT | Endpoint de introspección de esquema | Igual que ENDPOINT | No |
USER_DIRECTORY | Directorio adicional de operaciones para montar | - | No |
APOLLOGRAPHQL_CLIENT_NAME | Encabezado de identificación del cliente | galley-mcp-server@{hostname} | No |
SCHEMA_OUTPUT | Ruta del archivo de salida del esquema | /app/schema.graphql | No |
MCP_DEBUG | Habilitar modo de depuración con registro detallado | false | No |
DISABLE_INTROSPECTION | Deshabilitar capacidad de introspección en el servidor MCP | false | No |
ALLOW_MUTATIONS | Controlar permisos de mutaciones: none, explicit, o all | none | No |
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.graphqly 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 lecturaexplicit: Permitir solo mutaciones predefinidas de archivos de operaciones, pero no permitir que el LLM construya nuevas mutaciones dinámicamenteall: 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
-
Instale Claude Desktop desde https://claude.ai/download
-
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": {} } } } -
Reinicie Claude Desktop para cargar el servidor MCP
Cursor IDE
-
Instale Cursor desde https://cursor.sh
-
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" ] } -
Habilite el servidor MCP en el panel MCP de Cursor
VS Code
-
Instale VS Code desde https://code.visualstudio.com
-
Instale la Extensión MCP:
- Abra el panel de Extensiones (
Ctrl+Shift+X) - Busque "Model Context Protocol"
- Instale la extensión MCP
- Abra el panel de Extensiones (
-
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" ] } } } - Abra la configuración de VS Code (
🛠️ 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-namepara 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/amd64ylinux/arm64 - Múltiples etiquetas Docker: Publica etiquetas
latest,v1.0.1y1.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
developpara la rama de desarrollo - Validación de PR: Compila (pero no publica) para solicitudes de extracción
- Multiarquitectura: Admite tanto
linux/amd64comolinux/arm64 - Caché: Utiliza caché de GitHub Actions para compilaciones más rápidas
Etiquetas Docker Disponibles
latest- Última versión estable de la rama masterv1.0.1,1.0.1- Etiquetas de versión semántica de los lanzamientosdevelop- Ú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 ECRAWS_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
- Revise los registros de inicio:
docker logs <container_id>- Muestra la introspección y el proceso de inicio - Verifique la autenticación: Asegúrese de que su X-API-KEY o token Bearer sea válido
- Pruebe los endpoints: Confirme que tanto los endpoints de introspección como los de operaciones sean accesibles
- Revise Docker: Asegúrese de estar utilizando la versión más reciente de Docker
- 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
- Haga un fork del repositorio
- Cree una rama de características
- Realice sus cambios
- Pruebe a fondo
- Envíe una solicitud de extracción
Para obtener más información sobre el Model Context Protocol, visita https://modelcontextprotocol.io