Open Bio Variant Annotator

A Privacy-First macOS Desktop Application and Model Context Protocol (MCP) Toolkit for Clinical Variant Triage from NGS Spreadsheet Outputs

Overview (English)

Open Bio Variant Annotator is a local-first desktop application for macOS (.app / .dmg) and a Model Context Protocol (MCP) server designed for diagnostic genetics laboratories working with tabular variant callsets (such as Ion Torrent S5 .xls / .xlsx exports on hg19/GRCh37).

Key Capabilities

1. Strict Local Privacy (Zero Cloud File Uploads): Complete patient spreadsheets never leave the local computer. Working files, job history, and local annotation caches are stored strictly in ~/.openbio/ (0700 permissions). Only individual de-identified genomic coordinates (chr:pos) are queried against public NCBI Entrez E-utilities.

2. Bring-Your-Own-Key (BYOK) NCBI Authentication: No API keys are hardcoded in the software. On first launch, the application guides the user to configure their personal, free NCBI API key (https://www.ncbi.nlm.nih.gov/account/settings/), enabling rate-limited queries up to 9–10 requests/second while storing credentials locally in ~/.openbio/config.json (0600 permissions).

3. Indel & Coordinate Normalization (hg19/GRCh37): Automatically detects both standard Excel workbooks (.xlsx/.xls) and tab-separated .xls files exported by Ion Torrent Torrent Suite, resolving left-shifted vs. right-shifted indels and selecting the ClinVar record with the highest review status.

4. Automated Triage & Color-Coded Clinical Reports: Generates standardized 13-column Excel reports color-coded by clinical significance:

   • Red (#FF4C4C): Pathogenic / Likely pathogenic

   • Orange (#ED7D31): Uncertain significance (VUS)

   • Blue (#9FC5E8): Conflicting classifications of pathogenicity

   • White (#FFFFFF): Benign / Likely benign (automatically filtering out ~95% of benign polymorphisms in multigene panels)

   • Yellow (#FFE599): Not found in ClinVar (highlighting novel/unannotated variants for rapid downstream evaluation via pre-built gnomAD r2.1 and VarSome ACMG links).

5. Model Context Protocol (MCP) Server (mcp_server.py): Exposes variant lookup and batch spreadsheet annotation tools (search_variant, get_variant_by_id, inspect_excel, batch_query_clinvar, batch_query_folder) to MCP-compatible AI assistants.

Related MCP server: OakVar MCP Server

Installation & Quick Start (For Reviewers and Users)

Option A: Native macOS Application (.dmg)

1. Download Open Bio Variant Annotator.dmg from the GitHub Releases page.

2. Open the .dmg image and drag Open Bio Variant Annotator.app into your Applications folder.

3. Launch the app. On first launch, click Impostazioni / Settings → API key NCBI (or click the built-in link to https://www.ncbi.nlm.nih.gov/account/settings/) and paste your free NCBI API key.

4. Load the included sample dataset: sample_data/sample_variants_hg19.xls.

5. Inspect the interactive results table and click Salva report Excel to save the color-coded .xlsx report via the native macOS Save dialog.

Option B: Running from Source (Python 3.10+)

git clone https://github.com/Francescopad/openbio-variant-annotator.git
cd openbio-variant-annotator
pip install -r requirements.txt

# Launch the native macOS desktop window (pywebview + FastAPI)
python3 openbio_app.py

Testing with the Included Sample Dataset

The repository includes sample_data/sample_variants_hg19.xls, an anonymized Ion Torrent-compatible benchmark file (hg19/GRCh37) containing 7 reference variants:

• BRAF V600E (chr7:140453136 A>T) — Pathogenic

• MTHFR C677T (chr1:11856378 G>A) — Benign / Drug response

• BRCA1 c.68_69delAG (chr17:41277277 CT>C) — Pathogenic complex indel

• CFTR p.Phe508del (chr7:117199644 ATCT>A) — Pathogenic deletion

• HFE C282Y (chr6:26093141 G>A) — Pathogenic / Conflicting

• TTN missense (chr2:179415516 G>A) — Uncertain significance (VUS)

• TTN synthetic novel coordinate (chr2:179432185 A>G) — Not found in ClinVar (demonstrating novel variant triage with direct gnomAD/VarSome links).

Repository Structure

openbio/
├── openbio_app.py       # Native macOS desktop launcher (pywebview + native menus & file dialogs)
├── local_server.py      # Local FastAPI server (127.0.0.1 ephemeral port, analysis & history API)
├── mcp_server.py        # Model Context Protocol (MCP) server for AI agent integration
├── job_store.py         # Persistent local job & report store (~/.openbio/)
├── config_manager.py    # Secure local BYOK API key manager (~/.openbio/config.json, chmod 0600)
├── clinvar_client.py    # Async NCBI E-utilities ClinVar client with indel & hg19 resolution
├── gnomad_client.py     # gnomAD r2.1 (GRCh37) direct variant link builder
├── varsome_client.py    # VarSome ACMG client and URL builder
├── excel_handler.py     # Reader/writer for Excel (.xlsx/.xls) and Ion Torrent TSV outputs
├── clinvar_batch.py     # Batch folder & file processor with shared local caching
├── sample_data/
│   └── sample_variants_hg19.xls  # Anonymized benchmark dataset for testing & peer review
├── static/              # Frontend UI assets (index.html, style.css, app.js, dna.svg)
├── build_mac_app.py     # PyInstaller build script for macOS .app and .dmg distribution
├── requirements.txt     # Python dependencies
└── LICENSE              # MIT License (free for academic and non-commercial use)

Guida in Italiano

App desktop macOS per l'annotazione di varianti genomiche da file Excel (Ion Torrent S5 o tabelle hg19/GRCh37). Elaborazione locale — file e report restano sul tuo Mac (~/.openbio/); solo le singole coordinate delle varianti vengono inviate a NCBI per interrogare ClinVar tramite la tua API key personale.

Sviluppo e Build del DMG su macOS

pip install -r requirements.txt
python3 openbio_app.py        # Avvia l'app in modalità sviluppo
python3 build_mac_app.py      # Genera Open Bio Variant Annotator.app e .dmg in dist/

License

Released under the MIT License. Free for academic, research, and non-commercial clinical use.