mcpField
N
ncats-arax

ncats-arax

github.com/k-dense-ai数据与数据库55.1k899 次安装2 天前更新
代码仓库

关于 ncats-arax

NCATS ARAX 是用于生物医学知识图谱查询的受限客户端，采用经审阅的标识符和带类型的 TRAPI 查询。它保留查询及来源信息，供研究人员检查候选路径；结果仍需外部验证。

主要功能

  1. 01规范化并审阅生物医学标识符
  2. 02执行带类型的一跳与两跳查询
  3. 03联合查询指定提供方
  4. 04保存原始 TRAPI 和摘要文件
  5. 05检查查询绑定与来源信息

适用场景

  1. 01查询化合物与基因之间的候选关联
  2. 02探索端点固定的基因—疾病路径
  3. 03比较指定知识提供方的结果
  4. 04审查来源信息后跟进候选路径

MCP 相关

该客户端向 ARAX 服务提交受限的 TRAPI 查询，并支持实体查询与规范化。它保存原始响应和限定范围的摘要，以便检查来源信息。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/k-dense-ai/scientific-agent-skills --skill ncats-arax

安装后在 Claude Code 中输入/ncats-arax确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
output-schema.md
query-contract.md
scripts/
arax_client.py

详细介绍

NCATS ARAX

将 ARAX 用作受限的知识图谱查询服务。提交经过审核的 CURIE 和明确的 Biolink 类型，保留精确的 TRAPI 交换内容，检查查询边绑定与来源信息，并将返回的每一条路径都视为待后续验证的候选。

在构造查询之前，请阅读 query-contract.md。在解读保存的产物、警告、来源信息或部分结果时，请阅读 output-schema.md。

安全边界

  • 仅使用公开、非敏感的研究问题。即使请求了 store=false，ARAX 状态设施仍可能暴露查询和调用方元数据。
  • 不要提交患者信息、机密研究问题、未公开的化合物项目或专有靶点假设。
  • 不要将返回的路径呈现为已验证的机制或临床建议。
  • 将零结果报告为“在这些约束下未返回”，绝不要作为不存在任何关系的证据。
  • 将位置描述为未评分的响应顺序，绝不要描述为排名。
  • 另行通过文献和权威数据库验证重要候选。

工作流

  1. 单独规范化自由文本，然后审核并报告所提议的 CURIE 和类别。
  2. 选择带类型的一跳查询，或两端点均固定的恰好两跳查询。
  3. 除非用户明确指定两到五个提供方，否则使用默认的 RTX-KG2 查询。
  4. 确认该生物医学查询是公开的，并选择一个新的或空的输出目录。
  5. 运行客户端一次。在失败或空结果之后，不要静默更改提供方选择或扩展顺序。
  6. 检查 summary.json 以了解受限绑定和来源信息，检查 response.json 以了解精确的 TRAPI 载荷。
  7. 在 ARAX 之外验证科学上重要的路径。

预检

在不进行生物医学查询的情况下检查生产环境 OpenAPI：

python skills/ncats-arax/scripts/arax_client.py preflight

客户端会验证该服务是否自称为 ARAX、是否暴露 POST /query 和 GET /entity，以及是否报告受支持的 TRAPI 版本。它会读取 info.x-trapi.version，对于较旧的 OpenAPI 文档则回退到标题。非生产环境端点或未经测试的 TRAPI 系列需要显式覆盖；这两种覆盖都不会更改固定的查询形态或操作。

规范化实体

规范化仅供审核，绝不触发图查询：

python skills/ncats-arax/scripts/arax_client.py normalize "ivacaftor" \
  --expected-category biolink:SmallMolecule \
  --max-synonyms 10 \
  --acknowledge-public-query \
  --output-dir outputs/normalize-ivacaftor

在使用 CURIE 之前，请审核规范标识符、名称、类别和同义词预览。无论查询结果如何，都要报告所有 CURIE 和类别。类别警告或零结果是整理标识符的理由，而不是自动链接到 /query 的理由。

一跳查询

至少固定一个端点，并为两个节点指定类型：

python skills/ncats-arax/scripts/arax_client.py one-hop \
  --subject-id CHEBI:31690 \
  --subject-category biolink:SmallMolecule \
  --predicate biolink:affects \
  --object-id NCBIGene:25 \
  --object-category biolink:Gene \
  --qualifier biolink:object_aspect_qualifier=activity_or_abundance \
  --qualifier biolink:object_direction_qualifier=decreased \
  --acknowledge-public-query \
  --output-dir outputs/imatinib-abl1

