BioMCP-TS

Inspect and configure biomcp — unified observability and restricted controllability for every parameter. **What it covers:** three optional feature groups (database, analysis_r, analysis_biowasm) whose knobs live in the .biomcp.json project config file (written by this tool, loaded at server startup — a restart applies changes), plus every environment-only parameter (API keys, proxy, security boundaries), which is query-only. **Actions:** - status (default; call with {}): per-feature running state (with each feature's settable_keys), config file health, conflicts (e.g. an env var vetoing the…

Get the column schema for a specific table. **Returns for each column:** - Field name - Data type - Nullable status - Key type (PRI for primary key) - Default value **Workflow:** 1. Use `db_list_tables` first to see available databases, aliases, and tables 2. Use this tool to understand the column structure 3. Use `db_query` to query the data **Multiple databases:** table names resolve against the main database first, then attached databases in order; qualify as `alias.table` to disambiguate when the same table name exists in more than one database (SQLite multi-file setups).

List all tables/views across the configured database(s) with metadata. **Returns:** - `databases`: every reachable database (SQLite multi-file setups: `main` plus attached aliases) with its file path and table count - `collections`: table/view names with their owning `database`, type, and row count - Row count is approximate for MySQL; exact for SQLite tables, except for large databases (>256 MB) where it is omitted (use SELECT COUNT(*) instead) **Usage:** Call this first to discover available databases, aliases, and tables before using db_describe_table or db_query. Reference tables from at…

Execute a read-only SELECT query on the configured database(s). **Examples:** - Simple query: `SELECT * FROM genes LIMIT 10` - With named params: `SELECT * FROM variants WHERE significance = :significance` - Cross-database join (multiple SQLite files configured): `SELECT m.CellLineName, e.value FROM gene_effect e JOIN models m ON m.model_id = e.model_id WHERE e.gene_symbol = 'KRAS' LIMIT 10` **Parameters:** - Use named placeholders like `:paramName` for parameters - Pass parameter values in the `params` object: { "significance": "pathogenic" } **Multiple databases:** when several SQLite fil…

Free-text concept resolution - find entities matching a free-text query. Prefers a candidate whose name/symbol exactly matches the query (case-insensitive), ranks those exact matches first across entity types, and demotes numbered susceptibility-locus labels (e.g. "lung cancer susceptibility 1") within each backend's candidates; each result's matched_on field reports why it was picked ("exact" or "first")

Get drugs for a disease via OpenTargets. Results are ranked by max clinical phase, then trial-report count, with salt forms collapsed. Response is an envelope: { results, warnings?, errors? } — OpenTargets failures and unresolved diseases ride in errors[] as { source, message, retryable? } instead of inline items (issue #130)

Get detailed disease information by ID

Search for diseases by name, phenotype, or keyword. Response is an envelope: { results, warnings?, errors? } (issue #130)

Get clinical trials for a disease. Response is an envelope: { results, warnings?, errors? } (issue #130)

Get detailed drug information by name

Search for drugs by name or keyword (chemical identity: names, synonyms, and identifiers in ChEMBL/MyChem). This is NOT a mechanism or target search — MyChem has no mechanism text in this query, so "EGFR inhibitor"-style queries return nothing. For drugs targeting a gene/mechanism, use gene_drugs with the target gene symbol.

Find clinical trials for a drug

Predict the functional consequence of a variant on demand via Ensembl VEP — works even for NOVEL variants absent from every database, and for non-human species. Input forms: HGVS c./p./g. notation ("NM_004333:c.1799T>A", "NM_004333.6:c.1799T>A") or a dbSNP rsID ("rs113488060"). Prefer HGVS over rsIDs when both are available — rsIDs are resolved through dbSNP's coordinate mapping, which can yield less specific consequences. RefSeq accessions may carry a version ("NM_004333.6:c.1799T>A"); when the version is not carried by the current Ensembl release the call is retried against the bare accessi…

Find orthologues or paralogues of a gene across species (Ensembl Compara) — the cross-species gene mapping source in biomcp. Returns target stable IDs, gene symbols (when the assembly provides them, e.g. ARAF/RAF1 for BRAF paralogs), species, taxonomy level, and percent identity, sorted by identity. Accepts an HGNC symbol or Ensembl gene ID; scope to one species with target_species ('mouse') or target_taxon (10090). Use it for conservation questions ('is this gene conserved?', 'what is the mouse orthologue of BRAF?').

Resolve a gene in Ensembl terms for ANY Ensembl species (356 available): stable ID (ENSG…), symbol↔ID mapping, versioned identifier, canonical transcript, and coordinates on the current assembly (GRCh38 human, GRCm39 mouse, …). With expand=true, returns all transcripts with translation/protein IDs. Accepts an HGNC symbol (BRAF) or Ensembl gene ID (ENSG00000157764, versioned or bare — versions are resolved to the current record). Species accepts scientific names or aliases ('homo_sapiens'/'human', 'mus_musculus'/'mouse'). For rich human gene annotation (summary, pathways, drugs, diseases) use …

Query what lives in a genomic interval on the current assembly (GRCh38 for human): genes/transcripts (stable IDs, symbols, biotypes) and known variants (rsIDs, alleles, consequence terms, clinical significance). Ideal for locus triage — "what genes and known variants sit in this GWAS hit interval?". Genes/transcripts are always fetched for the FULL requested span, but variation density can reach ~100k variants in dense loci (which times out upstream), so when the span exceeds 50 kb variation is queried only for a 50 kb window centered on the region midpoint — the result echoes effective_varia…

Map a GenBank/RefSeq nucleotide accession to its NCBI Gene IDs (elink nuccore→gene). The returned gene_ids are NCBI Gene (entrezgene) IDs. gene_get takes an HGNC gene symbol, NOT a numeric entrez id, so an id must first be resolved to its symbol — gene_search result rows carry both symbol and entrez_id, so the id→symbol bridge exists via gene_search. Useful bridge from a sequence record to gene-level annotation.

Fetch a GenBank/RefSeq nucleotide record as text (GenBank flat file or FASTA). Whole-record fetches are capped at 2,000,000 bp — larger records require a seq_start/seq_stop region (1-based, inclusive, up to 10 Mb span; set strand=2 for a reverse-strand slice where seq_start > seq_stop — the region field echoes the request as given, while NCBI's text shows complement(min..max)). Output: records up to 1,000 characters are returned inline (sequence_text with char_count/truncated). Anything larger defaults to file mode — the FULL text is written to a server-side cache file and the reply carries m…

Search NCBI nucleotide records (GenBank/RefSeq/INSDC). Queries may be plain terms, an accession, or NCBI field syntax ("TP53[Gene Name] AND Homo sapiens[Organism]", "BRCA1[Gene Name]"). Results include accession.version, definition, length_bp, organism, and topology — chain accessions into genbank_get or genbank_genes.

Find articles about a gene. Response is an envelope: { results, warnings?, errors? } — per-backend failures ride in `errors` (never as items inside `results`), degradation notes in `warnings` (issue #130)

Get diseases associated with a gene. Requires DISGENET_API_KEY environment variable for DisGeNET data; falls back to OpenTargets gene-disease associations when unavailable.

Find drugs targeting a gene. Results are ranked by max clinical phase, then trial-report count, with salt forms collapsed. Response is an envelope: { results, warnings?, errors? } — OpenTargets failures and unresolved genes ride in errors[] as { source, message, retryable? } instead of inline items (issues #130, #179)

Perform pathway enrichment analysis for a gene list (Reactome over-representation). Requires at least 3 genes; the list is deduplicated (case-insensitive) before submission. Each pathway reports genes_overlap — the count of unique SUBMITTED genes Reactome matched there, resolved with one follow-up token lookup (Reactome's entity-level match count can exceed the gene count when one gene maps to multiple entities, e.g. a UniProt entry plus Ensembl gene/transcript). The reply also reports how many pathways Reactome found in total alongside the returned page.

Get detailed gene information by symbol. Response section keys mirror the requested section names: sections:["clinical_evidence"] returns sections.clinical_evidence, "protein_atlas" returns sections.protein_atlas, "dosage_sensitivity" returns sections.dosage_sensitivity, "disease_associations" returns sections.disease_associations — the legacy storage keys (civic, hpa, clingen, disgenet) never appear in responses.

Search for genes by symbol, name, or keyword

Find clinical trials for a gene

Get the full SOFT record details for a GEO entry: series (GSE...), sample (GSM...), or platform (GPL...). A series detail includes summary, organisms, platform_ids, a sample preview, supplementary file URLs, and cross-references for chaining: sra → sra_get(SRP.../SRR...), pubmed_ids → article_get, samples → geo_get(GSM...), platform_ids → geo_get(GPL...). GDS accessions (curated DataSets, not served by SOFT) return structured guidance as data — { accession, guidance, see_also: { series: "GSE…", sample: "GSM…" } } — pointing at the underlying series/sample records; this is a successful result…

Search NCBI GEO (Gene Expression Omnibus) for functional genomics studies — expression microarrays, RNA-seq, and other high-throughput sequencing series. Queries accept plain terms ("breast cancer RNA-seq", "melanoma single cell") or NCBI field syntax ("GSE183947[Accession]"). Every result carries accession (→ geo_get for full details), bioproject, and pubmed_ids (→ article_get). sra_project (→ sra_get) appears only when NCBI has linked the SRA study to the series — many newer series lack the link — so geo_get(accession) is the reliable route to SRA accessions (its sra field).

Get significant cis-eQTL associations for a gene in a specific GTEx tissue (GTEx Analysis v10): variant_id, p_value, and NES (effect direction/size), sorted by ascending p-value. tissue is a required GTEx tissueSiteDetailId (e.g. Whole_Blood, Brain_Cortex). An empty associations list is a VALID scientific result — the gene was tested but has no significant cis-eQTLs in that tissue (not a lookup failure). In that case the result carries a note listing other tissues where significant eQTLs DO exist (or stating that none exist in any tissue).

Get median gene expression across GTEx tissues (GTEx Analysis v10, 54 tissue sites, TPM, sorted highest first). Accepts an HGNC symbol (TP53) or Ensembl gene ID (ENSG00000141510, versioned or bare). Optionally filter to a single tissue via its tissueSiteDetailId (e.g. Brain_Cortex, Whole_Blood).

Journal quality metrics — an open-access alternative to the Clarivate impact factor (IF). Returns the OpenAlex 2-year mean citedness score (an IF-style metric), h-index, i10-index, citation counts, open-access flag (is_oa), and quality-list tiers (e.g. medline, norway-2, jufo-3…). Accepts a journal name, NLM abbreviation (e.g. 'N Engl J Med'), or ISSN (e.g. '0028-0836'; article records carry journal_issn).

Get patent details by publication number (e.g. "US11027025B2", "EP3904939B1", "US20260240819A1"). Sections: abstract, claims (US fulltext via USPTO Public Search; EP/WO via EPO OPS when configured, otherwise Google Patents pages — see per-section source fields), citations (backward + forward), family, classifications.

Search patents worldwide (US, EP, WO, JP, and 100+ authorities). Quote exact multi-word concepts (e.g. "flow cytometry") to avoid off-topic matches. Backend characters: ppubs = USPTO Public Search full-text conceptual search (US only, keyless, relevance-ranked; default US backend) | ops = EPO OPS worldwide bibliographic search over titles/abstracts (needs EPO_OPS_CONSUMER_KEY/EPO_OPS_CONSUMER_SECRET) | uspto_odp = US application metadata, bibliographic only but inventor/CPC/continuity-rich (needs USPTO_API_KEY) | google_patents = worldwide best-effort (often unavailable). Auto mode queries wor…

Access the Protein Data Bank (RCSB PDB) for macromolecular structure data. SEARCH: Provide "query" to find structures (e.g., "kinase inhibitor", "hemoglobin"). GET: Provide "pdb_id" to retrieve entry metadata with optional detail sections. Sections list per-entity records (polymer_entities, ligands, assembly); when some records fail while siblings succeed, each failure appears as an inline {_error} item AND the response carries a top-level "warnings" array naming the section and failed item. DOWNLOAD: Provide "pdb_id" + download=true to save the structure file and get the file path.

On-demand bioRxiv/medRxiv preprint full text (JATS XML, parsed to sections). Input: a preprint DOI (e.g. "10.1101/2025.03.05.641768"), optional version (default: latest). Downloads are strictly on-demand (never run during search), paced, and cached per (doi, version) — JATS per version is immutable, so repeat calls are served from cache without re-downloading. www.biorxiv.org rate-limits aggressively: on a 429/Cloudflare verdict this tool pauses downloads for >=60s (Retry-After honored) and every call during the cooldown returns an honest unavailable/rate_limited envelope with retry_after_sec …

Get full details for an SRA accession indexed by NCBI: run (SRR/ERR/DRR — instrument, spots, bases, size), experiment (SRX/ERX/DRX — library design), study (SRP/ERP/DRP — experiment list), or sample (SRS/ERS/DRS). NCBI SRA indexes NCBI, European (ENA), and DDBJ submissions alike, so accessions returned by sra_search resolve here regardless of prefix. Chain from geo_get (sra field) or sra_search (experiment_accession / first_run_accession).

Search NCBI's Sequence Read Archive (SRA) for sequencing experiments and runs. The query may be free text, an accession (SRP study, SRX experiment, SRR run, SRS sample), or NCBI field syntax ("RNA-SEQ AND Homo sapiens[Organism]"). Results list experiment/study/sample accessions (NCBI S…, European E…, or DDBJ D… prefixes — all resolvable by sra_get), organism, library strategy, run count, and first_run_accession for chaining into sra_get.

Get detailed trial information by NCT ID

Search clinical trials by condition, intervention, or keyword

Get detailed variant information with optional sections. Core data (id, gene, rsid, significance) is always returned at the top level. Use sections to request additional data. Response section keys mirror the requested section names: sections:["alphagenome_scores"] returns sections.alphagenome_scores — the legacy storage key (alphagenome) never appears in responses.

Get OncoKB annotations for a variant in a cancer gene. Requires ONCOKB_TOKEN environment variable.

Search for variants. Use structured parameters for best results: - rsid: e.g. query="rs113488022" - HGVS: e.g. query="NM_004333.4:c.1799T>A" - Gene filter: e.g. gene="BRAF" with hgvsp="V600E" or consequence="missense" - ClinVar significance: e.g. significance="pathogenic" Do NOT use compound free-text like "BRAF V600E" — use separate gene and hgvsp parameters instead.

Find clinical trials for a variant. Response is an envelope: { results, warnings? } — when MyVariant.info ID resolution fails, a warning rides alongside the results (which then come from searching the raw identifier) so a backend failure never masquerades as "no trials exist"; retry may resolve BRAF V600E-style naming (issue #198)