华大数据中台（bgi-data-mcp）

通过 MCP 服务 bgi-data-mcp 办理华大数据中台业务。参数以运行时 list_catalog 为准；与本手册不一致时以 list_catalog 为准。

全量 action / keys / 示例见 reference/。环境与配置见 env.md。

何时使用

• 用户要查或办华大数据中台业务（项目、合同、报价、审批、物料、投入、财务、伦理、成果、时空组学任务单/样品/质检等）
• 用户要查 ILIMS 联单任务单 / 联单样品（data_joint_task）
• 用户要查 DCSLIMS / GLIMS 建库测序（任务单、执行单、异常、文库、测序质控）
• 用户要安装 / 配置 / 排查 bgi-data-mcp（华大数据中台 MCP）

前置：检测并安装 MCP

每次办理华大数据中台业务前，先确认 MCP 可用。不可用则先完成安装配置，再执行业务。

1. 检测是否已安装

任选其一：

• 当前宿主已暴露 list_catalog、data_project 等 tool
• 调用 list_catalog(system="data") 能成功返回模块列表

若 tool 不存在 / 鉴权失败 / 调用 401 → 进入下方安装流程。

2. 未安装时的安装流程（Agent 必须执行）

1. 向用户确认（缺一不可，不要猜令牌；地址未指定则用生产默认）：
   - MCP url：须为 {Base}/mcp/pm。生产默认 https://bgipm.genomics.cn/pm-mcp/mcp/pm；其它环境为 https://<IP或域名>/pm-mcp/mcp/pm
   - PAT（必填，必须由用户提供）：写入 Authorization。用户若没有或不知道令牌，引导前往对应环境 PM 系统 → 个人中心 → 生成/启用个人访问密钥（PAT，pm_pat_…），拿到后再继续配置。禁止自行编造或跳过
2. 可选健康检查（无需鉴权）：GET {Base}/health，生产即 https://bgipm.genomics.cn/pm-mcp/health；不通则请用户确认地址/网络
3. 按当前宿主的 MCP 配置方式加入服务 bgi-data-mcp（Streamable HTTP：url + headers.Authorization）；仅在用户已提供 PAT 后写入，勿覆盖其它已有 MCP 服务
4. 提示用户：保存配置后在当前宿主中刷新/启用该 MCP，确认 tool 已出现
5. 复检：再调 list_catalog(system="data")；成功后再办业务

禁止：把真实 PAT 写进 skill、README 或提交到 git。禁止在用户未提供 PAT 时完成安装或调用业务 tool。

3. MCP 连接参数（仅 PAT）

服务名固定为 bgi-data-mcp。地址约定见 env.md。

Authorization 必须由用户提供真实 PAT。没有则请用户到 PM 系统个人中心生成密钥，再配置。

生产默认：

{
  "mcpServers": {
    "bgi-data-mcp": {
      "url": "https://bgipm.genomics.cn/pm-mcp/mcp/pm",
      "headers": {
        "Authorization": "pm_pat_用户提供的令牌"
      }
    }
  }
}

Agent 不得在用户未提供的情况下写入空令牌或占位符并当作已配置完成。配置文件路径、字段名以当前宿主 MCP 客户端文档为准；上表是 Streamable HTTP 的通用连接参数。

Agent 只负责把 url 与 PAT 配进当前宿主；地址不通时请用户确认 URL/网络，不要假装已连通。无 PAT 时停下来引导去 PM 系统个人中心生成秘钥，不要继续业务调用。

调用契约

1. （若未安装）先完成上一节安装
2. list_catalog() 或 list_catalog(system="data") → 看模块 / tool 名
3. list_catalog(system="data", module="<域>") → 看 action、keys、kind、必填项
4. data_<域>(action="...", keys={...}) → 执行
5. 缺必填 keys：先问用户，不要猜

分页统一：page（从 1）、page_size。联单与建库测序的 page_size 最大 500。

宿主

• MCP 服务名为 bgi-data-mcp（宿主展示名可能带前缀，以实际 tool 列表为准）
• 先按宿主方式确认 tool schema，再调用
• Authorization 由宿主注入 PAT；禁止做成或调用 login / logout / status tool

鉴权（宿主侧，仅 PAT）

权限菜单变更后：data_auth(action="refresh_perms", keys={})（write）。

写操作

kind=write 在必填 keys 齐后会真实执行下游，无二次 confirm。
服务端 bgi.pm.mcp.write-enabled=false 时返回 WRITE_DISABLED。

响应习惯

• 成功：看 sources[0]，ok=true；列表在 records，中文列名在 fields
• 失败：MISSING_KEYS / FORBIDDEN / BIZ_ERROR / UNKNOWN_ACTION / WRITE_DISABLED 等
• 导出类 action：只返回 fileName + downloadUrl，无文件二进制

模块索引

易混速查

更多对照与错误码见 pitfalls.md / faq.md。

最小示例

list_catalog(system="data", module="quotation")
data_quotation(action="ls", keys={"page": 1, "page_size": 10})
data_project(action="ls", keys={"project_type": "1"})
data_project(action="info", keys={"project_code": "...", "section": "basic"})
data_flow(action="ls", keys={})
data_contract(action="ls", keys={"name": "..."})
data_auth(action="refresh_perms", keys={})
list_catalog(system="data", module="stomics")
data_stomics(action="order_ls", keys={"order_code": "QDST20230810003"})
data_stomics(action="qc_ls", keys={"sample_code": "T2607721155"})
list_catalog(system="data", module="joint_task")
data_joint_task(action="ls", keys={"page": 1, "page_size": 10, "status": "生产中"})
data_joint_task(action="samples", keys={"task_order_num": "JT202601001"})
list_catalog(system="data", module="task_order")
data_task_order(action="ls", keys={"page": 1, "page_size": 10, "status": "生产中"})
data_task_order(action="samples", keys={"pb_code": "W260728019"})
data_seq_qc(action="ls", keys={"slide": "SL1"})
data_seq_qc(action="cyclone_ls", keys={"flow_cell": "FC1"})