# integrity-checker-mcp

MCP server for the [CMS File Integrity Checker](https://github.com/dmwm/CMSRucio/tree/master/DMOps/file_invalidation_server/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

```bash
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:

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

## Running with Docker

```bash
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

```bash
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.