Skip to content

talkops-ai/argocd-gitops-plugin

v0.4.0Apache-2.0

Agent Plugin bundling the ArgoCD MCP execution server with procedural GitOps skills for deployment, rollback, troubleshooting, and repository/project onboarding.


Architecture: Skill Layer vs. Execution Layer

Version 0.4.0 separates procedural GitOps knowledge from deterministic API execution:

  1. Execution Layer (argocd_mcp_server/):

    • 24 high-signal MCP tools across 4 toolset profiles (applications, deployments, repositories, projects), each with $\le 8$ parameters and full MCP ToolAnnotations.
    • 8 URI-addressed argocd:// resources for zero-side-effect context loading.
    • Non-blocking async HTTP (httpx.AsyncClient) with automatic retry on transient GET failures and model-directed error messages.
    • Safe read-only default (MCP_ALLOW_WRITE=false), dry_run=True defaults on sync_application and rollback_application, and human-in-the-loop confirmation via MCP Elicitation (ctx.elicit()) with a two-step confirm=True fallback.
  2. Skill Layer (skills/ + plugin.json + mcp.json):

    • Packaged as an Agent Plugin v1.0.0 (plugin.json + mcp.json) containing 4 progressive-disclosure Agent Skills (SKILL.md + references/ + stdlib-only scripts/):
      • deploying-argocd-applications
      • rolling-back-argocd-applications
      • troubleshooting-argocd-applications
      • onboarding-argocd-repositories-and-projects
src/argocd-mcp-server/
├── plugin.json                 # Agent Plugin v1.0.0 manifest
├── mcp.json                    # Portable MCP launcher config
├── skills/                     # 4 Progressive-Disclosure Agent Skills
│   ├── deploying-argocd-applications/
│   ├── rolling-back-argocd-applications/
│   ├── troubleshooting-argocd-applications/
│   └── onboarding-argocd-repositories-and-projects/
├── argocd_mcp_server/          # MCP Execution Server (FastMCP + httpx)
│   ├── config.py               # ServerConfig (allow_write=False default, MCP_TOOLSETS)
│   ├── main.py                 # CLI (--transport, --toolsets, --read-only)
│   ├── exceptions/             # Model-directed custom exceptions (401/403/404/409/5xx)
│   ├── server/                 # FastMCP bootstrap & middleware (tool caching disabled)
│   ├── services/               # ArgoCDClient, ArgoCDService, ArgoCDManagementService
│   ├── tools/                  # 24 tools across 4 toolset profiles
│   └── resources/              # 8 argocd:// URI resources
└── tests/                      # 3-Layer Test Suite (Unit, In-Memory MCP, E2E, Skills)

Bundled Agent Skills (skills/)

Skill DirectoryPurposeOffline Scripts (scripts/)Reference Guides (references/)
deploying-argocd-applicationsPre-sync diff validation (get_application_diff), dry-run preview, controlled sync execution, and declarative YAML authoringgenerate_argocd_manifests.pysync-strategies.md
rolling-back-argocd-applicationsInteger history ID resolution, auto-sync blocker detection, preview-first rollback, and recovery verification(uses rollback_application)rollback-edge-cases.md
troubleshooting-argocd-applicationsStructured root-cause diagnosis across OutOfSync, Degraded, Missing, warning events, and pod log streams(uses live diagnostic tools)argocd-error-catalog.md
onboarding-argocd-repositories-and-projectsCredential-isolated HTTPS/SSH/OCI repository onboarding, AppProject RBAC scoping, and safe local token setupfetch_argocd_token.pyrbac-and-credentials.md

Tool Catalog (24 Tools)

1. applications Toolset (7 Tools)

ToolRead-OnlyDestructiveParameters ($\le 8$)Description
list_applicationsYesNocluster, namespace, project, sync_status, health_status, limit, offsetList applications with filtering and pagination
get_application_detailsYesNoapp_name, detail_level ("summary" | "full")Get sync/health status, problem resources, and deployment history with history IDs
get_application_resource_treeYesNoapp_nameGet Kubernetes resource hierarchy (Deployment -> ReplicaSet -> Pod)
get_application_eventsYesNoapp_name, limit, warnings_onlyGet recent Kubernetes events sorted newest first
create_applicationNoNoapp_name, project, repo_url, path, destination_namespace, target_revision, destination_server, sync_policyRegister a new ArgoCD application
update_applicationNoNoapp_name, target_revision, sync_policy, path, destination_namespaceUpdate tracked revision, path, namespace, or sync policy
delete_applicationNoYesapp_name, cascade, confirmDelete an application (gated by MCP Elicitation / confirm=True)

2. deployments Toolset (7 Tools)

ToolRead-OnlyDestructiveParameters ($\le 8$)Description
get_application_diffYesNoapp_name, revision, validateCompare live cluster state vs. target Git manifests and optionally validate via dry-run sync
sync_applicationPreview / WriteConditional (prune=True)app_name, revision, dry_run (True), prune, force, resources, confirmPreview (dry_run=True) or execute (dry_run=False) an application sync
get_sync_statusYesNoapp_nameGet active operation phase, per-resource sync results, and recent history
get_application_logsYesNoapp_name, pod_name, container, tail_lines, since_seconds, errors_onlyFetch and parse ArgoCD NDJSON pod log streams with error extraction
rollback_applicationPreview / WriteYesapp_name, history_id, dry_run (True), prune, confirmPreview or execute a rollback to a deployment history ID with auto-sync blocker detection
refresh_applicationYesNoapp_name, mode ("normal" | "hard")Trigger soft (normal) or manifest-cache-invalidating (hard) refresh
cancel_deploymentNoNoapp_nameTerminate an ongoing sync operation

