zadig-mcp

Basic MCP server for Zadig OpenAPI.

Version target

This tool targets StoreHub's Zadig 4.3 deployment. API behavior should be checked against the live zadigx.shub.us instance and Zadig release-4.3.0 source when public documentation is incomplete.

Related MCP server: Dify Management MCP

Tools

• zadig_workflow_list: list/search project workflows.

• zadig_workflow_get: get one custom workflow detail.

• zadig_workflow_create: create one custom workflow. Defaults to dry run and requires confirm=true.

• zadig_workflow_update: update one custom workflow. Defaults to dry run and requires confirm=true.

• zadig_workflow_delete: delete one custom workflow. Defaults to dry run and requires confirm=true.

• zadig_workflow_diff: diff current workflow detail against a desired workflow payload.

• zadig_workflow_apply: create or update one workflow. Defaults to dry run and requires confirm=true.

• zadig_project_snapshot: create a redacted project snapshot for audit/GitOps preparation.

• zadig_workflow_task_list: list workflow tasks with deployment summaries.

• zadig_workflow_task_detail: get one workflow task detail with deployment summaries.

• zadig_workflow_task_job_log: get one workflow task job log, with tail and keyword filtering.

• zadig_test_list / zadig_test_get: list or inspect test configurations, including full detail fields with sensitive values redacted.

• zadig_test_create / zadig_test_update / zadig_test_delete: manage test configurations through Zadig's internal testing API, dry-run by default.

• zadig_test_diff / zadig_test_apply: compare or create/update a test configuration with explicit confirmation for writes.

• zadig_workflow_webhook_list: list saved webhook/git trigger settings for a workflow.

• zadig_workflow_webhook_preset: get current webhook/git trigger preset for a workflow.

• zadig_workflow_webhook_compare_to_preset: compare saved webhook/git trigger settings with the current preset.

• zadig_build_list: list/search build configurations.

• zadig_build_template_list: list/search build template store templates.

• zadig_build_template_get: get one build template store template by id or exact name.

• zadig_build_template_reference: list build configurations that reference one build template.

• zadig_build_template_create: create one build template store template. Defaults to dry run and requires confirm=true.

• zadig_build_template_update: update one build template store template. Defaults to dry run and requires confirm=true.

• zadig_build_template_delete: delete one build template store template. Defaults to dry run and requires confirm=true.

• zadig_build_template_diff: diff current build template detail against a desired payload.

• zadig_build_template_apply: create or update one build template. Defaults to dry run and requires confirm=true.

• zadig_build_get: get one build configuration detail.

• zadig_build_update: update one build configuration. Defaults to dry run and requires confirm=true.

• zadig_build_update_from_template: update a build created from a build template. Defaults to dry run and requires confirm=true.

• zadig_service_search: list/search K8s YAML services.

• zadig_service_get: get service detail, including YAML and variables.

• zadig_service_update_variables: replace service variables. Requires confirm=true.

• zadig_service_set_variable: upsert a single service variable. Defaults to dry run.

• zadig_service_set_image: update a container image in service YAML. Defaults to dry run.

• zadig_environment_list: list test or production environments.

• zadig_environment_get: get one environment detail.

• zadig_environment_create: create one environment. Defaults to dry run and requires confirm=true.

• zadig_environment_update: update one environment registry/global variables. Defaults to dry run and requires confirm=true.

• zadig_environment_delete: delete one environment. Defaults to dry run and requires confirm=true.

• zadig_environment_diff: diff current environment against desired Environment spec.

• zadig_environment_apply: create or update one environment. Defaults to dry run and requires confirm=true.

• zadig_environment_service_list: list services in an environment.

• zadig_environment_service_get: get service detail in an environment.

• zadig_environment_service_apply: add or update one environment service. Defaults to dry run and requires confirm=true.

• zadig_environment_service_delete: delete one environment service. Defaults to dry run and requires confirm=true.

• zadig_code_scan_list: list/search project code scan configurations.

