xrootd-mcp-server: Instructions file for Codex

AI Agent Instructions for XRootD MCP Server

This document provides guidance for AI agents (GitHub Copilot, Claude, ChatGPT, etc.) working on this repository.

Project Overview

XRootD MCP Server - A Model Context Protocol server that provides LLMs access to XRootD file systems for the EIC (Electron-Ion Collider) project.

• Language: TypeScript (Node.js)
• MCP SDK: @modelcontextprotocol/sdk v0.5.0
• Purpose: File access, search, analysis, and ROOT file metadata extraction for scientific computing
• Target: HEP (High Energy Physics) / Nuclear Physics data analysis workflows

Architecture

src/
├── index.ts        # MCP server implementation, tool definitions
├── xrootd.ts       # XRootD client wrapper, core functionality
└── cache.ts        # Directory listing cache (TTL-based)

build/              # Compiled JavaScript (generated, do not edit)
docs/               # Documentation
examples/           # Usage examples and configuration

Key Principles

1. Security First

• Base directory restriction: All paths must be within XROOTD_BASE_DIR
• Path resolution: Use resolvePath() to validate and normalize paths
• No write operations: Read-only access to XRootD server
• Input validation: Validate all user inputs before passing to shell commands

2. XRootD Integration

• Commands: Use xrdfs for metadata, xrdcp for file content
• Shell escaping: Always properly escape paths in commands
• Buffer sizes: Use 50MB maxBuffer for large directory listings
• Error handling: Catch and wrap xrootd errors with descriptive messages

3. MCP Protocol Standards

• Tool schemas: Define clear JSON schemas for all parameters
• Response format: Return { content: [{ type: 'text', text: JSON.stringify(...) }] }
• Error responses: Include isError: true for failures
• Capabilities: Declare only implemented capabilities (currently: tools)

4. Performance & Caching

• Cache strategy: Time-based TTL (default 60 minutes)
• Cache bypass: Provide useCache parameter where appropriate
• Recursive operations: Be mindful of performance on large directory trees
• Lazy loading: Don't fetch data until needed