Gaz MCP

Servidor MCP para acesso somente leitura a MySQL/PostgreSQL, administração de Jenkins e diagnóstico ao vivo de processos Go via pprof/expvar. Construído para agentes de codificação de IA.

GitHubExperimente este MCPPatrocinado

Documentação

gaz-mcp — MySQL, PostgreSQL, Jenkins, image generation, and Go diagnostics exposed as an MCP server

gaz-mcp

gaz-mcp é um servidor MCP para acesso somente leitura a MySQL/PostgreSQL, administração de Jenkins com histórico de configuração, geração de imagens via OpenRouter e diagnóstico de processos Go em execução por meio de pprof e expvar. Ele também inclui o módulo Go independente diagnostics para adicionar esses endpoints a serviços de destino.

Ele usa transporte stdio: um único binário, sem daemon e sem listener aberto pelo próprio MCP. Os alvos SQL e Jenkins são configurados uma vez; um alvo de diagnóstico Go é fornecido diretamente em cada chamada de ferramenta.

Capacidades

Capacidade	Propósito	Configuração	Guia completo
SQL	Inspecionar dados MySQL e PostgreSQL sem gravações	`environments`	SQL: MySQL e PostgreSQL
Jenkins	Inspecionar e administrar CI/CD, incluindo histórico de configuração	`jenkins`, `snapshot`	Jenkins
Geração de imagens	Gerar e comparar imagens por meio de uma lista de permissões fechada de modelos OpenRouter	`image_generation`	Geração de imagens
Diagnóstico Go	Capturar perfis e inspecionar goroutines, métricas de runtime/processo/host/cgroup e pools SQL opcionais	URL `target` por chamada	Diagnóstico de processos Go

Propriedades compartilhadas

Servidor MCP stdio — um único binário, sem daemon, sem portas de rede.
SQL e Jenkins multiambiente — selecione o ambiente configurado por chamada.
Aplicação de SQL somente leitura — verificações do aplicativo mais sessões de banco de dados somente leitura.
Seleção dinâmica de banco de dados — o banco de dados pertence a cada solicitação SQL, não à configuração estática.
Conjunto de ferramentas Jenkins — 33 ferramentas para jobs, builds, nós, visualizações, fila, plugins, credenciais, console de script e snapshots.
Histórico de configuração — snapshots do Jenkins são armazenados em SQLite para as operações que suportam captura e rollback.
Deduplicação SHA-256 — snapshots de configuração consecutivos idênticos não são armazenados duas vezes.
Geração de imagens controlada — escolha um modelo de imagem OpenRouter configurado por solicitação, com controles de prompt, referências de seed, dimensões, qualidade, formato, seed e roteamento de provedor.
Diagnóstico de processos Go — perfis pprof, pilhas de goroutines agrupadas, métricas brutas de runtime/processo/host/cgroup e uma lista separada de suspeitas heurísticas baseadas em evidências.
Saída JSON estruturada — projetada para consumo programático.
Configuração YAML — configuração baseada em Viper, com renderização de segredos em tempo de implantação.
Arquitetura hexagonal — camadas de domínio, aplicação e plataforma permanecem separadas.

Requisitos

A versão do Go declarada em go.mod (atualmente Go 1.26.0) para compilar a partir do código-fonte, ou um binário pré-compilado.
Um servidor MySQL/PostgreSQL e/ou instância Jenkins acessível a partir do host que executa o MCP.

Instalação

Compilar a partir do código-fonte

go build -o gaz-mcp ./cmd/server/

Binário pré-compilado

Linux e macOS:

# Latest release
curl -fsSL https://raw.githubusercontent.com/jcastilloa/gaz-mcp/master/scripts/install.sh | sh

# Specific version
curl -fsSL https://raw.githubusercontent.com/jcastilloa/gaz-mcp/master/scripts/install.sh | VERSION=vX.Y.Z sh

Variável	Padrão
`REPO`	`jcastilloa/gaz-mcp`
`SERVICE_NAME`	`gaz-mcp`
`INSTALL_DIR`	`~/.local/bin`
`VERSION`	Tag da versão mais recente

Habilidades do agente

As habilidades do agente voltadas ao produto são distribuídas em skills/, separadamente do .codex/skills usado para desenvolver este repositório:

Habilidade	Capacidade
`gaz-mcp-db`	Inspeção somente leitura de MySQL e PostgreSQL
`gaz-mcp-jenkins`	Operações Jenkins e histórico de configuração
`gaz-mcp-diagnostics`	Instrumentação de serviços Go, pprof, expvar, métricas e suspeitas de diagnóstico

Instale o diretório completo para cada capacidade habilitada. Por exemplo, a partir de um checkout do gaz-mcp, copie-os para um projeto separado que consuma o MCP:

