mcp-argocd 0.1.0__tar.gz

mcp_argocd-0.1.0/.env.example

@@ -0,0 +1,16 @@
+# Argo CD base URL, including any path prefix (required)
+ARGOCD_URL=https://argocd.example.com
+
+# Bearer token (required) — any of these work, checked in this order:
+# - ARGOCD_TOKEN
+# - ARGOCD_AUTH_TOKEN (the argocd CLI's name)
+# - ARGOCD_API_TOKEN (the official server's name)
+# Generate one: argocd account generate-token --account <name> --expires-in 24h
+ARGOCD_TOKEN=
+
+# Optional settings
+# ARGOCD_READ_ONLY=false
+# ARGOCD_TIMEOUT=30
+# ARGOCD_SSL_VERIFY=true
+# ARGOCD_INSECURE=false
+# ARGOCD_APP_NAMESPACE=

mcp_argocd-0.1.0/.github/dependabot.yml

@@ -0,0 +1,24 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 10
+    labels:
+      - dependencies
+    commit-message:
+      prefix: "chore(deps)"
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - dependencies
+      - ci
+    commit-message:
+      prefix: "chore(ci)"

mcp_argocd-0.1.0/.github/workflows/link-check.yml

@@ -0,0 +1,23 @@
+name: Link check
+
+# Documentation links are checked on a schedule rather than per-push. They
+# assert on third-party availability, so a transient failure at pypi.org or
+# shields.io says nothing about the commit that triggered it -- it only reddens
+# an unrelated PR. Weekly is often enough to catch real rot, and a failure here
+# is information rather than a merge blocker.
+on:
+  schedule:
+    - cron: "0 6 * * 1" # Mondays, 06:00 UTC
+  workflow_dispatch:
+
+jobs:
+  links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+      - run: uv sync --all-extras
+      # -m network selects exactly what the default run excludes.
+      - run: uv run pytest -m network tests/test_links.py

mcp_argocd-0.1.0/.github/workflows/lint.yml

@@ -0,0 +1,11 @@
+name: Lint
+on: [push, pull_request]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .

