Skip to content

About

Primer Pair PCR Generator

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

PrimerForge

AI-native PCR primer design platform by YambaCode AB

PrimerForge designs, validates, and ranks PCR primer pairs for any gene via three interfaces: an MCP server (for Claude Code / AI agents), a FastAPI HTTP API, and a SvelteKit web UI with live streaming.


Features

  • 4 design modes: Standard PCR · qPCR (TaqMan) · RT-PCR (exon-junction) · SNP-aware
  • Live pipeline streaming — watch each stage complete in real time via SSE
  • Gene resolution via NCBI Gene + Nuccore (free, no account needed)
  • SNP masking from dbSNP (avoids primers spanning common variants)
  • Off-target specificity via local BLAST+ (human genome)
  • Thermodynamic analysis via Primer3 — Tm, ΔG, dimers, hairpins
  • Multi-criteria scoring (0–100) with weighted pass/fail verdicts

Where the Data Comes From

PrimerForge pulls from three free public sources — no proprietary database required:

Source What it provides Access
NCBI Gene / Nuccore Gene symbol → RefSeq transcript (mRNA, CDS, exon boundaries) E-utilities (free; optional API key for 10 req/s)
dbSNP (NCBI) Common SNPs (MAF ≥ 1%) → masked positions E-utilities (same key)
BLAST+ databases Off-target specificity vs. reference genome One-time download (~30 GB human genome)

Use Case Walkthrough — RT-PCR primers for BRCA1

User Input
  gene = "BRCA1"
  mode = rt_pcr
      │
      ▼
[1] Gene Resolution   (NCBI Gene → Nuccore)      ~3–8 s
      BRCA1 → NM_007294.4 · 7,088 nt · 24 exons
      Exon-exon junction positions extracted
      │
      ▼
[2] SNP Masking   (dbSNP)                         ~1–2 s
      47 polymorphic positions → masked with N
      Prevents primer binding at common variants
      │
      ▼
[3] Primer Design   (Primer3)                     < 0.1 s
      5 candidate pairs · spanning exon 10-11 junction
      Product size 150–250 bp · Tm opt 60°C
      │
      ▼
[4] Thermodynamic Analysis   (Primer3-py)         < 0.1 s
      Pair 1: Fwd Tm=61.2°C · Rev Tm=60.8°C · ΔTm=0.4°C
      GC 55%/50% · hairpin 38°C · cross-dimer 32°C
      │
      ▼
[5] Specificity Check   (local BLAST+)            ~5–30 s / pair
      Pair 1: 0 off-targets · score=100 ✓
      Pair 2: 2 off-targets · score=72  ⚠
      Pair 3: 0 off-targets · score=100 ✓
      │
      ▼
[6] Validation & Ranking
      Rank 1: Pair 1 · score=94/100 ✓ spans exon junction
      Rank 2: Pair 3 · score=87/100 ✓
      Rank 3: Pair 5 · score=81/100 ✓
      Rank 4: Pair 4 · score=74/100 ⚠ high hairpin
      Rank 5: Pair 2 · score=68/100 ⚠ off-targets

How to Use

1. Prerequisites

# Python 3.11+
python --version

# BLAST+ binaries (macOS)
brew install blast

# BLAST+ (Ubuntu/Debian)
sudo apt-get install ncbi-blast+

2. Install

git clone https://github.com/yambacode/primerforge
cd primerforge
pip install -e .

3. Set Environment Variables

export NCBI_EMAIL=your@email.com        # required by NCBI
export NCBI_API_KEY=your_key            # optional: raises rate limit to 10 req/s
export BLAST_DB_PATH=./data/blast_dbs   # path to downloaded BLAST databases

4. Download BLAST Database (one-time, ~30 GB)

mkdir -p data/blast_dbs
cd data/blast_dbs
update_blastdb.pl --decompress human_genome
# Or for a smaller test database:
update_blastdb.pl --decompress nt

5a. Run as MCP Server (for Claude Code)

python -m primerforge.server

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "primerforge": {
      "command": "python",
      "args": ["-m", "primerforge.server"],
      "cwd": "/path/to/primerforge",
      "env": {
        "NCBI_EMAIL": "your@email.com",
        "NCBI_API_KEY": "your_key"
      }
    }
  }
}

Then in Claude Code:

Design RT-PCR primers for BRCA1 spanning exon junctions

5b. Run as HTTP API

uvicorn primerforge.api:app --host 0.0.0.0 --port 8000

Stream a full pipeline run:

curl --no-buffer -X POST http://localhost:8000/api/v1/stream/design-and-validate \
  -H "Content-Type: application/json" \
  -d '{"gene":"BRCA1","mode":"rt_pcr","num_return":5}' \
  | while IFS= read -r line; do echo "$line"; done

Or call the non-streaming endpoint:

curl -X POST http://localhost:8000/api/v1/design-and-validate \
  -H "Content-Type: application/json" \
  -d '{"gene":"TP53","mode":"standard"}' | python -m json.tool

5c. Run the Web UI

cd primerforge-ui
cp .env.example .env         # set VITE_API_BASE=http://localhost:8000
npm install
npm run dev                  # → http://localhost:5173

Deployment

Backend → GCP Cloud Run (free tier)

# Build and push container
gcloud builds submit --tag gcr.io/YOUR_PROJECT/primerforge-api

# Deploy (free tier: 2M req/month + 360k GB-seconds)
gcloud run deploy primerforge-api \
  --image gcr.io/YOUR_PROJECT/primerforge-api \
  --region europe-west1 \
  --allow-unauthenticated \
  --memory 2Gi \
  --timeout 3600 \
  --set-env-vars NCBI_EMAIL=your@email.com

See cloudrun.yaml for the full service definition with Cloud Storage FUSE for BLAST databases.

Frontend → Vercel (free tier)

cd primerforge-ui
# Set VITE_API_BASE to your Cloud Run URL in Vercel env vars
vercel deploy

MCP Tools

Tool Description
resolve_gene Gene symbol/ID/accession → mRNA sequence + exon map
fetch_snps SNP masking at polymorphic positions
design_primers Primer3 engine (4 modes)
check_specificity BLAST+ off-target scan
analyze_thermo Tm, dimers, hairpins analysis
validate_and_rank Multi-criteria scoring
design_and_validate Full pipeline (recommended)

HTTP API

Endpoint Method Description
/api/v1/stream/design-and-validate POST SSE streaming — emits events per stage
/api/v1/design-and-validate POST Full pipeline (blocking)
/api/v1/resolve-gene POST Gene resolution only
/api/v1/fetch-snps POST SNP masking only
/api/v1/design-primers POST Primer3 design only
/api/v1/check-specificity POST BLAST specificity only
/api/v1/analyze-thermo POST Thermodynamics only
/api/v1/validate-and-rank POST Scoring only
/health GET Health check

Full OpenAPI docs: http://localhost:8000/docs


Tests

pytest tests/ -v

License

Proprietary — YambaCode AB

About

Primer Pair PCR Generator

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages