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 master
  • v1.0.0, v1.1.0, etc. - Tags de versão semântica de lançamentos
  • 1.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

  1. Introspecção de Esquema: Introspecta automaticamente o esquema GraphQL da Galley de https://app.galleysolutions.com/graphql
  2. Validação de Esquema: Verifica se o esquema foi recuperado com sucesso (a inicialização falha se a introspecção falhar)
  3. 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)

  1. Baixe o Docker Desktop de https://www.docker.com/products/docker-desktop
  2. Instale o arquivo .dmg
  3. Inicie o Docker Desktop a partir de Applications
  4. 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)

  1. Baixe o Docker Desktop de https://www.docker.com/products/docker-desktop
  2. Execute o instalador
  3. Reinicie o computador quando solicitado
  4. Inicie o Docker Desktop
  5. 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ávelDescriçãoPadrãoObrigatório
X_API_KEYAutenticação X-API-KEY da Galley-*
X_USER_API_KEYAutenticação x-user-api-key da Galley-*
GALLEY_AUTH_TOKENAutenticação por token Bearer da Galley-*
STAGINGUsar endpoints de ambiente de stagingfalseNão
ENDPOINTURL do endpoint GraphQL para operações MCPhttps://app.galleysolutions.com/graphql (prod) ou https://staging-app.galleysolutions.com/graphql (staging)Não
INTROSPECT_ENDPOINTEndpoint de introspecção de esquemaIgual a ENDPOINTNão
USER_DIRECTORYDiretório adicional de operações para montar-Não
APOLLOGRAPHQL_CLIENT_NAMECabeçalho de identificação do clientegalley-mcp-server@{hostname}Não
SCHEMA_OUTPUTCaminho do arquivo de saída do esquema/app/schema.graphqlNão
MCP_DEBUGAtivar modo de depuração com log detalhadofalseNão
DISABLE_INTROSPECTIONDesativar capacidade de introspecção no servidor MCPfalseNão
ALLOW_MUTATIONSControlar permissões de mutação: none, explicit ou allnoneNã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.graphql e 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 leitura
  • explicit: Permite apenas mutações pré-definidas de arquivos de operação, mas não permite que o LLM construa novas mutações dinamicamente
  • all: 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

  1. Instale o Claude Desktop de https://claude.ai/download

  2. 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": {}
        }
      }
    }
    
  3. Reinicie o Claude Desktop para carregar o servidor MCP

Cursor IDE

  1. Instale o Cursor de https://cursor.sh

  2. 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"
      ]
    }
    
  3. Ative o servidor MCP no painel MCP do Cursor

VS Code

  1. Instale o VS Code de https://code.visualstudio.com

  2. Instale a Extensão MCP:

    • Abra o painel de Extensões (Ctrl+Shift+X)
    • Pesquise por "Model Context Protocol"
    • Instale a extensão MCP
  3. 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"
          ]
        }
      }
    }
    

🛠️ 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-name para 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/amd64 e linux/arm64
  • Múltiplas tags Docker: Publica tags latest, v1.0.1 e 1.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 develop para o branch de desenvolvimento
  • Validação de PR: Compila (mas não publica) para pull requests
  • Multi-arquitetura: Suporta tanto linux/amd64 quanto linux/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 master
  • v1.0.1, 1.0.1 - Tags de versão semântica de lançamentos
  • develop - 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 ECR
  • AWS_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

  1. Verifique os logs de inicialização: docker logs <container_id> - Mostra o processo de introspecção e inicialização
  2. Verifique a autenticação: Garanta que seu X-API-KEY ou token Bearer seja válido
  3. Teste os endpoints: Confirme que tanto os endpoints de introspecção quanto os de operação estão acessíveis
  4. Verifique o Docker: Certifique-se de estar usando a versão mais recente do Docker
  5. 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

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça suas alterações
  4. Teste minuciosamente
  5. Envie um pull request

Para mais informações sobre o Model Context Protocol, visite https://modelcontextprotocol.io