Gaz MCP

Servidor MCP para acceso de solo lectura a MySQL/PostgreSQL, administración de Jenkins y diagnóstico en vivo de procesos Go mediante pprof/expvar. Diseñado para agentes de codificación con IA.

GitHubPrueba este MCPPatrocinado

Documentación

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

gaz-mcp

gaz-mcp es un servidor MCP para acceso de solo lectura a MySQL/PostgreSQL, administración de Jenkins con historial de configuración, generación de imágenes OpenRouter y diagnóstico de procesos Go en ejecución mediante pprof y expvar. También incluye el módulo Go independiente diagnostics para añadir esos endpoints a los servicios de destino.

Utiliza transporte stdio: un solo binario, sin daemon y sin listener abierto por el propio MCP. Los destinos SQL y Jenkins se configuran una sola vez; un destino de diagnóstico Go se proporciona directamente con cada llamada de herramienta.

Capacidades

Capacidad	Propósito	Configuración	Guía completa
SQL	Inspecciona datos de MySQL y PostgreSQL sin escrituras	`environments`	SQL: MySQL and PostgreSQL
Jenkins	Inspecciona y administra CI/CD, incluido el historial de configuración	`jenkins`, `snapshot`	Jenkins
Generación de imágenes	Genera y compara imágenes mediante una lista blanca cerrada de modelos OpenRouter	`image_generation`	Image generation
Diagnóstico de Go	Captura perfiles e inspecciona goroutines, métricas de runtime/proceso/host/cgroup y pools SQL opcionales	URL `target` por llamada	Go process diagnostics

Propiedades compartidas

Servidor MCP stdio — un solo binario, sin daemon, sin puertos de red.
SQL y Jenkins multi-entorno — selecciona el entorno configurado por llamada.
Aplicación de solo lectura en SQL — comprobaciones de la aplicación más sesiones de solo lectura en la base de datos.
Selección dinámica de base de datos — la base de datos pertenece a cada solicitud SQL, no a la configuración estática.
Conjunto de herramientas Jenkins — 33 herramientas para trabajos, builds, nodos, vistas, cola, plugins, credenciales, consola de scripts y snapshots.
Historial de configuración — los snapshots de Jenkins se almacenan en SQLite para las operaciones que admiten captura y reversión.
Deduplicación SHA-256 — los snapshots de configuración consecutivos idénticos no se almacenan dos veces.
Generación de imágenes controlada — elige un modelo de imagen OpenRouter configurado por solicitud, con controles de prompt, referencias de semilla, dimensiones, calidad, formato, semilla y enrutamiento de proveedor.
Diagnóstico de procesos Go — perfiles pprof, pilas de goroutines agrupadas, métricas brutas de runtime/proceso/host/cgroup y una lista separada de sospechas heurísticas respaldadas por evidencia.
Salida JSON estructurada — diseñada para consumo programático.
Configuración YAML — configuración basada en Viper, con renderizado de secretos en tiempo de despliegue.
Arquitectura hexagonal — las capas de dominio, aplicación y plataforma permanecen separadas.

Requisitos

La versión de Go declarada en go.mod (actualmente Go 1.26.0) para compilar desde el código fuente, o un binario precompilado.
Un servidor MySQL/PostgreSQL y/o una instancia de Jenkins accesible desde el host que ejecuta el MCP.

Instalación

Compilar desde el código fuente

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

Binario precompilado

Linux y 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

Variable	Predeterminado
`REPO`	`jcastilloa/gaz-mcp`
`SERVICE_NAME`	`gaz-mcp`
`INSTALL_DIR`	`~/.local/bin`
`VERSION`	Última etiqueta de publicación

Habilidades de agente

Las habilidades de agente orientadas al producto se distribuyen bajo skills/, por separado del .codex/skills utilizado para desarrollar este repositorio:

Habilidad	Capacidad
`gaz-mcp-db`	Inspección de solo lectura de MySQL y PostgreSQL
`gaz-mcp-jenkins`	Operaciones de Jenkins e historial de configuración
`gaz-mcp-diagnostics`	Instrumentación de servicios Go, pprof, expvar, métricas y sospechas de diagnóstico

Instala el directorio completo para cada capacidad habilitada. Por ejemplo, desde un checkout de gaz-mcp, cópialos en un proyecto separado que consuma el 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/"

