genomoncology/biomcp releases

0.8.22 — 2026-04-30

New features

• Extended WHO Prequalification drug coverage to include active pharmaceutical
  ingredients (APIs) alongside finished pharmaceutical products;
  search drug --region who --product-type api filters explicit WHO searches
  to API rows. (232)
• Added the CDC CVX/MVX vaccine identity bridge for default and EU/all
  vaccine-brand drug search, backed by local CDC bundle downloads and explicit
  refresh via biomcp cvx sync. (233)
• Added CDC WONDER VAERS as the aggregate vaccine adverse-event source for
  search adverse-event --source <faers|vaers|all>, including combined
  vaccine search, health visibility, and source inventory/docs surfaces. (235)
• Added the local GTR-backed diagnostic entity with search/get diagnostic,
  first-use bundle refresh, explicit biomcp gtr sync, and the supporting
  health/docs/spec contract. (236)
• Expanded diagnostic into a local multi-source surface with WHO Prequalified IVD
  infectious-disease products, source-aware search/get behavior, and explicit
  biomcp who-ivd sync. (237)
• Added FDA 510(k) and PMA regulatory overlays to
  get diagnostic <id> regulatory, rendering source-aware FDA device status
  when records match and a truthful empty regulatory section when they do not.
  (238)
• Added opt-in diagnostic pivots to gene and disease cards with
  get gene <symbol> diagnostics and get disease <name_or_id> diagnostics,
  backed by local GTR and WHO IVD diagnostic search. (239)
• Extended article search follow-up guidance with cross-entity keyword hints:
  JSON _meta.next_commands now includes gene and drug pivots for recognizable
  keyword patterns, while markdown See also: adds discover and
  get disease recovery paths for short disease-like phrases. (242)
• Added opt-in clinical_features disease output backed by MedlinePlus
  clinical summaries, reviewed HPO phenotype mapping, source-native evidence
  URLs, and unsupported-disease empty states via
  get disease <name> clinical_features. (252, 253, 254)
• Added offline routing via biomcp suggest <question> so worked-example
  prompts can resolve to structured _meta.workflow guidance without requiring
  a live tool call. (279)
• Added workflow-ladder sidecars and schema-backed _meta.ladder[] payloads
  so routed workflows can carry explicit ladder steps across the CLI/MCP
  contract. (282)
• Added richer CLI help examples for batch/variant-limit usage and preserved
  the parser-level skill uninstall contract through current help and MCP guard
  surfaces. (217, 224)
• Added opt-in article fulltext source-boundary coverage and PDF fallback so
  article retrieval can truthfully report source limits while recovering PDF
  text when structured fulltext is unavailable. (255, 256)
• Added DDInter-backed drug-drug interaction workflows with
  biomcp drug interactions <name>, get drug <name> interactions, local
  bundle health, source-scoped empty wording, and biomcp ddinter sync.
  (303)

Docs

• Added BioASQ-oriented how-to routing rows to skills/SKILL.md for
  gene-disease association, gene localization/protein-function, drug regulatory
  date, and variant clinical-significance workflows, steering agents to
  structured-data shortcuts before article search. (240)
• Refreshed architecture, source-integration, and current-state docs so the
  shipped architecture and CLI guidance match the post-decomposition repo
  surface. (272, 273, 274, 275)
• Repaired backtick quoting in the mustmatch study/spec contract, published
  BioASQ benchmark guidance, and made the canonical SKILL.md render/install
  contract explicit for agents and operators. (276, 280, 281)
• Aligned the public landing-copy contract with the shipped suggest and
  workflow landing bullets so make test-contracts accepts the current README
  and docs homepage feature counts. (286)
• Refreshed source, licensing, versioning, CLI decomposition, diagnostic,
  clinical-features, API-key, quality-bar, and staging-demo docs to match the
  shipped v0.8.22 surface and current local-runtime key expectations. (222,
  272, 292, 304, 306, 314, 318, 329, 332, 341, 358, 362)

Fixes

• Changed custom CLI validation failures (BioMcpError::InvalidArgument) to exit
  2, matching clap parser failures and separating bad usage from runtime
  failures. (353)
• Fixed suggest so resistance-to-drug mechanism questions anchor starter
  commands on the drug instead of filler text. (291)
• Patched rustls-webpki to the safe release line and made make check enforce
  the cargo-deny advisory gate alongside the existing license gate. (290)
• Fixed cargo-install compatibility, deterministic EMA freshness checks, OLS4
  smoke routing, WHO drug JSON envelopes, and WHO API cache-limit wording so
  install, health, and explicit WHO/API drug searches stay stable. (218, 220,
  226, 232)
• Added compact diagnostic rows and capped disease diagnostic pivots so
  gene/disease diagnostic follow-ups stay scannable and bounded. (266, 267)
• Replaced the stale GTR sample with a live-valid GTR example and added
  zero-result recovery for the local diagnostic surface. (268, 269)
• Tightened entity-aware article follow-ups with a same-session loop-breaker
  for overlapping suggestions and PubMed ESearch cleanup for bounded
  question-format filler words. (277, 278, 283)
• Improved sparse drug research-code recovery, relational discover filtering,
  trial help example/flag consistency, and CTGov intervention alias preservation
  so generated follow-up commands stay useful and shell-safe for degraded or
  ambiguous inputs. (302, 310, 313, 338, 339, 340, 342, 351, 357)
• Repaired the targeted SPEC_SMOKE_ARGS lane so it stores stable smoke
  section IDs and resolves them to current mustmatch pytest item IDs at runtime;
  the quality ratchet now checks collectability before stale line-qualified
  selectors can reach make spec-smoke. (288)
• Hardened update and machine-readable CLI contracts: biomcp update fails
  closed when checksum sidecars are missing, biomcp --json version documents
  its plain-text exception, biomcp --json list remains parseable, and
  short-literal update ratchets were replaced with structural behavior checks.
  (331, 333, 352, 355)
• Stabilized MCP stdio no-input guidance, cBioPortal study download idle/stall
  handling, disease clinical-feature specs, OLS4 disease/discover fallback IDs,
  WikiPathways parallel tests, and protein ComplexPortal specs with regression
  coverage. (326, 336, 345, 346, 350, 354, 358)