3. repositories Toolset (5 Tools)

ToolRead-OnlyDestructiveParameters ($\le 8$)Description
list_repositoriesYesNorepo_filterList onboarded Git/Helm/OCI repositories (credentials redacted)
get_repositoryYesNorepo_urlGet repository connection status and metadata (credentials redacted)
validate_repository_connectionYesNorepo_url, insecureValidate connectivity using server-configured Git credentials
onboard_repositoryNoNorepo_url, repo_type, project, enable_lfs, insecure, force_http_basic_authOnboard HTTPS or SSH repository using server-side credentials
delete_repositoryNoYesrepo_url, confirmDelete a registered repository (gated by MCP Elicitation / confirm=True)

4. projects Toolset (5 Tools)

ToolRead-OnlyDestructiveParameters ($\le 8$)Description
list_projectsYesNoname_filterList AppProjects with source repos and destination rules
get_projectYesNoproject_nameGet detailed AppProject RBAC rules and resource restrictions
create_projectNoNoproject_name, description, source_repos, destinations, resource_restrictionsCreate an AppProject with RBAC restrictions
update_projectNoNoproject_name, description, source_repos, destinations, resource_restrictionsUpdate an existing AppProject
delete_projectNoYesproject_name, confirmDelete an AppProject (gated by MCP Elicitation / confirm=True)

Resource Catalog (8 URI-Addressed Resources)

Resource URIDescription
argocd://applicationsCatalog of all ArgoCD applications with sync and health status
argocd://applications/{app_name}Full state, resources, and deployment history for a specific application
argocd://applications/{app_name}/historyDeployment revision history with integer ids for rollback targeting
argocd://applications/{app_name}/resource-treeHierarchical Kubernetes resource tree for an application
argocd://clustersRegistered target Kubernetes clusters with connection state and version
argocd://repositoriesOnboarded Git, Helm, and OCI repositories (credentials redacted)
argocd://projects/{project_name}AppProject RBAC rules, allowed source repositories, and destinations
argocd://healthArgoCD API connectivity, server version, and MCP_ALLOW_WRITE posture

Quick Start & Configuration

Installation

cd src/argocd-mcp-server
uv sync --dev

Environment Variables

VariableDefaultDescription
ARGOCD_SERVER_URLhttps://argocd-server.argocd.svc:443ArgoCD API server URL
ARGOCD_AUTH_TOKENNoneArgoCD Bearer JWT token
ARGOCD_INSECUREfalseSkip TLS verification for self-signed ArgoCD certs
ARGOCD_TIMEOUT300HTTP request timeout in seconds
ARGOCD_MAX_RETRIES2Automatic retries for transient GET failures
MCP_ALLOW_WRITEfalseSafe default: read-only mode (true enables mutating tools)
MCP_TOOLSETSallComma-separated toolsets (all,readonly,applications,deployments,repositories,projects)
MCP_TRANSPORThttpTransport mode (stdio or http)
GIT_USERNAME""Server-side username for HTTPS repository onboarding
GIT_PASSWORDNoneServer-side PAT/token for HTTPS repository onboarding
SSH_PRIVATE_KEY_PATH~/.ssh/id_rsaServer-side SSH private key path for SSH repository onboarding

Running the Server

# Default stdio transport in safe read-only mode
uv run argocd-mcp-server --transport stdio --read-only

# Enable specific toolsets
uv run argocd-mcp-server --transport stdio --toolsets applications,deployments

# Streamable HTTP transport
uv run argocd-mcp-server --transport http

Migration Guide: v0.3.0 -> v0.4.0

v0.3.0 Componentv0.4.0 ReplacementReason
Required cluster_name parameter on per-app toolsRemoved (list_applications retains optional cluster filter; argocd://clusters resource added)ArgoCD REST API identifies applications by app_name; cluster_name was unused in per-app endpoints
rollback_application + rollback_to_revisionConsolidated rollback_application(app_name, history_id=None, dry_run=True, prune=False, confirm=False)Fixes Git-SHA-as-integer-history-ID bug (N2) and detects auto-sync blockers
validate_application_configget_application_diff(app_name, revision=None, validate=True)N-to-1 consolidation: computes live-vs-target diffs and validates via dry-run in one call
onboard_repository_https + onboard_repository_sshonboard_repository(repo_url, repo_type="git", project=None, ...)Infers HTTPS vs. SSH from repo_url and resolves credentials from server env vars
generate_application_manifest + create_applicationset_manifestskills/deploying-argocd-applications/scripts/generate_argocd_manifests.pyPure offline YAML templating moved to deterministic skill script
generate_repository_secret_manifestRemovedSecurity hardening: prevents secret material from entering LLM context (N8)
7 @mcp.prompt() workflows + argocd://workflow4 Agent Skills under skills/Progressive disclosure via Agent Skills Open Spec

Testing & Verification

# Run all 58 Unit, In-Memory FastMCP Integration, E2E Workflow, and Skill Contract tests
uv run pytest tests/ -v --tb=short

# Run static type checking
uv run pyright .