# InterProScan MCP Service

`interproscan_mcp` is a standalone FastMCP service for protein family, domain, and functional annotation. It keeps one MCP contract while supporting two backends:

- `local`: runs a mounted or locally installed `interproscan.sh` against a prepared InterProScan data directory.
- `api`: submits small protein FASTA jobs to the configured EMBL-EBI InterProScan REST endpoint.
- `auto`: the default; local is preferred, API is used when the local executable, Java runtime, data directory, or run root is unavailable.

The first version does not download, update, or package InterProScan databases. Server deployments must mount an existing installation and prepared data.

## MCP Tools

- `interproscan_validate_environment`: validates backend policy, local runtime, data directory, writable run root, allowed input roots, application list, and API reachability.
- `interproscan_list_applications`: returns the bounded member-application names accepted by this MCP.
- `interproscan_annotate_sequence`: validates protein FASTA text, creates one job directory, annotates through the selected backend, and returns structured results.
- `interproscan_annotate_fasta_file`: validates an allowed FASTA file path and annotates it as one job.

## Artifacts

Every annotation job writes under `runs/jobs/<job_id>/`:

- `input.fasta` and `input_meta.json`
- `command.json` for local jobs or `request.json` for API jobs
- raw local outputs such as `output.tsv`, or API files such as `api_response.tsv`
- `stdout.log` and `stderr.log` for local jobs
- `results.json`
- `manifest.json`

The manifest records input hash, input type, backend policy, backend used, fallback reason, local data path, API endpoint, effective parameters, timestamps, exit code or HTTP status, status, and artifact paths.

## Configuration

Copy `.env.example`, `configs/workstation.env`, or `configs/server.env` and set environment variables before startup.

Key variables:

```text
INTERPROSCAN_BACKEND=auto
INTERPROSCAN_EXECUTABLE=/opt/interproscan/interproscan.sh
INTERPROSCAN_DATA_DIR=/opt/interproscan/data
INTERPROSCAN_RUN_ROOT=./runs
INTERPROSCAN_ALLOWED_INPUT_ROOTS=./examples,./runs
INTERPROSCAN_API_ENDPOINT=https://www.ebi.ac.uk/Tools/services/rest/iprscan5
INTERPROSCAN_API_EMAIL=your-email@example.org
INTERPROSCAN_DEFAULT_THREADS=4
INTERPROSCAN_DEFAULT_TIMEOUT=120
INTERPROSCAN_MCP_TRANSPORT=stdio
```

## Local Setup

```powershell
cd D:\future\antigravity\mgi\interprosanc_mcp
.\quick_setup.ps1
.\env\Scripts\python.exe .\src\server.py
```

HTTP mode:

```powershell
$env:INTERPROSCAN_MCP_TRANSPORT="http"
$env:INTERPROSCAN_MCP_HOST="127.0.0.1"
$env:INTERPROSCAN_MCP_PORT="8114"
$env:INTERPROSCAN_MCP_PATH="/mcp"
$env:INTERPROSCAN_BACKEND="auto"
$env:INTERPROSCAN_RUN_ROOT="D:\future\antigravity\mgi\interprosanc_mcp\runs"
.\env\Scripts\python.exe .\src\server.py
```

## Docker

```bash
cd docker
docker compose up -d --build
```

Default HTTP endpoint:

```text
http://127.0.0.1:8114/mcp
```

For server local mode, mount:

- `INTERPROSCAN_INSTALL_ROOT`: directory containing `interproscan.sh`
- `INTERPROSCAN_DATA_ROOT`: prepared data directory
- `INTERPROSCAN_RUN_ROOT`: writable artifacts directory

## ProteinMCP

The service is registered in ProteinMCP as `interproscan_mcp` and `interproscan`.

```powershell
cd D:\future\antigravity\mgi\ProteinMCP
python -m src.mcp_cli info interproscan_mcp
python -m src.mcp_cli install interproscan_mcp --no-register
```

## Troubleshooting

- `interproscan_not_found`: set `INTERPROSCAN_EXECUTABLE` to a valid `interproscan.sh`.
- `needs_setup`: mount or configure the prepared InterProScan data directory.
- `interproscan_api_unavailable`: check `INTERPROSCAN_API_ENDPOINT`, network access, and `INTERPROSCAN_API_EMAIL`.
- `path_not_allowed`: move FASTA files under `INTERPROSCAN_ALLOWED_INPUT_ROOTS`.
- `unsupported_application` or `unsupported_output_format`: use the bounded values returned by `interproscan_list_applications` and documented output formats.