BioEvidence MCP

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

Repository: 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, then install the project dependencies:

uv sync

Manual testing

Call the health tool directly through FastMCP:

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

The structured result should be:

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

To run the MCP server over the default stdio transport:

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

Evaluation

Run the deterministic, network-free release gate:

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:

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.