pharmacogenomics-guidelines-mcp-server

---

概述

来自公共 CPIC Database API 的临床药物基因组学证据：经过评估的基因–药物对、指南、等位基因功能和频率、双倍型到表型的转换，以及处方建议，并附有 ClinPGx 检测标签和指南链接。您可以查找基因–药物对、转换患者的双倍型，并浏览建议，或将建议与明确提供的基因结果进行匹配。全部 6 个工具均为只读，无需 API 密钥，可作为 stdio 进程、本地 Streamable HTTP 服务运行，也可通过上述公共托管端点访问。

工具

工具	描述
pgx_search_pairs	按基因、药物、RxNorm/ATC 标识符、CPIC 级别或检测标签搜索经过评估的基因–药物对
pgx_get_guideline	按 ID、基因或药物获取指南覆盖范围及相关药物和基因–药物对
pgx_lookup_diplotype	将双倍型或 HLA 等位基因状态转换为基因结果、活性评分和查询键
pgx_get_recommendations	浏览或匹配来源处方建议，以及选择启用的 CDS 测试提醒示例
pgx_search_alleles	查看等位基因功能、证据、定义元数据和人群频率
pgx_list_reference	列出基因、基因特异性结果、受控词汇和输入格式

Agent 技能

skills/pharmacogenomics-guidelines-guide 是为调用这些工具的 Agent 发布的 Agent Skill：说明每个标识符的来源、双倍型标记法，以及从实验室结果到建议之间的判断条件。插件安装和 .mcpb 捆绑包会直接加载它；MCP 客户端将其作为 skill://pharmacogenomics-guidelines-guide/SKILL.md 资源读取。

功能参考

pgx_search_pairs _工具

• 可选筛选条件，组合时采用 AND：geneSymbol、drugName（字面子字符串）、drugId、rxnormId、atcId（精确代码，不展开层级）、cpicLevel、provisional、pgxTesting 和 usedForRecommendation。
• RxNorm/ATC 前缀和 ATC 字母在声明的架构和运行时验证中均接受任意大小写。忽略首尾空格；空白标识符视为未设置。
• limit 默认值为 25；超过 100 的正安全整数会限制为 100，并附带通知。使用 page.nextOffset 继续查询。
• 返回完整的配对记录，每条记录均包含其药物记录和指南链接。只有设置 includeRetired: true 或 cpicLevel: "Retired" 时才会显示 Retired 配对。

---

pgx_get_guideline _工具

• 支持三种查询模式；不接受其他模式的选择器：
  • by: "id"，并提供 guidelineId
  • by: "gene"，并提供 geneSymbol
  • by: "drug"，并且只能提供 drugName（精确匹配，不区分大小写）或 drugId
• 默认的 view: "summary" 会分页返回完整指南记录，并提供精确的 drugCount 和 pairCount。view: "drugs" 或 "pairs" 要求 by: "id"，保留指南描述信息，并对选定的顶层集合分页；另一集合会被省略。
• limit 默认值为 25；超过 100 的正安全整数会限制为 100，并附带通知。请根据 page.nextOffset 继续查询。页面在两个响应面和补充数据之间采用 24,000 字节的软性限制，只会在完整行之间截断。若某行无法拆分且超出限制，则会设置 oversizedRow: true，并附带通知。
• 无匹配范围时返回 found: false。药物名称有歧义时返回分页的 candidates；此时 page、shown 和 truncated 描述这些候选项。请使用该列表中的 drugId 重试。

---

pgx_lookup_diplotype _工具

