Metadata-Version: 2.4
Name: rucio-mcp
Version: 0.6.0
Summary: MCP Server for rucio
Project-URL: Documentation, https://rucio-mcp.readthedocs.io/
Project-URL: Homepage, https://github.com/kratsg/rucio-mcp
Project-URL: Bug Tracker, https://github.com/kratsg/rucio-mcp/issues
Project-URL: Discussions, https://github.com/kratsg/rucio-mcp/discussions
Project-URL: Changelog, https://github.com/kratsg/rucio-mcp/releases
Author-email: Giordon Stark <kratsg@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.10
Requires-Dist: prometheus-client>=0.20
Description-Content-Type: text/markdown

# rucio-mcp v0.6.0

[![Actions Status][actions-badge]][actions-link]
[![Documentation Status][rtd-badge]][rtd-link]

[![PyPI version][pypi-version]][pypi-link]
[![Conda-Forge][conda-badge]][conda-link]
[![PyPI platforms][pypi-platforms]][pypi-link]

[![GitHub Discussion][github-discussions-badge]][github-discussions-link]

[![Coverage][coverage-badge]][coverage-link]

<!-- --8<-- [start:intro] -->

An MCP server that exposes [Rucio](https://rucio.cern.ch) distributed data
management operations as tools for LLMs. Designed for ATLAS physicists working
with grid data on analysis facilities, but usable with any Rucio instance.

<!-- --8<-- [end:intro] -->

<!-- --8<-- [start:what-it-does] -->

## What it does

`rucio-mcp` lets Claude (or any MCP-compatible LLM) query and manage your Rucio
data directly:

- **Find data**: search for datasets/containers by pattern, list files, browse
  DID hierarchies
- **Check replicas**: see where data is physically stored, which sites have a
  dataset, generate access URLs
- **Manage rules**: list, create, update, move, approve, and delete replication
  rules
- **Monitor**: check RSE storage usage, account quotas, proxy certificate
  validity

All tool descriptions include ATLAS dataset naming conventions so the LLM
understands scope formats, AMI tags, and DID structure without extra prompting.

<!-- --8<-- [end:what-it-does] -->

<!-- --8<-- [start:installation] -->

## Installation

```bash
pip install rucio-mcp
```

Or with pixi (recommended for ATLAS facilities):

```bash
pixi add rucio-mcp
```

<!-- --8<-- [end:installation] -->

<!-- --8<-- [start:requirements] -->

## Requirements

- Python 3.10+
- A configured Rucio environment (`rucio.cfg` and valid authentication)
- For x509 proxy auth: a valid VOMS proxy (`voms-proxy-init -voms <VO>`)
<!-- --8<-- [end:requirements] -->

<!-- --8<-- [start:quick-start] -->

## Quick start

### 1. Set up authentication

**x509 proxy (ATLAS sites):**

```bash
voms-proxy-init -voms atlas
export RUCIO_ACCOUNT=<your_atlas_account>
```

**When installed via pixi (recommended):**

`ca-policy-lcg` is included as a dependency and sets `X509_CERT_DIR`
automatically to the certificates bundled in the conda environment. No manual
configuration needed.

If you run into an error about expired CRLs

```text
Error: Certificate verification failed.
sslutils.c:1911:error:40000405:lib(128)::outdated CRL found, revoking all certs till you get new CRL
sslutils.c:2106:error:40000411:lib(128)::certificate validation error: CRL has expired
```

then you need to run the following to refresh the CRLs:

```bash
pixi run sh -c '$X509_CERT_DIR/refresh_crls.sh'
```

or

```
bash
pixi exec --with rucio-mcp sh -c '$X509_CERT_DIR/refresh_crls.sh'
```

**On CVMFS-based facilities without pixi (e.g. UChicago Analysis Facility):**

```bash
voms-proxy-init -voms atlas
export RUCIO_ACCOUNT=<your_atlas_account>
export X509_CERT_DIR=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/etc/grid-security-emi/certificates
export RUCIO_CONFIG=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/x86_64/rucio-clients/35.6.0/etc/rucio.cfg
rucio-mcp serve --site atlas --auth-type x509
```

**x509 proxy (CMS sites):**

```bash
voms-proxy-init -voms cms
export RUCIO_ACCOUNT=<your_cms_account>
rucio-mcp serve --site cms --auth-type x509
```

### 2. Test the server

```bash
rucio-mcp serve
```

The server speaks MCP over stdio. Configure your MCP client to launch it.

### 3. Configure Claude Code

Add to your `.mcp.json` (project) or `~/.claude.json` (global).

The key name (`rucio-atlas` below) lets you tell Claude which Rucio server to
use — useful when you have multiple Rucio instances configured. Choose any name
you like.

**With pixi** (`X509_CERT_DIR` set automatically by `ca-policy-lcg`):

```json
{
  "mcpServers": {
    "rucio-atlas": {
      "type": "stdio",
      "command": "pixi",
      "args": [
        "run",
        "--manifest-path",
        "/path/to/rucio-mcp",
        "rucio-mcp",
        "serve",
        "--site",
        "atlas",
        "--auth-type",
        "x509"
      ],
      "env": {
        "RUCIO_ACCOUNT": "youraccount"
      }
    }
  }
}
```

**Without pixi** (if you have CVMFS + ATLAS, use the path below; otherwise point
`X509_CERT_DIR` at your local CA bundle):

```json
{
  "mcpServers": {
    "rucio-atlas": {
      "type": "stdio",
      "command": "rucio-mcp",
      "args": ["serve", "--site", "atlas", "--auth-type", "x509"],
      "env": {
        "RUCIO_ACCOUNT": "youraccount",
        "X509_CERT_DIR": "/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/etc/grid-security-emi/certificates",
        "RUCIO_CONFIG": "/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/x86_64/rucio-clients/35.6.0/etc/rucio.cfg"
      }
    }
  }
}
```

### 4. Configure Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).

**With pixi:**

```json
{
  "mcpServers": {
    "rucio-atlas": {
      "type": "stdio",
      "command": "pixi",
      "args": [
        "run",
        "--manifest-path",
        "/path/to/rucio-mcp",
        "rucio-mcp",
        "serve",
        "--site",
        "atlas",
        "--auth-type",
        "x509"
      ],
      "env": {
        "RUCIO_ACCOUNT": "youraccount"
      }
    }
  }
}
```

**Without pixi** (if you have CVMFS + ATLAS, use the path below; otherwise point
`X509_CERT_DIR` at your local CA bundle):

```json
{
  "mcpServers": {
    "rucio-atlas": {
      "type": "stdio",
      "command": "rucio-mcp",
      "args": ["serve", "--site", "atlas", "--auth-type", "x509"],
      "env": {
        "RUCIO_ACCOUNT": "youraccount",
        "X509_CERT_DIR": "/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/etc/grid-security-emi/certificates",
        "RUCIO_CONFIG": "/path/to/rucio-clients/etc/rucio.cfg"
      }
    }
  }
}
```

<!-- --8<-- [end:quick-start] -->

<!-- --8<-- [start:http-mode] -->

## HTTP mode (multi-user, OIDC)

For sites that support OIDC (e.g. the ESCAPE Virtual Research Environment),
rucio-mcp can run as a hosted OAuth 2.1 Authorization Server proxy — one server
for many users with no IAM registration required:

```bash
rucio-mcp serve \
  --transport http \
  --site escape \
  --resource-url https://rucio-mcp.example.com \
  --host 0.0.0.0 \
  --port 8000
```

Each site is mounted under `{resource-url}/site/{name}/`. Configure your MCP
client with the site URL:

```json
{
  "mcpServers": {
    "rucio-escape": {
      "type": "http",
      "url": "https://rucio-mcp.example.com/site/escape/"
    }
  }
}
```

See [docs/oauth-setup.md](docs/oauth-setup.md) for the full setup guide.

### Shared-secret HTTP mode (single pre-authenticated client)

To expose a **single pre-authenticated instance** (e.g. an x509/VOMS-proxy
identity on a service host) over HTTP without the per-user OIDC bridge, start
the server with `--shared-secret` (or `RUCIO_MCP_SHARED_SECRET`). It serves one
env-built client (like stdio, honoring `--auth-type`) gated by a server-wide
static bearer:

```bash
export RUCIO_ACCOUNT=<your_account>
voms-proxy-init -voms atlas
rucio-mcp serve \
  --transport http \
  --site atlas \
  --auth-type x509 \
  --shared-secret "$(openssl rand -hex 32)" \
  --host 0.0.0.0 \
  --port 9000
```

Clients send the secret as a bearer token (any other value → `401`):

```json
{
  "mcpServers": {
    "rucio-atlas": {
      "type": "http",
      "url": "http://host:9000/site/atlas/",
      "headers": { "Authorization": "Bearer <secret>" }
    }
  }
}
```

This mode serves a single `--site` and bypasses the OAuth bridge entirely (no
`/authorize`, `/token`, or `/register`). See
[docs/configuration.md](docs/configuration.md#hosting-a-pre-authenticated-instance-over-http-shared-secret)
for details.

<!-- --8<-- [end:http-mode] -->

<!-- --8<-- [start:read-only] -->

## Read-only mode

Start the server with `--read-only` to block all write operations. Tools that
create, modify, or delete replication rules will return an error instead of
executing.

```bash
rucio-mcp serve --read-only
```

Or in your MCP config:

```json
{
  "mcpServers": {
    "rucio-escape": {
      "command": "rucio-mcp",
      "args": ["serve", "--read-only"],
      "env": { "...": "..." }
    }
  }
}
```

Useful when you want the LLM to help explore data without the ability to
accidentally create rules or modify existing ones.

<!-- --8<-- [end:read-only] -->

<!-- --8<-- [start:tools] -->

## Available tools

### Connectivity

| Tool                    | Description                                   |
| ----------------------- | --------------------------------------------- |
| `rucio_ping`            | Check server connectivity and version         |
| `rucio_whoami`          | Show authenticated account info               |
| `rucio_voms_proxy_info` | Show VOMS proxy certificate status and expiry |

### DID discovery

| Tool                     | Description                                        |
| ------------------------ | -------------------------------------------------- |
| `rucio_list_dids`        | Search for datasets/containers by wildcard pattern |
| `rucio_get_did`          | Get type, size, and timestamps for a DID           |
| `rucio_list_content`     | List immediate contents of a container or dataset  |
| `rucio_list_files`       | List all files within a DID                        |
| `rucio_get_metadata`     | Retrieve metadata key-value pairs for a DID        |
| `rucio_list_parent_dids` | Find containers that hold a given DID              |

### Replicas

| Tool                            | Description                                           |
| ------------------------------- | ----------------------------------------------------- |
| `rucio_list_replicas`           | Physical replica locations (PFNs) for files           |
| `rucio_list_dataset_replicas`   | Dataset availability summary across RSEs              |
| `rucio_list_container_replicas` | Dataset replica summary aggregated across a container |

### Replication rules

| Tool                           | Write? | Description                                     |
| ------------------------------ | ------ | ----------------------------------------------- |
| `rucio_list_did_rules`         | —      | List all rules for a specific DID               |
| `rucio_list_replication_rules` | —      | List rules globally, filtered by scope/account  |
| `rucio_get_replication_rule`   | —      | Detailed info for a specific rule               |
| `rucio_list_rule_history`      | —      | Full state history of rules for a DID           |
| `rucio_add_rule`               | ✓      | Create a new replication rule                   |
| `rucio_delete_rule`            | ✓      | Delete a rule (optionally purge replicas)       |
| `rucio_update_rule`            | ✓      | Update lifetime, locked flag, comment, activity |
| `rucio_reduce_rule`            | ✓      | Reduce the number of copies in a rule           |
| `rucio_move_rule`              | ✓      | Move a rule to a different RSE expression       |
| `rucio_approve_rule`           | ✓      | Approve a rule awaiting approval                |
| `rucio_deny_rule`              | ✓      | Deny a rule awaiting approval                   |

### RSEs and storage

| Tool                         | Description                                    |
| ---------------------------- | ---------------------------------------------- |
| `rucio_list_rses`            | List RSEs matching an expression               |
| `rucio_get_rse`              | Detailed configuration info for an RSE         |
| `rucio_list_rse_attributes`  | Key-value attributes for an RSE                |
| `rucio_get_rse_usage`        | Total, used, and free storage at an RSE        |
| `rucio_get_rse_limits`       | Configured space limits for an RSE             |
| `rucio_get_rse_protocols`    | Transfer protocols supported by an RSE         |
| `rucio_get_distance`         | Network distance (ranking) between two RSEs    |
| `rucio_list_transfer_limits` | Global transfer limit policies by activity/RSE |

### Requests and transfers

| Tool                          | Description                                   |
| ----------------------------- | --------------------------------------------- |
| `rucio_list_requests`         | Current transfer requests between two RSEs    |
| `rucio_list_requests_history` | Historical transfer requests between two RSEs |

### Accounts and quotas

| Tool                             | Description                            |
| -------------------------------- | -------------------------------------- |
| `rucio_list_accounts`            | List accounts, optionally filtered     |
| `rucio_get_account`              | Detailed info for a specific account   |
| `rucio_get_local_account_usage`  | Storage used per RSE for an account    |
| `rucio_get_local_account_limits` | Storage quota limits for an account    |
| `rucio_list_account_rules`       | All replication rules owned by account |

### Subscriptions

| Tool                            | Description                                |
| ------------------------------- | ------------------------------------------ |
| `rucio_list_subscriptions`      | List subscriptions, optionally filtered    |
| `rucio_list_subscription_rules` | Rules generated by a specific subscription |

### Locks

| Tool                             | Description                         |
| -------------------------------- | ----------------------------------- |
| `rucio_get_dataset_locks`        | Locks on a specific dataset DID     |
| `rucio_get_dataset_locks_by_rse` | All dataset locks at a specific RSE |

### Scopes

| Tool                            | Description                        |
| ------------------------------- | ---------------------------------- |
| `rucio_list_scopes`             | List all available scopes          |
| `rucio_list_scopes_for_account` | Scopes owned by a specific account |

<!-- --8<-- [end:tools] -->

<!-- --8<-- [start:example-prompts] -->

## Example prompts

Once configured, you can ask Claude things like:

- _"Find all DAOD_PHYS containers for mc20_13TeV DSID 700320"_
- _"Which sites have dataset X available and how complete is each replica?"_
- _"Create a rule to replicate this dataset to a US Tier-1 disk site for 30
  days"_
- _"Is my proxy still valid? How long do I have left?"_
- _"Show me the replication rules for this container and their current states"_
- _"What's my storage quota at CERN-PROD_DATADISK?"_
<!-- --8<-- [end:example-prompts] -->

<!-- prettier-ignore-start -->
[actions-badge]:            https://github.com/kratsg/rucio-mcp/actions/workflows/ci.yml/badge.svg
[actions-link]:             https://github.com/kratsg/rucio-mcp/actions
[conda-badge]:              https://img.shields.io/conda/vn/conda-forge/rucio-mcp
[conda-link]:               https://github.com/conda-forge/rucio-mcp-feedstock
[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
[github-discussions-link]:  https://github.com/kratsg/rucio-mcp/discussions
[pypi-link]:                https://pypi.org/project/rucio-mcp/
[pypi-platforms]:           https://img.shields.io/pypi/pyversions/rucio-mcp
[pypi-version]:             https://img.shields.io/pypi/v/rucio-mcp
[rtd-badge]:                https://readthedocs.org/projects/rucio-mcp/badge/?version=latest
[rtd-link]:                 https://rucio-mcp.readthedocs.io/en/latest/?badge=latest
[coverage-badge]:           https://codecov.io/github/kratsg/rucio-mcp/branch/main/graph/badge.svg
[coverage-link]:            https://codecov.io/github/kratsg/rucio-mcp

<!-- prettier-ignore-end -->
