XRootD

You can interact with XRootD file systems through a dedicated MCP (Model Context Protocol) server, enabling you to list directories, read file metadata, fetch file contents with byte-range support, and perform a variety of search, analytics, and campaign-related queries from your MCP client.

How to use

Connect your MCP client to the XRootD MCP Server to perform practical file-system operations. You can browse the XRootD hierarchy, inspect file metadata (size, modification time, permissions), and read file contents with optional byte ranges. You can also check for existence, calculate directory sizes, and apply advanced search and filtering to locate files by patterns, size, or date. For ROOT files, you can analyze structure and extract metadata. Campaigns and datasets can be discovered, with recent changes tracked to monitor production progress.

How to install

Prerequisites you need before running the MCP server:

• Node.js version 18 or higher

• Access to an XRootD server

• xrdfs command-line tool installed (from the xrootd-client package)

Installation via Docker

docker pull ghcr.io/eic/xrootd-mcp-server:latest

docker run -i --rm \
  -e XROOTD_SERVER="root://dtn-eic.jlab.org" \
  -e XROOTD_BASE_DIR="/volatile/eic/EPIC" \
  ghcr.io/eic/xrootd-mcp-server:latest

Installation from source

npm install
npm run build

Post-install configuration

Set the XRootD server URL and optional base directory to control where you access data. You can configure these as environment variables in your runtime environment.

Starting the server from an MCP client configuration

When running from an MCP client, you typically provide a configuration that starts the MCP server as a local (stdio) process using Node.js and the built entry point. The following configuration is an example you can adapt for your environment.

Notes on caching and performance

Directory listing results are cached to improve performance. You can tune caching with environment variables to balance freshness against speed.

Additional configuration options

Configure the following environment variables to control behavior and access: XROOTD_SERVER, XROOTD_BASE_DIR, XROOTD_CACHE_ENABLED, XROOTD_CACHE_TTL, XROOTD_CACHE_MAX_SIZE. Relative paths are resolved against the base directory when XROOTD_BASE_DIR is set.

Configuration details

• XROOTD_SERVER: URL of the remote XRootD server, e.g. root://dtn-eic.jlab.org

• XROOTD_BASE_DIR: Optional base directory to restrict access, e.g. /volatile/eic/EPIC

• XROOTD_CACHE_ENABLED: Enable or disable directory listing caching, default true

• XROOTD_CACHE_TTL: Cache time-to-live in minutes, default 60

• XROOTD_CACHE_MAX_SIZE: Maximum number of cache entries, default 1000

Available tools

list_directory

List contents of an XRootD directory to browse the file system hierarchy.

get_file_info

Fetch detailed metadata for a specific file, including size, modification time, and permissions.

read_file

Read contents of a file with optional byte-range support.

check_file_exists

Check whether a file or directory exists at a given path.

get_directory_size

Calculate the total size of a directory by aggregating contained files.

search_files

Find files by glob pattern or regex to locate data quickly.

list_directory_filtered

List a directory with advanced filtering options (size, date, extension, pattern).

find_recent_files

Identify files modified within a specified time period.

get_statistics

Provide comprehensive statistics about files in a directory.

list_campaigns

List available production campaigns.

list_datasets

List datasets within a specific campaign.

summarize_recent_changes

Summarize files added in a time period with detailed statistics.