# BioEvidence MCP

Evidence-grounded biomedical retrieval and summarization through the Model Context Protocol.

Repository: [github.com/mihir19/bioevidence-mcp](https://github.com/mihir19/bioevidence-mcp)

The distribution name is `bioevidence-mcp`. The Python import namespace
remains `bioreason` for backward compatibility with existing integrations.

Research use only. No diagnosis, treatment recommendations, or patient data.

## Setup

Install Python 3.12 and [uv](https://docs.astral.sh/uv/), then install the project dependencies:

```bash
uv sync
```

## Manual testing

Call the `health` tool directly through FastMCP:

```bash
uv run fastmcp call src/bioreason/server.py health
```

The structured result should be:

```json
{
  "status": "ok",
  "version": "0.1.1"
}
```

To run the MCP server over the default stdio transport:

```bash
uv run fastmcp run src/bioreason/server.py:mcp
```

## Evaluation

Run the deterministic, network-free release gate:

```bash
uv run python -m bioreason.evaluation.runner \
  --mode offline \
  --output evaluation/reports/offline-report.json \
  --markdown evaluation/reports/offline-report.md
```

Run one explicitly selected live integration case:

```bash
uv run --env-file .env python -m bioreason.evaluation.runner \
  --mode live \
  --case-id brca1-c68-69delag \
  --output evaluation/reports/live-brca1.json \
  --markdown evaluation/reports/live-brca1.md
```

Offline evaluation is deterministic and CI-safe. Live evaluation requires network access, and exact evidence counts may change. OpenAI is optional: missing summarizer configuration produces an incomplete integration case without losing retrieval results. Evaluation establishes citation provenance and eligibility, not clinical validity or complete semantic entailment. See [evaluation/README.md](evaluation/README.md).