rucio-mcp: Instructions file for Claude Code

rucio-mcp — Contributor Guide

MCP server that exposes ATLAS Rucio data management operations as tools for LLMs.

Architecture

Two transport modes:

# stdio (local, single-user)
LLM <--MCP/stdio--> rucio-mcp serve <--HTTPS (rucio.client)--> Rucio server
                              |
                              +--subprocess--> voms-proxy-info

# http (hosted, multi-user)
MCP client  <--auth-code+PKCE-->  rucio-mcp (OAuth AS proxy)  <--polling-->  Rucio auth server  <--IdP-->
                                         |                                          |
                                  BridgeProvider mints                   /auth/oidc + /auth/oidc_redirect
                                  auth codes; bearer = rucio token       (Rucio session token)

Stdio mode: one rucio.client.Client built at server startup from env vars; reused for all tool calls. All rucio auth types supported.

HTTP mode: rucio-mcp acts as an OAuth 2.1 Authorization Server proxy (RFC 8414 + CIMD + auth-code+PKCE). It bridges MCP client auth to Rucio's custom OIDC polling flow (/auth/oidc → /auth/oidc_redirect). The resulting Rucio session token is returned verbatim as the MCP access_token. No IAM registration is required by operators or end-users.

Shared-secret HTTP mode: when serve is given --shared-secret (env RUCIO_MCP_SHARED_SECRET), HTTP transport switches to a distinct, mutually-exclusive model: it serves a single env-built Client (exactly like stdio, honoring --auth-type — e.g. a pre-authenticated x509 instance) gated by a server-wide static bearer. An MCPServer TokenVerifier (auth/shared_secret.py::SharedSecretVerifier, constant-time compare) enforces the secret; there is no OAuth bridge, OIDC poller, CIMD, /bridge, /authorize, /token, or /register. Single site only (one env config = one client). Built by _make_shared_secret_mcp / _make_shared_secret_app in server.py; reuses EnvBasedClientFactory.

Broker HTTP mode: when serve is given --broker-url (env RUCIO_MCP_BROKER_URL), HTTP transport runs behind af-mcp-platform's aggregator: bearers are broker-issued identity JWTs verified against the broker's JWKS (auth/broker.py::make_broker_token_verifier, backed by af-credentials), and BrokerProxyClientFactory redeems the caller's VOMS proxy from the broker per tool call, authenticates a fresh ProxyAuthClient (auth_type=x509_proxy, disk token cache disabled so one user's rucio token can never leak to another via the shared /tmp cache), and deletes the proxy file as soon as authentication completes. The rucio account is left unset — the Rucio server resolves it from the proxy DN's default-account mapping (AF unixnames do not match CERN/Rucio account names; an explicit account via the broker redeem response is tracked in af-mcp-platform#191). Single site only; mutually exclusive with --shared-secret; no OAuth bridge, CIMD, or /register. Built by _make_broker_mcp / _make_broker_app in server.py (the single-site app shell is shared with shared-secret mode via _wrap_single_site_app). Requires the broker extra (pip install rucio-mcp[broker]).