CIViC MCP Server

CIViC MCP 服务

这是一个基于 Cloudflare Workers 的模型上下文协议（MCP）服务，提供用于查询 CIViC（癌症变异临床解读）API 的工具。该服务使用 Durable Objects 将 GraphQL 响应转换为可查询的 SQLite 表，以便高效处理数据。

CIViC 数据库是一个由社区共同维护的癌症变异临床解读资源库。此 MCP 服务支持通过与 AI 助手进行自然语言交互，对癌症基因组信息进行结构化查询和数据分析。

MCP 规范合规性

此服务通过 fleet 的无状态 SDK v2 适配器实现 MCP 2026-07-28：

• server/discover 取代初始化，且每个请求都携带协议/能力封装。
• Worker 使用无状态 Streamable HTTP，不使用 MCP 会话 Durable Object 或 Mcp-Session-Id。
• SDK 会验证 Mcp-Method / Mcp-Name，添加 resultType 和 serverInfo，并提供缓存提示。
• 工具列表采用确定性的注册顺序。
• 工具在成功和出错时都会返回 content 和 structuredContent；出错时会设置 isError: true。
• 大型结构化结果会保留 fleet 的暂存机制和 100KB 传输保护。

工具注解参考

此服务为 MCP 客户端定义了全面的工具注解：

// GraphQL Query Tool
annotations: {
  readOnlyHint: false,      // Creates/modifies data in SQLite
  destructiveHint: false,   // Non-destructive data staging
  idempotentHint: false,    // Different queries produce different results
  openWorldHint: true       // Interacts with external CIViC API
}

// SQL Query Tool  
annotations: {
  readOnlyHint: true,       // Only reads data
  destructiveHint: false,   // Cannot modify data (read-only SQL)
  idempotentHint: true,     // Same query produces same results
  openWorldHint: false      // Operates on closed SQLite database
}

传输

// MCP 2026-07-28 stateless Streamable HTTP
CivicMCP.serve("/mcp").fetch(request, env, ctx)

保留的 Durable Objects 仅用于应用/数据对象的暂存； 它们不是 MCP 传输会话。

功能

• GraphQL 转 SQL：自动将 CIViC API 响应转换为结构化 SQLite 表
• 高效数据存储：使用 Cloudflare Durable Objects 和 SQLite 暂存并查询数据
• 智能响应处理：对于小型响应、错误和架构内省查询，跳过暂存以优化性能
• 工具流水线：
  1. civic_graphql_query：执行 GraphQL 查询并暂存大型数据集
  2. civic_query_sql：支持对暂存数据进行基于 SQL 的分析
  3. civic_execute：代码模式 — 在 V8 isolate 中运行 JavaScript，并使用 gql.query() 和架构辅助工具全面访问 GraphQL

安装与配置

前提条件

• Cloudflare 账户
• 已安装 Wrangler CLI
• Claude 桌面应用

部署到 Cloudflare Workers

1. 克隆此仓库：

   git clone <repository-url>
   cd civic-mcp-server
   

2. 安装依赖项：

   npm install
   

3. 部署到 Cloudflare Workers：

   npm run deploy
   

4. 部署完成后，你会获得类似这样的 URL：https://civic-mcp-server.YOUR_SUBDOMAIN.workers.dev

配置 Claude 桌面应用

将此配置添加到你的 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "civic-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://civic-mcp-server.quentincody.workers.dev/mcp"
      ]
    }
  }
}

将 quentincody 替换为你的实际 Cloudflare Workers 子域名。

使用方法

配置完成后，重启 Claude 桌面应用。此服务提供三个主要工具：

1. civic_graphql_query：针对 CIViC API 执行 GraphQL 查询
2. civic_query_sql：使用 SQL 查询暂存数据
3. civic_execute：代码模式 — 在 V8 isolate 中编写 JavaScript，以访问 CIViC GraphQL API

提示词

此服务提供三个 MCP 提示词，指导模型使用 civic_graphql_query 工具，并采用正确的 GraphQL 语法和可靠的搜索策略：

单独的数据类型提示词

• get-variant-evidence — 仅为证据条目生成 GraphQL（不使用 variantName 筛选条件，因为 CIViC 架构不支持）
• get-variant-assertions — 仅为断言生成 GraphQL，并采用系统性的回退策略

组合数据提示词

• get-variant-data — 同时执行证据条目和断言查询，进行全面的变异分析

示例（VS Code Copilot Chat / 斜杠命令）：

• /get-variant-evidence molecularProfileName:"TP53 Mutation" diseaseName:"Lung Adenocarcinoma" evidenceType:"PROGNOSTIC" first:"200"
• /get-variant-assertions molecularProfileName:"TPM3-NTRK1 Fusion" therapyName:"Larotrectinib" status:"ALL"
• /get-variant-data molecularProfileName:"BRAF V600E" diseaseName:"Melanoma" therapyName:"Trametinib" status:"ALL"

提示词的主要特点

• 可靠的 GraphQL 生成：完整、经过验证的查询，不会失败
• 智能搜索策略：自动采用备用方法查找相关数据
• 全面的结果：证据条目包含临床描述；断言提供高层级摘要
• 最优筛选：默认状态为 "ALL"，以避免过度筛选；自动排除 null 参数
• 正确生成 URL：提供规范链接以供验证（证据：/evidence/{id}，断言：/assertions/{id}）

这些提示词提供完整的 GraphQL 查询，符合 CIViC v2 架构规范，并采用系统化的搜索方法，即使用户提供的参数不够准确，也能确保发现数据。

查询示例

你可以向 Claude 提出如下问题：

• “BRAF 突变有哪些最新的证据条目？”
• “显示肺癌变异的所有治疗解读”
• “查找 CIViC 数据库中证据条目最多的基因”

Claude 会使用服务（及其 civic_graphql_query 工具）从 CIViC 数据库获取相关数据并呈现给你。该服务专为查询 CIViC API 的第 2 版而设计，确保你获取最新信息。

如果遇到问题，或者 Claude 似乎没有使用 CIViC 数据，请仔细检查上述配置步骤。

响应处理

该服务会将大型结果存储在临时 SQLite 数据库中，从而智能优化上下文用量。当 GraphQL 响应符合特定条件时，会直接返回原始响应，而不创建数据库：

• 小型响应（< 1500 个字符）：直接返回，避免不必要的开销
• 错误响应：直接传递，便于排查问题
• 空/null 响应：跳过处理，以避免创建空数据库
• 架构内省查询：包含 __schema、__type 或其他内省模式的查询会直接返回，因为这类查询包含的是元数据，而非适合转换为 SQL 的数据

这一优化让服务更加高效，并提供更清晰的错误信息，同时仍支持基于 SQL 对大量数据进行强大的分析。

许可证

MIT 许可证（附学术引用要求）——请参阅 LICENSE.md