Galley MCP Server
Integra a API GraphQL da Galley com clientes MCP. Ele faz introspecção automática do esquema GraphQL para uso contínuo com ferramentas como Claude e VS Code.
Documentação
Galley MCP Server
Um servidor Model Context Protocol (MCP) para integração com a API GraphQL da Galley usando o Apollo MCP Server com introspecção automática obrigatória de esquema. O servidor faz a introspecção do seu esquema GraphQL da Galley na inicialização e fornece integração perfeita com clientes MCP como Claude, Cursor e VS Code.
🚀 Início Rápido
Pré-requisitos
- Docker instalado no seu sistema
- Autenticação da API Galley (X-API-KEY ou token Bearer)
- Acesso de rede aos endpoints GraphQL da Galley
Build e Execução
# 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
Imagens Pré-construídas
Imagens Docker multi-arquitetura pré-construídas estão disponíveis no Amazon ECR Public Gallery:
- Registry:
public.ecr.aws/o0r1r5q2/galley-mcp - Mais recente:
public.ecr.aws/o0r1r5q2/galley-mcp:latest - Arquiteturas:
linux/amd64,linux/arm64 - Lançamentos automáticos: As imagens são construídas e publicadas automaticamente a cada commit no branch master
Tags de versão disponíveis:
latest- Versão estável mais recente do branch masterv1.0.0,v1.1.0, etc. - Tags de versão semântica de lançamentos1.0.0,1.1.0, etc. - Tags de versão sem o prefixo 'v'develop- Versão de desenvolvimento mais recente do branch develop
O que Acontece na Inicialização
- Introspecção de Esquema: Introspecta automaticamente o esquema GraphQL da Galley de
https://app.galleysolutions.com/graphql - Validação de Esquema: Verifica se o esquema foi recuperado com sucesso (a inicialização falha se a introspecção falhar)
- Início do Servidor MCP: Inicia o Apollo MCP Server com o esquema introspectado e suas operações
Importante: Modo Interativo Necessário
Os servidores MCP precisam rodar em modo interativo (flag -i) para se comunicar com clientes MCP. Isso permite:
- Comunicação bidirecional entre o cliente e o servidor
- Tratamento de requisição/resposta em tempo real para operações GraphQL
- Gerenciamento adequado de fluxos stdin/stdout para o protocolo MCP
Sempre use docker run -i ao executar o contêiner para integração com clientes MCP.
📋 Instalação do 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
Opção 1: Docker Desktop (Recomendado)
- Baixe o Docker Desktop de https://www.docker.com/products/docker-desktop
- Instale o arquivo
.dmg - Inicie o Docker Desktop a partir de Applications
- Verifique a instalação:
docker --version
Opção 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
Opção 1: Docker Desktop (Recomendado)
- Baixe o Docker Desktop de https://www.docker.com/products/docker-desktop
- Execute o instalador
- Reinicie o computador quando solicitado
- Inicie o Docker Desktop
- Verifique a instalação:
docker --version
Opção 2: WSL2 + Docker (Avançado)
# Enable WSL2
wsl --install
# Install Docker in WSL2
# Follow Linux installation steps inside WSL2
⚙️ Configuração
Variáveis de Ambiente
| Variável | Descrição | Padrão | Obrigatório |
|---|---|---|---|
X_API_KEY | Autenticação X-API-KEY da Galley | - | * |
X_USER_API_KEY | Autenticação x-user-api-key da Galley | - | * |
GALLEY_AUTH_TOKEN | Autenticação por token Bearer da Galley | - | * |
STAGING | Usar endpoints de ambiente de staging | false | Não |
ENDPOINT | URL do endpoint GraphQL para operações MCP | https://app.galleysolutions.com/graphql (prod) ou https://staging-app.galleysolutions.com/graphql (staging) | Não |
INTROSPECT_ENDPOINT | Endpoint de introspecção de esquema | Igual a ENDPOINT | Não |
USER_DIRECTORY | Diretório adicional de operações para montar | - | Não |
APOLLOGRAPHQL_CLIENT_NAME | Cabeçalho de identificação do cliente | galley-mcp-server@{hostname} | Não |
SCHEMA_OUTPUT | Caminho do arquivo de saída do esquema | /app/schema.graphql | Não |
MCP_DEBUG | Ativar modo de depuração com log detalhado | false | Não |
DISABLE_INTROSPECTION | Desativar capacidade de introspecção no servidor MCP | false | Não |
ALLOW_MUTATIONS | Controlar permissões de mutação: none, explicit ou all | none | Não |
Prioridade de Autenticação: X_API_KEY tem precedência sobre X_USER_API_KEY, que tem precedência sobre GALLEY_AUTH_TOKEN se vários forem fornecidos.
Modos de Ambiente
O servidor suporta ambientes de produção e staging:
Modo de Produção (Padrão)
# 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 - Introspecção:
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 - Introspecção:
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 Depuração
Defina MCP_DEBUG=true para ativar log detalhado e saída detalhada:
- Introspecção de Esquema: Mostra a saída detalhada do Rover e estatísticas do esquema
- Apollo MCP Server: Ativa log de depuração com
--log DEBUG - Configuração: Exibe todas as variáveis de ambiente e configurações
- Modo Silencioso: Quando
MCP_DEBUG=false(padrão), saída mínima para uso em produção
# 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
Introspecção de Esquema
- Obrigatória: A introspecção de esquema é executada em toda inicialização e não pode ser ignorada
- Falha Rápida: O servidor não iniciará se a introspecção de esquema falhar
- Autenticação: Usa o mesmo método de autenticação (X-API-KEY ou token Bearer) para introspecção
- Saída: O esquema é salvo em
/app/schema.graphqle usado pelo Apollo MCP Server
Controle de Introspecção
O servidor MCP suporta capacidades de introspecção que permitem aos clientes explorar o esquema GraphQL dinamicamente. Você pode controlar esse comportamento com a variável de ambiente DISABLE_INTROSPECTION:
- Comportamento padrão: A introspecção está habilitada (
DISABLE_INTROSPECTION=false) - Consideração de segurança: Desative a introspecção em ambientes de produção por segurança
- Impacto no cliente: Quando desativada, os clientes MCP não podem explorar o esquema dinamicamente
# 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
Controle de Mutação
O servidor MCP fornece controle granular sobre mutações GraphQL através da variável de ambiente ALLOW_MUTATIONS. Isso ajuda a manter a segurança dos dados e controlar quais operações os clientes MCP podem executar:
none(padrão): Não permite nenhuma mutação - acesso somente leituraexplicit: Permite apenas mutações pré-definidas de arquivos de operação, mas não permite que o LLM construa novas mutações dinamicamenteall: Permite que o LLM construa e execute mutações dinamicamente (maior risco)
# 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
Recomendação de Segurança: Use none ou explicit em ambientes de produção para evitar modificações não intencionais de dados.
Exemplos de Configuração
Configuração de Produção (Somente Leitura)
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
Configuração de Produção (Somente Mutações 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
Desenvolvimento com Operações Personalizadas e Depuração
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
Ambiente 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
🔌 Integração com Clientes MCP
Claude Desktop
-
Instale o Claude Desktop de https://claude.ai/download
-
Configure o Servidor MCP nas configurações do Claude:
Configuração somente leitura (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 mutações 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 o Claude Desktop para carregar o servidor MCP
Cursor IDE
-
Instale o Cursor de https://cursor.sh
-
Adicione a Configuração MCP nas configurações do Cursor:
- Abra Configurações → Extensões → MCP
- Adicione nova configuração 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" ] } -
Ative o servidor MCP no painel MCP do Cursor
VS Code
-
Instale o VS Code de https://code.visualstudio.com
-
Instale a Extensão MCP:
- Abra o painel de Extensões (
Ctrl+Shift+X) - Pesquise por "Model Context Protocol"
- Instale a extensão MCP
- Abra o painel de Extensões (
-
Configure o Servidor MCP:
- Abra as configurações do VS Code (
Ctrl+,) - Pesquise por "MCP"
- Adicione a configuração do 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 as configurações do VS Code (
🛠️ Desenvolvimento
Operações Personalizadas
Adicione suas próprias operações GraphQL montando um diretório 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
Introspecção de Esquema
O servidor introspecta automaticamente o esquema GraphQL da Galley na inicialização. O esquema é salvo em /app/schema.graphql e usado pelo Apollo MCP Server.
Principais Recursos:
- Execução obrigatória: Não pode ser ignorada ou desativada
- Comportamento de falha rápida: O servidor para se a introspecção falhar
- Autenticação: Usa as mesmas credenciais das operações MCP
- Esquema em tempo real: Sempre obtém o esquema mais recente na inicialização
- Identificação do cliente: Envia o cabeçalho
apollographql-client-namepara rastreamento
Ferramentas Integradas
A imagem Docker inclui:
- Apollo MCP Server: Versão mais recente instalada em
/usr/local/bin - Rover: Ferramenta CLI GraphQL da Apollo para introspecção de esquema
- Debian Bookworm Slim: Imagem base leve com suporte a glibc
Depuração
Ative o modo de depuração para saída detalhada e solução 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
Recursos do Modo de Depuração:
- Mostra todos os valores de configuração
- Exibe o comando de introspecção do Rover e sua saída
- Mostra estatísticas do esquema (linhas, tamanho do arquivo)
- Ativa o log de depuração do Apollo MCP Server
- Exibe o método de autenticação em uso
📁 Estrutura do Projeto
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 Principais
- entrypoint.sh: Orquestra a introspecção de esquema e a inicialização do servidor
- introspect-schema.sh: Usa o Rover para buscar o esquema GraphQL mais recente da Galley
- operations/: Contém suas operações GraphQL (queries, mutations, subscriptions)
- Dockerfile: Build multi-estágio com Apollo MCP Server e Rover pré-instalados
🔄 Pipeline CI/CD
O projeto inclui CI/CD automatizado usando GitHub Actions com dois fluxos de trabalho especializados:
🚀 Fluxo de Trabalho de Lançamento (release.yml)
Gatilhos: Push para o branch master
O que faz:
- Versionamento automático: Incrementa automaticamente a versão de patch a partir da tag mais recente
- Lançamentos no GitHub: Cria lançamento com notas geradas automaticamente
- Builds multi-arquitetura: Compila para
linux/amd64elinux/arm64 - Múltiplas tags Docker: Publica tags
latest,v1.0.1e1.0.1 - Documentação do lançamento: Inclui URLs de imagens Docker e informações de commit
Exemplo: Push para master → Cria lançamento v1.0.1 + publica imagens Docker
🔧 Fluxo de Trabalho de Build (build-and-push.yml)
Gatilhos:
- Push para o branch
develop - Pull requests para
master
O que faz:
- Builds de desenvolvimento: Publica a tag
developpara o branch de desenvolvimento - Validação de PR: Compila (mas não publica) para pull requests
- Multi-arquitetura: Suporta tanto
linux/amd64quantolinux/arm64 - Cache: Usa cache do GitHub Actions para builds mais rápidos
Tags Docker Disponíveis
latest- Lançamento estável mais recente do branch masterv1.0.1,1.0.1- Tags de versão semântica de lançamentosdevelop- Versão de desenvolvimento mais recente do branch develop
Configuração do Repositório
Para configurar o pipeline CI/CD, configure estes segredos do repositório GitHub:
AWS_ACCESS_KEY_ID: Chave de acesso AWS para permissões de push no ECRAWS_SECRET_ACCESS_KEY: Chave secreta AWS para permissões de push no ECR
Permissões: O fluxo de trabalho de lançamento precisa da permissão contents: write (configurada automaticamente).
O repositório ECR precisa ser criado como repositório público na região us-east-1 com o nome galley-mcp.
🔧 Solução de Problemas
Problemas Comuns
Erros de Autenticação
# 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
Falha na Introspecção de Esquema
# 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 com o 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 com 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 .
Obtendo Ajuda
- Verifique os logs de inicialização:
docker logs <container_id>- Mostra o processo de introspecção e inicialização - Verifique a autenticação: Garanta que seu X-API-KEY ou token Bearer seja válido
- Teste os endpoints: Confirme que tanto os endpoints de introspecção quanto os de operação estão acessíveis
- Verifique o Docker: Certifique-se de estar usando a versão mais recente do Docker
- Reconstrua a imagem: Tente
docker build --no-cache -t galley-mcp .para forçar um build limpo
Indicadores Comuns de Sucesso
Quando tudo funciona corretamente, você deve ver:
Modo Silencioso (MCP_DEBUG=false, padrão):
Error: Schema introspection failed. Server cannot start without valid schema.
(Only errors are shown)
Modo de Depuração (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
📄 Licença
[Sua Licença Aqui]
🤝 Contribuindo
- Faça um fork do repositório
- Crie um branch de funcionalidade
- Faça suas alterações
- Teste minuciosamente
- Envie um pull request
Para mais informações sobre o Model Context Protocol, visite https://modelcontextprotocol.io