mcp_argocd-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-n-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          files: dist/*
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install mcp-publisher
+        run: |
+          curl -sL https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_linux_amd64.tar.gz | tar xz -C /usr/local/bin mcp-publisher
+          mcp-publisher --help
+
+      - name: Publish to MCP Registry
+        run: |
+          mcp-publisher login github-oidc
+          mcp-publisher publish

mcp_argocd-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,308 @@
+name: Semantic Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Version bump type (ignored if version is set)"
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+      version:
+        description: "Explicit version (e.g. 0.7.0) — overrides bump"
+        required: false
+        type: string
+        default: ""
+      dry_run:
+        description: "Dry run (no tag/push)"
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Get current version
+        id: current
+        run: |
+          version=$(grep '^version' pyproject.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "Current version: $version"
+
+      - name: Compute next version
+        id: next
+        run: |
+          if [ -n "${{ inputs.version }}" ]; then
+            version="${{ inputs.version }}"
+            echo "Explicit version: $version"
+          else
+            IFS='.' read -r major minor patch <<< "${{ steps.current.outputs.version }}"
+            case "${{ inputs.bump }}" in
+              major) major=$((major + 1)); minor=0; patch=0 ;;
+              minor) minor=$((minor + 1)); patch=0 ;;
+              patch) patch=$((patch + 1)) ;;
+            esac
+            version="$major.$minor.$patch"
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "Next version: $version"
+
+      - name: Update pyproject.toml version
+        run: |
+          sed -i "s/^version = \".*\"/version = \"${{ steps.next.outputs.version }}\"/" pyproject.toml
+          cat pyproject.toml | grep '^version'
+
+      - name: Update llms-full.txt version
+        run: |
+          for f in llms-full.txt; do
+            [ -f "$f" ] && sed -i 's/^- \*\*Version\*\*: .*/- **Version**: ${{ steps.next.outputs.version }}/' "$f"
+          done
+
+      - name: Update server.json version
+        env:
+          NEXT_VERSION: ${{ steps.next.outputs.version }}
+        run: |
+          python3 - <<'PY'
+          import json
+          import os
+
+          version = os.environ["NEXT_VERSION"]
+
+          with open("server.json") as f:
+              data = json.load(f)
+          data["version"] = version
+          for pkg in data.get("packages", []):
+              pkg["version"] = version
+          with open("server.json", "w") as f:
+              json.dump(data, f, indent=2)
+              f.write("\n")
+          PY
+
+      - name: Derive gemini-extension.json and llms.txt
+        run: python scripts/derive_artifacts.py
+
+      - name: Regenerate uv.lock
+        run: uv lock
+
+      - name: Generate CHANGELOG.md
+        id: changelog
+        env:
+          NEXT_VERSION: ${{ steps.next.outputs.version }}
+        run: |
+          # Find previous tag
+          PREV_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+          if [ -z "$PREV_TAG" ]; then
+            RANGE="HEAD"
+          else
+            RANGE="${PREV_TAG}..HEAD"
+          fi
+
+          DATE=$(date -u +%Y-%m-%d)
+          ENTRY="## [${NEXT_VERSION}] - ${DATE}"$'\n'
+
+          # Collect commits grouped by type
+          # Classify on the SUBJECT only. `git log --grep` matches the whole
+          # commit message, so a wrapped body line beginning "test ..." filed the
+          # same commit under both "Bug Fixes" and "Tests".
+          ALL_COMMITS=$(git log "$RANGE" --pretty=format:"%s|%h" 2>/dev/null || true)
+          for type_label in "feat:Features" "fix:Bug Fixes" "refactor:Refactoring" "docs:Documentation" "perf:Performance" "test:Tests" "chore:Chores"; do
+            type="${type_label%%:*}"
+            label="${type_label#*:}"
+            commits=$(printf '%s\n' "$ALL_COMMITS" \
+              | { grep -E "^${type}(\(.*\))?!?:" || true; } \
+              | while IFS='|' read -r msg hash; do printf -- "- %s (%s)\n" "$msg" "$hash"; done)
+            if [ -n "$commits" ]; then
+              ENTRY+=$'\n'"### ${label}"$'\n'
+              ENTRY+="${commits}"$'\n'
+            fi
+          done
+
+          # Collect commits that don't match any conventional type
+          other=$(printf '%s\n' "$ALL_COMMITS" \
+            | { grep -v -E "^(feat|fix|refactor|docs|perf|test|chore)(\(.*\))?!?:" || true; } \
+            | while IFS='|' read -r msg hash; do
+                if [ -n "$msg" ]; then printf -- "- %s (%s)\n" "$msg" "$hash"; fi
+              done)
+          if [ -n "$other" ]; then
+            ENTRY+=$'\n'"### Other"$'\n'
+            ENTRY+="${other}"$'\n'
+          fi
+
+          # Prepend to existing CHANGELOG.md or create new
+          if [ -f CHANGELOG.md ]; then
+            # Insert new entry after the first line (# Changelog header)
+            {
+              head -1 CHANGELOG.md
+              echo ""
+              echo "$ENTRY"
+              tail -n +2 CHANGELOG.md
+            } > CHANGELOG.tmp
+            mv CHANGELOG.tmp CHANGELOG.md
+          else
+            {
+              echo "# Changelog"
+              echo ""
+              echo "$ENTRY"
+            } > CHANGELOG.md
+          fi
+
+          # Save entry for summary display
+          echo "$ENTRY" > /tmp/changelog-entry.txt
+          echo "Generated CHANGELOG.md entry for v${NEXT_VERSION}"
+
+      - name: Verify build
+        run: uv build
+
+      - name: Create release commit and tag via API
+        if: ${{ !inputs.dry_run }}
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_PAT }}
+          NEXT_VERSION: ${{ steps.next.outputs.version }}
+        run: |
+          MAIN_SHA=$(gh api repos/${{ github.repository }}/git/ref/heads/main --jq '.object.sha')
+          BASE_TREE=$(gh api repos/${{ github.repository }}/git/commits/$MAIN_SHA --jq '.tree.sha')
+
+          # Create blobs for all modified files (use temp files to avoid ARG_MAX limits on large files)
+          create_blob() {
+            local file="$1"
+            base64 -w 0 "$file" > /tmp/b64content.txt
+            jq -Rs '{"encoding":"base64","content":rtrimstr("\n")}' /tmp/b64content.txt > /tmp/blob.json
+            gh api repos/${{ github.repository }}/git/blobs \
+              -X POST --input /tmp/blob.json --jq '.sha'
+          }
+
+          PYPROJECT_BLOB=$(create_blob pyproject.toml)
+          UVLOCK_BLOB=$(create_blob uv.lock)
+          CHANGELOG_BLOB=$(create_blob CHANGELOG.md)
+          LLMS_BLOB=$(create_blob llms.txt)
+          LLMS_FULL_BLOB=$(create_blob llms-full.txt)
+          SERVER_BLOB=$(create_blob server.json)
+          GEMINI_BLOB=$(create_blob gemini-extension.json)
+
+          # Create tree with all release files
+          NEW_TREE=$(gh api repos/${{ github.repository }}/git/trees \
+            -X POST \
+            --input - <<EOF | jq -r '.sha'
+          {
+            "base_tree": "$BASE_TREE",
+            "tree": [
+              {
+                "path": "pyproject.toml",
+                "mode": "100644",
+                "type": "blob",
+                "sha": "$PYPROJECT_BLOB"
+              },
+              {
+                "path": "uv.lock",
+                "mode": "100644",
+                "type": "blob",
+                "sha": "$UVLOCK_BLOB"
+              },
+              {
+                "path": "CHANGELOG.md",
+                "mode": "100644",
+                "type": "blob",
+                "sha": "$CHANGELOG_BLOB"
+              },
+              {
+                "path": "llms.txt",
+                "mode": "100644",
+                "type": "blob",
+                "sha": "$LLMS_BLOB"
+              },
+              {
+                "path": "llms-full.txt",
+                "mode": "100644",
+                "type": "blob",
+                "sha": "$LLMS_FULL_BLOB"
+              },
+              {
+                "path": "server.json",
+                "mode": "100644",
+                "type": "blob",
+                "sha": "$SERVER_BLOB"
+              },
+              {
+                "path": "gemini-extension.json",
+                "mode": "100644",
+                "type": "blob",
+                "sha": "$GEMINI_BLOB"
+              }
+            ]
+          }
+          EOF
+          )
+
+          # Create the commit
+          COMMIT_SHA=$(gh api repos/${{ github.repository }}/git/commits \
+            -X POST \
+            --input - <<EOF | jq -r '.sha'
+          {
+            "message": "chore(release): $NEXT_VERSION",
+            "tree": "$NEW_TREE",
+            "parents": ["$MAIN_SHA"],
+            "author": {
+              "name": "github-actions[bot]",
+              "email": "github-actions[bot]@users.noreply.github.com"
+            }
+          }
+          EOF
+          )
+
+          # Update main to point to the new commit
+          gh api repos/${{ github.repository }}/git/refs/heads/main \
+            -X PATCH \
+            -f sha="$COMMIT_SHA" \
+            -F force=false
+
+          # Create the tag reference
+          gh api repos/${{ github.repository }}/git/refs \
+            -X POST \
+            -f ref="refs/tags/v$NEXT_VERSION" \
+            -f sha="$COMMIT_SHA"
+
+          echo "Created commit $COMMIT_SHA and tag v$NEXT_VERSION"
+
+      - name: Dry run summary
+        if: ${{ inputs.dry_run }}
+        run: |
+          echo "## Dry Run Summary" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Current: ${{ steps.current.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Next: ${{ steps.next.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Bump: ${{ inputs.bump }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- No changes pushed." >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "### Changelog Preview" >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          cat /tmp/changelog-entry.txt >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Release summary
+        if: ${{ !inputs.dry_run }}
+        run: |
+          echo "## Release v${{ steps.next.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Tag pushed. Publish workflow will deploy to PyPI." >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "### Changelog Entry" >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          cat /tmp/changelog-entry.txt >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"

mcp_argocd-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,21 @@
+name: Tests
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --all-extras
+      - run: uv run pytest --cov --cov-report=xml --cov-fail-under=98
+      - name: Upload coverage
+        if: matrix.python-version == '3.13'
+        uses: codecov/codecov-action@v7
+        with:
+          file: coverage.xml
+        continue-on-error: true

mcp_argocd-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+.venv/
+venv/
+env/
+.env
+.env.local
+*.log
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.tox/
+.nox/
+.hypothesis/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.iml
+.claude/
+.cursorrules
+.cursor/
+
+# 1Password shell-plugin config: local tool state, not project config.
+.op/
+
+# Internal ticket tracker and spec; never committed.
+.internal/

mcp_argocd-0.1.0/AGENTS.md

@@ -0,0 +1,181 @@
+# mcp-argocd — Agent Context
+
+MCP server exposing 37 tools, 7 resources, and 7 prompts over the Argo CD REST API. Read-mostly
+operations for Argo CD 3.x: application status, sync, rollback, drift, logs, ApplicationSets,
+clusters, projects, and repositories. Needs an API token; no cluster access.
+
+## Protocol Support
+
+Supports the MCP 2026-07-28 specification (MCP 2.0) and stays compatible with 2025-11-25 clients.
+Built on FastMCP 4.x and the MCP Python SDK 2.x. Verified over `stdio` and `streamable-http`.
+
+Transports: `stdio` (default), `streamable-http` (recommended for remote), and `sse`. The
+2026-07-28 specification deprecates `sse`, so the server prints a warning when you use it. The
+server uses no roots, sampling, logging, elicitation, or resource subscriptions, so the 2026-07-28
+deprecations do not affect it.
+
+## Architecture
+
+- **Entry point**: `src/mcp_argocd/__init__.py` — click CLI, loads `.env`, runs the FastMCP server
+- **Client**: `src/mcp_argocd/client.py` — async httpx client; path-prefix-safe `{url}/api/v1` base with `/api/version` requested absolutely; grpc-gateway error mapping; `stream_lines` for logs
+- **Tools**: `src/mcp_argocd/servers/argocd.py` — all 37 FastMCP tool registrations and the `_slim_*` functions
+- **Resources**: `src/mcp_argocd/servers/resources.py` — 7 MCP resources (4 `resource://rules/*`, 3 `resource://guides/*`), content in `src/mcp_argocd/resources/*.md`
+- **Prompts**: `src/mcp_argocd/servers/prompts.py` — 7 MCP prompts (multi-tool workflows)
+- **Helpers**: `src/mcp_argocd/servers/_helpers.py` — file loader with traversal guard, `_scrub` over one `SECRET_KEYS` tuple, `_page`, `_split_app_name`, `_parse_resource_selector`, `_truncate`, `_terminal`
+- **Config**: `src/mcp_argocd/config.py` — `ArgoCDConfig` built from env vars
+- **Exceptions**: `src/mcp_argocd/exceptions.py` — `ArgoCDError` base; `ArgoCDApiError` (with `grpc_code`), `ArgoCDAuthError`, `ArgoCDNotFoundError`, `ArgoCDConflictError`, `ArgoCDWriteDisabledError`, `ArgoCDTimeoutError`
+- **Tests**: `tests/` — `unit/test_tools.py`, `test_tool_contract.py`, `test_client.py`, `test_config.py`, `test_exceptions.py`, `test_helpers.py`, `test_server_assembly.py`, `test_resources.py`, `test_prompts.py`, `test_doc_parity.py`, `test_derived_artifacts.py`, plus `tests/test_links.py`. Fixtures in `tests/fixtures/` and shared fixtures in `tests/conftest.py`
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest --cov
+uv run ruff check .
+uv run ruff format --check .   # CI runs --check; formatting drift fails the build
+```
+
+`pytest` uses `asyncio_mode = "auto"` — async tests need no marker. Ruff line length is 100,
+target py310; lint rules include `S` (bandit), `EM`, `N`, `UP`. `tests/**` waives `S101`,
+`S105`, `S106`.
+
+## Patterns
+
+- All tools are `async def` returning JSON strings
+- `_ok(data)` for success, `_err(e)` for failure, `_paginated(items, total, has_more, next_offset)` for lists; `_ok_scrubbed` for repository/cluster/project payloads
+- `_slim_*` functions trim each payload type; `get_*` tools expose `full=True` for the raw payload
+- Write access control: `@tool_result(write=True)` runs `_check_write(ctx)`, which raises `ArgoCDWriteDisabledError` when `ARGOCD_READ_ONLY=true`
+- Client-side paging: Argo CD list endpoints take no paging parameters, so the server fetches once, filters, sorts by name, and slices
+- `namespace/name` handling: `_split_app_name` splits apps-in-any-namespace names into `name` + `appNamespace`
+- Tags: every tool tagged `{"argocd", "<category>", "read"|"write"}`
+- Parameters use `Annotated[type, Field(description=...)]`; `Literal[...]` for closed sets
+
+## MCP Compliance Rules
+
+### Tool annotations (mandatory)
+Every tool MUST have `annotations={}` with at minimum `readOnlyHint`.
+- Read tools: `annotations={"readOnlyHint": True, "idempotentHint": True, "openWorldHint": True}`
+- Non-destructive writes: `destructiveHint: False`, `readOnlyHint: False`
+- Destructive writes: `destructiveHint: True`, `readOnlyHint: False`
+- Idempotent writes: add `idempotentHint: True`
+
+### Tool descriptions
+1-2 sentences. Front-load what it does AND what it returns.
+
+### Error handling
+- Every tool wraps in `@tool_result`; expected `ArgoCDError` failures become the `_err` JSON envelope, anything else surfaces as a `ToolError` with a logged traceback.
+- Error text MUST be actionable: what went wrong plus a suggested fix.
+- Never expose the token, stack traces, or request headers.
+
+### Parameter design
+- `Annotated[type, Field(description="...")]` on every parameter; a default on every optional.
+- `Literal[...]` for known value sets; flatten — no nested dicts unless necessary.
+
+### Read-only mode
+Every write tool MUST call `_check_write(ctx)` (via `@tool_result(write=True)`) before any mutation.
+
+## Naming verbs
+
+`list`, `get`, `sync`, `rollback`, `terminate`, `create`, `patch`, `delete`, `run`, `invalidate`,
+`generate`, `wait`, `can`.
+
+## Tool Categories (37)
+
+| Category | Count | Operations |
+|---|---|---|
+| Applications — read | 14 | list, get, resource-tree, managed-resources, resource, manifests, events, logs, history, revision-metadata, operation, wait, sync-windows, resource-actions |
+| Applications — write | 8 | sync, rollback, terminate, create, patch, delete, run action, delete resource |
+| ApplicationSets | 3 | list, get, generate (dry-run) |
+| Projects | 2 | list, get |
+| Clusters | 3 | list, get, invalidate cache |
+| Repositories | 3 | list, refs, apps |
+| Server and account | 4 | version, userinfo, can-i, settings |
+
+## Common Workflows
+
+- **Status triage**: `argocd_get_application` → `argocd_get_resource_tree` → `argocd_get_application_events` → `argocd_get_pod_logs`
+- **Diagnose sync failure**: `argocd_get_operation` → `argocd_get_application_events` → `argocd_get_managed_resources`
+- **Review drift**: `argocd_list_applications(sync_status=OutOfSync)` → `argocd_get_managed_resources`
+- **Safe sync**: `argocd_get_sync_windows` → `argocd_sync_application(dry_run=True)` → `argocd_sync_application(wait=True)` → `argocd_get_application`
+- **Rollback**: `argocd_get_application_history` → `argocd_get_revision_metadata` → `argocd_rollback_application(wait=True)`
+- **Fleet status**: `argocd_list_clusters` → `argocd_list_applications`
+- **Inspect ApplicationSet**: `argocd_get_applicationset` → `argocd_generate_applicationset`
+
+## Prompts
+
+Prompt content lives as `.md` files in `src/mcp_argocd/resources/prompts/`. `servers/prompts.py`
+loads each via `string.Template.safe_substitute` and registers it with `@mcp.prompt()`. Each
+returns a user message (workflow template) plus an assistant acknowledgment.
+
+| Prompt | Purpose | Tags |
+|---|---|---|
+| `triage_application` | Diagnose a Degraded/OutOfSync app | argocd, triage |
+| `diagnose_sync_failure` | Classify a sync failure | argocd, sync |
+| `review_drift` | Review OutOfSync apps and diffs | argocd, drift |
+| `safe_sync` | Dry-run then sync and wait | argocd, sync |
+| `rollback_application` | Roll back with the auto-sync check | argocd, rollback |
+| `fleet_status` | Cluster and app health across a fleet | argocd, fleet |
+| `inspect_applicationset` | Compare generated vs existing apps | argocd, applicationset |
+
+## Environment Variables
+
+| Variable | Required | Default | Notes |
+|---|---|---|---|
+| `ARGOCD_URL` | yes | — | Base URL including any path prefix; trailing slash stripped; `/api/v1` appended. Falls back to `ARGOCD_SERVER` |
+| `ARGOCD_TOKEN` | yes | — | Bearer token; also reads `ARGOCD_AUTH_TOKEN`, `ARGOCD_API_TOKEN` |
+| `ARGOCD_READ_ONLY` | no | `false` | `true`/`1`/`yes` blocks the 9 write tools before any API call |
+| `ARGOCD_TIMEOUT` | no | `30` | Request timeout in seconds |
+| `ARGOCD_SSL_VERIFY` | no | `true` | `false`/`0`/`no` skips verification; `ARGOCD_INSECURE=true` is an alias |
+| `ARGOCD_APP_NAMESPACE` | no | — | Default `appNamespace` for apps-in-any-namespace installs |
+
+CLI flags override env: `--argocd-url`, `--argocd-token`, `--read-only`, `--insecure`, plus
+`--transport {stdio,sse,streamable-http}` with `--host` and `--port` for non-stdio transports.
+
+## Release Workflow
+
+Releases run through GitHub Actions — never bump versions manually.
+
+```bash
+gh workflow run release.yml -f version=0.1.0
+gh workflow run release.yml -f bump=minor -f dry_run=true  # preview changelog, no push
+```
+
+1. `release.yml` (workflow_dispatch) — bumps the version in `pyproject.toml`, `llms-full.txt`,
+   `server.json`; runs `scripts/derive_artifacts.py`; regenerates `uv.lock`; prepends a CHANGELOG
+   entry; creates the release commit and tag via the GitHub API with `RELEASE_PAT`.
+2. `publish.yml` (on a `v*` tag) — builds the wheel, publishes to PyPI (trusted publishing,
+   environment `pypi`), creates the GitHub Release, then publishes to the MCP Registry.
+
+Rules: never edit the `pyproject.toml` version directly; never create tags manually; use
+Conventional Commits (`feat:`, `fix:`, `docs:`, …).
+
+## Documentation Freshness (mandatory)
+
+When a changeset adds, removes, or modifies tools, resources, or prompts, update ALL of these in
+the same commit:
+
+- `README.md` — counts in heading and intro, tool table, full tool reference, usage examples, permissions
+- `llms.txt` — count in tagline and documentation link (derived from `llms-full.txt`)
+- `llms-full.txt` — count in tagline, documentation link, full tool reference
+- `AGENTS.md` — counts in intro, tool category table
+- `server.json` — description field (≤100 chars)
+
+`llms.txt` and `gemini-extension.json` are derived — run `python scripts/derive_artifacts.py`,
+never hand-edit them.
+
+## Known Limitations
+
+- 37 tools in one server file, past the 5-15 guideline. If you refactor it, split by category.
+- Errors come back as successful tool results carrying `{"error": ...}` (soft-error pattern);
+  callers inspect the JSON rather than relying on protocol-level errors.
+- Argo CD list endpoints have no server-side paging, so a very large install pays one full fetch
+  per list call; the server pages the result client-side.
+- Pod logs are capped at 1000 lines.
+
+## Future work
+
+- **OAuth 2.1 / identity passthrough** is out of scope for 0.1.0 (spec decision D6). A design
+  exists at `.internal/specs/2026-10-03-oauth21.md`; when it lands it applies to all four sibling
+  servers at once. Until then, use an API-key account or a project-role token.
+- **Session login** (`ARGOCD_USERNAME`/`ARGOCD_PASSWORD` → `POST /api/v1/session`) is deferred: it
+  works only for local accounts with the `login` capability, never SSO, and tokens expire in 24h.