integrity-checker-mcp

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.