内容
# Open Targets 平台 MCP
[](https://github.com/opentargets/open-targets-platform-mcp/commits)
[](https://github.com/opentargets/open-targets-platform-mcp/blob/main/LICENSE)
> **⚠️ 免责声明：该项目目前为实验性项目，正在积极开发中。功能、API 和文档可能会在未通知的情况下发生变化 ⚠️**
**Open Targets 平台的模型上下文协议（MCP）服务器**
本软件包是官方的 Open Targets 平台 MCP 服务器实现，旨在使 AI 助手能够与 Open Targets 平台 GraphQL API 进行交互，后者是靶点-疾病关联和药物发现数据的综合资源。
## 快速导航
- [功能](#功能)
- [官方 MCP 服务器](#官方MCP服务器)
- [本地部署](#本地部署)
- [高级部署](#高级部署)
- [可用命令](#可用命令)
- [服务器设置](#服务器设置)
- [可用工具](#可用工具)
- [策略](#策略)
- [Claude 桌面设置](#Claude桌面设置)
- [项目结构](#项目结构)
- [测试](#测试)
- [贡献](#贡献)
- [许可证](#许可证)
## 功能
- 🔍 **基于类别的模式访问**：使用基于类别的子模式获取和探索 Open Targets 平台 GraphQL 模式的聚焦子集
- 🚀 **预获取模式优化**：GraphQL 模式在服务器启动时预获取并缓存，以确保工具立即可用
- 📊 **查询执行**：针对 Open Targets 平台 API 执行自定义 GraphQL 查询
- ⚡ **批量查询处理**：使用不同参数高效执行相同查询多次
- 🔎 **实体搜索**：跨多个类型（靶点、疾病、药物、变体、研究）搜索实体
- 🛠️ **CLI 工具**：用于启动服务器的易用命令行界面
- 🎯 **jq 过滤（可选）**：使用 [jq](https://jqlang.org/) 进行服务器端 JSON 处理，以减少令牌消耗并提高性能。有关详细信息，请参见 [jq 过滤（可选）](#jq过滤可选)。
## 官方 MCP 服务器
使用 Open Targets 基础设施在 `https://mcp.platform.opentargets.org/mcp` 提供的托管服务，是使用 Open Targets 平台 MCP 的最简单方式。
## 本地部署
### 通过 uvx（快速入门）
使用 `uvx` 是快速入门的最快方式，它将直接从 GitHub 下载并运行软件包。
**示例：**
```bash
# 启动绑定到 localhost:8000 的 HTTP 服务器（默认）
uvx --from git+https://github.com/opentargets/open-targets-platform-mcp otp-mcp
# 获取帮助
uvx --from git+https://github.com/opentargets/open-targets-platform-mcp otp-mcp --help
# 启用 jq 过滤
uvx --from git+https://github.com/opentargets/open-targets-platform-mcp otp-mcp --jq
```
### Docker 部署
可以使用官方 Docker 镜像运行 MCP 服务器：
```bash
# 拉取最新镜像
docker pull ghcr.io/opentargets/open-targets-platform-mcp
# 作为守护进程运行，启用 HTTP 传输
docker run -d \
-p 8000:8000 \
-e OTP_MCP_HTTP_HOST=0.0.0.0 \
ghcr.io/opentargets/open-targets-platform-mcp
# 作为守护进程运行，启用 jq 过滤
docker run -d \
-p 8000:8000 \
-e OTP_MCP_HTTP_HOST=0.0.0.0 \
-e OTP_MCP_JQ_ENABLED=true \
ghcr.io/opentargets/open-targets-platform-mcp
```
### 服务器设置
有关可用的 CLI 参数和环境变量，请参见 [服务器设置](#服务器设置) 表。
## 高级部署
两种高级部署选项都需要克隆存储库并首先设置虚拟环境：
```bash
# 克隆存储库
git clone https://github.com/opentargets/open-targets-platform-mcp.git
cd open-targets-platform-mcp
# 安装依赖项
uv sync --python 3.10
```
### FastMCP CLI
对于高级用法并利用所有 FastMCP 选项，可以直接使用 FastMCP CLI 与服务器模块：
```bash
# 使用 FastMCP CLI 运行
uv run fastmcp run ./src/open_targets_platform_mcp/server.py
```
> **注意**：有关所有 FastMCP CLI 选项，请参见 [FastMCP 文档](https://gofastmcp.com/patterns/cli#fastmcp-run)。
> **注意**：使用环境变量（请参见 [服务器设置](#服务器设置) 表）来配置使用 FastMCP CLI 时的服务器。
### 开发安装（可编辑）
对于开发或修改代码库：
```bash
# 运行服务器
uv run otp-mcp
# 获取帮助
uv run otp-mcp --help
```
## 可用命令
软件包提供两个命令变体：
- `otp-mcp`：较短的别名（推荐）
- `open-targets-platform-mcp`：完整的命令名称
两个命令在功能上是相同的。
## 服务器设置
使用环境变量（前缀均为 `OTP_MCP_`）配置服务器。下表显示了所有可用的配置选项：
| 环境变量 | CLI 选项 | 描述 | 默认值 |
| --- | --- | --- | --- |
| `OTP_MCP_API_ENDPOINT` | `--api` | Open Targets 平台 API 端点 URL | `https://api.platform.opentargets.org/api/v4/graphql` |
| `OTP_MCP_SERVER_NAME` | `--name` | MCP 中显示的服务器名称 | `"Open Targets 平台的模型上下文协议服务器"` |
| `OTP_MCP_TRANSPORT` | `--transport` | 传输类型：`stdio` 或 `http` | `http` |
| `OTP_MCP_HTTP_HOST` | `--host` | HTTP 服务器主机（仅在 `http` 传输中使用） | `localhost` |
| `OTP_MCP_HTTP_PORT` | `--port` | HTTP 服务器端口（仅在 `http` 传输中使用） | `8000` |
| `OTP_MCP_STATELESS_HTTP` | `--stateless-http` | 启用无状态 HTTP 模式（仅在 `http` 传输中使用） | `true` |
| `OTP_MCP_API_CALL_TIMEOUT` | `--timeout` | API 调用请求的超时时间（秒） | `30` |
| `OTP_MCP_JQ_ENABLED` | `--jq` | 启用 jq 过滤支持 | `false` |
| `OTP_MCP_RATE_LIMITING_ENABLED` | `--rate-limiting` | 启用速率限制 | `false` |
| `OTP_MCP_RATE_LIMITING_MAX_REQUESTS_PER_SECOND` | _（仅限环境变量）_ | 启用速率限制时的每秒最大请求数 | `3` |
| `OTP_MCP_RATE_LIMITING_BURST_CAPACITY` | _（仅限环境变量）_ | 启用速率限制时的最大突发容量 | `100` |
| `OTP_MCP_DETAILED_TIMING_ENABLED` | `--detailed-timing` | 启用请求详细时间信息的日志记录 | `false` |
**示例：**
**使用环境变量：**
```bash
export OTP_MCP_TRANSPORT=stdio
export OTP_MCP_JQ_ENABLED=true
otp-mcp
```
**使用 CLI 选项：**
```bash
otp-mcp --transport stdio --jq
```
**注意：** 当同时提供 CLI 选项和环境变量时，CLI 选项优先于环境变量。
## 可用工具
MCP 服务器提供以下工具：
1. **`get_open_targets_graphql_schema`**：从 Open Targets 平台 API 获取基于类别的子模式，包括相关类型和字段的详细文档
2. **`get_type_dependencies`**：通过获取指定类型及其递归可达依赖项的确切 GraphQL SDL（模式定义语言）子集来探索模式类型关系
3. **`query_open_targets_graphql`**：执行 GraphQL 查询以检索有关靶点、疾病、药物及其关联的数据
4. **`batch_query_open_targets_graphql`**：执行相同的 GraphQL 查询，并带有不同的变量集，以便进行高效的批量处理
5. **`search_entities`**：搜索跨多个类型（靶点、疾病、药物、变体、研究）的实体并检索其标准化 ID
## 策略
MCP 服务器实施一个 3 步工作流程，以引导 LLM 从 Open Targets 平台高效检索数据：
### 步骤 1：从模式中学习查询结构
LLM 调用 `get_open_targets_graphql_schema`，带有特定类别（例如“靶点”，“药物机制”），以检索聚焦的子模式。该模式提供了相关类型和字段的详细文档，使 LLM 能够在不被整个模式淹没的情况下构造有效查询。模式还包括如何正确声明 GraphQL 变量以避免变量解析错误的特定指导。
如果需要更深入或更具体的模式探索，LLM 可以使用 `get_type_dependencies` 工具来获取一个或多个特定类型及其递归可达依赖项的确切依赖树和 SDL 子集。
**关键实体类型包括：**
- **靶点/基因**：使用 ENSEMBL ID（例如 `ENSG00000139618` 表示 BRCA2）
- **疾病**：使用 EFO/MONDO ID（例如 `MONDO_0007254` 表示乳腺癌）
- **药物**：使用 ChEMBL ID（例如 `CHEMBL1201583` 表示阿司匹林）
- **变体**：使用“chr_pos_ref_alt”格式或 rsID
### 步骤 2：解析标识符（如果需要）
当用户查询包含通用名称（基因符号、疾病名称、药物名称）时，LLM 使用 `search_entities` 将它们转换为 API 所需的标准 ID。
### 步骤 3：执行查询
LLM 使用以下方法构造并执行 GraphQL 查询：
- 步骤 2 中的标准化 ID
- 查询结构来自模式
- **jq 过滤器（可选）**，如果启用，则提取仅所需字段，尽量减少令牌消耗
**工具选择：**
- `query_open_targets_graphql` 用于单个查询
- `batch_query_open_targets_graphql` 用于带有不同参数的多个相同查询（减少延迟和令牌）
### jq 过滤（可选）
MCP 服务器支持使用 jq 表达式进行可选的服务器端 JSON 处理。此功能**默认禁用**，但如果您想减少令牌消耗，可以启用它。
#### 何时启用 jq 过滤：
- 您想通过从 API 响应中提取特定字段来减少令牌消耗
- 处理大型 API 响应时，只需要数据的一个子集
- 调用 LLM 熟练使用工具调用，可以可靠地构造 jq 过滤器
#### 何时禁用 jq 过滤：
- 优先考虑简单性而不是优化
- 处理不需要过滤的直接查询
- LLM 应接收完整的 API 响应
#### jq 过滤器的工作原理
启用 jq 过滤时，查询工具会公开一个 `jq_filter` 参数。jq 过滤器在返回响应之前在服务器端应用，提取相关数据并丢弃不必要的字段。
**示例：** 要从靶点查询中提取仅基因符号和 ID：
```jq
jq_filter: ".data.target | {id, symbol: .approvedSymbol}"
```
这通过仅返回请求的字段而不是完整的 API 响应，显著减少了令牌消耗。
## Claude 桌面设置
有关使用 Open Targets 平台 MCP 服务器配置 Claude 桌面（包括远程托管服务和本地安装配置）的详细说明，请参见 [CLAUDE_DESKTOP.md](CLAUDE_DESKTOP.md)。
## 测试
测试套件围绕两个指导原则构建：
**1. 在最高有意义的级别进行测试。**
测试通过 [fastmcp](https://gofastmcp.com/) 进程内客户端（`Client.call_tool()`）来运行服务器，这是 LLM 在运行时使用的相同接口。这使得每个测试都是一个近乎系统的测试：工具注册、参数验证、描述生成和响应序列化都被涵盖为一个单一的端到端路径，而不是单独测试内部函数。
**2. 使用 GraphQL 回放代替实时网络调用。**
实际的 API 响应通过运行生成器脚本针对实时 API 记录到 cassette 文件（`test/fixtures/generated/graphql_cassette.json`）中。在正常测试运行期间，cassette 被确定性地重放，因此测试快速、可重复，并且不依赖于网络可用性。cassette 有意在需要新查询时重新生成：
```bash
uv run python test/fixtures/generated/generate_fixtures.py
```
要针对实时 API 而不是 cassette 运行测试：
```bash
uv run python -m pytest --live
```
## 贡献
欢迎贡献！请在 [GitHub 仓库](https://github.com/opentargets/open-targets-platform-mcp) 上打开问题或提交拉取请求。
## 许可证
该项目根据 [LICENSE](LICENSE) 中指定的许可证条款获得许可。