• Surfaced Semantic Scholar authentication/degradation status in article search
  and honored Retry-After during authenticated retries so throttled searches
  disclose source health and back off correctly. (364, 365, 366)

Internal

• Completed release/docs contract cleanup for the 0.8.22 line so the latest
  release notes, ticket inventory, and release metadata stay aligned. (264, 265)
• Made make check include the public Python/docs contract lane and added
  make release-gate as the named local release-blocking command, so
  release-readiness docs and validation profiles share one contract. (287)
• Reworked SPEC_SMOKE_ARGS handling around stable smoke inventory and current
  mustmatch pytest item IDs, and cleaned up .march artifact handling for
  repo submission paths. (270, 271)
• Migrated the release gate to the spec-v2 corpus, made spec-pr self-contained
  for March kickoff, restored release-gate reliability, and kept stable smoke,
  canary, cache-warm, and test-contract lanes aligned with the current shipped
  docs/spec surface. (294, 297, 298, 299, 300, 301, 307, 308, 344)
• Decomposed oversized CLI modules, absorbed residual line-cap allowlists,
  clarified the benchmark harness as internal, and added runtime-wiring/line-cap
  ratchets so structural cleanup cannot reintroduce public-surface drift. (309,
  319, 320, 321, 322, 323, 324, 325, 334, 335, 343, 347)
• Strengthened release readiness with gene-all warm-budget coverage, local gate
  uv-build fixes, leaked-artifact cleanup, binary asset attributes, CI wrapper
  stale-binary warnings, Python 3.12/Rust 1.95 CI compatibility, self-contained
  local-data spec fixtures, and final v0.8.22 readiness audits before publish.
  (247, 258, 262, 263, 285, 289, 315, 316, 317, 327, 328, 330, 348, 363, 367)
• Recorded the diagnostic-entity, HPO clinical-feature, Obsidian vault,
  biomedical news, post-v0.8.21 shipped-surface, and neural-reranking reviews
  as architecture or deferred work unless runtime wiring shipped in the bullets
  above. (230, 243, 244, 245, 246, 284)

0.8.21 — 2026-04-16

New features

• Added article date-range filtering (--date-from/--date-to and
  --year-min/--year-max aliases) to search article. (182)
• Added EMA regulatory region (--region eu) to search drug and get drug,
  backed by local EMA human-medicine feeds; data auto-downloads on first use via
  biomcp ema sync. (203)
• Added entity-aware HATEOAS suggestions (_meta.next_commands) to article
  search JSON output; gene-anchored and keyword searches return contextually
  appropriate follow-up commands. (195, 202)
• Added article search fallback suggestions when discover resolves no entities,
  so dead-end queries get recovery paths. (204)
• Surfaced EuropePMC and PubMed first_index_date per article in
  search article --json; null for sources that do not expose index dates. (196)
• Expanded trial search with drug alias union so searches match trials registered
  under any approved drug name variant. (198)
• Surfaced opt-in section hints (More: block) in gene and disease base card
  responses; get gene <symbol> and get disease <name> now show funding
  and survival opt-in hints. (209)

Fixes

• Fixed search all --counts-only --json so sections correctly omit results,
  links, and total fields per the counts-only contract. (206)
• Disambiguated FAERS 404 (drug not in post-marketing database) from "found but
  no matching events"; added ClinicalTrials.gov fallback for adverse-event
  lookups when FAERS returns 404. (197)
• Improved error messages for study download 403/404 (actionable, with
  --list recovery hint) and DisGeNET 403 (env var name and docs URL). (212)
• Added study subcommand help descriptions and a regression test so help
  completeness is enforced going forward. (210)

Docs

• Refreshed architecture docs to the post-decomposition state: source map,
  modes prose, and MCP allowlist contract. (213)
• Fixed documentation drift: README source count, CHANGELOG WHO entry, and
  root help command count. (211)
• Published two blog posts on biomcp.org: daraxonrasib six-commands workflow
  article and a follow-up that removes biomcp-python references. (200, 201)

Internal

• Added mustmatch lint for spec bash blocks so spec sections that silently
  skip due to a missing pipe are now caught. (221)
• Untracked .march build artifacts from git so worktree state stays clean. (193)
• Added Compact Approval Fields spec block for EMA and EU regulatory data
  contract assertions. (194)
• Consolidated EnvVarGuard and TempDirGuard into a central test_support
  module shared across all test crates. (199)
• Added docs-only validation profile so make docs can run without triggering
  the full build gate. (205)
• Updated tar and rustls-webpki for active RustSec advisories. (207)
• Fixed 7 make test-contracts failures from assertion drift after the
  decomposition batch. (208)

0.8.20 — 2026-03-30

Security

• Remove partial API key from health output (067)
• Harden MCP allowlist for mutating study download paths (068)

Fixes

• batch --json always includes _meta contract field (069)
• Harden GWAS variant section against live decode failures (070)
• Fix gene-to-PGx and disease-to-drug See-also routing (077)
• Fix large PMC OA full-text downloads timing out (080)

New features

• Cross-entity See-also links: drug→PGx, gene→PGx, disease→study, zero-result→discover (076)
• Quality ratchet in make check: mustmatch lint, MCP allowlist, source-registry drift (075)
• Study top-mutated helper and disease literature fallback

BioASQ product gap fixes

• Disease definitions: show full "characterized by..." text instead of truncating (080)
• Disease phenotypes: distinguish defining features from comprehensive HPO list with ranked key-feature summaries (081)
• Protein isoforms: surface UniProt isoforms in gene protein section (082)
• Drug target families: show family name (e.g., "PARP") alongside individual targets (083)
• Protein legacy names: show legacy names alongside current gene symbols (084)
• Variant legacy nomenclature: show legacy names alongside HGVS (085)
• Drug mechanism labels: improve purine-analog mechanism coverage (086)
• Protein function truncation: gene-level protein view now shows full function text (087)
• Variant-specific targets: drug targets now show variant-specific entries from CIViC (087)

Improvements

• Reworked CLI help and skill catalog for self-teaching agent navigation (072-074)
• Replaced in-shell mustmatch shim with packaged mustmatch lint entrypoint (088)

Docs

