AI导哈

XRootD MCP 文件访问服务

XRootD MCP Server 是一个模型上下文协议服务，用于让大语言模型通过标准 MCP 接口访问 XRootD 分布式文件系统，支持目录浏览、文件元数据与内容读取、搜索过滤以及 ROOT 文件分析，适用于科研数据管理和规模化数据分析场景。

  • by eic
  • TypeScript
  • 混合部署
  • 1 星标
  • 更新于
在 GitHub 查看 eic/xrootd-mcp-server

使用说明

XRootD MCP Server

A Model Context Protocol (MCP) server that provides access to XRootD file systems. This server allows LLMs to interact with XRootD servers to list directories, read file metadata, access file contents, and more.

📚 View Full Documentation

Features

  • List directories: Browse XRootD file system hierarchy
  • File metadata: Get detailed information about files (size, modification time, permissions)
  • Read file contents: Access file data from XRootD servers with byte-range support
  • File operations: Check file existence, calculate directory sizes
  • Search & filtering: Find files by pattern (glob/regex), filter by size/date
  • Statistics & analytics: Comprehensive directory statistics and usage reports
  • Campaign discovery: List available production campaigns and datasets
  • Recent changes: Track newly added files and monitor production progress
  • ROOT file analysis: Inspect ROOT file structure, extract metadata, analyze events and collections
  • Dataset aggregation: Aggregate event statistics across multiple ROOT files
  • Protocol support: Connect to XRootD servers via root:// protocol

Installation

Using Docker (Recommended)

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

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

See Docker Usage Guide for detailed instructions.

From Source

npm install
npm run build

Configuration

Set the XRootD server URL using the XROOTD_SERVER environment variable:

export XROOTD_SERVER="root://dtn2304.jlab.org:8443"

Optionally, set a base directory to restrict access and simplify paths:

export XROOTD_BASE_DIR="/jlab-osdf-ro/eic/EPIC/volatile"

When XROOTD_BASE_DIR is set:

  • Relative paths are resolved relative to the base directory
  • Absolute paths must be within the base directory (access control)
  • For example, with base /jlab-osdf-ro/eic/EPIC/volatile, the path EVGEN refers to /jlab-osdf-ro/eic/EPIC/volatile/EVGEN

Transports

The server speaks stdio by default (for clients that spawn it themselves). Two HTTP transports are available via MCP_TRANSPORT:

# Streamable HTTP: MCP endpoint at http://127.0.0.1:9102/mcp
MCP_TRANSPORT=http XROOTD_SERVER="root://dtn2304.jlab.org:8443" node build/src/index.js

# Legacy SSE: endpoints at /sse and /messages
MCP_TRANSPORT=sse XROOTD_SERVER="root://dtn2304.jlab.org:8443" node build/src/index.js

MCP_HOST (default 127.0.0.1) and MCP_PORT (default 9102) control the bind address. The server binds loopback by default; binding any other address prints a warning because the tools carry no authentication.

An HTTP client config then looks like:

{
  "mcpServers": {
    "xrootd": {
      "type": "http",
      "url": "http://127.0.0.1:9102/mcp"
    }
  }
}

Caching

Directory listing results are cached for improved performance:

export XROOTD_CACHE_ENABLED=true      # default: true
export XROOTD_CACHE_TTL=60            # minutes, default: 60
export XROOTD_CACHE_MAX_SIZE=1000     # max entries, default: 1000

The cache uses a time-based expiration strategy (TTL):

  • Directory listings are cached in memory
  • Cache entries expire after the configured TTL
  • Automatic cleanup removes expired entries every 15 minutes
  • LRU eviction when cache size exceeds 1000 entries

Note: Cached data may be up to TTL minutes old. For production data that changes infrequently, a 60-minute TTL provides good performance with acceptable staleness.

Usage

With MCP Client

Add to your MCP client configuration:

{
  "mcpServers": {
    "xrootd": {
      "command": "node",
      "args": ["/path/to/xrootd-mcp-server/build/index.js"],
      "env": {
        "XROOTD_SERVER": "root://dtn2304.jlab.org:8443",
        "XROOTD_BASE_DIR": "/jlab-osdf-ro/eic/EPIC/volatile",
        "XROOTD_CACHE_ENABLED": "true",
        "XROOTD_CACHE_TTL": "60"
      }
    }
  }
}

Available Tools

Basic File Operations:

  • list_directory: List contents of an XRootD directory
  • get_file_info: Get detailed metadata about a file
  • read_file: Read contents of a file (with optional byte range)
  • check_file_exists: Check if a file or directory exists
  • get_directory_size: Calculate total size of a directory

Advanced Search & Analysis:

  • search_files: Search for files by glob pattern or regex
  • list_directory_filtered: List directory with advanced filtering (size, date, extension, pattern)
  • find_recent_files: Find files modified within a time period
  • get_statistics: Get comprehensive statistics about files in a directory

Campaign & Dataset Discovery:

  • 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

Timeouts

Every tool except list_servers takes timeout (seconds; default 120, or XROOTD_TOOL_TIMEOUT). On expiry the tool returns Error: <tool> did not finish within N s. ... with what to try (deeper path, recursive: false, smaller range, or retry once later: the xrootd command keeps running until it finishes).

Development

# Build
npm run build

# Watch mode
npm run watch

Requirements

  • Node.js 18 or higher
  • Access to an XRootD server
  • xrdfs command-line tool installed (from xrootd-client package)

License

MIT

相关 MCP