# MCP Read-Only Argo CD Server

[![Tests](https://github.com/lukleh/mcp-read-only-argocd/actions/workflows/test.yml/badge.svg)](https://github.com/lukleh/mcp-read-only-argocd/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

A secure MCP (Model Context Protocol) server that provides read-only access to Argo CD instances using browser session cookies.

> Default layout:
> - Config: `~/.config/lukleh/mcp-read-only-argocd/connections.yaml`
> - Credentials: stored in `connections.yaml`
> - Cache: `~/.cache/lukleh/mcp-read-only-argocd/`

## Features

- Read-only by design: only read operations are exposed
- Session cookie authentication: uses your existing `argocd.token` browser session
- Multi-instance support: connect to multiple Argo CD instances at once
- Automatic cookie rotation: refreshed session cookies are persisted to `connections.yaml`
- Stale token recovery: a 401 response triggers a one-time Chrome cookie refresh and retry
- Package-native runtime paths: no repository checkout required for normal use

## Why Session Cookies?

Unlike token-based setups, this server can reuse your existing browser session:

- no extra API token management
- uses your existing SSO/OIDC login
- matches the permissions you already have in the UI

## Prerequisites

- Python 3.11 or higher
- [uv](https://github.com/astral-sh/uv)
- an Argo CD browser session cookie
- an MCP client such as Claude Code or Codex

## Quick Start

### 1. Install the Server

```bash
# Run the published package without cloning the repository
uvx mcp-read-only-argocd@latest --write-sample-config

# Or install it once and reuse the command directly
uv tool install mcp-read-only-argocd
mcp-read-only-argocd --write-sample-config
```

When using `uvx`, prefer `mcp-read-only-argocd@latest` in user-facing docs and
MCP client configs. This avoids reusing a stale cached tool environment after a
new release is published.

The command above writes a starter config to `~/.config/lukleh/mcp-read-only-argocd/connections.yaml`.

### 2. Confirm Runtime Paths

```bash
uvx mcp-read-only-argocd@latest --print-paths
```

### 3. Edit the Connections File

Edit `~/.config/lukleh/mcp-read-only-argocd/connections.yaml`:

```yaml
- connection_name: staging
  url: https://argocd.example.com
  description: Staging Argo CD
  session_token: your-session-token

- connection_name: production
  url: https://argocd-prod.example.com
  description: Production Argo CD
  session_token: your-other-session-token
```

### 4. Get Your `argocd.token` Session Cookie

1. Log in to your Argo CD web UI
2. Open browser developer tools
3. Go to Application/Storage -> Cookies
4. Copy the value of the `argocd.token` cookie

### 5. Store the Session Cookie

Put the cookie value in the `session_token` field for each connection in
`~/.config/lukleh/mcp-read-only-argocd/connections.yaml`. The server detects
changes to `connections.yaml` before tool calls, so editing this file does not
require an MCP restart.

If Argo CD rejects the active token with a 401 response, the server tries once to
load a fresh `argocd.token` from Chrome Profile 1 for the matching connection
domain. When that token differs from the active token, the failed request is
retried once. If the retry succeeds, the fresh token is written back to
`connections.yaml`.

### 6. Configure Your MCP Client

**Claude Code**

```bash
claude mcp add mcp-read-only-argocd \
  --scope user \
  -- uvx mcp-read-only-argocd@latest
```

**Codex**

```bash
codex mcp add mcp-read-only-argocd \
  -- uvx mcp-read-only-argocd@latest
```

### 7. Restart and Test

Restart your MCP client and try a simple query such as:

```text
List all applications in the staging Argo CD instance.
```

## Configuration

`connections.yaml` supports a list of Argo CD connections:

```yaml
- connection_name: staging
  url: https://argocd.example.com
  description: Staging Argo CD instance
  session_token: your-session-token
  timeout: 30
  verify_ssl: true
```

Fields:

- `connection_name`: unique identifier used in tool calls and token refreshes
- `url`: Argo CD base URL
- `description`: optional human-readable description
- `session_token`: Argo CD `argocd.token` browser cookie
- `timeout`: optional request timeout in seconds
- `verify_ssl`: optional SSL verification toggle

Runtime path override environment variables:

- `MCP_READ_ONLY_ARGOCD_CONFIG_DIR`
- `MCP_READ_ONLY_ARGOCD_CACHE_DIR`

## Command Line Testing

```bash
# Show the resolved runtime paths
uvx mcp-read-only-argocd@latest --print-paths

# Write or refresh the default connections.yaml
uvx mcp-read-only-argocd@latest --write-sample-config
uvx mcp-read-only-argocd@latest --write-sample-config --overwrite

# Run the server with the default home-directory config
uvx mcp-read-only-argocd@latest

# Or point at a different runtime root
uvx mcp-read-only-argocd@latest --config-dir /path/to/config-dir
```

## MCP Tools

### Core

- `list_connections`
- `get_version`
- `get_settings`

### Applications

- `list_applications`
- `get_application`
- `get_application_resource_tree`
- `get_application_managed_resources`
- `get_application_logs`

### Projects

- `list_projects`
- `get_project`

### Clusters

- `list_clusters`
- `get_cluster`

### Repositories

- `list_repositories`
- `get_repository`

## Local Development

If you want to work on the repository itself:

```bash
git clone https://github.com/lukleh/mcp-read-only-argocd.git
cd mcp-read-only-argocd
uv sync --extra dev
uv run pytest -q
uv run mcp-read-only-argocd --print-paths
uv run python smoke_test.py --print-paths
```

The checked-in sample file remains available at [connections.yaml.sample](connections.yaml.sample) for documentation and review, but package users should prefer `--write-sample-config`.

## License

MIT