GAZ_MCP_DIR=/path/to/gaz-mcp
CONSUMER_PROJECT=/path/to/project-using-gaz-mcp
mkdir -p "$CONSUMER_PROJECT/.codex/skills"
cp -R "$GAZ_MCP_DIR/skills/gaz-mcp-db" "$CONSUMER_PROJECT/.codex/skills/"
cp -R "$GAZ_MCP_DIR/skills/gaz-mcp-jenkins" "$CONSUMER_PROJECT/.codex/skills/"
cp -R "$GAZ_MCP_DIR/skills/gaz-mcp-diagnostics" "$CONSUMER_PROJECT/.codex/skills/"

Consulte o catálogo de habilidades para caminhos de projeto/global em Claude Code, Codex, OpenCode e Cursor, além do limite entre habilidades de produto e de contribuidor.

Configuração

Crie config.yaml no diretório de trabalho ou em ~/.config/gaz-mcp/config.yaml.

service:
  transport: stdio
  version: 0.4.0

# SQL environments (MySQL + PostgreSQL)
environments:
  dev1:
    engine: mysql
    host: 127.0.0.1
    port: 3306
    user: readonly_user
    password: your-password

  analytics:
    engine: postgres
    host: 127.0.0.1
    port: 5432
    user: postgres
    password: your-password

# Jenkins environments
jenkins:
  production:
    url: https://jenkins.example.com
    user: admin
    api_key: "${JENKINS_PROD_API_KEY}" # Jenkins API token or password
    timeout: 30s
    insecure: false
  staging:
    url: https://jenkins-staging.example.com
    user: admin
    api_key: "${JENKINS_STAGING_API_KEY}"
    timeout: 30s
    insecure: true # allow self-signed TLS

# Jenkins configuration history (SQLite, pure Go)
snapshot:
  enabled: true
  db_path: ~/.config/gaz-mcp/jenkins_history.db
  max_versions: 50 # positive retention limit per object
  auto_prune: true

# OpenRouter image generation. models is a closed allowlist: image_generate
# rejects every model not declared here.
image_generation:
  api_key: "${OPENROUTER_API_KEY}"
  base_url: https://openrouter.ai/api/v1
  timeout: 2m
  models:
    - openai/gpt-image-1
    - google/gemini-2.5-flash-image

engine assume o padrão mysql quando omitido. O database SQL é selecionado pela chamada da ferramenta, não aqui. Para imagens, image_model_list retorna a lista de permissões configurada e image_generate seleciona uma de suas entradas por chamada. O target de diagnóstico Go também é deliberadamente não configurado aqui: o chamador fornece a URL do processo autorizado para cada solicitação.

Nota de configuração: image_generation.api_key expande ${NAME} a partir do ambiente do processo. Mantenha todos os outros placeholders de segredos sob controle de configuração em tempo de implantação. max_versions é atualmente normalizado para o padrão de 50 quando configurado como zero ou outro valor não positivo, portanto, use um valor positivo no YAML.

Segurança: use ${OPENROUTER_API_KEY} (ou outro mecanismo de segredo em tempo de implantação) para image_generation.api_key; ele é mascarado na saída JSON. As ferramentas de imagem são registradas somente quando image_generation.models não está vazio, e uma chave de API é então necessária. O api_key do Jenkins aceita um token de API do Jenkins (recomendado, criado em User → Configure → API Token) ou uma senha. Mantenha os segredos resolvidos fora do controle de versão e use configuração restrita em tempo de implantação.

Consulte config.sample.yaml para o exemplo completo, incluindo as configurações do provedor OpenAI usadas pelo aplicativo.

Início rápido

1. Configurar

cp config.sample.yaml config.yaml
# Edit the environments, jenkins, snapshot, and image_generation sections, then render secret placeholders.

2. Executar

go run ./cmd/server/ --transport stdio
# Or with the built binary:
./gaz-mcp --transport stdio

3. Registrar em um cliente MCP

Claude Desktop, Cursor e clientes baseados em JSON