• Architecture contract docs for See-also, discover grammar, CI, post-tag proof (078)
• Documentation consistency audit across public docs surface
• Repo cleanup for layout, example paths, tracked artifacts (079)

Full changelog: https://github.com/genomoncology/biomcp/compare/v0.8.19...v0.8.20

What's New

Charts

• Added 4 new chart types: pie, heatmap, stacked bar, and scatter (now 12 total) (041, 062)
• Added waterfall chart for mutation burden visualization (062)
• Added --cols/--rows flags for terminal chart dimensions (062)
• Added --width/--height flags for SVG/PNG canvas size (062)
• Added --scale flag for PNG DPI control (062)

EMA (European Medicines Agency)

• EU drug data now auto-downloads on first use (~9 MB) — no manual setup required (057)
• Data refreshes automatically after 72 hours; biomcp ema sync for manual refresh
• search drug, get drug regulatory/safety/shortage all support --region us|eu|all

Semantic Scholar

• Cleaned up health display for unauthenticated users (055)

CI

• Moved EMA-backed specs out of PR-blocking gate (056)

Docs

• Refreshed README and docs index with marketing voice (061)
• Added 18 per-source SEO landing pages (059, 060)
• Added 3 new blog posts: agent skills, article search, cancer genomics charts

Known CI issue

• spec/03-variant.md::GWAS Supporting PMIDs failed with "error decoding response body" — this is a transient GWAS Catalog API issue, not a BioMCP bug. The test passes when the upstream API is healthy.

Full Changelog: https://github.com/genomoncology/biomcp/compare/v0.8.18...v0.8.19

0.8.18 — 2026-03-25

New sources

• Added EMA regional drug coverage backed by local EMA human-medicine feeds,
  so search drug, get drug, and get drug shortage support
  --region us|eu|all across EU regulatory status, DHPCs, referrals, PSUSAs,
  shortages, and the existing US label surface. (043, 044)
• Added the BioASQ benchmark module with benchmarks/bioasq/ingest_public.py,
  dataset and validity manifests, and the published BioASQ benchmark
  reference at docs/reference/bioasq-benchmark.md. (045, 046)

Improvements

• search drug now defaults to --region all, get drug --region is
  surfaced in help, OpenFDA label fallback prefers exact brand-name matches,
  and OpenTargets drug-indication lookups are corrected for mixed US/EU
  workflows. (043, 044)
• S2_API_KEY is now optional for Semantic Scholar-backed article
  enrichment and helpers: unauthenticated calls use the shared Semantic
  Scholar pool at 1 req/2sec, while authenticated calls keep the 1 req/sec
  quota with retry backoff. (047)

New sources

• WikiPathways as a third pathway source alongside Reactome and KEGG
• KEGG pathway integration
• Semantic Scholar search leg for search article (when S2_API_KEY is set), with directness-first merged ranking across PubTator3, Europe PMC, and Semantic Scholar
• gnomAD constraint metrics for variant-interpretation context
• Human Protein Atlas tissue expression in gene output
• ComplexPortal protein complex data
• DisGeNET gene-disease association scores

New commands

• biomcp discover <query> — free-text concept resolution via OLS4, with optional UMLS crosswalks and MedlinePlus context
• biomcp article batch <id>... — compact multi-article summary cards with parallel fetch (limit 20)

Improvements

• Pathway progressive disclosure and exact-title-first ranking across sources
• Source labels and evidence URLs across all entity detail outputs (Markdown and JSON)
• get gene / get drug misses now return discovery-backed canonical suggestions instead of dead-end errors
• Typed variant retrieval accepts shorthand forms and long-form protein notation (e.g. AKT2 p.Pro50Thr)
• search all cross-routing stays inside controlled typed fallback rules
• Compact answer-bearing summaries for approvals, population frequencies, and disease/variant evidence
• Deepened OpenTargets integration with tractability and genetic-association sections
• JATS-aware PMC full-text extraction for article detail views
• MCP chart responses return SVG inline as base64 image payload
• --debug-plan routing metadata for search all / search article
• Paper/reproducibility artifacts: paper/, CONTRIBUTING.md, CODE_OF_CONDUCT.md, .zenodo.json

Fixes

• Fixed drug interaction output returning empty for supported drugs
• Fixed g:Profiler enrichment timeouts
• Fixed DisGeNET template crash on sparse/null payloads
• Fixed default article retraction filtering (only confirmed retractions excluded)
• Fixed OpenTargets knownDrugs → drugAndClinicalCandidates upstream API migration

Full Changelog: https://github.com/genomoncology/biomcp/compare/v0.8.16...v0.8.17

What's Changed

