Metadata-Version: 2.4
Name: mcp-read-only-argocd
Version: 0.2.0
Summary: MCP server for read-only access to Argo CD instances using browser session cookies
Project-URL: Homepage, https://github.com/lukleh/mcp-read-only-argocd
Project-URL: Repository, https://github.com/lukleh/mcp-read-only-argocd
Project-URL: Issues, https://github.com/lukleh/mcp-read-only-argocd/issues
Project-URL: Changelog, https://github.com/lukleh/mcp-read-only-argocd/blob/main/CHANGELOG.md
Author-email: Lukas Lehner <lehner.lukas@gmail.com>
License: MIT
License-File: LICENSE
Keywords: argocd,kubernetes,mcp,mcp-server,read-only
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: httpx>=0.24.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.2.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: ty>=0.0.28; extra == 'dev'
Requires-Dist: vulture>=2.16; extra == 'dev'
Description-Content-Type: text/markdown

# 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`
> - Rotated session state: `~/.local/state/lukleh/mcp-read-only-argocd/session_tokens.json`
> - 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 local state
- 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 persists
rotated session cookies to
`~/.local/state/lukleh/mcp-read-only-argocd/session_tokens.json`, keyed by
`connection_name`. The server detects changes to `connections.yaml` before tool
calls, so editing this file does not require an MCP restart. If both
`connections.yaml` and the state file contain a token for the same connection,
the persisted state file wins until you update or remove it.

### 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 rotated session state
- `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_STATE_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
