feat: ApplicationSet support to the MCP server

[rishabh625]

Add Full ArgoCD ApplicationSet Support

Summary

This change adds full ArgoCD ApplicationSet support to the MCP server, covering:

Test video is shared at the end of Description

• Listing ApplicationSets
• Fetching ApplicationSets
• Generating (dry-run) ApplicationSets
• Previewing ApplicationSets
• Creating ApplicationSets (read/write mode only)
• Updating ApplicationSets (read/write mode only)
• Deleting ApplicationSets (read/write mode only)

Previously, the MCP server only supported standalone Application resources. ApplicationSets—the controller-based mechanism for templating multiple Applications from generators such as list, git, cluster, matrix, etc.—had no representation, preventing callers from inspecting or managing them.

---

Fixes #82
Closes #135

Changes

ArgoCDClient

Added new client methods that mirror the existing Application APIs.

List ApplicationSets

listApplicationSets(params)

• GET /api/v1/applicationsets
• Supports offset/limit pagination
• Returns only:
  • metadata
  • spec
  • status

---

Get ApplicationSet

getApplicationSet(appSetName, appsetNamespace?)

• GET /api/v1/applicationsets/{name}

---

Create ApplicationSet

createApplicationSet(appSet)

• POST /api/v1/applicationsets

---

Update ApplicationSet

updateApplicationSet(appSet, options?)

• POST /api/v1/applicationsets
• Always sends:

upsert=true

to match ArgoCD API semantics.

---

Delete ApplicationSet

deleteApplicationSet(appSetName, options?)

• DELETE /api/v1/applicationsets/{name}

Supports:

• cascade
• propagationPolicy

---

Resource Tree

getApplicationSetResourceTree(appSetName, appsetNamespace?)

• GET /api/v1/applicationsets/{name}/resource-tree

---

Generate (Dry Run)

generateApplicationSet(req)

• POST /api/v1/applicationsets/generate

Returns the Applications that would be created from the supplied spec without persisting anything.

---

Type Exports

Added generated types:

• V1alpha1ApplicationSet
• V1alpha1ApplicationSetList
• V1alpha1ApplicationSetTree
• V1alpha1ApplicationSetGenerateRequest
• V1alpha1ApplicationSetGenerateResponse

---

Zod Schema

Added:

ApplicationSetSchema

Strongly Typed

metadata.name
metadata.namespace

Flexible

spec: z.record(z.any())

ApplicationSet specs intentionally remain flexible because different generator types (list, git, matrix, cluster, etc.) have different schemas.

---

MCP Tools

Read-Only Tools

Always registered (even when MCP_READ_ONLY=true).

Tool	Description
list_applicationsets	List ApplicationSets
get_applicationset	Fetch a single ApplicationSet
get_applicationset_resource_tree	Retrieve generated resource tree
generate_applicationset	Dry-run generation
preview_applicationset	Preview an existing ApplicationSet

---

Mutating Tools

Only registered when:

MCP_READ_ONLY=false

Tool	Description
create_applicationset	Create
update_applicationset	Update
delete_applicationset	Delete

---

preview_applicationset

A convenience tool that:

1. Fetches an existing ApplicationSet
2. Calls generateApplicationSet() using its spec

This answers:

"What would this ApplicationSet produce right now?"

without manually reconstructing its specification.

---

Existing MCP Behavior Preserved

All new tools automatically inherit:

• per-call argocdBaseUrl override
• token registry resolution
• addJsonOutputTool
• multi-instance support

No additional implementation work is required.

---

Tests

Added test coverage for:

Tool Registration

Verifies that all five read-only ApplicationSet tools are registered.

---

Token Resolution

Ensures:

list_applicationsets

follows the exact same security model as listApplications.

If an overridden argocdBaseUrl has no matching token in the registry:

• request fails
• default token is never reused

---

Read-Only Mode

Verifies:

When:

MCP_READ_ONLY=true

the following tools are not registered:

• create_applicationset
• update_applicationset
• delete_applicationset

while the five read-only tools remain available.

---

Behavior Notes

• Read/write split exactly matches the existing Application tools.
• Read-only ApplicationSet tools are always available.
• Mutating tools are gated behind MCP_READ_ONLY.
• updateApplicationSet() always sends:

upsert=true

to match ArgoCD API behavior.

Unlike listApplications, which strips most of the Application spec, listApplicationSets intentionally preserves:

• spec
• status.conditions
• status.applicationStatus

because the ApplicationSet specification itself is the primary resource callers need to inspect.

---

Known Gap

README.md has not yet been updated.

Recommended before merge:

Add a new section:

ApplicationSet Management

alongside:

• Applications
• Clusters
• Projects

to document the new MCP tools.

---

Examples

Generate (Dry Run)

Generate the Applications an ApplicationSet would produce without creating anything.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "generate_applicationset",
    "arguments": {
      "applicationSet": {
        "metadata": {
          "name": "guestbook-set",
          "namespace": "argocd"
        },
        "spec": {
          "generators": [
            {
              "list": {
                "elements": [
                  {
                    "cluster": "engineering-dev"
                  },
                  {
                    "cluster": "engineering-prod"
                  }
                ]
              }
            }
          ],
          "template": {
            "metadata": {
              "name": "guestbook-{{cluster}}"
            },
            "spec": {
              "project": "default",
              "source": {
                "repoURL": "https://github.com/argoproj/argocd-example-apps.git",
                "targetRevision": "HEAD",
                "path": "guestbook"
              },
              "destination": {
                "server": "{{cluster}}",
                "namespace": "guestbook"
              }
            }
          }
        }
      }
    }
  }
}

---

Preview an Existing ApplicationSet

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "preview_applicationset",
    "arguments": {
      "applicationSetName": "guestbook-set"
    }
  }
}

---

Testing

Run before merging:

tsc --noEmit

pnpm build

pnpm test

Includes:

• ApplicationSet tool registration
• Read-only mode validation
• Token resolution security tests

pnpm lint

---

Runtime Validation

Verify behavior with:

MCP_READ_ONLY=true

Expected:

Registered:

• list_applicationsets
• get_applicationset
• get_applicationset_resource_tree
• generate_applicationset
• preview_applicationset

Not Registered:

• create_applicationset
• update_applicationset
• delete_applicationset

Tested MCP client using mcp-inspector
https://drive.google.com/file/d/1-GOezvGESTKDIMkCKHo2u7LjOk0mW8Q6/view?usp=sharing

[rishabh625]

@leoluz @pjiang-dev @suryaval

Can you please help with review and share your valuable comments.
To take this change ahead.