opentargets-link
by berntpopp
README.md
# opentargets-link
[](https://www.python.org/)
[](https://github.com/berntpopp/opentargets-link/actions/workflows/ci.yml)
[](https://github.com/berntpopp/opentargets-link/actions/workflows/conformance.yml)
[](LICENSE)
An **MCP** server (Streamable HTTP or stdio) for the
[Open Targets Platform](https://platform.opentargets.org/): target tractability, ChEMBL drugs
and clinical candidates, disease-to-target association ranking, and target–disease evidence
(somatic drivers from IntOGen, ClinVar somatic and germline, clinical precedence, gene burden,
GWAS credible sets). Data are fetched live from the
[Open Targets Platform GraphQL API](https://api.platform.opentargets.org/api/v4/graphql).
It is one backend in the GeneFoundry `-link` fleet.
> [!IMPORTANT]
> Research use only. Not clinical decision support. Do not use for diagnosis,
> treatment, triage, or patient management.
The output is not a clinical actionability report.
## Why
"Which drugs act on BRAF, and which were studied in melanoma?" is an Open Targets question. The
GraphQL API can answer it, but its quirks are where an agent goes wrong:
- `knownDrugs` is gone; `drugAndClinicalCandidates` nests every trial report (220 KB for BRAF);
- evidence needs `efoIds`, so "all evidence for a gene" takes two calls;
- some datasources (COSMIC Cancer Gene Census, Europe PMC) are licensed for Open Targets
users only or mix non-commercial terms;
- variable errors arrive as HTTP 400 with `errors[]`, and the last page still has a cursor.
This server handles each of them:
- **Fixed queries only.** Callers never send GraphQL. GraphQL errors become typed errors that
name the offending parameter (`isError: true`); a vanished field is reported as schema drift.
- **Datasource allowlist.** Evidence and association scores come only from reviewed sources.
`cancer_gene_census`, `genomics_england`, `crispr` (Project Score), `europepmc` and the held
`cancer_biomarkers` are never served, and scores are recomputed with them at weight 0.
- **Bounded drug answers.** Trial reports appear only in `response_mode="full"` (top 3 per drug).
- **Honest paging.** `total` is Open Targets' own count; `truncated` and `next_offset` /
`next_cursor` say whether more rows exist.
- **Labelled builds.** Variant IDs and target locations are GRCh38.
- **Empty is not negative.** A zero-row answer says "no Open Targets data found", never "not
druggable".
## Quick start
Hosted, no install:
```bash
claude mcp add --transport http opentargets https://opentargets-link.genefoundry.org/mcp
```
Run it locally (Python 3.14+, [uv](https://github.com/astral-sh/uv)). There is no data-build
step and no data snapshot: the server calls Open Targets live and keeps a short in-process cache.
```bash
uv sync --group dev
uv run opentargets-link # unified: FastAPI /health + MCP /mcp on 127.0.0.1:8000
claude mcp add --transport http opentargets-link --scope user http://127.0.0.1:8000/mcp
```
Use `unified` (the default) for MCP over HTTP; `--transport http` serves `/health` only. The
`opentargets-link-mcp` entry point serves stdio. Health check: `curl localhost:8000/health`.
## Tools
| Tool | Purpose |
|------|---------|
| `resolve_target` | Entry resolver: symbol, alias or Ensembl gene ID → target (GRCh38 location, synonyms) |
| `get_target_tractability` | Tractability buckets per modality (small molecule, antibody, PROTAC, other) |
| `get_drug_candidates` | ChEMBL drugs and clinical candidates for a target, optionally for one disease |
| `search_disease_targets` | Targets ranked for a disease by the allowlist-only association score |
| `get_target_disease_evidence` | Evidence rows linking a target to a disease (or to any disease) |
| `get_server_capabilities` | Discovery: datasource allowlist, limits, error codes, licence and citation |
| `get_diagnostics` | Local runtime state: request budget, cache hits, latency |
Leaf names are **unprefixed** per Tool-Naming Standard v1. Behind `genefoundry-router` this
server mounts under the namespace `opentargets`, so `resolve_target` surfaces as
`opentargets_resolve_target`. Every tool is read-only. Errors are returned as the fleet's typed
envelope (`isError: true`, six error codes) and every response carries `_meta.next_commands`.
Example:
```text
resolve_target(query="BRAF") → ENSG00000157764
get_target_tractability(target="BRAF") → SM: Approved Drug, High-Quality Pocket, ...
get_drug_candidates(target="BRAF", disease="melanoma") → dabrafenib, vemurafenib, encorafenib, ...
get_target_disease_evidence(target="BRAF", disease="MONDO_0005105", datasource="intogen")
```
## Data & provenance
**Source.** The Open Targets Platform GraphQL API at
`https://api.platform.opentargets.org/api/v4/graphql`. No key is needed. Only
`api.platform.opentargets.org` is ever contacted. Each payload carries `data_version` (the Open
Targets data release from `meta.dataVersion`, e.g. `26.09`) and `retrieved_at`.
**Rate limit.** Open Targets publishes no request limit and asks bulk users to download its
releases. The default is 0.34 s spacing process-wide (~3 req/s) plus a 20,000/UTC-day cap, an
in-process cache (15 min), backoff on 429/5xx and an honest `User-Agent`. When the queue or
the daily budget is exhausted, a tool answers `rate_limited` with `retry_after_s`.
**Handling.** ChEMBL mechanism-of-action strings and clinical-report titles are fenced as
`{"kind": "untrusted_text", ...}` with provenance and a SHA-256 digest. Treat them as data,
not instructions.
**Licence and citation.** Open Targets Platform data are marked
[CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/); attribution and citation are
requested. Drug and mechanism data derive from ChEMBL (CC BY-SA 3.0). Cite:
> Buniello A, et al. Open Targets Platform: facilitating therapeutic hypotheses building in
> drug discovery. **Nucleic Acids Res. 2025;53(D1):D1467-D1475.** PMID 39657122.
## Documentation
- [Deployment](docs/deployment.md): Docker, the `OPENTARGETS_LINK_*` environment reference,
transports, Host/Origin allowlists and the rate-limit settings.
- [Design record](docs/superpowers/specs/2026-11-20-opentargets-link-design.md): scope, the
datasource allowlist and the upstream contracts.
- [AGENTS.md](AGENTS.md): engineering conventions, invariants, and make targets.
- [CHANGELOG.md](CHANGELOG.md): version history.
## Contributing
See [AGENTS.md](AGENTS.md). Write the failing test first. Unit tests replay recorded Open Targets
responses with `respx` and never touch the network. `make ci-local` is the
definition-of-done gate: format, lint, line budget, README standard, surface budget, mypy
`--strict`, and tests.
## License
Code: [MIT](LICENSE). Open Targets data: CC0 1.0, with attribution requested; ChEMBL-derived drug data CC BY-SA 3.0 ([NOTICE](NOTICE)).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues