内容
# togodx-mcp
一个连接人工智能代理到 [TogoDX/Human](https://togodx.dbcls.jp/human/) 的 [MCP](https://modelcontextprotocol.io/) 服务器，TogoDX/Human 是一个用于探索整合生命科学数据的平台。
代理可以从自然语言中建立过滤条件，导出 TogoDX UI 可上传的预设 JSON，映射用户 ID 列表，并获取结果表格 —— 实现 **可解释、可验证的 AI 辅助数据探索**。
## 功能
- **属性发现** — 在 8 个类别（基因、蛋白质、结构、相互作用、化合物、糖链、疾病、变异）中搜索和浏览 65 个 TogoDX/Human 属性。
- **节点解析** — 在实时的 `/breakdown` 和 `/suggest` API 响应中确定过滤值；绝不猜测节点 ID。
- **预设 JSON 生成器** — 生成 TogoDX 条件上传功能接受的精确 JSON 格式。
- **ID 转换** — 通过 [TogoID](https://togoid.dbcls.jp/) API 将外部标识符转换为 TogoDX 兼容的数据集。
- **结果预览** — 使用 `/aggregate` 检查匹配计数，并使用 `/dataframe` 获取表格。
- **可解释的工作流** — 使用 `export_preset` 导出 JSON，以便研究人员在 TogoDX 网页 UI 中验证条件。
## 要求
- Ruby **3.1 或更高**
- 可以访问 `togodx.dbcls.jp` 和 `api.togoid.dbcls.jp` 的网络
## 安装
```bash
git clone https://github.com/ktym/togodx-mcp-ruby.git
cd togodx-mcp-ruby
bundle config set --local path vendor/bundle
bundle install
```
## Cursor 设置
将以下内容添加到您的 Cursor MCP 设置（`.cursor/mcp.json` 或全局设置）中。
将 `/path/to/togodx-mcp-ruby` 替换为您的克隆目录。
```json
{
"mcpServers": {
"togodx": {
"command": "bundle",
"args": ["exec", "ruby", "exe/togodx-mcp"],
"cwd": "/path/to/togodx-mcp-ruby"
}
}
}
```
需要 Ruby 3.1+。如果 `bundle` 不在您的 PATH 中，请使用 Ruby 3.1+ 的 `bundle` 可执行文件的完整路径。
## MCP 工具
每次对话首先调用 **`togodx_usage_guide`**。
| 工具 | 描述 |
|------|-------------|
| `togodx_usage_guide` | 代理工作流指南 |
| `list_categories` | 列出属性类别 |
| `get_attribute` | 获取一个属性的元数据 |
| `search_attributes` | 属性的关键词搜索 |
| `breakdown` | 列出属性层次结构中的节点 |
| `suggest_nodes` | 分类节点的关键词搜索 |
| `resolve_nodes` | 将自然语言术语映射到节点 ID |
| `convert_ids` | 通过 TogoID 转换 ID |
| `locate_ids` | 将用户 ID 映射到分解节点 |
| `preview_aggregate` | 预览匹配条目计数 |
| `build_preset` | 生成可上传的预设 JSON |
| `get_dataframe` | 获取结果表格 |
| `export_preset` | 编写 JSON 文件并返回上传说明 |
## 典型工作流
用户询问：
> *"显示在肺和肠中高表达、定位到血浆膜、具有 ChEMBL 相互作用测定数据、与抗感染药物相关的蛋白质 — 包括结构和药物阶段注释。"*
代理应：
1. 调用 `togodx_usage_guide`。
2. 使用 `search_attributes` 提出表达、定位和相互作用属性的建议；与用户确认。
3. 通过 `resolve_nodes` 或 `suggest_nodes` 解析组织名称（`Lung`、`Intestine`）和 GO 术语（`GO_0005886`）。
4. 在 **过滤器** 中放置缩小条件；在 **注释** 中放置仅显示的属性。
5. 调用 `build_preset` → `preview_aggregate` → `get_dataframe`。
6. 调用 `export_preset` 并指示用户在 [TogoDX/Human](https://togodx.dbcls.jp/human/) 中上传 JSON。
参见 `doc/togodx-preset_example_case1.json` 获取参考预设。
### 过滤器 vs 注释
| 类型 | 角色 | 示例 |
|------|------|---------|
| **过滤器** | 缩小结果集 | 组织表达、血浆膜、测定存在 |
| **注释** | 添加投影列 | 结构存在、药物开发阶段 |
## 环境变量
| 变量 | 默认值 |
|----------|---------|
| `TOGODX_BASE_URL` | `https://togodx.dbcls.jp/human` |
| `TOGODX_CONFIG_URL` | `attributes.json` 的 URL |
| `TOGOID_BASE_URL` | `https://api.togoid.dbcls.jp` |
| `TOGODX_UI_URL` | `https://togodx.dbcls.jp/human` |
## 开发
参见 [doc/Development.md](doc/Development.md) 获取架构、API 映射和贡献说明。
```bash
rake smoke # live API 烟雾测试
rake test # MCP 协议测试
```
## 许可证
MIT
## 相关
- [TogoDX/Human](https://togodx.dbcls.jp/human/)
- [togodx-server](https://github.com/togodx/togodx-server)
- [说明](doc/Instructions.md) — 原始项目要求
