xrootd-mcp-server AGENTS.md

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