内容
# mcp-okn
一个用于查询 **联合 SPARQL 端点** (`https://apps.okn.us/federation/sparql`) 的 MCP 服务器，适用于 [Proto-OKN](https://www.proto-okn.net/) 知识图谱。
它允许 LLM 发现哪些知识图谱是相关的（来自 [okn-registry](https://registry.okn.us/registry/) 描述），然后运行限定在一个或多个名为 `https://purl.org/okn/frink/kg/{shortname}` 的命名图上的 SPARQL 查询。
---
## 关于 Proto-OKN
[Proto-OKN](https://www.proto-okn.net/) — **原型开放知识网络** — 是一个国家科学基金会倡议（与 NASA、NIH、国家司法研究所、NOAA 和美国地质调查局合作），资助研究团队建立一个公开、可互联的数据存储库和知识图谱集。这些图谱涵盖健康、环境、刑事司法、空间探索和供应链安全等领域，并通过 **FRINK** 联合 SPARQL 端点提供服务，该服务器查询该端点。[okn-registry](https://registry.okn.us/registry/) 目录列出了参与的知识图谱。
---
## 示例
### 示例提示
一旦在 MCP 客户端中配置了服务器（参见 [连接您的客户端](#连接您的客户端)），只需用自然语言提问 — 助手会为您选择图谱、编写 SPARQL 并组合结果。一些可以尝试的提示：
- *"列出所有 Proto-OKN 知识图谱，表格形式，包含短名称和描述。"* — [结果](docs/crosswalks/proto-okn-knowledge-graphs.md)
- *"列出所有已验证的交叉映射，按领域分组，并附上每个映射可以回答的示例。"* — [结果](docs/crosswalks/proto-okn-crosswalk-inventory.md)
- *"给出 spoke-genelab 知识图谱的高级概述 — 其主要类和关系 — 并绘制模式图。"* — [结果](docs/spoke-genelab-schema.png)
- *"哪些基因与 rdkg 关联自闭症谱系障碍？"* — [结果](docs/crosswalks/crosswalks_examples/disease06_q1_spoke-rdkg_autism-genes.md)
- *"每个县的最大 PFAS 测量值是多少？"* — [结果](docs/crosswalks/crosswalks_examples/geospatial04_q1_sawgraph_spatialkg_pfas_max_by_county.md)
- *"如何连接 spoke-okn 和 prokn？显示已验证的配方和共享标识符。"* — [结果](docs/crosswalks/spoke-prokn-join.md)
- *"哪些知识图谱提供 GO、通路或特征注释，以便我可以加入 Entrez？"* — 使用 `find_context_sources` 列出每个提供者及其连接密钥和大小
- *"加载了哪个版本的 prokn，何时更新？"* — 通过 `get_kg_version` 读取 `okn-void` 源
- *"创建此分析的聊天记录。"* — 在可下载的 Markdown 文件中创建记录
- *"创建此分析的 PDF 格式聊天记录。"* — 服务器返回 Markdown，客户端将 `.md` 转换为 `.pdf` 文件（Claude Desktop / claude.ai）
### 交叉映射查询和记录
**交叉映射** 是连接两个（或三个）Proto-OKN 知识图谱的验证方法 — 例如，在一个图谱中链接疾病到另一个图谱中与之相关的基因，通过共同的 MONDO 或 DOID id。由于图谱由不同团队使用不同的本体构建，因此这些连接的价值在于：一个图谱无法单独回答的问题，通过组合两个图谱变得可以回答。本节目录列出了已验证的交叉映射，并展示了执行这些映射的查询。
整个网络的可视化地图 — 所有 33 个图谱之间的 134 个交叉映射，以直接 KG 到 KG 边表示（边宽 ∝ 验证连接计数的对数）。每个交叉映射都是一个独立的边，因此多个交叉映射在同一对图谱之间以平行弧线展开。标识符桥接连接（例如，通过 `ubergraph` 的 `DOID↔MONDO`，通过 `wikidata` 的 `HGNC→Entrez`）显示为直接边，标签中注明桥梁，线条样式（`ubergraph` 桥梁为虚线，`wikidata` 为点线，直接连接为实线）。
> **▶ 点击图片打开交互式、可缩放的网络。**
[](https://sbl-sdsc.github.io/mcp-okn/docs/crosswalks/crosswalk-network.html)
三个资源，每个资源都由实时联合 SPARQL 连接支持，验证后可以回答问题（生物医学声明针对 PubMed / Paperclip 进行检查；地理空间和工业连接针对其权威共享标准进行检查）：
- **[Proto-OKN 交叉映射清单](docs/crosswalks/proto-okn-crosswalk-inventory.md)**
— 单页映射 **已验证的交叉映射**：连接的 KG、共享密钥、行计数和每个映射可以回答的单行注释。从这里开始查看哪些图谱连接以及通过哪个标识符。
- **[跨 KG 交叉映射目录](docs/crosswalks/crosswalks_example.md)**
— **268 个示例问题**，来自已验证的交叉映射 — 每个交叉映射两个问题，除 spoke-genelab×spoke-okn Entrez 连接外，该连接说明两次（G10 表达 + G17 甲基化），共 134 个示例对 — 跨 12 个领域（解剖学和细胞类型、化学品、疾病和表型、环境毒理学、功能和通路、基因、地理空间、工业和供应链、司法和公共安全、蛋白质、社会决定因素和服务、分类学），每个领域都有完整的记录。
- **[多领域集成目录](docs/crosswalks/multi-domain-examples.md)**
— 24 个使用案例，融合 **不同** 领域（例如，毒理学 × 转录组学 × 临床疾病，或 PFAS 采样 × 水文学 × 公共卫生）。
每个目录行都链接到一个独立的、可重放的记录 — 提示、答案和每个 SPARQL 查询及其结果。下面是交叉映射目录中的几个示例：
| 问题 | 知识图谱 | 记录 |
|---|---|---|
| 哪些基因与 rdkg 关联自闭症谱系障碍（通过 ubergraph 桥接 DOID↔MONDO）？ | spoke-okn × rdkg × ubergraph | [md](docs/crosswalks/crosswalks_examples/disease06_q1_spoke-rdkg_autism-genes.md) |
| AOP 靶基因在基因表达 atlas-okn 疾病研究中差异表达 | biobricks-aopwiki × gene-expression-atlas-okn | [md](docs/crosswalks/crosswalks_examples/genes01_q1_aopwiki-gxa_aop-targets-de-disease.md) |
| 按县划分的最大 PFAS 测量值 | sawgraph × spatialkg | [md](docs/crosswalks/crosswalks_examples/geospatial04_q1_sawgraph_spatialkg_pfas_max_by_county.md) |
| 糖尿病基因档案 — pankgraph 基因 × gene-expression-atlas-okn 表达 × spoke-okn 疾病 | gene-expression-atlas-okn × pankgraph × spoke-okn | [md](docs/crosswalks/multidomain_examples/multi-domain01_diabetes_gene_dossier.md) |
这些记录由 `create_chat_transcript` 生成，可以使用 `scripts/replay_transcript.py` 在端点上重新运行。
目录通过驱动模型使用 [交叉映射生成提示](docs/crosswalks/crosswalks_prompt.md) 生成 — 列出每个 `list_crosswalks` 配方，编写每个交叉映射的两个研究问题，运行并验证每个问题为实时 SPARQL，并验证发现结果与文献的一致性。
### 案例研究
七个端到端的分析，联合多个 Proto-OKN 图谱成一个单一的、基于证据的地图 — 四个疾病生物学（基因、变体、通路/基因集、药物、改变的活性签名和临床/生物标志物特征），一个环境 PFAS 源归因（检测与监管设施共定位，解析为化学身份、功能用途和毒理学覆盖），一个双酚的化学暴露组（暴露和工业用途 → 不利结果通路 → 分子靶点 → 测定活性 → 疾病），以及一个累积环境司法负担在美国各县（PFAS、监管设施、社会脆弱性、法院活动、农村性和治疗服务稀缺，按跨来源协议排名）— 每个发现都标记了其来源和证据类型，然后按跨来源协议排名。每个案例研究都附带一个交互式 HTML 报告、一个 Markdown 报告和一个可重放的分析记录（保留每个逐字 SPARQL 查询）。
| 案例研究 | 报告（HTML） | 报告（Markdown） | 分析记录 |
|---|---|---|---|
| **2 型糖尿病** — 9 个 KG，1,327 个发现 | [HTML](https://sbl-sdsc.github.io/mcp-okn/docs/examples/Diabetes2/T2D_knowledge_map_report.html) | [Markdown](docs/examples/Diabetes2/T2D_knowledge_map_report.md) | [记录](docs/examples/Diabetes2/T2D_analysis_transcript.md) |
| **阿尔茨海默病** — 8 个 KG，491 个发现 | [HTML](https://sbl-sdsc.github.io/mcp-okn/docs/examples/Alzheimers/AD_knowledge_map_report.html) | [Markdown](docs/examples/Alzheimers/AD_knowledge_map_report.md) | [记录](docs/examples/Alzheimers/AD_analysis_transcript.md) |
| **多发性硬化** — 7 个 KG，474 个发现 | [HTML](https://sbl-sdsc.github.io/mcp-okn/docs/examples/MS/MS_knowledge_map_report.html) | [Markdown](docs/examples/MS/MS_knowledge_map_report.md) | [记录](docs/examples/MS/MS_analysis_transcript.md) |
| **与空间飞行相关的神经眼综合征（SANS）** — 8 个 KG，1,203 个基因签名 | [HTML](https://sbl-sdsc.github.io/mcp-okn/docs/examples/SANS/SANS_ocular_spaceflight_report.html) | [Markdown](docs/examples/SANS/SANS_ocular_spaceflight_report.md) | [记录](docs/examples/SANS/SANS_reproducibility_transcript.md) |
| **PFAS 源优先级** — 5 个 KG，696 个共定位设施 | [HTML](https://sbl-sdsc.github.io/mcp-okn/docs/examples/PFAS/pfas_source_attribution.html) | [Markdown](docs/examples/PFAS/pfas_source_attribution.md) | [记录](docs/examples/PFAS/PFAS_reproducibility_transcript.md) |
| **双酚的化学暴露组** — 14 个 KG，216 个发现 | [HTML](https://sbl-sdsc.github.io/mcp-okn/docs/examples/Exposome/bisphenol_exposome_report.html) | [Markdown](docs/examples/Exposome/bisphenol_exposome_report.md) | [记录](docs/examples/Exposome/bisphenol_exposome_transcript.md) |
| **累积环境司法负担** — 12 个 KG，70,839 个发现 | [HTML](https://sbl-sdsc.github.io/mcp-okn/docs/examples/Environmental-Justice/report.html) | [Markdown](docs/examples/Environmental-Justice/report.md) | [记录](docs/examples/Environmental-Justice/transcript.md) |
---
## 连接您的客户端
服务器托管在 **`https://apps.okn.us/okn-mcp-dev/mcp`** — 任意 MCP 客户端都指向该 URL，无需本地安装。（有关本地安装，请参见 [本地安装](#本地安装)。）
### Claude Desktop
1. 打开 **设置 → 连接器 → 添加自定义连接器**。
2. 命名为 `mcp-okn-dev`，输入 URL `https://apps.okn.us/okn-mcp-dev/mcp`。
3. 点击 **配置**，将工具权限设置为 **始终允许**。
4. 在新聊天中，点击 `+` 图标并启用 `mcp-okn-dev` 切换开关。
> Claude Pro 或 Max 订阅对于 Claude Desktop 中的 MCP 连接器是必需的。
### Claude 代码
从 CLI 注册：
```bash
claude mcp add --transport http mcp-okn-dev https://apps.okn.us/okn-mcp-dev/mcp
```
或将其添加到项目根目录的 `.mcp.json`（或 `~/.claude/settings.json` 以实现通用访问）：
```json
{
"mcpServers": {
"mcp-okn-dev": {
"type": "url",
"url": "https://apps.okn.us/okn-mcp-dev/mcp"
}
}
}
```
使用 `/mcp` 验证 — 您应该看到 `mcp-okn-dev` 列为已连接。
### ChatGPT
在 <https://chatgpt.com> 支持 ChatGPT 网页应用。
1. 登录 <https://chatgpt.com>。
2. 点击您的个人资料名称/头像。
3. 打开 **设置**。
4. 进入 **应用**。
5. 打开 **高级设置**。
6. 启用 **开发者模式**（ChatGPT 中自定义 MCP 应用所需）。
7. 返回 **应用**。
8. 点击 **创建应用**。
9. 输入 MCP 应用详细信息：
- **名称：** `mcp-okn-dev`
- **网址：** `https://apps.okn.us/okn-mcp-dev/mcp`
10. 保存或创建应用。
11. 开始新的聊天。
12. 点击消息框中的 `+` 按钮。
13. 从可用应用/工具列表中选择 `mcp-okn-dev`。
14. 在测试前关闭 **网络搜索**，以便 ChatGPT 使用 MCP 应用而不是网络搜索。
15. 运行验证提示。如果 ChatGPT 返回图谱列表，则 MCP 应用正在工作。
> ChatGPT 中需要订阅 MCP 连接器。
### VS Code + GitHub Copilot
在代理模式下将 MCP 与 GitHub Copilot 扩展一起使用，网址相同：`https://apps.okn.us/okn-mcp-dev/mcp`。
---
## 本地安装
要自己运行服务器而不是使用托管服务：
### 要求
安装 **[uv](https://docs.astral.sh/uv/)** （参见
[安装指南](https://docs.astral.sh/uv/getting-started/installation/)），
然后克隆此仓库：
```bash
git clone https://github.com/sbl-sdsc/mcp-okn.git
```
### 注册服务器
对于 Claude 代码，从 CLI 注册：
```bash
claude mcp add mcp-okn -- uv --directory /path/to/mcp-okn run mcp-okn
```
或将其添加到任何 MCP 客户端的配置中（例如 Claude Desktop `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"mcp-okn": {
"command": "uv",
"args": ["--directory", "/path/to/mcp-okn", "run", "mcp-okn"]
}
}
}
```
将 `/path/to/mcp-okn` 替换为您的绝对路径。
---
## 工具和资源
### 工具
工具遵循典型的分析流程 —— **发现 → 检查 → 计划连接 → 查询 → 记录**。下面的单个表格按此顺序分组。
| 工具 | 用途 |
| --- | --- |
| **1. 发现图谱** | |
| `list_kgs` | 列出所有知识图谱（KG），包含 `shortname`、`title`、`description`、`homepage`、`named_graph` 和 `payload` 列表 —— 每个图谱提供的精选上下文类型（例如 `digcfdekg` → `gene, gene_set, trait, disease`），以便您根据图谱的内容进行评估，而不仅仅是名称。数据来源于捆绑的快照，实现即时启动。 |
| `describe_kg(shortname, long_description=False)` | 单个知识图谱的完整注册文档（前言 + 正文），提供更深入的上下文。设置 `long_description=True` 以获取注册文档的大约 150 字正文 —— 在选择近似重叠的知识图谱时非常有用。对于 `spoke-genelab`，还会附加其 [空间飞行试验比较规则](#spoke-genelab-spaceflight-assay-comparisons)。 |
| `get_kg_version(shortname=None)` | 知识图谱的发布 `version` 和 `last_updated`（ISO-8601 时间戳）—— 直接从 `okn-void` 元图谱的 VoID 来源读取（`pav:version`、`pav:lastUpdatedOn`）。省略 `shortname` 以获取所有记录来源的知识图谱（42 个中的 39 个），按短名称排序。使用它来检查图谱的更新状态或引用分析背后的确切版本。 |
| **2. 检查图谱的模式和标识符** | |
| `get_schema(shortname, compact=True)` | 单个知识图谱的模式 —— 类、谓词、边属性（带有重构查询模板）和节点属性。在可用时使用精选的元数据，否则通过探测端点获取不同类/谓词。**查询前**调用此函数。返回具有查询时域规则的图谱的 `usage_notes`（指南 + 可重用的 SPARQL 代码段），例如 [`spoke-genelab`](#spoke-genelab-spaceflight-assay-comparisons)。 |
| `visualize_schema(shortname)` | 知识图谱模式的确定性 Mermaid `classDiagram`，通过 `get_schema` 在服务器端生成 —— 类框、标记的边和边属性谓词作为具有类型字段的中介类（节点类为浅蓝色，边类为橙色，并带有图例）。当精选元数据命名谓词但不命名其端点时，边会从图谱的 `rdfs:domain`/`rdfs:range` 恢复，限定在精选类内。返回 `mermaid_block`（已经包装在 ` ```mermaid ` 围栏中）—— 原样输出；不要重绘为 SVG/图像。渲染示例：[spoke-genelab](docs/spoke-genelab-schema.png)、[dreamkg](docs/dreamkg-schema.png)、[rdkg](docs/rdkg-schema.png)（[详情](docs/verification-visualize-schema.md)）。 |
| `probe_namespaces(shortname, predicate, sample=0)` | 报告哪些标识符/本体命名空间填充谓词的对象。`get_schema` 列出了知识图谱的谓词，但没有列出哪些受控词汇填充了它们的值 —— 在主要查询前调用此函数，以查看实际的命名空间分布并选择最佳连接标识符。探索性 —— 不记录。 |
| `find_crosswalks(shortname, sample=0)` | 以任意编码方式查找知识图谱中的本体/数据库 ID，配置文件同时涉及三个位置：映射谓词（`rdfs:seeAlso`、`owl:sameAs`、SKOS `*Match`、`oboInOwl:hasDbXref`）、节点 IRI（即本体术语）（`role="subject"`）和特定领域谓词携带 ID（`role="object"`）。后两个在仅扫描映射谓词时是不可见的。只要知识图谱似乎缺少明显的谓词上的所需标识符，就使用此函数。 |
| **3. 计划跨图谱连接** | |
| `list_crosswalks(include_examples=True)` | 一次调用列出 **所有** 已验证的跨知识图谱集成点 —— 一个全局地图，显示哪些图谱连接以及基于什么共享密钥。行按 `domain`（基因、地理空间、疾病和表型……）分组，并按本体排序，以便呈现为表格。每一行都是一个紧凑的摘要（`domain`、连接的 `kgs` 按官方短名称连接顺序、 `shared_key`、`bridge_kg`、`verified_count` 和示例问题（默认）；设置 `include_examples=False` 以获取更简洁的列表）。对于单个对的完整配方，请使用 `get_join_strategy(kg_a, kg_b)`。 |
| `get_join_strategy(kg_a, kg_b=None)` | 查找加入两个知识图谱的预计算、手动验证的配方 —— 谓词、角色、共享标识符、桥图、验证计数和可运行的 `skeleton_query`（示例 SPARQL 复制和构建；它已经编码了 IRI 重写）。**查询前**调用此函数。返回 `verified` / `known_non_join` / `unknown`；省略 `kg_b` 以列出与 `kg_a` 相关的所有连接。 |
| `find_context_sources(want=None, join_key=None)` | 反向能力索引 —— `get_join_strategy` 的逆。回答“哪些知识图谱 **提供** 路径 / GO / 表型 / 疾病 …… 对于我可以通过 `join_key` 连接的实体？”通过将每个知识图谱的 `payload` 标签与验证的交叉表结合。返回每个请求的上下文类型，提供知识图谱的谓词 + 共享密钥 + 验证连接 `size`，**按最大连接排序**，以及一个 `payload_only` 存储桶（知识图谱携带类型但关键字不同，例如 Ensembl 与 Entrez）。请求的空列表是积极证据，表明没有任何内容在该密钥上提供，因此您永远不会在检查前得出结论，某个上下文是“不可用的”。 |
| `taxon_overlap(kg_a, kg_b)` | 通过 `ubergraph` 组成两个中心知识图谱之间的 NCBITaxon 重叠。返回两个可运行的骨架 —— `exact_id`（相同的分类标识符）和 `clade_membership`（kg_b 分类标识符在 kg_a 的分类 * 下，属于 `subClassOf*`，这可能在其中一侧粒度较粗时更大）—— 以及，对于具有预计算的非零重叠的对，`materialized_overlap` 下的物化计数（`list_crosswalks` 在 NCBITaxon 中显示的相同对计数）。使用 `sparql_query` 运行骨架。 |
| `point_to_s2(lat, lng, level=13)` | 将纬度/经度点转换为其空间 kg/KWG S2 单元格 IRI（默认为 13 级）—— 空间桥背后的确定性基元。在知识图谱携带 POINT 坐标但没有 S2 密钥时使用，您需要单元格 IRI 空间 kg 存储。 |
| `spatial_bridge(point_query, target_pattern, select_vars="*", extra_prefixes="", limit=500)` | 适用于 **任何** 带有点的图谱的通用点到 S2 桥，该图谱缺少存储的 S2 密钥（sudokn 是第一个此类图谱）。`point_query` 必须 `SELECT ?site ?lat ?lng`；服务器在 Python 中计算每个单元格，并将 `(?site ?cell)` 作为 `VALUES` 块注入到联合查询中，其 `target_pattern` 将 `?cell` 连接到 spatialkg/fiokg/sawgraph（例如，县/FIPS）。没有任何内容被持久化；计算出的密钥仅在请求内部存在。 |
| **4. 运行查询** | |
| `sparql_query(query, format="json", exploratory=False, compact=False)` | 在联合查询端点上运行 SPARQL 查询。对于交互记录，除非 `exploratory=True`，否则会记录实质性结果。通过 `compact=True` 获取高效的 JSON 形状 —— `{ "columns", "data", "count" }` 带有位置行 —— 而不是默认的重复键 `{ "vars", "rows", "row_count" }`（仅影响返回的有效载荷，而不影响交互记录）。带括号的 `<https://schema.org/…>` IRI 被规范化为 `http://` 形式，以便大多数知识图谱存储（字符串文字和 `IRI(CONCAT(…))` 按原样书写）。少数知识图谱存储 `https://` 形式（nikg、ruralkg、ufokn）；通过绑定谓词作为变量并匹配无模式，可以访问这些谓词，例如 `FILTER(STRENDS(STR(?p),'schema.org/location'))`。 |
| `expand_ontology_term(term, relation="subClassOf", direction="descendants", include_self=True, limit=1000)` | 通过 `ubergraph` 图谱扩展本体术语到其完整子树/闭包。 |
| **5. 记录可复制的交互记录** | |
| `reset_query_log()` | 清除会话查询日志。在分析开始时调用此函数，以限定交互记录的范围。 |
| `get_query_log()` | 返回此会话记录的查询（仅返回行且非探索性）。 |
| `create_chat_transcript(model, exchanges, ...)` | 发出会话的可复制的 Markdown（或 JSON）记录 —— 提示、答案、产生发现的原始查询 + 结果，以及任何 `visualize_schema` 图表。在分析 **结束** 时调用此函数。 |
### 资源
| 资源 | 用途 |
| --- | --- |
| `transcript://session/latest` (`text/markdown`) | 由 `create_chat_transcript` 渲染的最新交互记录，以便客户端可以直接获取/保存文档（与传输无关；适用于远程服务器）。由 `reset_query_log` 清除。 |
---
## 开发
### 设计
- **[mcp-okn redesign](docs/mcp-okn-redesign.md)** （也作为 [幻灯片，PDF](docs/mcp-okn-redesign.pdf)）
— 之前 **`mcp-proto-okn`** 服务器与此 **`mcp-okn`** 重设计的并排比较，涵盖查询模型、知识图谱覆盖、模式/注册处理、跨图连接和可复制性。
### 模块布局
软件包按关注点组织。`server.py` 是一个薄的组装点：它导入工具模块以触发它们的 `@mcp.tool()` 注册并重新导出它们的公共符号（因此 `from mcp_okn.server import ...` 仍然有效）。共享的 `mcp` 应用程序实例位于 `app.py` 中，与 `server.py` 分开，以便工具模块可以导入它而无需循环依赖。
```
src/mcp_okn/
├── app.py # 共享的 FastMCP `mcp` 实例 + 指令
├── server.py # 组装点：注册工具，重新导出，main()
├── registry.py # 来自 okn-registry 的知识图谱发现（+ 捆绑快照）
├── schema.py # get_schema / visualize_schema 逻辑
├── sparql.py # 联邦查询端点客户端 + schema.org 规范化
├── crosswalks.py # 精选的跨知识图谱连接表（data/crosswalks.json）
├── payloads.py # 精选的每知识图谱 payload 标签（data/kg_payloads.json）
├── void.py # 每知识图谱版本 / 最后更新自 okn-void 图谱
├── taxon.py # NCBITaxon 中心：分类重叠骨架组成
├── session.py # 内存查询/图表日志用于交互记录
├── data/ # 捆绑快照：kgs.json, crosswalks.json, kg_payloads.json
└── tools/ # 每个关注点的模块；每个模块通过 @mcp.tool() 注册
├── _shared.py # >1 工具模块使用的帮助程序（_to_uri，…）
├── discovery.py # list_kgs, describe_kg, get_kg_version
├── schema_tools.py # get_schema, visualize_schema
├── probe.py # probe_namespaces, find_crosswalks
├── joins.py # get_join_strategy, taxon_overlap, list_crosswalks, find_context_sources
├── query.py # sparql_query, expand_ontology_term
└── transcript.py # reset/get_query_log, create_chat_transcript, resource
```
```bash
uv run python -m pytest # 单元测试（离线）
uv run ruff check . # 校验
uv run ruff format . # 自动格式化（在 CI 中使用 --check）
uv run mypy # 类型检查 src/mcp_okn
# 现场烟雾测试：
uv run python -c "import asyncio; from mcp_okn.sparql import run_sparql; \
print(asyncio.run(run_sparql('SELECT ?s WHERE { ?s ?p ?o } LIMIT 3')))"
```
CI（`.github/workflows/ci.yml`）在每次推送/拉取请求时运行 ruff 校验、ruff 格式检查和 mypy，以及 Python 3.10 和 3.12 上的离线测试套件。
待改进项在 [BACKLOG.md](BACKLOG.md) 中跟踪 —— 目前为空。
### 验证笔记
对离线单元测试无法覆盖的行为进行可复制检查：
- [schema.org http/https 规范化](docs/verification-schema-org-normalization.md)
— 带括号的 `<https://schema.org/…>` IRI 规范化为 `http`，因此查询
编写为 `https` 形式仍然可以命中存储的 `http` 数据（dreamkg `schema:Rating`
→ 3762），而字符串文字 / `IRI(CONCAT(…))` 保持不变（见下文）。
- [visualize_schema 渲染](docs/verification-visualize-schema.md) — 生成的
Mermaid 以类图形式通过 `mermaid-cli` 清晰渲染，跨三种模式路径（精选、仅类、探测回退），并且在 `create_chat_transcript` 往返后存活。
- [交互记录 MCP 资源](docs/verification-transcript-resource.md) — `transcript://session/latest`
资源通过资源 API 提供完整的文档，带有嵌入的图表，仍可渲染。
#### 以非规范的 `https` 形式存储的 schema.org 谓词
少数图谱以 `https://` 形式存储 schema.org 术语。规范化
仅影响 **带括号的 IRI**，因此这些谓词无法通过 IRI 访问（带括号的
`https` 形式被重写为 `http`，数据不是），但在谓词
绑定为变量或 IRI 从字符串文字重建时匹配（现在保留）。
在联邦查询中验证：
| 图谱（谓词） | `<https://schema.org/X>` （带括号） | `IRI(CONCAT('https://schema.org/','X'))` | `STRENDS(STR(?p),'schema.org/X')` |
| --- | --- | --- | --- |
| `nikg` (`location`) | 0 | 296,189 | 296,189 |
| `ruralkg` (`postalCode`) | 0 | 9,037 | 9,037 |
| `ufokn` (`value`，13 级样本) | 0 | 5/5 (`LIMIT 5`) | 5/5 |
在每种情况下，`IRI(CONCAT)` 和 `STRENDS` 形式一致（相同行 / 相同十进制 S2
ID for ufokn），而带括号的 IRI 返回 0 — 确认 literal-preservation
修复和变量谓词变通方法记录在 `ruralkg` / `ufokn` 交叉映射
注释中。
#### spoke-genelab 空间飞行试验比较
`spoke-genelab` （NASA GeneLab）将每个差异测量建模为具有两个臂的 `Assay`
—— `factor_space_1` / `factor_space_2` （条件标签）和
`factors_1` / `factors_2` （列表捆绑条件标签 * 加额外因素
如剂量、时间、性别、菌株）。将任何试验读作“空间飞行效应”是
错误的；两个领域规则适用：
1. **方向** — 仅保留 `factor_space_1 = "Space Flight"` **和**
`factor_space_2 = "Ground Control"`。丢弃反向和所有其他配对。
验证现场：**680** 试验是 SF→GC 而 **664** 是反向（另外 1244 个 SF/SF，
424 个 GC/GC 和 Basal/Vivarium 配对）。通过此方向分组 1 =
Space Flight，因此 `log2fc` / `methylation_diff` / `lnfc` > 0 表示在空间飞行中增加。
2. **可比性** — 只有两个单独的 `Assay` 记录如果它们
共享相同的材料（优先使用 `material_id_1` / `material_id_2`）**和**
相同的 `factors_1` / `factors_2` *在* 删除实验条件标签后，
然后测试剩余因素的相等性（允许存在一个共享因素如果它存在于两侧）。
剥夺只删除了 **15** 个不同值，现场验证：拼写出的标签
（`Space Flight`，`Ground Control`，`Basal Control`，`Vivarium Control`，
`Cell Culture Control`；不区分大小写，因此 `Ground control` / `Vivarium control`
匹配）和短组代码通过 **锚定** 正则表达式
`^(GC|FLT|VIV|BSL|CC)(_C[0-9]+)?$`（`GC`，`FLT`，`VIV_C2`，`BSL_C1`，`CC_C1`，...）。
锚定是故意的：真正的因素如果仅包含控制词 —
`Hardware 1G Ground Control`，`Ground Control Rerun`，`HLU_IR`
（下肢卸载）— 保留为合法的不同因素。
规则存在于 `src/mcp_okn/contrasts.py`（指南正文 + 可重用
SPARQL 签名）和服务器 `INSTRUCTIONS` 中，作为 `usage_notes` 在
`get_schema("spoke-genelab")` 上，并追加到
`describe_kg("spoke-genelab")`。
### 知识图谱快照
`list_kgs` 提供一个捆绑的快照，位于 `src/mcp_okn/data/kgs.json` (~42
个知识图谱），因此第一次调用会立即返回而无需获取各个注册文件。
仅当缺少快照时（或传递内部 `refresh=True`）才会联系实时注册。
要刷新快照，请在注册更改后：
```bash
uv run python scripts/refresh_snapshot.py
```
注册中但未在其预期的联合查询命名图下实际加载的知识图谱（目前为
`semopenalex`）将被过滤
掉，因此 `list_kgs` 只返回可以查询的图谱。
精选的交叉映射表在 `metadata/crosswalks.json` 中编辑，并由相同的
`refresh_snapshot.py` 运行捆绑到 `src/mcp_okn/data/crosswalks.json`。
两个帮助程序将实时验证的计数重新计算到联合查询，并将它们写回去：
`scripts/verify_skeletons.py` （每个交叉映射的 `skeleton_query` 计数）和
`scripts/refresh_taxon_overlaps.py` （NCBITaxon 中心对的成对 `exact_id` + 分类
计数 — `--inject` 写入， `--pair A B` 用于一对）。运行 `refresh_snapshot.py`
后再同步捆绑副本。
### 有效载荷标签
每个知识图谱都带有精选的 `payload` 标签 — 它 **提供** 的上下文类型 —
在 `metadata/kg_payloads.json` 中编辑，并在 `refresh_snapshot.py` （验证每个标签
都是定义的词汇术语，并且每个可服务知识图谱都有标签）。这些标签
部分源自每个知识图谱的实体模式，`get_schema` 从上游的 `*_entities.csv`
文件实时获取 — 因此知识图谱的模式可以在标签下更改。
`scripts/check_payload_drift.py` 防止这种情况：它指纹每个知识图谱的实时类 +
## 引用
`mcp-okn` 是 [`mcp-proto-okn`](https://github.com/sbl-sdsc/mcp-proto-okn) 的下一代继承者。如果您使用该软件，请引用描述前者的论文：
> Rose, P. W., Good, B. M., Saravia-Butler, A. M., Nelson, C. A., Balhoff, J. P.,
> Kebede, Y., Whetzel, P. L., Bizon, C., Su, A. I., & Baranzini, S. E. (2026).
> *mcp-proto-okn：通过模型上下文协议访问开放的科学知识图谱*
> arXiv:2605.30283。
> <https://arxiv.org/abs/2605.30283>
```bibtex
@misc{rose2026mcpprotookn,
title = {mcp-proto-okn：通过模型上下文协议访问开放的科学知识图谱},
author = {Rose, Peter W. and Good, Benjamin M. and Saravia-Butler, Amanda M. and Nelson, Charlotte A. and Balhoff, James P. and Kebede, Yaphet and Whetzel, Patricia L. and Bizon, Christopher and Su, Andrew I. and Baranzini, Sergio E.},
year = {2026},
eprint = {2605.30283},
archivePrefix = {arXiv},
primaryClass = {cs.AI},
url = {https://arxiv.org/abs/2605.30283}
}
```
---
## 资金支持
- **美国国家科学基金会** 奖项 [#2333819](https://www.nsf.gov/awardsearch/show-award?AWD_ID=2333819): "Proto-OKN 主题 1：通过 SPOKE 知识图谱连接地球和太空的生物医学信息"
- **美国国家科学基金会** 奖项 [#2535091](https://www.nsf.gov/awardsearch/show-award?AWD_ID=2535091): "Proto-OKN 主题 2：OKN-Fabric"
---
## 许可证
该项目在 [BSD 3-Clause License](LICENSE) 下获得许可。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器