查询模式是默认模式，会将扩展固定为 infores:rtx-kg2。它默认返回 20 条结果。使用 --result-limit N 请求 1-50 条结果；无论哪种模式，50 都是硬性上限。

端点固定的两跳查询

使用恰好一个带类型、未固定的中间节点：

python skills/ncats-arax/scripts/arax_client.py two-hop \
  --subject-id CHEBI:66901 \
  --subject-category biolink:SmallMolecule \
  --predicate-1 biolink:affects \
  --intermediate-category biolink:Gene \
  --predicate-2 biolink:associated_with \
  --object-id MONDO:0009061 \
  --object-category biolink:Disease \
  --qualifier-1 biolink:object_aspect_qualifier=activity_or_abundance \
  --qualifier-1 biolink:object_direction_qualifier=increased \
  --expand-order right-first \
  --acknowledge-public-query \
  --output-dir outputs/ivacaftor-cystic-fibrosis

右优先扩展是默认方式。如果空结果值得再试一次，请显式使用 --expand-order left-first 运行一个新查询，并将各次运行分开保留。

选定提供方联合查询

联合查询是显式的，接受两到五个指定提供方：

python skills/ncats-arax/scripts/arax_client.py one-hop \
  --subject-id CHEBI:31690 \
  --subject-category biolink:SmallMolecule \
  --predicate biolink:affects \
  --object-id NCBIGene:25 \
  --object-category biolink:Gene \
  --mode federated \
  --kp infores:rtx-kg2 \
  --kp infores:molepro \
  --acknowledge-public-query \
  --output-dir outputs/federated-imatinib-abl1

联合查询默认使用硬性上限 50 条结果。提供方错误可能与有用结果并存；此类运行会在保留其产物后以退出码 7 退出，并被标记为部分结果。查询模式中某个提供方失败时同样如此。显式的非成功 ARAX 响应状态会以退出码 6 退出，并保留原始响应；不得将其报告为成功的零结果查询。

检查保存的来源信息

在没有网络访问的情况下重建受限摘要：

python skills/ncats-arax/scripts/arax_client.py summarize \
  --request outputs/ivacaftor-cystic-fibrosis/request.json \
  --response outputs/ivacaftor-cystic-fibrosis/response.json \
  --format text

检查器仅接受与实时命令生成的相同受限请求形态和固定操作。使用 --format json 在标准输出上获取规范化视图。

解读结果

  • 遵循每个分析的查询边绑定；不要对每一条知识图谱边都进行概括。
  • 保留 ARAX 返回的物理边主语、谓语、宾语和限定符值。 返回的谓语或限定符方面可能比查询约束更具体。
  • 检查所有源对象，包括 primary、aggregator、supporting-data、upstream-resource 和 source-record URL 字段。
  • 在声称得到佐证之前，将 aggregator 边追溯到其 primary/upstream 来源和出版物。多个提供方可能 重新分发同一条记录；报告不同的 primary 证据，而不是将提供方数量作为置信度或独立复现。
  • 将 publication_availability: not_returned 视为缺失元数据，而不是不存在出版物的证据。
  • 将缺失的辅助图引用和提供方故障视为显式警告。
  • 当有界摘要省略细节，或服务响应不完整、不熟悉或在科学上令人意外时，查阅原始响应。

有意排除的功能

该客户端没有 raw-query、workflow、operation、overlay、ranking、inference、link-prediction、 Pathfinder、ARS、batch、all-provider、three-hop、cache、daemon、SDK、MCP 或 natural-language-to-TRAPI 接口。不要在本技能下通过直接 HTTP 调用来绕过这些限制。

官方参考

于 2026-09-30 对照生产环境 ARAX 1.5.4 / TRAPI 1.5.0 审阅（URL 中仍包含 v1.4）。 preflight、normalization、qualified one-hop 和 endpoint-pinned two-hop 查询，以及 RTX-KG2/MolePro 联合的实时公开冒烟测试已通过。结果和提供方可用性可能发生变化。 官方入门指南包含较旧的响应示例；请使用已部署的 schema 和当前 ARAX 源代码作为字段和操作 契约。该客户端不使用任何 Python SDK。

评论

支持 Markdown