• 接受 geneSymbol 和受数据源支持的 diplotype，等位基因顺序不限：
  • 星号等位基因（*1/*2、*1x2/*4）
  • HLA 等位基因状态（*57:01 positive）
  • 非星号标记法（c.1905+1G>A (*2A)/Reference）
• 返回 found、matchedDiplotype、guidance，以及每条匹配的数据源记录，包括其基因结果、活性评分、EHR 优先级和查询键。
• 若匹配到多条记录，会保留歧义，不会判定为其中某一条。不会计算结果。

---

pgx_get_recommendations _工具

• 开具处方建议时，省略 view 或使用 view: "recommendations"。view: "test_alerts" 会选择 CPIC 的示例 CDS 语言，并使用相同的药物、基因型、结果、人群和分页选择器；它不会获取建议或关联指南。
• mode: "drug" 必须且只能指定 drugName（精确匹配，不区分大小写）或 drugId。
  • 单独使用，或与 geneSymbol 或 population 搭配时，会浏览（exploratory）。
  • 若要匹配，请添加 phenotype 或 activityScore。如果该药物的建议涉及多个基因，则还需要 geneSymbol。
  • 也可以添加 geneResults 映射：包含 1–10 个基因，每个基因对应 { kind: "phenotype" | "activityScore" | "alleleStatus", value }。
• mode: "genotype" 接受 genotype：包含 1–10 个“基因 → 双倍型”条目，每个条目都必须能唯一解析。可选的药物选择器会缩小结果范围。
• mode: "results" 根据 geneResults 跨药物查找，或根据 geneSymbol 与一个 phenotype/activityScore 查找。可选的药物选择器会缩小结果范围。不相关的面板基因不会排除某项建议；与其前提条件相冲突的结果则会排除。
• 源基因的 lookupmethod 决定可接受的结果类型：PHENOTYPE 允许 phenotype；ACTIVITY_SCORE 允许 phenotype 或 activityScore；ALLELE_STATUS 允许 alleleStatus。值会根据源结果/评分字段进行验证。表型不会转换为计算得出的评分。匹配前请查看 pgx_list_reference 中的 genes 和 phenotypes 主题。
• 所有模式都接受精确的 population、limit（默认值为 10）和 offset。超过 50 的正安全整数 limit 会截断为 50，并附带提示。incompleteLimit（默认值为 25）会独立截断超过 100 的值；incompleteOffset 会通过 incompletePage.nextOffset 对缺失基因诊断进行分页。
• status 为 exploratory、matched、no_match、incomplete 或 unresolved。药物匹配和结果匹配要求至少有一个提供的基因与结果重叠；若重叠的前提条件存在冲突，则会拒绝匹配；不相关且已验证的面板基因会被忽略。只有当查找键中的每个基因都有明确结果时，某一行才会匹配。incompleteMatches 会列出需要更多基因的行及其 missingGenes，且不包含处方文本。
• 空结果提示会区分无法解析的药物、不存在的建议表、人群不匹配和超出范围的分页。如果源数据覆盖范围足够，不存在建议表的提示会附上供查阅的指南链接。
• 警报视图会在 alerts 中返回完整的源记录，包括有序的 alerttext、单数形式的 phenotype、查找键、等位基因状态、评分、人群和版本。No CDS、n/a、稀疏字段以及源数据中明确标记为 No Result 的行都会保持原样。省略的遗传信息绝不会变成 No Result。缺失的前提条件只会以 { testAlertId, drugId, missingGenes } 的形式出现在 incompleteAlerts 中，不包含警报文本。items 和 incompleteMatches 保持为空；page 和 incompletePage 描述警报和诊断信息。默认响应会省略这两个警报字段。

---

pgx_search_alleles _工具

• 必须提供 geneSymbol。先按字面匹配 name，然后尝试匹配去掉基因前缀的星号等位基因。clinicalFunctionalStatus 按字面文本进行不区分大小写的匹配。返回的来源拼写保持不变；effectiveQuery 会显示使用的等位基因名称。
• limit 默认为 25；大于 100 的正安全整数会被限制为 100，并附带说明。非正数、小数和不安全的限制值会在获取数据前报错。offset 必须是非负安全整数。
• 24,000 字节的软性上限针对整个序列化工具结果，包括两个响应表面和补充信息。裁剪仅发生在完整等位基因之间，并保留所有频率行。若首行过大且无法拆分，则设置 oversizedRow: true，并附带说明。请使用 page.nextOffset 重建剩余行。
• 返回等位基因功能和证据，以及定义元数据和 populationFrequencies。频率保持为来源中的分数，缺失值仍保持缺失，推断出的频率会标记为推断值。

---

pgx_list_reference _工具

• topic 可选值：
  • genes — 可选的 geneSymbol 筛选条件
  • phenotypes — 必须提供 geneSymbol
  • cpic_levels、pgx_testing、classifications、input_formats
• 两个动态主题（genes、phenotypes）支持通过 limit（默认 25）和 offset 分页。大于 100 的正安全整数限制值会被限制为 100，并附带说明。它们会返回完整的基因和基因结果记录，包括不同的活性评分、频率和咨询文本。
• 静态主题会返回其完整词汇表，且不会调用 CPIC API。它们不接受 geneSymbol，并包含 verificationDate。

功能特性

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、结构化日志记录及可选的 OpenTelemetry 跟踪。

CPIC 专属：

• 单一查询链：参考值 → 配对 → 指南 → 等位基因和双倍型证据 → 建议
• CPIC 评估级别、ClinPGx 检测标签和建议分类彼此独立。检测标签不是 FDA 标签，已评估的配对也不是建议。
• 匹配仅使用你提供的结果。省略的基因绝不会被假定为正常、阴性或 Indeterminate。表型、十进制活性评分和 HLA 等位基因状态均依据 CPIC 自身的取值进行检查。
• 有界工作流：
  • 45 秒截止时间，最多 100 次 HTTP 尝试，三个并发请求，每个请求最多重试两次
  • 相关扫描最多处理 2,000 行（药物解析为 500 行）。指南列表和详情视图会按来源分页；相关计数使用来源提供的精确总数，仅在缺少总数时进行有界扫描。超过扫描上限后，调用会以 query_too_broad 失败，而不是返回部分结果。

便于 Agent 使用的输出：

• 来源信息： 去重后的精确请求 URL、访问时间戳、返回行版本，以及许可和政策链接。每个版本使用指向结果的 RFC 6901 JSON Pointer，并通过 requestIndex 指向 requestUrls。API v1 表示接口版本，而非数据库版本。
• 明确的结果： 建议 status、逐基因的 geneResolutions、incompleteMatches，以及附带恢复说明的类型化错误原因。
• 无损文本输出： content[] 以 JSON 形式承载完整结果；每个渲染区块中，每个不同的目标地址各有一个可点击链接，并与 structuredContent 匹配。effectiveQuery、notices 和 page（total、nextOffset）会说明每项结果。

来源归属与临床局限

数据来自 CPIC Database 和 ClinPGx。CPIC 数据许可 和 ClinPGx 使用政策适用于源数据；本仓库的 Apache-2.0 许可证适用于代码。

数据库表可能省略指南中的细节，或未及时反映指南更新，因此临床使用前请查阅每份链接的指南。结果仅适用于其中所述的基因、药物、人群和适应症，治疗决策仍由临床医生和患者共同决定。服务不会存储患者记录，但遗传查询会发送至 CPIC API，包含查询内容的请求 URL 也会出现在响应中。

开始使用

连接托管实例，无需安装：

claude mcp add --transport http pharmacogenomics-guidelines-mcp-server https://pharmacogenomics-guidelines.caseyjhand.com/mcp

查询托管实例时，会经由该实例的服务转发至 CPIC API。对于患者数据，请运行自己的实例。

或者在本地运行：

claude mcp add pharmacogenomics-guidelines-mcp-server -- npx -y @cyanheads/pharmacogenomics-guidelines-mcp-server

对于其他客户端，请将以下内容添加到 MCP 配置文件：

{
  "mcpServers": {
    "pharmacogenomics-guidelines-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/pharmacogenomics-guidelines-mcp-server"]
    }
  }
}

无需 API 密钥。有关 Docker 或从源代码构建的信息，请参阅运行服务。

配置

无需设置特定于服务的环境变量。

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_HOST	HTTP 绑定地址。	127.0.0.1
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_HTTP_ENDPOINT_PATH	MCP 端点路径。	/mcp
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	debug
OTEL_ENABLED	启用 OpenTelemetry。	false

有关常见的框架覆盖设置，请参阅 .env.example。

运行服务

本地开发

需要 Bun v1.4.0 或更高版本（或 Node.js v24+），并且可以访问网络 https://api.cpicpgx.org。

• 克隆并安装：

  git clone https://github.com/cyanheads/pharmacogenomics-guidelines-mcp-server.git
  cd pharmacogenomics-guidelines-mcp-server && bun install
  cp .env.example .env   # optional: adjust transport, logging, or telemetry settings
  

• 构建并运行生产版本：

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

• 运行检查和测试：

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

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/pharmacogenomics-guidelines-mcp-server:latest

镜像默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/pharmacogenomics-guidelines-mcp-server。若要通过 MCP 客户端使用 stdio 运行，请设置 "command": "docker"，并使用 "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/pharmacogenomics-guidelines-mcp-server:latest"]。若要在本地构建，请运行 docker build -t pharmacogenomics-guidelines-mcp-server .；默认会安装 OpenTelemetry 对等依赖项，若要省略这些依赖项，请使用 --build-arg OTEL_ENABLED=false 构建。

项目结构

目录	用途
src/mcp-server/tools/definitions	六个工具定义和 allToolDefinitions 注册表。
src/mcp-server/tools/shared	分页模式和无损 Markdown 渲染。
src/services/cpic	固定主机的 CPIC 请求、源记录模式、发现、证据和建议匹配。
skills	已发布的 Agent 技能，通过 createApp({ skills }) 经由 MCP 提供。
tests/unit	服务、工具契约、边界和格式化器测试。
tests/integration	检查已发布技能资源的 Stdio 服务测试。
tests/scripts	Bundle 清理器和打包 linter 选择器测试。
docs	设计契约和生成的目录树。

开发指南

有关开发指南和架构规则，请参阅 CLAUDE.md。简要来说：

• 处理程序抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 存储数据
• 在 allToolDefinitions（src/mcp-server/tools/definitions/index.ts）中注册新工具；src/index.ts 会将其传递给 createApp()
• 封装外部 API 调用：先验证原始数据 → 再规范化为领域类型 → 最后返回输出架构；绝不伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。