io.github.cyanheads/pharmacogenomics-guidelines-mcp-server

---

Overview

Clinical pharmacogenomics evidence from the public CPIC Database API: evaluated gene–drug pairs, guidelines, allele function and frequency, diplotype-to-phenotype translation, and prescribing recommendations, with ClinPGx testing labels and guideline links. You can discover pairs, translate a patient's diplotype, and browse recommendations or match them against explicitly supplied gene results. All six tools are read-only, need no API key, and run as a stdio process or a local Streamable HTTP server.

Tools

Tool	Description
pgx_search_pairs	Search evaluated gene–drug pairs by gene, drug, RxNorm/ATC identifier, CPIC level or testing label
pgx_get_guideline	Retrieve guideline coverage by ID, gene or drug, with related drugs and pairs
pgx_lookup_diplotype	Translate a diplotype or HLA allele status into its gene result, activity score and lookup key
pgx_get_recommendations	Browse a drug's prescribing recommendations, or match explicit gene results or genotypes
pgx_search_alleles	Inspect allele function, evidence, definition metadata and population frequencies
pgx_list_reference	List genes, gene-specific results, controlled vocabulary and input formats

Capability reference

pgx_search_pairs _tool

• Optional filters, combined with AND: geneSymbol, drugName (literal substring), drugId, rxnormId, atcId (exact code, no hierarchy expansion), cpicLevel, provisional, pgxTesting and usedForRecommendation.
• limit 1–100 (default 25); continue from page.nextOffset.
• Returns complete pair records, each with its drug record and guideline link. Retired pairs appear only with includeRetired: true or cpicLevel: "Retired".

---

pgx_get_guideline _tool

• Three lookup modes; selectors from other modes are rejected:
  • by: "id" with guidelineId
  • by: "gene" with geneSymbol
  • by: "drug" with exactly one of drugName (exact, case-insensitive) or drugId
• Default view: "summary" pages complete guideline records with exact drugCount and pairCount. view: "drugs" or "pairs" requires by: "id", retains the guideline descriptor, and pages the selected top-level collection; the other collection is omitted.
• limit defaults to 25; positive safe integers above 100 clamp to 100 with a notice. Follow page.nextOffset. Pages use a 24,000-byte soft budget across both response surfaces and enrichment, cutting only between complete rows. One indivisible oversized row sets oversizedRow: true with a notice.
• No coverage returns found: false. An ambiguous drug name returns paged candidates; page, shown and truncated then describe those candidates. Retry with a drugId from that list.

---

pgx_lookup_diplotype _tool