• zadig_code_scan_get: get one code scan by name or ID.

• zadig_code_scan_create: create one code scan. Defaults to dry run and requires confirm=true.

• zadig_code_scan_update: update one code scan. Defaults to dry run and requires confirm=true.

• zadig_code_scan_delete: delete one code scan. Defaults to dry run and requires confirm=true.

• zadig_code_scan_diff: diff a code scan against the live Zadig configuration.

• zadig_code_scan_apply: create or update one code scan. Defaults to dry run and requires confirm=true.

Config

[mcp_servers.zadig]
command = "uv"
args = ["--directory", "/Users/storehub/Desktop/devops-tools-auto/zadig-mcp", "run", "zadig-mcp"]

[mcp_servers.zadig.env]
ZADIG_BASE_URL = "https://zadigx.shub.us"
ZADIG_TOKEN = "replace-me"
ZADIG_PROJECT = "devops-tools"
UV_CACHE_DIR = "/tmp/uv-cache"

ZADIG_PROJECT is optional. Every tool also accepts project_key.

Workflow task tools use Zadig v4 workflow task read APIs and return compact summaries by default. Set include_raw=true only when the caller needs the raw task payload; credential-like fields are recursively redacted before returning.

Development

uv run python -m py_compile zadig_mcp/*.py
uv run zadig-mcp

GitOps preparation

zadig-gitops snapshot exports a redacted project snapshot into a stable YAML file tree that is suitable for Git review and later PR-based change loops.

ZADIG_BASE_URL="https://zadigx.shub.us" \
ZADIG_TOKEN="..." \
uv run zadig-gitops snapshot \
  --project fat \
  --output ./zadig-config

The output layout is:

zadig-config/
  projects/<project>/
    project.yaml
    _snapshot/
      metadata.yaml
      errors.yaml
    iterations/index.yaml
    workflows/index.yaml
    workflows/details/<workflow>.yaml
    webhooks/<workflow>.yaml
    builds/index.yaml
    workflows/index.yaml
    workflows/items/<workflow>.yaml
    workflows/scripts/<workflow>/<stage>.<job>.script.sh
    workflows/scripts/index.yaml
    workflows/triggers/<workflow>.yaml
    workflows/notifications/<workflow>.yaml
    builds/items/<build>.yaml
    builds/scripts/<script>.sh
    builds/scripts/<script>.meta.yaml
    tests/index.yaml
    code-scans/index.yaml
    code-scans/items/<scan>.yaml
    services/index.yaml
    services/items/<service>.yaml
    environments/index.yaml
    releases/index.yaml
  templates/
    build-templates/
      index.yaml
      <template>.<id>.yaml
    helm-charts/
      <chart>/
        Chart.yaml
        values.yaml
        templates/

Project snapshots only include build templates that are actually referenced by that project, and those templates are written under templates/ because Zadig template-library resources are shared resources rather than project-owned resources.

Per-template files under templates/build-templates/ are exported as kind: BuildTemplate documents. Their spec is the desired Zadig template payload; metadata.id keeps the live template ID when known, and metadata.name is used to resolve the template when the ID is absent.

When a build template contains non-empty script fields such as scripts, pre_build.scripts, or post_build.scripts, snapshot-template writes those scripts under templates/build-templates/scripts/<template>/ and replaces the inline value with a *_ref object containing the path and SHA-256 checksum. Template apply expands those refs back into the Zadig template payload after verifying the checksum. This keeps template metadata reviewable while preserving exact scripts as separate files.

_snapshot/errors.yaml is not Zadig configuration. It records snapshot-time API failures or unsupported sections so GitOps reviewers can tell whether an export is complete.

services/index.yaml is an inventory only. Per-service files under services/items/ hold the live service detail and a GitOps-oriented spec section that later service CRUD apply commands can use.

builds/index.yaml is also an inventory only. Per-build files under builds/items/ hold the live build detail and a GitOps-oriented spec. When a build has a build_script, snapshot writes the script under projects/<project>/builds/scripts/ and replaces the inline script with spec.build_script_ref. Multiple builds with identical scripts share one script file and the matching .meta.yaml lists the used_by impact set. Build apply expands the script ref back into the Zadig build_script payload after checking the optional SHA-256 checksum.

project.yaml is the top-level project document exported from live Zadig project metadata. It is currently read-only snapshot data plus a small GitOps-oriented spec.

code-scans/index.yaml is an inventory only. Each scan configuration is stored under code-scans/items/<scan>.yaml as a kind: CodeScan document. The configuration is under spec; server-generated IDs, timestamps, and runtime statistics are retained under live and are excluded from the desired state.

The GitOps CLI supports code scan CRUD with the same dry-run-first behavior as other project resources:

zadig-gitops apply code-scan \
  --project mobile \
  --dir ./zadig-config/projects/mobile/code-scans

zadig-gitops apply code-scan \
  --project mobile \
  --code-scan sonarqube-test \
  --diff

zadig-gitops apply code-scan \
  --project mobile \
  --code-scan sonarqube-test \
  --mode delete \
  --confirm

Workflow snapshots are split for reviewability:

• workflows/items/<workflow>.yaml stores the main kind: Workflow desired state.

• workflows/scripts/<workflow>/*.sh stores long job scripts referenced by script_ref with a SHA-256 checksum.

• workflows/triggers/<workflow>.yaml stores kind: WorkflowTriggers under the workflow namespace.

• workflows/notifications/<workflow>.yaml stores kind: WorkflowNotifications.

Workflow apply expands script_ref and notifications_ref back into the Zadig workflow payload. Trigger apply is intentionally separate so webhook drift can be reviewed without mixing it into stage/job changes.

Environment snapshots are split for future CRUD support:

projects/<project>/environments/
  index.yaml
  items/
    <env>.yaml
  services/
    <env>/
      index.yaml
      <service>.yaml

items/<env>.yaml is a kind: Environment document for cluster, namespace, registry, global variables, and a services_ref. Environment service placement is exported separately as kind: EnvironmentService files under services/<env>/, so changing the environment and changing service deployment state remain reviewable as separate diffs.

For a smaller export:

uv run zadig-gitops snapshot \
  --project fat \
  --section workflows \
  --section workflow_details \
  --section webhooks \
  --workflow fat-pipelines \
  --output ./zadig-config

Export the shared build-template library independently from project snapshots:

uv run zadig-gitops snapshot-template \
  --output ./zadig-config

Export one template by name or id:

uv run zadig-gitops snapshot-template \
  --template fat-build \
  --output ./zadig-config

Snapshot output is redacted by default. Credential-like fields and variables marked with is_credential=true are written as ***redacted***.

Apply a workflow from YAML. This is a dry-run unless --confirm is set.

uv run zadig-gitops apply \
  --project fat \
  --workflow my-new-workflow \
  --file ./zadig-config/projects/fat/workflows/items/my-new-workflow.yaml

Print only the diff:

uv run zadig-gitops apply \
  --project fat \
  --workflow my-new-workflow \
  --file ./zadig-config/projects/fat/workflows/items/my-new-workflow.yaml \
  --diff

You can omit --file/--dir when using the default config layout:

uv run zadig-gitops apply workflow \
  --project fat \
  --workflow my-new-workflow \
  --diff

Actually create or update the workflow:

uv run zadig-gitops apply \
  --project fat \
  --workflow my-new-workflow \
  --file ./zadig-config/projects/fat/workflows/items/my-new-workflow.yaml \
  --confirm

Real apply rejects files that still contain ***redacted*** placeholders by default. Replace the placeholder values before applying, or pass --allow-redacted only when the target fields are intentionally redacted-safe.

Apply service desired state from per-service YAML files. This is also dry-run unless --confirm is set.

uv run zadig-gitops apply service \
  --project bi \
  --file ./zadig-config/projects/bi/services/items/product-insights.yaml

Apply all service files in a project:

uv run zadig-gitops apply service \
  --project bi \
  --dir ./zadig-config/projects/bi/services

Delete live services that are missing from the desired service directory:

uv run zadig-gitops apply service \
  --project bi \
  --dir ./zadig-config/projects/bi/services \
  --prune \
  --confirm

Service apply currently supports creating Helm chartTemplate services, deleting missing services with --prune, and updating supported mutable fields (spec.yaml and spec.template.variables) when Zadig exposes them.

Apply build desired state from per-build YAML files. This is dry-run unless --confirm is set.

uv run zadig-gitops apply build \
  --project bi \
  --file ./zadig-config/projects/bi/builds/items/bi-build.yaml

Build update defaults to --build-update-api auto: it first tries Zadig's OpenAPI and falls back to the UI-compatible build API when the live instance requires UI-only fields such as codehost_id. The fallback loads the live build detail, preserves repository/codehost/target fields, and maps only supported desired fields such as build_script, post_build, outputs, and timeout. Use --build-update-api ui to force that path for known script-only updates.

Apply all build files in a project:

uv run zadig-gitops apply build \
  --project bi \
  --dir ./zadig-config/projects/bi/builds

Delete live builds that are missing from the desired build directory:

uv run zadig-gitops apply build \
  --project bi \
  --dir ./zadig-config/projects/bi/builds \
  --prune \
  --confirm

Apply build template desired state from templates/build-templates. This is dry-run unless --confirm is set.

uv run zadig-gitops apply template \
  --project fat \
  --file ./zadig-config/templates/build-templates/fat-build.<id>.yaml

Print only the template diff:

uv run zadig-gitops apply template \
  --project fat \
  --file ./zadig-config/templates/build-templates/fat-build.<id>.yaml \
  --diff

Delete a build template explicitly by name or id:

uv run zadig-gitops apply template \
  --project fat \
  --template fat-build \
  --mode delete

Template prune is intentionally unsupported because build templates are shared library resources and the blast radius can cross projects. Delete templates one at a time after checking references.

Apply environment desired state from projects/<project>/environments. This is dry-run unless --confirm is set. Environment apply manages the environment object itself, including registry and global variables; deployed services are handled by environment-service.

uv run zadig-gitops apply environment \
  --project bi \
  --file ./zadig-config/projects/bi/environments/items/fat.yaml

Print only the environment diff:

uv run zadig-gitops apply environment \
  --project bi \
  --file ./zadig-config/projects/bi/environments/items/fat.yaml \
  --diff

Delete an environment explicitly. By default this only deletes the Zadig environment record where supported; add --delete-resources only when the underlying Kubernetes namespace/resources should also be removed.

uv run zadig-gitops apply environment \
  --project bi \
  --environment fat \
  --mode delete

Apply services deployed inside an environment:

uv run zadig-gitops apply environment-service \
  --project bi \
  --environment fat \
  --dir ./zadig-config/projects/bi/environments/services/fat

Delete one service from an environment. By default not_delete_resource=true; add --delete-resources to ask Zadig to delete underlying Kubernetes resources.

uv run zadig-gitops apply environment-service \
  --project bi \
  --environment fat \
  --service csp-v1-web-fe \
  --mode delete

Apply test configurations from projects/<project>/tests/items. The test configuration API is an internal Zadig endpoint, so keep the snapshot and apply version aligned with the deployed Zadig release. Writes are dry-run by default and require --confirm.

uv run zadig-gitops apply test \
  --project mobile \
  --dir ./zadig-config/projects/mobile/tests \
  --diff

uv run zadig-gitops apply test \
  --project mobile \
  --dir ./zadig-config/projects/mobile/tests \
  --confirm

Plan project changes from project.yaml. Project apply is intentionally plan-only for now: create/update/delete modes only compare desired config with live Zadig state and never call mutating project APIs, even when --confirm is passed.

uv run zadig-gitops apply project \
  --project bi \
  --dir ./zadig-config/projects/bi

uv run zadig-gitops apply project \
  --project bi \
  --mode delete