BioMCP Documentation

BioMCP provides structured access to a wide variety of upstream biomedical databases, organized by the type of information they provide. While the main User Guide is organized by entities (genes, variants, articles, etc.), the Sources documentation helps you select a provider based on your specific research goal, the keyword you are targeting, or the required provenance.

Common use cases include:

• Literature & Research: PubMed (articles/annotations), Semantic Scholar (TLDRs/citations).
• Clinical & Regulatory: ClinicalTrials.gov (recruiting studies), OpenFDA (recalls/labels), EMA (EU regulatory), WHO Prequalification (vaccines).
• Genomics & Variants: ClinVar (clinical significance), gnomAD (population frequency), CIViC (clinical variant evidence), OncoKB (oncology actionability).
• Proteins & Pathways: UniProt (protein cards), Reactome (pathway records), KEGG (pathway IDs).
• Pharmacology & Drugs: ChEMBL (drug-target activity), DDInter (drug-drug interactions), PharmGKB / CPIC (pharmacogenomics).

The biomcp_news_spike package provides a structured implementation for biomedical news discovery, article extraction, entity analysis, and personalized briefing. It is designed to be imported directly into downstream Python projects to avoid shelling out to CLI binaries.

Core Capabilities:

• Discovery: RSS/headline discovery and source matrix construction.
• Extraction: HTTP fetching, Trafilatura-based text extraction, and access/extraction classification.
• Analysis: Heuristic entity extraction, profile scoring, and briefing card generation.
• Validation: BioMCP pivot selection, result validation, checksums, and regression comparison.

from pathlib import Path
from biomcp_news_spike import PipelineConfig, run_pipeline

payload = run_pipeline(
    PipelineConfig(
        label="daily-news-smoke",
        output=Path("results/news_smoke.json"),
        per_source=4,
        max_articles=20,
        max_entity_articles=10,
        conservative_ranking=True,
    )
)

BioMCP uses section_outcomes to distinguish between different states of biomedical data collection. This ensures that scripts and agents can differentiate between a confirmed zero (a successful lookup that returned no results) and missing evidence (data that was never requested or could not be retrieved).

Key Outcome States

• empty: A successful query was made to a provider (e.g., OpenFDA), and the provider explicitly returned no results. The section_outcomes will reflect {"outcome":"empty", "sources":["Provider Name"]}.
• not_requested: The specific section was not part of the query. The section_outcomes will reflect {"outcome":"not_requested", "sources":[]} and the _meta.section_sources will not contain an entry for that key.
• inapplicable: A local decision was made to skip a provider because the input data lacked the required identifiers (e.g., a GWAS lookup requires an rsID, so a coordinate-only input results in an inapplicable outcome). In this case, the sources array in section_outcomes remains empty to avoid incorrectly crediting the provider with the decision.

Data Structure Integration

When an outcome is recorded, it is reflected in two places:

1. section_outcomes: Contains the outcome and the sources that provided the result.
2. _meta.section_sources: Tracks source attribution and metadata for the collection process.

The architecture enforces strict ownership boundaries to ensure deterministic output:

Key Requirements:

• Entity code must not depend on markdown-specific quoting helpers for semantic command construction.
• JSON _meta.next_commands must be treated as a behavior contract.
• Markdown tests should assert stable structural anchors rather than exact prose/word counts.

BioMCP provides CLI commands and API proxies for querying genomic variants and scientific literature.

Variant Capabilities:

• Search/Get: Supports searching for variants and retrieving specific details using search variant and get variant.
• Supported Identifiers: Accepts exact IDs like rsID, genomic HGVS (chrN:g.posRef>Alt), or gene + protein (e.g., BRAF V600E, BRAF p.Val600Glu).
• Unsupported Formats: Transcript HGVS (e.g., NM_000248.3:c.135del) is currently unsupported and will fail fast.
• Data Sources: Uses MyVariantClient as a base resolver, providing access to clinvar, population, conservation, cosmic, cgi, civic, cbioportal, gwas, and predict sections.
• Provenance: Outputs include section-level provenance (e.g., gnomAD via MyVariant.info).

Article/Literature Capabilities:

• Search/Get: Supports search article, get article, article entities, article batch, citations, references, and recommendations.
• Identifiers: Accepts PMID, PMCID, and DOI (DOI resolution currently depends on Europe PMC).
• Full-text Retrieval: Uses a ladder of sources including NCBI ID Converter, Europe PMC (PMC XML/MED XML/HTML), NCBI EFetch PMC XML, PMC OA archive XML, and Semantic Scholar PDF (requires --pdf flag).
• Federated Sources: Integrates PubTator3, Europe PMC, PubMed, Semantic Scholar, and LitSense2 (keyword-gated).