pkdb-mcp

# pkdb-mcp 面向 [PK-DB](https://pk-db.com) REST API 的 MCP 服务器 —— 服务于药理学计量学与药物动力学数据平台。 [](https://python.org) [](LICENSE) [](https://docs.astral.sh/ruff) [](https://pypi.org/project/pkdb-mcp/) `pkdb-mcp` 通过[模型上下文协议](https://modelcontextprotocol.io)将 AI 智能体与 PK-DB 相连。启动时，它会拉取 PK-DB 的实时 OpenAPI 文档，并为每个 API 操作动态注册一个 MCP 工具——无需手动编写接口绑定。 --- <!-- README-I18N:START --> **中文** | [English](./README.en.md) <!-- README-I18N:END --> ## 功能特性 - **动态工具生成** —— 读取 PK-DB 的实时 Swagger/OpenAPI 文档，将所有操作注册为带类型签名的 MCP 工具。 - **后备规范** —— 若实时文档不可用，服务器会回退至包含核心公开接口的内置规范文件。 - **辅助工具** —— 始终可用，用于操作发现和临时请求。 - **Swagger 2.0 与 OpenAPI 3.x** —— 透明解析两种格式。 - **二进制响应** —— 自动对 ZIP、PDF、XLSX 等二进制载荷进行 Base64 编码。 - **多传输通道** —— 支持 `stdio`、`SSE` 和 `streamable-http` 三种 MCP 传输方式。 ## 什么是 PK-DB？ [PK-DB](https://pk-db.com) 是一个药理学计量学数据管理网络平台。药理学计量学通过数学模型描述药物在人体内的吸收、分布、代谢和排泄过程。PK-DB 存储药代动力学/药效学（PK/PD）研究数据、非房室分析（NCA）结果、群体 PK 模型及相关元数据。该平台提供 [REST API](https://pk-db.com/api/v1/swagger.json)，用于查询研究、化合物、受试者、观测数据以及进行统计分析。 ## 工作原理 ```mermaid flowchart LR A[AI 智能体 / MCP 客户端] -->|MCP 协议| B[pkdb-mcp 服务器] B -->|启动时| C[PK-DB OpenAPI 文档] B -->|运行时| D[PK-DB REST API] C -->|动态注册| B ``` 运行时，服务器执行以下流程： 1. 从配置的 URL 获取 OpenAPI 文档 2. 将每个 `路径 + 方法` 的操作解析为标准化的操作目录 3. 为每个操作注册一个 MCP 工具，并附带适当的类型化参数 4. 将传入的工具调用转发至 PK-DB REST API 5. 返回 JSON、纯文本或 Base64 编码的二进制响应 > [!NOTE] > 如果实时文档获取失败，且 `PKDB_USE_FALLBACK_SPEC` 设置为 `true`（默认值），服务器将回退至包含核心公开接口的内置规范文件。如需严格依赖实时文档，请将其设为 `false`。 ## 环境要求 - Python 3.13+ - [uv](https://docs.astral.sh/uv/) ## 安装 ```bash # 推荐：直接从 PyPI 运行（无需本地安装） uvx pkdb-mcp ``` 或者从源码安装： ```bash git clone https://github.com/lyjjl/pkdb-mcp.git cd pkdb-mcp uv sync --extra dev ``` …