BioContext

Authoritative Biological Entity Resolution & Contextual Intelligence Framework.

BioContext standardizes, resolves, and cross-references biological entities (genes, proteins, transcripts, genomic loci) across fragmented reference authorities (HGNC, NCBI Entrez, UniProt, Ensembl) with deterministic accuracy and explainable audit trails.

Designed natively for AI coding agents and biological research workflows via the Model Context Protocol (MCP).

---

Key Capabilities (Phase 0 - MVP v0.1.0)

• Authoritative Resolution Hierarchy:
  • Human Genes (HGNC Primary): Direct symbol resolution and historical alias/previous symbol traversal (e.g. HER2 $\rightarrow$ ERBB2, p53 $\rightarrow$ TP53).
  • NCBI Entrez Integration: Entrez Gene ID lookup (7157 $\rightarrow$ TP53) and cross-species identifier support.
  • UniProtKB Cross-Mapping: Direct accession resolution (P04637 $\rightarrow$ TP53) and protein structural metadata enrichment.
• Explainable Audit Trail: Every resolution result includes exact matching rules, confidence scores ($0.0 - 1.0$), and authoritative source citations.
• Strongly Typed Schemas: Comprehensive Pydantic models for GeneEntity, ProteinEntity, GenomicLocation, and ResolutionResult.
• Embedded Persistence: Zero-configuration SQLite key-value cache with configurable TTL to reduce latency and comply with NCBI rate limits.
• Model Context Protocol (MCP): Native stdio server compliant with MCP 2.x for integration with Claude Desktop, Antigravity IDE, Cursor, and custom LLM tool-calling clients.

---

Architecture Overview

[ LLM / AI Client / Agent ]
           |
       (MCP stdio)
           v
   [ FastMCP Server ]
           |
   [ Entity Resolver ]
      /    |     \
     v     v      v
  [HGNC] [NCBI] [UniProt]
     \     |     /
    [ SQLite Cache ]

---

Installation (Single Source of Truth)

BioContext is distributed as a standalone CLI tool and MCP server via uv.

Global Installation (Recommended)

Install biocontext globally into your system path using uv tool:

# Install directly from GitHub
uv tool install git+https://github.com/CORE-Lab-Research/biocontext.git

Once installed, the biocontext command is available everywhere across your terminal.

To update to the latest release:

uv tool upgrade biocontext

Local Development Setup

If you are developing or contributing to the codebase:

git clone https://github.com/CORE-Lab-Research/biocontext.git
cd biocontext

# Install editable tool locally
uv tool install --editable .

# Or synchronize local virtualenv with dev dependencies
uv sync --extra dev

---

Configuration & Rate Limits

BioContext operates out-of-the-box with zero required configuration using public biological REST APIs.

NCBI Entrez API Key (Optional)

NCBI enforces a rate limit of 3 requests/second without an API key, and 10 requests/second with an API key. BioContext features an internal client-side token bucket rate limiter to automatically prevent HTTP 429 throttling.

To increase your throughput when working with extensive batches:

# Set your NCBI API key in your shell environment
export NCBI_API_KEY="your_ncbi_api_key_here"

BioContext automatically detects NCBI_API_KEY from the environment and dynamically unlocks 10 req/s concurrency.

---

Running Tests

Execute the complete asynchronous test suite:

uv run --extra dev pytest -v

All 8 integration tests verify HGNC exact matching, alias traversal, UniProt accession lookup, NCBI Entrez ID lookup, and MCP tool endpoints.

---

Using BioContext as an MCP Server

BioContext exposes its tools via standard input/output (stdio), making it compatible with any MCP-compliant client.

Option A: Run directly from GitHub via uvx (No local clone needed)

If uv is installed on your system, you or any user can run BioContext directly without cloning the repository:

{
  "mcpServers": {
    "biocontext": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/CORE-Lab-Research/biocontext.git",
        "biocontext"
      ]
    }
  }
}

Option B: Local Repository Setup

When working with a locally cloned repository:

uv run biocontext

Add the server to your client's MCP configuration (claude_desktop_config.json, Cursor, Antigravity IDE, etc.):

{
  "mcpServers": {
    "biocontext": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/biocontext",
        "run",
        "biocontext"
      ]
    }
  }
}