• ci: add contracts job to PR CI and make test-contracts local target by @imaurer in https://github.com/genomoncology/biomcp/pull/193
• demo: upgrade Streamable HTTP client to BRAF V600E end-to-end workflow by @imaurer in https://github.com/genomoncology/biomcp/pull/194
• Fix stable totals for age-filtered clinical trial search by @imaurer in https://github.com/genomoncology/biomcp/pull/195
• Rename MCP tool from shell to biomcp by @imaurer in https://github.com/genomoncology/biomcp/pull/196
• fix: use TypeAlias for Python 3.11 compatibility in streamable HTTP demo by @imaurer in https://github.com/genomoncology/biomcp/pull/197
• demo: polish Streamable HTTP demo with README, CLI args, and coherent BRAF/melanoma scenario by @imaurer in https://github.com/genomoncology/biomcp/pull/198
• Fix trial age filtering for sub-year units and stabilize CTGov cursor across page boundaries by @imaurer in https://github.com/genomoncology/biomcp/pull/199
• ci: add version-sync check to catch manifest drift by @imaurer in https://github.com/genomoncology/biomcp/pull/200
• Fix federated article search offset/sort semantics and add correctness spec by @imaurer in https://github.com/genomoncology/biomcp/pull/201
• Simplify streamable HTTP demo script by @imaurer in https://github.com/genomoncology/biomcp/pull/202
• Add parser-level validity gate for generated next_commands by @imaurer in https://github.com/genomoncology/biomcp/pull/203
• Support fractional age values for trial eligibility filtering by @imaurer in https://github.com/genomoncology/biomcp/pull/204
• Remove tracked .climb scratch files and add CI guardrail by @imaurer in https://github.com/genomoncology/biomcp/pull/205
• Add protein entity spec coverage by @imaurer in https://github.com/genomoncology/biomcp/pull/207
• Add CITATION.cff and citation pointers by @imaurer in https://github.com/genomoncology/biomcp/pull/206
• Add WARN_PAGE_THRESHOLD constant, next_commands property tests, and improved article error copy by @imaurer in https://github.com/genomoncology/biomcp/pull/208
• Add spec suite gate to PR CI by @imaurer in https://github.com/genomoncology/biomcp/pull/209
• Move age filter to cheap CTGov path and add traversal page cap by @imaurer in https://github.com/genomoncology/biomcp/pull/210
• Centralize CTGov search parameter construction by @imaurer in https://github.com/genomoncology/biomcp/pull/211
• Fix retraction filter bypass and leading-NOT eligibility parsing by @imaurer in https://github.com/genomoncology/biomcp/pull/212
• Clarify trial filter help: facility modes, phase 1/2 semantics, sex all no-op by @imaurer in https://github.com/genomoncology/biomcp/pull/213
• Split volatile live-network specs out of PR CI gate by @imaurer in https://github.com/genomoncology/biomcp/pull/214
• Add native chart rendering to study commands via kuva by @imaurer in https://github.com/genomoncology/biomcp/pull/215
• Build contracts CI against branch biomcp binary by @imaurer in https://github.com/genomoncology/biomcp/pull/216
• Signal approximate totals for age-only trial count searches by @imaurer in https://github.com/genomoncology/biomcp/pull/217
• Upgrade quinn-proto and PyJWT to fix security vulnerabilities by @imaurer in https://github.com/genomoncology/biomcp/pull/218
• Add guide workflows page to public docs by @imaurer in https://github.com/genomoncology/biomcp/pull/219
• Add cross-entity pivot workflow guide by @imaurer in https://github.com/genomoncology/biomcp/pull/221
• Add search all workflow guide by @imaurer in https://github.com/genomoncology/biomcp/pull/222
• Add Semantic Scholar article enrichment, citation graph, and recommendations by @imaurer in https://github.com/genomoncology/biomcp/pull/223
• Release v0.8.16 by @imaurer in https://github.com/genomoncology/biomcp/pull/224

Full Changelog: https://github.com/genomoncology/biomcp/compare/v0.8.15...v0.8.16

0.8.15 — 2026-03-11

• Fixed the planning-docs CI path regression so release validation uses the
  repo-local planning fixtures by default instead of an Ian-local absolute
  path. This is the fix from PR #191 that unblocks release packaging on
  GitHub Actions.
• Refreshed the public discovery docs so search all is taught as the unified
  cross-entity entry point in the README and docs index. This is the docs
  alignment from PR #190.

What's new in v0.8.14

• Newcomer docs: new getting-started guide for remote Streamable HTTP clients — how to start biomcp serve-http, use /mcp, and check /health and /readyz
• Runnable demo: demo/streamable_http_client.py — a self-contained PEP 723 script using the official Python MCP SDK, runnable with uv run --script
• Docs home: remote HTTP server section added to docs/index.md so the transport is visible from first visit
• README: updated with remote HTTP quick-start and demo reference
• serve-sse migration guidance: kept visible for users still on the legacy SSE path

See the CHANGELOG for full details.

See CHANGELOG.md for full details.

What's Changed

• Make all search subcommands accept bare positional arguments by @imaurer in https://github.com/genomoncology/biomcp/pull/160
• Update CHANGELOG and docs for releases 0.8.5–0.8.11 by @imaurer in https://github.com/genomoncology/biomcp/pull/161
• Harden CLI for agent use: multi-token args, --until alias, variant error guidance by @imaurer in https://github.com/genomoncology/biomcp/pull/162
• Replace SKILL.md with experiment-validated version, remove use-case files by @imaurer in https://github.com/genomoncology/biomcp/pull/163
• Improve CLI usability: variant fallback, NCT validation, bare-entity shortcuts, and better timeouts by @imaurer in https://github.com/genomoncology/biomcp/pull/164
• Auto-discover skill install target using cross-tool standard by @imaurer in https://github.com/genomoncology/biomcp/pull/165
• Refresh skills reference material and add schema drift validation by @imaurer in https://github.com/genomoncology/biomcp/pull/166
• Add local cBioPortal study adapters with study query CLI by @imaurer in https://github.com/genomoncology/biomcp/pull/167
• Add cohort filtering, survival aggregates, and group comparison for cBioPortal studies by @imaurer in https://github.com/genomoncology/biomcp/pull/168
• Add multi-omics cross-table join for study filtering by @imaurer in https://github.com/genomoncology/biomcp/pull/169
• Add Fisher's exact p-value to gene co-occurrence analysis by @imaurer in https://github.com/genomoncology/biomcp/pull/170

Full Changelog: https://github.com/genomoncology/biomcp/compare/v0.8.11...v0.8.12

Changes