{
  "mcpServers": {
    "gaz-mcp": {
      "command": "/absolute/path/to/gaz-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

Codex (TOML)

[mcp_servers.gaz-mcp]
command = "/absolute/path/to/gaz-mcp"
args = ["--transport", "stdio"]
startup_timeout_sec = 20.0

Codex CLI

codex mcp add gaz-mcp -- /absolute/path/to/gaz-mcp --transport stdio

OpenCode

opencode mcp add

Siga os prompts: projeto ou global, nome gaz-mcp, tipo local, depois comando /absolute/path/to/gaz-mcp --transport stdio.

Sempre use um caminho absoluto do binário e transporte stdio.

Mapa de documentação

O documento raiz contém instalação, configuração, configuração do cliente, arquitetura e desenvolvimento. As referências operacionais completas estão nos guias focados abaixo; nenhuma referência de ferramenta é intencionalmente duplicada aqui.

Guia	Inclui
SQL: MySQL e PostgreSQL	Contrato `sql_query`, padrões de descoberta MySQL/PostgreSQL, ambas as proteções somente leitura e limites de pool
Jenkins	Todas as 33 ferramentas, parâmetros exatos, cobertura de snapshots e restauração, destilação de saída grande, fluxos de trabalho e notas de segurança
Diagnóstico de processos Go	Trecho `pprof`/`expvar` no lado do serviço, métricas opcionais `database/sql`, todas as nove ferramentas, descobertas e fluxos de trabalho de perfil

O módulo do lado do serviço é lançado independentemente usando tags compatíveis com módulos como diagnostics/v0.1.0; as tags de lançamento do servidor MCP (v0.4.x) não são versões de módulo para github.com/jcastilloa/gaz-mcp/diagnostics.

Para mover os endpoints do serviço de /debug/... para um prefixo personalizado, use diagnostics.WithBasePath("/internal/diagnostics"); depois passe http://service:6060/internal/diagnostics como o target da ferramenta de diagnóstico.

Arquitetura

gaz-mcp/
├── cmd/server/              # Entry point
├── diagnostics/             # Independent service-side instrumentation Go module
├── skills/                  # Product-facing agent skills distributed to gaz-mcp users
├── mcp/
│   ├── application/
│   │   ├── diagnostics/     # Go process diagnosis use cases
│   │   ├── image/           # Image-generation use cases
│   │   ├── jenkins/         # Jenkins use cases + NoopSnapshotRepository
│   │   └── sql/             # SQL use case (read-only enforcement)
│   └── domain/
│       ├── diagnostics/     # Diagnostic target and profile-store ports
│       ├── image/           # Image-generation repository port
│       ├── jenkins/         # Repository + SnapshotRepository ports
│       └── sql/             # Repository port
├── platform/
│   ├── config/              # Viper config reader
│   ├── di/                  # Dependency injection container
│   └── mcp/
│       ├── commands/        # Cobra runner + tool wiring
│       ├── diagnostics/     # HTTP pprof/expvar adapter + profile store
│       ├── image/           # OpenRouter image API adapter
│       ├── jenkins/         # gojenkins infrastructure adapter
│       ├── server/          # MCP server wrapper
│       ├── snapshot/        # SQLite snapshot repository
│       ├── sql/             # MySQL + PostgreSQL adapters
│       └── tools/           # MCP tool definitions
└── shared/
    ├── ai/domain/           # AI provider contracts
    └── config/domain/       # Configuration contracts

Regra de dependência: platform → shared + mcp/application + mcp/domain. Nunca inverta essa direção.

Desenvolvimento

go build ./...                                    # Build all packages
go vet ./...                                      # Static analysis
go test ./...                                     # All tests
go test ./mcp/application/jenkins/... -v          # Jenkins service unit tests
go test ./platform/mcp/snapshot/... -v            # SQLite snapshot integration tests
go test ./mcp/application/diagnostics/... -v      # Diagnostic service tests
go test ./platform/mcp/diagnostics/... -v         # HTTP adapter and profile-store tests
(cd diagnostics && go test ./...)                 # Service-side instrumentation module

Licença

A permissão é concedida, gratuitamente, a qualquer pessoa que obtenha uma cópia deste software e dos arquivos de documentação associados (o "Software"), para lidar com o Software sem restrição, incluindo, sem limitação, os direitos de usar, copiar, modificar, mesclar, publicar, distribuir, sublicenciar e/ou vender cópias do Software, e permitir que as pessoas a quem o Software é fornecido façam o mesmo, sujeito às seguintes condições:

O aviso de direitos autorais acima e este aviso de permissão devem ser incluídos em todas as cópias ou partes substanciais do Software.

O SOFTWARE É FORNECIDO "COMO ESTÁ", SEM GARANTIA DE QUALQUER TIPO, EXPRESSA OU IMPLÍCITA, INCLUINDO, MAS NÃO SE LIMITANDO ÀS GARANTIAS DE COMERCIALIZAÇÃO, ADEQUAÇÃO A UM FIM ESPECÍFICO E NÃO VIOLAÇÃO. EM NENHUM CASO OS AUTORES OU DETENTORES DE DIREITOS AUTORAIS SERÃO RESPONSÁVEIS POR QUALQUER RECLAMAÇÃO, DANOS OU OUTRA RESPONSABILIDADE, SEJA EM AÇÃO DE CONTRATO, ATO ILÍCITO OU OUTRA FORMA, DECORRENTE DE, FORA DE OU EM CONEXÃO COM O SOFTWARE OU O USO OU OUTRAS NEGOCIAÇÕES NO SOFTWARE.