integrity-checker-mcp

MCP server for the CMS File Integrity Checker.

Exposes integrity check operations as tools for AI agents (Archi) so users can submit and query file integrity jobs through natural language.

Tools

Tool	Description
submit_integrity_request	Submit up to N LFNs for integrity checking (async job)
get_integrity_request	Poll status and results for a request by ID
list_integrity_requests	List requests, optionally filtered by status or user
get_integrity_files	Per-file results for a completed request
get_integrity_replicas	Per-replica results for a completed request
get_queue_status	Current queue depth (submitted + in-progress counts)

Configuration

Variable	Required	Default	Must match
INTEGRITY_CHECKER_URL	yes	—	—
INTEGRITY_CHECKER_TOKEN	no	—	—
INTEGRITY_CHECKER_TIMEOUT	no	60	—
INTEGRITY_CHECKER_MAX_LFNS_PER_REQUEST	no	20	FIC_MAX_LFNS_PER_REQUEST on server
INTEGRITY_CHECKER_MAX_CONCURRENT_JOBS	no	3	FIC_MAX_CONCURRENT_JOBS on server
INTEGRITY_CHECKER_MCP_TRANSPORT	no	stdio	—
INTEGRITY_CHECKER_MCP_HOST	no	0.0.0.0	—
INTEGRITY_CHECKER_MCP_PORT	no	8000	—

INTEGRITY_CHECKER_MAX_LFNS_PER_REQUEST and INTEGRITY_CHECKER_MAX_CONCURRENT_JOBS must be kept in sync with the corresponding env vars on the integrity checker server.

Running locally

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

In stdio mode (the default) the server is launched as a subprocess by your MCP client (Claude Desktop, Archi, etc.) — configure it there rather than running it directly.

For manual testing with a network-accessible endpoint, use SSE transport:

INTEGRITY_CHECKER_URL=https://your-server \
INTEGRITY_CHECKER_MCP_TRANSPORT=sse \
integrity-checker-mcp

Running with Docker

docker build -t integrity-checker-mcp .
docker run \
  -e INTEGRITY_CHECKER_URL=https://your-server \
  -e INTEGRITY_CHECKER_TOKEN=your-token \
  -p 8000:8000 \
  integrity-checker-mcp

Development

pytest tests/

Tests use a MockClient — no live server required.

How it works

Integrity checks are asynchronous. The typical flow is:

1. Submit a request → get a request_id
2. Check queue depth with get_queue_status (cron runs every minute)
3. Poll get_integrity_request until status is COMPLETED
4. Fetch results with get_integrity_files or get_integrity_replicas

Important: ERROR replica status means the file was inaccessible (e.g. on tape), not that it is corrupted. Never report ERROR replicas as corrupted.