• Evidence URLs and citations on entity outputs (#156)
• Gene enrichment — GTEx expression data, DGIdb druggability, ClinGen gene-disease validity (#157)
• Streamlined CI — PR checks are now Rust-only (~3 min); release workflow consolidates validation, binary builds, PyPI wheels, and docs deployment into a single pipeline (#159)

What's Changed

• 200: search-all output polish, link safety, and infrastructure hygiene by @imaurer in https://github.com/genomoncology/biomcp/pull/144
• Delete docs/changelog.md by @imaurer in https://github.com/genomoncology/biomcp/pull/145
• 204: trial search improvements and PyPI trusted publisher by @imaurer in https://github.com/genomoncology/biomcp/pull/146

Full Changelog: https://github.com/genomoncology/biomcp/compare/v0.8.9...v0.8.10

What's Changed

• 198-biomcp-search-all: add cross-entity search all command by @imaurer in https://github.com/genomoncology/biomcp/pull/141
• 198: bump version to 0.8.9 by @imaurer in https://github.com/genomoncology/biomcp/pull/142

Full Changelog: https://github.com/genomoncology/biomcp/compare/v0.8.8...v0.8.9

Output Cleanup & Help Discoverability

Output Deduplication

• Population data shown exactly once (was rendered 3x with inline summary + pipe table + AF line)
• Conservation, AlphaGenome, interactions converted from pipe tables to key-value pairs
• Adverse event reactions/outcomes converted from single-column tables to bullet lists
• All entity metadata headers standardized to plain Key: Value (no bold)

Actionable Footers

• Sections: replaced with More: / All: showing copy-pasteable biomcp get commands
• Related: replaced with See also: listing full biomcp commands, one per line
• All 11 entity templates updated consistently

Help Discoverability

• biomcp list starts with quickstart block showing example commands
• Skills tip added to list output
• biomcp list skill now works (aliases to skill list)
• list enrich and list batch are first-class help pages
• --biomarker documented in list trial, --since documented in list article
• list phenotype and list gwas expanded with workflow examples
• health shows affected features when APIs fail

Quality

• 349 Rust tests, 0 clippy warnings
• 117 VV executable documentation contracts passing

What's Changed

• 193-biomcp-help-fixes: improve help discoverability and completeness by @imaurer in https://github.com/genomoncology/biomcp/pull/138

Full Changelog: https://github.com/genomoncology/biomcp/compare/v0.8.6...v0.8.7

What's Changed

• 191: fix trial filter accuracy — age post-filter, exclusion detection, pathway source by @imaurer in https://github.com/genomoncology/biomcp/pull/137

Full Changelog: https://github.com/genomoncology/biomcp/compare/v0.8.5...v0.8.6

What's Changed

• fix: install.sh resolves latest to release with assets by @imaurer in https://github.com/genomoncology/biomcp/pull/134
• 189: Enforce pagination and validation contracts by @imaurer in https://github.com/genomoncology/biomcp/pull/135
• 190: Harden input safety, SSRF prevention, and pagination contracts by @imaurer in https://github.com/genomoncology/biomcp/pull/136

Full Changelog: https://github.com/genomoncology/biomcp/compare/v0.8.4...v0.8.5

What's Changed

• 187-biomcp-ci-simplify: simplify CI triggers, cache protoc, bump 0.8.4 by @imaurer in https://github.com/genomoncology/biomcp/pull/133

Full Changelog: https://github.com/genomoncology/biomcp/compare/v0.8.3...v0.8.4

Changes

• Remove NCI vocabulary entities — Deleted organization, intervention, and biomarker search entities (search-only wrappers around NCI CTS vocabulary API with no unique value over trial search). Entity count: 15 → 12.
• Fix word-boundary regex — Punctuated biomarker tokens like HER2+, ER+, PD-L1 now match correctly in eligibility keyword filtering.
• Documentation consistency — Synced pyproject.toml version, added changelog entries for 0.8.1–0.8.3, updated CLI/quick reference with all helpers, reconciled README and docs/index helper blocks.
• Eligibility inclusion/exclusion post-filter (from 0.8.3 prior work) — Reduces exclusion-only false positives in trial matching.

Stats

• 326 Rust tests passing
• 366 VV tests passing
• 27 files changed, +131 / -1,740 lines

What's Changed

• 181: location-level post-filter for facility+geo searches by @imaurer in https://github.com/genomoncology/biomcp/pull/130

Full Changelog: https://github.com/genomoncology/biomcp/compare/v0.8.1...v0.8.2

What's Changed

• Fix CI: docs deploy, release builds, flaky contracts by @imaurer in https://github.com/genomoncology/biomcp/pull/127
• Fix skill install --force EEXIST on macOS by @imaurer in https://github.com/genomoncology/biomcp/pull/128

Full Changelog: https://github.com/genomoncology/biomcp/compare/v0.8.0...v0.8.1

What's Changed

• Rust 080 by @imaurer in https://github.com/genomoncology/biomcp/pull/124

Full Changelog: https://github.com/genomoncology/biomcp/compare/v0.7.3...v0.8.0

Final legacy Python BioMCP release.

What's Changed

• chore(deps): Bump astral-sh/setup-uv from 6 to 7 by @dependabot[bot] in https://github.com/genomoncology/biomcp/pull/76
• oncokbapi by @azingalis-go in https://github.com/genomoncology/biomcp/pull/77

Full Changelog: https://github.com/genomoncology/biomcp/compare/v0.7.0...v0.7.1

Adds --assembly option to biomcp variant get command, allowing users to specify genome assembly (hg19 or hg38) when retrieving variant annotations from MyVariant.info API.

Problem: The MyVariant.info API supports an assembly query parameter, but this was not exposed in the BioMCP CLI or MCP tools, forcing users to work exclusively with hg19 coordinates.

Solution: Added full assembly parameter support across the entire variant getter stack with comprehensive testing and documentation.

Addresses Issues:
https://github.com/genomoncology/biomcp/issues/69
https://github.com/genomoncology/biomcp/issues/72

Addresses https://github.com/genomoncology/biomcp/pull/68

Summary of Changes Made:

1. Fixed Character Encoding Issue

• Modified getter.py to explicitly use UTF-8 encoding when reading resource files
• This fixes the Windows cp1252 encoding error

1. Removed External Sequential-Thinking References

• Updated docs/blog/researcher-persona-resource.md:
  • Removed the separate sequential-thinking server from the JSON config
  • Changed references from "Sequential Thinking MCP" to "built-in sequential thinking"
  • Updated text to clarify the think tool is included in BioMCP

Fix Windows compatibility and update Docker documentation

Fix fcntl import error on Windows (Issue ModuleNotFoundError: No module named 'fcntl' #57)

Added conditional import with try/except for fcntl module
File locking now only applies on Unix systems
Windows users get full functionality without file locking
Refactored cache functions to reduce complexity
Add Docker build instructions to README (Issue Docker image not found #58)

Added docker build command before docker run
Clarifies that biomcp:latest is a local build, not from Docker Hub

• feat: Add comprehensive OpenFDA integration with 12 new tools

  Implements full OpenFDA API integration providing access to FDA regulatory data
  for drug safety, device events, approvals, recalls, and shortages.

  New Modules:

  • adverse_events.py: Search/retrieve drug adverse event reports (FAERS)
  • device_events.py: Search/retrieve device malfunction reports (MAUDE)
  • drug_labels.py: Search/retrieve FDA drug labels (SPL)
  • drug_approvals.py: Search/retrieve drug approval records (Drugs@FDA)
  • drug_recalls.py: Search/retrieve drug recall notices (Enforcement)
  • drug_shortages.py: Search/retrieve drug shortage data with 24hr caching

  Key Features:

  • 12 new MCP tools (6 searchers + 6 getters) for AI agent integration
  • Flexible API key support via parameter, env var (OPENFDA_API_KEY), or none
  • Smart device search with wildcard matching (no hardcoding)
  • Robust handling of polymorphic FDA fields (string/list types)
  • Genomics device filtering for precision medicine focus
  • Rate limiting: 40 req/min (no key) or 240 req/min (with key)

  CLI Enhancements:

  • New 'biomcp openfda' command with 6 subcommands
  • All commands support --api-key parameter
  • Pagination support with --page and --limit

  Documentation:

  • Added openfda-prompts.md with 30+ example prompts
  • Updated MCP tools reference (now 35 tools total)
  • Comprehensive API key usage examples
  • Integration patterns for complex safety analyses

  Testing & Quality:

  • All quality checks passing (ruff, mypy, pre-commit)
  • MCP integration tests updated for new tool count
  • API key priority handling verified
  • Endpoint registry updated with FDA endpoints

  This integration enables comprehensive FDA regulatory data access for
  drug safety assessment, post-market surveillance, and treatment planning
  in precision oncology workflows.

Co-authored-by: Justin Yeakley [email protected]

Restructure and improve documentation

• Simplified navigation structure from 10 to 5 top-level sections
• Removed expandable/collapsible navigation in favor of clean sections display
• Fixed code block horizontal scrolling issues across all documentation
• Converted grid card layouts to stacked format for better readability
• Removed all emojis from headers for professional appearance
• Made documentation more concise, especially the overview page
• Fixed broken anchor links and embedded ASCII diagrams inline
• Removed unnecessary sections (migrations, breaking changes, feedback)
• Synced outdated docs changelog with main CHANGELOG.md (v0.4.0 → v0.6.2)
• Added CSS improvements for code block wrapping and responsive design
• Improved overall user experience with cleaner, flatter navigation

The documentation now provides optimal onboarding, clear navigation paths,
and professional presentation suitable for production deployment.

Add NCI Clinical Trials Search API integration

Integrates the National Cancer Institute's Clinical Trials Search API to provide
enhanced cancer trial search capabilities alongside existing ClinicalTrials.gov support.

New Features

Core NCI Integration

• Added dual source support for trial search/getter (ClinicalTrials.gov + NCI)
• Implemented NCI API key handling via environment variable or parameter
• Added advanced trial filters: biomarkers, prior therapy, brain metastases

New NCI-Specific Tools (6 MCP tools + CLI commands)

• Organizations: Search/get cancer centers, hospitals, research institutions
• Interventions: Search/get drugs, devices, procedures, biologicals
• Biomarkers: Search trial eligibility biomarkers (reference genes, branches)
• Diseases: Search NCI's controlled vocabulary of cancer conditions

API Features

• Real-time access to NCI's curated cancer trials database
• Support for all NCI API parameters and filters
• Automatic cBioPortal integration for gene searches
• Proper parameter mapping (org_city, org_state_or_province, etc.)
• Comprehensive error handling for Elasticsearch limits

Documentation

• Added NCI tutorial with example prompts: docs/tutorials/nci-prompts.md
• Created API parameter reference: docs/api-changes/nci-api-parameters.md
• Updated CLAUDE.md with NCI usage instructions and parameter notes

CLI Integration

# New commands
biomcp organization search "MD Anderson" --api-key YOUR_KEY
biomcp intervention search pembrolizumab --type Drug --api-key YOUR_KEY
biomcp biomarker search --name "PD-L1" --api-key YOUR_KEY
biomcp disease search melanoma --source nci --api-key YOUR_KEY

# Enhanced trial commands
biomcp trial search --condition melanoma --source nci --api-key YOUR_KEY
biomcp trial get NCT04280705 --source nci --api-key YOUR_KEY

Requires NCI API key from: https://clinicaltrialsapi.cancer.gov/

Dependency fix for alphagenome that prevented pypi publish

feat: Complete streamable HTTP transport implementation with event resumption

Implements full MCP-compliant streamable HTTP transport protocol (spec 2025-03-26) with
production-ready features including Last-Event-ID support for connection resumability.

Transport Layer:

• Add streamable HTTP mode to CLI server (biomcp run --mode streamable_http)
• Enable FastMCP's native /mcp endpoint for streamable HTTP transport
• Support configurable host/port options for HTTP-based transports
• Maintain backward compatibility with legacy SSE endpoints

Event Resumption:

• Implement in-memory event store with configurable retention (1000 events/stream, 15min TTL)
• Add Last-Event-ID header support for SSE connection recovery
• Automatic event replay on client reconnection
• Background cleanup task to manage memory usage
• Full test coverage with 6 comprehensive test scenarios

Cloudflare Worker:

• Update worker to support both GET and POST methods on /mcp endpoint
• Add session ID handling and event streaming support
• Improve error handling and request proxying

Documentation:

• Add comprehensive streamable HTTP deployment guide
• Document event resumption usage and client implementation
• Update tutorials with HTTP transport examples
• Add remote server configuration for Claude Desktop

Testing:

• Add event store unit tests covering all resumption scenarios
• Test event limits, cleanup, multi-stream support
• Verify UUID-based event IDs and replay functionality

This provides a robust, scalable deployment option with automatic recovery from network
interruptions, making BioMCP suitable for production cloud deployments.

Add BioThings integration for gene, drug, and disease data access

This commit adds comprehensive integration with the BioThings API suite (MyGene.info,
MyChem.info, MyDisease.info) to provide real-time access to biomedical databases.

Core Integration Features

New MCP Tools (3 tools added, total now 17)

• gene_getter: Query MyGene.info for gene information (symbols, names, summaries)
• drug_getter: Query MyChem.info for drug/chemical data (formulas, indications, mechanisms)
• disease_getter: Query MyDisease.info for disease information (definitions, synonyms, ontologies)

Unified Search/Fetch Enhancement

• Added gene, drug, disease as new searchable domains alongside article, trial, variant
• Integrated into unified search syntax: search(domain="gene", keywords=["BRAF"])
• Query language support: gene:BRAF, drug:pembrolizumab, disease:melanoma
• Full fetch support: fetch(domain="drug", id="DB00945")

Key Changes

1. Search Tool Compliance

• Made call_benefit optional (was required) in search tool
• query is now the ONLY required parameter as per OpenAI spec
• Preserved call_benefit functionality for BigQuery logging and LLM accuracy

2. Fetch Tool Compliance

• Changed parameter from id_ to id (OpenAI expects exact name)
• Made domain optional with intelligent auto-detection
• id is now the ONLY required parameter as per OpenAI spec
• Added domain auto-detection logic:
  • NCT* → trial
  • DOIs (contains "/" with numeric prefix) → article
  • Pure numeric → article (PMID)
  • rs* or HGVS notation → variant

3. OpenAPI Specification

• Added version field to FastMCP initialization (required by OpenAI)
• Ensures valid OpenAPI 3.1.0 spec is served in worker mode

4. CI/CD Improvements

• Separated integration tests from unit tests in CI pipeline
• Integration tests now run in optional job (allowed to fail)
• Prevents flaky test failures from blocking deployments
• Added pytest markers and configuration for test categorization

5. Documentation Updates

• Added comprehensive testing guide
• Updated Claude Desktop tutorial with new optional parameters
• Created detailed OpenAI MCP compliance report
• Added testing documentation to mkdocs navigation

Testing

• All 438 tests passing (including new domain auto-detection tests)
• Quality checks pass (linting, formatting, type checking)
• Integration tests separated to improve CI reliability

Breaking Changes

None - all changes are backward compatible. Existing code will continue
to work as before.

Fixes OpenAI MCP validation errors:

• "search action query parameter is not the only required"
• "fetch action does not have an id parameter"
• "fetch action id parameter is not the only required"

feat: Optimize article_searcher performance and suppress non-critical ASGI errors

Performance Optimizations for article_searcher

• Add result caching with 5-minute TTL using SHA256 cache keys
• Leverage shared context to avoid redundant gene validations
• Implement infrastructure for batching multiple searches
• Cache cBioPortal summaries to reduce API calls
• Maintain full backward compatibility with existing API

ASGI Error Suppression

• Add logging filter to suppress non-critical Starlette middleware errors
• Filter out "Exception in ASGI application" and "http.response.body" assertion errors
• Clean up logs from known streaming response issues that don't affect functionality
• Apply filters to uvicorn, starlette, and fastapi loggers

Implementation Details

• Create search_optimized.py module with caching and context-aware search
• Add get_cache() function to request_cache.py for named cache instances
• Implement ASGIErrorFilter class for intelligent log filtering
• Update article_searcher to use optimized implementation
• Fix all related tests to work with new function signatures

Testing

• All article_searcher tests passing with updated mock expectations
• No breaking changes to existing functionality
• External cBioPortal API test failure unrelated to these changes

Complete HTTP centralization and improve code quality

This commit completes the HTTP request centralization effort and addresses
all code quality issues identified during review.

HTTP Centralization

• Remove deprecated CBioPortalClient class from external.py
• Delete obsolete retry_utils.py module (retry logic now in centralized client)
• Refactor cBioPortal integrations to use new CBioPortalExternalClient
• Create CBioHTTPAdapter for cBioPortal-specific HTTP handling
• Fix circular import issues between modules
• Update all tests to use new client architecture

Code Quality Improvements

• Refactor complex methods into smaller, focused functions
• Add comprehensive docstrings to all public methods
• Fix all mypy type errors with proper annotations
• Replace magic numbers with named constants
• Fix linting issues (ruff, pre-commit hooks)
• Improve error handling and encapsulation

Test Reliability

• Make KRAS integration test more robust with retry logic
• Add graceful skipping when APIs return no data
• Remove 2 obsolete skipped tests for thinking functionality
• Fix cache clearing to use proper API instead of private attributes
• Add test constants file for maintainability
• Fix AlphaGenome test to handle "not installed" case

Documentation

• Create HTTP_CLIENT_GUIDE.md for centralized HTTP client usage
• Create MIGRATION_EXAMPLES.md showing before/after patterns
• Create ERROR_HANDLING.md documenting error types and handling
• Create INTEGRATION_TESTING.md for handling flaky tests
• Add all new docs to mkdocs.yml in alphabetical order
• Update README with references to new documentation

Build System

• Add make update-endpoints target to regenerate THIRD_PARTY_ENDPOINTS.md
• Add make check-docs to verify all docs are in mkdocs.yml
• Create endpoint registry for tracking all external APIs
• Add pre-commit hooks for endpoint updates and doc checking
• Configure make docs to auto-update endpoints before serving
• Add PyYAML dependency for mkdocs.yml parsing

Pre-commit Configuration

• Add hook to regenerate THIRD_PARTY_ENDPOINTS.md when registry changes
• Add hook to check all docs are referenced in mkdocs.yml
• Update hooks to use uv run for proper environment handling
• Reorder hooks to prevent prettier/generation conflicts

The codebase now has:

• Fully centralized HTTP request handling
• Comprehensive documentation
• Reliable integration tests
• Automated documentation management
• Clean separation of concerns

This fixes the issue where fetching Europe PMC preprints by DOI would fail
with "Error 400: Could not retrieve publications". The system now correctly
routes DOI requests to Europe PMC API.

Changes:

• Add fetch_europe_pmc_article() function to query Europe PMC by DOI
• Add is_doi() and is_pmid() functions for identifier type detection
• Update _article_details() to route DOIs to Europe PMC, PMIDs to PubTator3
• Update article_getter MCP tool to accept both PMIDs and DOIs
• Update fetch unified tool to support DOIs for article domain
• Update CLI article get command to handle mixed PMID/DOI requests
• Add proper error handling for invalid identifiers

Tests:

• Add comprehensive test suite for DOI detection and Europe PMC fetching
• Add BDD test scenario for fetching preprints by DOI
• Fix router test to handle new identifier validation behavior

Documentation:

• Update CLAUDE.md with DOI support notes for tools
• Update README.md with DOI examples
• Update CLI documentation with DOI support and examples
• Add changelog entry for this enhancement

This enables seamless fetching of both published articles (via PMID) and
preprints (via DOI) through a unified interface.

This update enhances the AlphaGenome integration to support per-request API keys,
enabling secure usage in hosted environments where users provide their own keys.

Key Changes:

Added optional api_key parameter to predict_variant_effects() function
Enhanced MCP tool to recognize "My AlphaGenome API key is..." pattern in user messages
Added --api-key CLI option that overrides environment variables
Improved error messages with clear ACTION REQUIRED prompts
Implementation Details:

API key precedence: parameter > environment variable > prompt user
Natural language pattern recognition for AI assistants
Maintains backward compatibility with ALPHAGENOME_API_KEY env var
Enhanced error message guides users to provide their key inline
Documentation:

Created comprehensive API key handling guide
Updated setup documentation to prioritize per-request keys
Added examples showing API key inclusion in prompts
Testing:

Fixed all test assertions for new error message format
Added comprehensive test coverage for API key functionality
All 384 tests passing with 100% coverage
Both make check and make test pass successfully
Security Enhancement:

Added comprehensive sanitization to Cloudflare Worker BigQuery logging
API keys and other sensitive fields are now redacted as "[REDACTED]"
Recursive sanitization handles nested objects and arrays
Prevents sensitive data from being stored in analytics logs
This feature enables BioMCP to be safely hosted in multi-user environments
while complying with AlphaGenome's terms of service. Users can now provide
their own API keys per request without sharing credentials, and those keys
are protected from being logged to BigQuery.

AlphaGenome as an optional dependency to predict variant effects on gene regulation, complementing existing database lookups with AI predictions.

Features:

• Add alphagenome_predictor MCP tool for variant effect predictions
• Predict gene expression, chromatin accessibility, and splicing changes
• Support tissue-specific predictions using UBERON ontology
• Configurable significance thresholds for log2 fold changes
• 30-minute result caching to minimize API calls
• CLI command: biomcp variant predict chr7 140753336 A T

Implementation:

• Core prediction module in src/biomcp/variants/alphagenome.py
• Lazy imports to keep AlphaGenome optional
• Input validation for chromosomes (chr1-22, X, Y, M/MT) and nucleotides
• Graceful error handling with helpful messages for missing API key/package
• Integration with existing caching infrastructure

Testing:

• 13 comprehensive unit tests covering all edge cases
• BDD scenarios for user workflows
• Mock integration tests for API interactions
• 100% code coverage achieved

Documentation:

• Setup guide with API key configuration
• Prompt examples for common use cases
• Docker deployment instructions
• Updated CLAUDE.md with AlphaGenome guidelines

Infrastructure:

• Dockerfile updated to clone and install AlphaGenome
• docker-compose.yml includes ALPHAGENOME_API_KEY environment variable
• Suppress harmless protobuf warnings in test output
• Add alphagenome to deptry ignore list (DEP003)

Breaking Changes: None - AlphaGenome is fully optional

Requirements:

• AlphaGenome API key from https://deepmind.google.com/science/alphagenome
• Manual installation: git clone && pip install ./alphagenome

• cBioPortal Integration

• Fixed lat/long for prompt

• Added verbiage to biomcp to clarify usage to AI Clients

  BREAKING CHANGES:

  • Sequential thinking moved from search(domain="thinking") to dedicated think tool
  • Think tool is now MANDATORY before any search operations
  • Search query parameter changed from optional to required with empty default

  Added:

  • Dedicated think tool for systematic biomedical analysis (required first step)
  • 10 individual tools restored: article_searcher/getter, trial_searcher/getter + 3 detail getters, trial_locations_getter, variant_searcher/getter
  • Thinking usage tracker with automatic reminders in search results
  • Enhanced cBioPortal integration in individual tools via include_cbioportal parameter
  • Centralized cbioportal_helper module to reduce code duplication
  • Location parameter validation for trial searches

  Fixed:

  • MyVariant.info timeout issues (now uses configured 120s timeout)
  • Added myvariant to aggressive retry domains
  • Optimized BRAF V600E query pattern to prevent timeouts
  • Improved timeout error messages with actionable suggestions

  Improved:

  • Total of 13 MCP tools: 3 core (think, search, fetch) + 10 individual
  • Better code organization with dedicated helper modules
  • Enhanced type safety with proper annotations
  • Consistent error handling and logging
  • ChatGPT compatibility with simplified query parameter

  Updated all documentation to reflect new tool structure and mandatory think-first workflow.

API Simplification:

• Consolidate 10 separate MCP tools into 2 unified tools (search and fetch)
• Implement unified query language for cross-domain searches
• Add domain-specific handlers with OpenAI MCP format compliance

Reliability & Fault Tolerance:

• Add rate limiting with token bucket and sliding window algorithms
• Implement retry logic with exponential backoff for transient failures
• Add circuit breaker pattern to prevent cascading failures
• Fix global state issues with session-based thinking management

Observability & Monitoring:

• Add comprehensive performance metrics collection system
• Track request counts, success rates, and response time percentiles
• Add MCP tool for retrieving performance metrics
• Integrate metrics tracking into HTTP client and router

Code Quality Improvements:

• Refactor complex functions to meet cyclomatic complexity standards
• Extract router handlers to reduce code complexity
• Replace magic numbers with named constants throughout codebase
• Fix trial fetch error handling for wrapped API responses

Testing & CI/CD:

• Add comprehensive test coverage for error scenarios
• Add circuit breaker pattern tests
• Add GitHub Actions workflows for CI/CD
• Configure Dependabot for automated dependency updates

Infrastructure:

• Create modular HTTP client with retry and circuit breaker support
• Add domain-specific retry configurations
• Implement proper error handling hierarchy
• Add session management for concurrent thinking operations

Additional Sources:

• Added additional article search (bioRxiv, medRxiv, europe pmc)
• Added additional variant search capabilities (TCGA/GDC, 1000 Genomes)

Other:

• MCP Review Verification
• Updated Big Query logging to ignore thinking

Breaking Changes:

• API consolidated from 10 tools to 2 - may require client updates

Initial remote policies added

Sequential thinking inside of biomcp.

v0.1.11