Consulta el catálogo de habilidades para las rutas de proyecto/global en Claude Code, Codex, OpenCode y Cursor, además del límite entre habilidades de producto y de colaboradores.

Configuración

Crea config.yaml en el directorio de trabajo o en ~/.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 tiene como valor predeterminado mysql cuando se omite. El database de SQL se selecciona mediante la llamada de herramienta, no aquí. Para imágenes, image_model_list devuelve la lista blanca configurada y image_generate selecciona una de sus entradas por llamada. El target de diagnóstico Go tampoco se configura deliberadamente aquí: el llamador proporciona la URL de proceso autorizada para cada solicitud.

Nota de configuración: image_generation.api_key expande ${NAME} desde el entorno del proceso. Mantén todos los demás marcadores de secretos bajo control de configuración en tiempo de despliegue. max_versions se normaliza actualmente al valor predeterminado de 50 cuando se configura como cero u otro valor no positivo, así que usa un valor positivo en YAML.

Seguridad: usa ${OPENROUTER_API_KEY} (u otro mecanismo de secretos en tiempo de despliegue) para image_generation.api_key; se enmascara en la salida JSON. Las herramientas de imagen se registran solo cuando image_generation.models no está vacío, y entonces se requiere una clave API. El api_key de Jenkins acepta un token de API de Jenkins (recomendado, creado en User → Configure → API Token) o una contraseña. Mantén los secretos resueltos fuera del control de versiones y usa configuración restringida en tiempo de despliegue.

Consulta config.sample.yaml para ver el ejemplo completo, incluida la configuración del proveedor OpenAI utilizada por la aplicación.

Inicio rápido

1. Configura

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

2. Ejecuta

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

3. Registra en un cliente MCP

Claude Desktop, Cursor y clientes basados en 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

Sigue las indicaciones: proyecto o global, nombre gaz-mcp, tipo local, luego comando /absolute/path/to/gaz-mcp --transport stdio.

Usa siempre una ruta absoluta al binario y transporte stdio.

Mapa de documentación

El documento raíz contiene instalación, configuración, preparación del cliente, arquitectura y desarrollo. Las referencias operativas completas se encuentran en las guías específicas a continuación; ninguna referencia de herramientas se duplica intencionalmente aquí.

Guía	Incluye
SQL: MySQL and PostgreSQL	Contrato `sql_query`, patrones de descubrimiento de MySQL/PostgreSQL, ambas protecciones de solo lectura y límites de pool
Jenkins	Las 33 herramientas, parámetros exactos, cobertura de snapshots y restauración, destilación de salidas grandes, flujos de trabajo y notas de seguridad
Go process diagnostics	Fragmento `pprof`/`expvar` del lado del servicio, métricas opcionales `database/sql`, las nueve herramientas, hallazgos y flujos de trabajo de perfilado

El módulo del lado del servicio se publica de forma independiente usando etiquetas compatibles con módulos, como diagnostics/v0.1.0; las etiquetas de publicación del servidor MCP (v0.4.x) no son versiones de módulo para github.com/jcastilloa/gaz-mcp/diagnostics.

Para mover los endpoints del servicio de /debug/... a un prefijo personalizado, usa diagnostics.WithBasePath("/internal/diagnostics"); luego pasa http://service:6060/internal/diagnostics como herramienta de diagnóstico target.

Arquitectura

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

Regla de dependencia: platform → shared + mcp/application + mcp/domain. Nunca inviertas esa dirección.

Desarrollo

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

Licencia

Por la presente se concede permiso, de forma gratuita, a cualquier persona que obtenga una copia de este software y de los archivos de documentación asociados (el "Software"), para tratar con el Software sin restricción, incluidos, sin limitación, los derechos de usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del Software, y para permitir que las personas a las que se les proporcione el Software hagan lo mismo, sujeto a las siguientes condiciones:

El aviso de copyright anterior y este aviso de permiso se incluirán en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUIDAS, ENTRE OTRAS, LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN FIN PARTICULAR Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE CUALQUIER RECLAMO, DAÑO U OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O DE OTRO MODO, QUE SURJA DE, O EN RELACIÓN CON, EL SOFTWARE O EL USO U OTROS TRATOS EN EL SOFTWARE.