Note: Replace /path/to/biocontext with the absolute path to your cloned directory (e.g. /home/user/projects/biocontext on Linux/macOS or C:/Users/Username/projects/biocontext on Windows).

---

Command-Line Interface (CLI)

BioContext includes a built-in CLI for direct terminal testing without needing an active LLM client:

# Resolve a gene symbol or alias
biocontext resolve TP53
biocontext resolve HER2

# Resolve with contextual hint for disambiguation (e.g. chromosome, locus type)
biocontext resolve TP53 --chrom 17
biocontext resolve TP53 --locus-type protein-coding

# Query cross-species (e.g. Mus musculus - taxon 10090)
biocontext resolve Trp53 --taxon 10090

# Batch resolve multiple entities
biocontext batch TP53 HER2 EGFR MYC

# Fetch protein metadata from UniProt
biocontext protein P04637

# Manage local cache
biocontext cache stats
biocontext cache clear

# Run built-in accuracy benchmark & test suite
biocontext bench
biocontext test

---

Available MCP Tools

Tool	Parameters	Description
resolve_gene	query: str, taxon_id: int = 9606, chromosome: str = None, locus_type: str = None	Resolves official symbols (TP53), aliases (HER2), or Entrez IDs (7157) to a canonical GeneEntity with contextual scoring adjustments.
batch_resolve_genes	queries: list[str], taxon_id: int = 9606	Concurrently resolves multiple gene identifiers or aliases.
get_protein_info	accession: str	Retrieves structured protein metadata from UniProtKB by primary accession (e.g. P04637).

---

Benchmark & Empirical Validation

To validate Phase 0 accuracy KPIs, a 25-case benchmark suite evaluates standard symbols, historical aliases (MLL, OCT4, INT1, HER2), Entrez IDs (7157, 672, 2064), UniProt accessions, and cross-species lookups:

uv run --extra dev pytest tests/test_benchmark.py -v

• Accuracy: $100%$ ($25/25$ benchmark cases passing).
• Target KPI: $\ge 95%$ accuracy achieved.

---

Example Resolution Output

{
  "query": "HER2",
  "match_status": "alias",
  "confidence_score": 0.85,
  "resolved_entity": {
    "symbol": "ERBB2",
    "name": "erb-b2 receptor tyrosine kinase 2",
    "taxon_id": 9606,
    "species": "Homo sapiens",
    "hgnc_id": "HGNC:3430",
    "ncbi_gene_id": "2064",
    "ensembl_gene_id": "ENSG00000141736",
    "uniprot_ids": ["P04626"],
    "synonyms": ["HER2", "NEU", "NGL", "TKR1", "CD340", "HER-2", "MLN 19", "HER-2/neu"],
    "locus_type": "gene with protein product",
    "location": {
      "chromosome": "17q12",
      "start": null,
      "end": null,
      "strand": null,
      "assembly": "GRCh38"
    }
  },
  "match_reasons": [
    {
      "source": "HGNC",
      "rule": "alias_match",
      "confidence": 0.85,
      "details": "Matched alias_match via HGNC REST API for symbol 'ERBB2'"
    }
  ]
}

---

Roadmap

• Phase 0 (MVP v0.1.0) [CURRENT]: Core schemas, HGNC, NCBI Entrez, UniProt adapters, SQLite cache, FastMCP server.
• Phase 1 (v0.5.0): Ensembl & MGI adapters, batch processing engine, PyPI package publication, REST API bridge.
• Phase 2 (v1.0.0): Knowledge Graph integration, Biological Evidence & Provenance layer, AI Reasoning (Bio-RAG).
• Phase 3 (v2.0.0): Variant interpretation, Drug discovery cross-referencing, multi-omics integration.

---

Citation

If you use BioContext in your scientific research or software workflows, please cite:

@software{nandatama2026biocontext,
  author = {Nandatama, Engki},
  title = {BioContext: Authoritative Biological Entity Resolution & Contextual Intelligence Framework},
  year = {2026},
  url = {https://github.com/CORE-Lab-Research/biocontext},
  version = {0.1.0}
}

Or reference CITATION.cff.

---

License

Distributed under the Apache License, Version 2.0. See LICENSE for more information.