• Takes geneSymbol plus a source-supported diplotype, in either allele order:
  • star alleles (*1/*2, *1x2/*4)
  • HLA allele status (*57:01 positive)
  • non-star notation (c.1905+1G>A (*2A)/Reference)
• Returns found, matchedDiplotype, guidance, and every matching source record with its gene result, activity score, EHR priority and lookup key.
• Several matching records are left ambiguous, never resolved to one. No result is calculated.

---

pgx_get_recommendations _tool

• mode: "drug" takes exactly one of drugName (exact, case-insensitive) or drugId.
  • On its own, or with geneSymbol or population, it browses (exploratory).
  • To match, add phenotype or activityScore. These need geneSymbol when the drug's recommendations involve several genes.
  • Alternatively, add a geneResults map: 1–10 genes, each { kind: "phenotype" | "activityScore" | "alleleStatus", value }.
• mode: "genotype" takes genotype: 1–10 gene → diplotype entries, each of which must resolve uniquely. An optional drug selector narrows the results.
• mode: "results" discovers across drugs from geneResults, or geneSymbol with one phenotype/activityScore. An optional drug selector narrows the results. Unrelated panel genes do not exclude a recommendation; conflicting results for its prerequisites do.
• All modes accept an exact population, limit 1–50 (default 10) and offset. incompleteLimit 1–100 (default 25) and incompleteOffset page missing-gene diagnostics independently through incompletePage.nextOffset.
• status is exploratory, matched, no_match, incomplete or unresolved. A row matches only when every gene in its lookup key has an explicit result. incompleteMatches lists the rows that need more genes, with their missingGenes and without prescribing text.
• Empty-result notices distinguish unresolved drugs, absent recommendation tables, population mismatches and past-end pages. Where source coverage exists, a no-table notice links the guideline for consultation.

---

pgx_search_alleles _tool

• Requires geneSymbol. name matches literally first, then retries a matching gene-prefixed star allele without that prefix. clinicalFunctionalStatus matches literal text case-insensitively. Returned source spelling stays unchanged; effectiveQuery shows the allele name used.
• limit defaults to 25; positive safe integers above 100 clamp to 100 with a notice. Nonpositive, fractional and unsafe limits fail before fetching. offset is a nonnegative safe integer.
• The 24,000-byte soft budget measures the entire serialized tool result, including both response surfaces and enrichment. It cuts only between complete alleles, keeping every frequency row. An indivisible oversized first row sets oversizedRow: true with a notice. Follow page.nextOffset to reconstruct the remaining rows.
• Returns allele function and evidence with definition metadata and populationFrequencies. Frequencies stay as source fractions, missing values stay missing, and inferred frequencies are flagged as inferred.

---

pgx_list_reference _tool

• topic is one of:
  • genes — optional geneSymbol filter
  • phenotypes — requires geneSymbol
  • cpic_levels, pgx_testing, classifications, input_formats
• The two live topics (genes, phenotypes) page with limit 1–100 (default 25) and offset. They return full gene and gene-result records, including distinct activity scores, frequencies and consultation text.
• Static topics return their whole vocabulary without calling the CPIC API. They reject geneSymbol and carry a verificationDate.

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

CPIC-specific:

• One lookup chain: reference values → pairs → guidelines → allele and diplotype evidence → recommendations
• CPIC evaluation levels, ClinPGx testing labels and recommendation classifications are kept separate. A testing label is not an FDA label, and an evaluated pair is not a recommendation.
• Matching uses only results you supply. An omitted gene is never assumed normal, negative or Indeterminate. Phenotypes, decimal activity scores and HLA allele statuses are each checked against CPIC's own values.
• Bounded workflows:
  • 45-second deadline, at most 100 HTTP attempts, three concurrent requests, two retries per request
  • Related scans stop at 2,000 rows (drug resolution 500). Guideline lists and detail views page at the source; related counts use exact source totals, with bounded scans only when totals are missing. Past a scan cap the call fails as query_too_broad rather than returning partial results.

Agent-friendly output:

• Provenance: exact deduplicated request URLs, access timestamp, returned row versions, and license and policy links. Each version uses an RFC 6901 JSON Pointer into the result and a requestIndex into requestUrls. API v1 names the interface, not a database release.
• Explicit outcomes: recommendation status, per-gene geneResolutions, incompleteMatches, and typed error reasons with recovery text.
• Lossless text output: content[] carries the complete result as JSON with one clickable link per distinct destination in each rendered block, matching structuredContent. effectiveQuery, notices and page (total, nextOffset) explain every result.

Source attribution and clinical limitations

Data comes from the CPIC Database and ClinPGx. The CPIC data license and the ClinPGx usage policy cover the source data; this repository's Apache-2.0 license covers its code.

The database tables can omit guideline nuances or lag behind guideline updates, so check each linked guideline before clinical use. Results apply only to their stated genes, drugs, populations and indications, and treatment decisions remain with the clinician and patient. The server stores no patient records, but genetic queries are sent to the CPIC API, and the request URLs, which contain them, appear in responses.

Getting started

Add the following to your MCP client configuration file:

{
  "mcpServers": {
    "pharmacogenomics-guidelines-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/pharmacogenomics-guidelines-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "pharmacogenomics-guidelines-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/pharmacogenomics-guidelines-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "pharmacogenomics-guidelines-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/pharmacogenomics-guidelines-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bunx @cyanheads/pharmacogenomics-guidelines-mcp-server@latest
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• Network access to https://api.cpicpgx.org. No API key is needed.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/pharmacogenomics-guidelines-mcp-server.git

2. Navigate into the directory:

cd pharmacogenomics-guidelines-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# optional: adjust transport, logging, or telemetry settings

Configuration

No server-specific environment variables are required.

Variable	Description	Default
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_HOST	HTTP bind address.	127.0.0.1
MCP_HTTP_PORT	HTTP server port.	3010
MCP_HTTP_ENDPOINT_PATH	MCP endpoint path.	/mcp
MCP_SESSION_MODE	HTTP session mode: stateless, stateful or auto.	stateless
MCP_AUTH_MODE	Authentication: none, jwt or oauth.	none
MCP_LOG_LEVEL	Log level (debug, info, warning, error, etc.).	debug
OTEL_ENABLED	Enable OpenTelemetry.	false

See .env.example for the common framework overrides.

Running the server

Local development

• Build and run the production version:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• Run checks and tests:

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

Project structure

Directory	Purpose
src/mcp-server/tools/definitions	The six tool definitions and the allToolDefinitions registry.
src/mcp-server/tools/shared	Paging schemas and lossless Markdown rendering.
src/services/cpic	Fixed-host CPIC requests, source record schemas, discovery, evidence and recommendation matching.
tests/unit	Service, tool contract, boundary and formatter tests.
docs	Design contract and generated directory tree.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for logging, ctx.state for storage
• Register new tools in allToolDefinitions (src/mcp-server/tools/definitions/index.ts), which src/index.ts passes to createApp()
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.