pkdb-mcp 0.1.0

Model Context Protocol server for the PK-DB REST API.

pkdb-mcp

面向 PK-DB REST API 的 MCP 服务器 —— 服务于药理学计量学与药物动力学数据平台。

pkdb-mcp 通过模型上下文协议将 AI 智能体与 PK-DB 相连。启动时，它会拉取 PK-DB 的实时 OpenAPI 文档，并为每个 API 操作动态注册一个 MCP 工具——无需手动编写接口绑定。

---

中文 | English

功能特性

• 动态工具生成 —— 读取 PK-DB 的实时 Swagger/OpenAPI 文档，将所有操作注册为带类型签名的 MCP 工具。
• 后备规范 —— 若实时文档不可用，服务器会回退至包含核心公开接口的内置规范文件。
• 辅助工具 —— 始终可用，用于操作发现和临时请求。
• Swagger 2.0 与 OpenAPI 3.x —— 透明解析两种格式。
• 二进制响应 —— 自动对 ZIP、PDF、XLSX 等二进制载荷进行 Base64 编码。
• 多传输通道 —— 支持 stdio、SSE 和 streamable-http 三种 MCP 传输方式。

什么是 PK-DB？

PK-DB 是一个药理学计量学数据管理网络平台。药理学计量学通过数学模型描述药物在人体内的吸收、分布、代谢和排泄过程。PK-DB 存储药代动力学/药效学（PK/PD）研究数据、非房室分析（NCA）结果、群体 PK 模型及相关元数据。该平台提供 REST API，用于查询研究、化合物、受试者、观测数据以及进行统计分析。

工作原理

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

安装

git clone https://github.com/lyjjl/pkdb-mcp.git
cd pkdb-mcp
uv sync --extra dev

使用方法

作为 MCP 服务器运行

uv run pkdb-mcp

配置 Claude Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "pkdb": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/pkdb-mcp", "run", "pkdb-mcp"],
      "env": {
        "PKDB_API_BASE_URL": "https://pk-db.com/api/v1",
        "PKDB_OPENAPI_URL": "https://pk-db.com/api/v1/swagger.json"
      }
    }
  }
}

配置 OpenCode

在 opencode.jsonc 中添加：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pkdb": {
      "type": "local",
      "command": [
        "uv",
        "--directory",
        "/absolute/path/to/pkdb-mcp",
        "run",
        "pkdb-mcp",
      ],
      "enabled": true,
      "environment": {
        "PKDB_API_BASE_URL": "https://pk-db.com/api/v1",
        "PKDB_OPENAPI_URL": "https://pk-db.com/api/v1/swagger.json",
      },
    },
  },
}

配置 Codex

在 ~/.codex/config.toml 中添加：

[mcp_servers.pkdb]
command = "uv"
args = ["--directory", "/absolute/path/to/pkdb-mcp", "run", "pkdb-mcp"]

[mcp_servers.pkdb.env]
PKDB_API_BASE_URL = "https://pk-db.com/api/v1"
PKDB_OPENAPI_URL = "https://pk-db.com/api/v1/swagger.json"

[!TIP] 在 env 块中设置 PKDB_API_TOKEN 以访问需要身份认证的写入/审核接口。请勿将具备写入权限的令牌存放在共享配置文件中。

配置

所有配置项均为环境变量，以 PKDB_ 为前缀：

变量	默认值	描述
PKDB_API_BASE_URL	https://pk-db.com/api/v1	REST API 基础 URL
PKDB_OPENAPI_URL	https://pk-db.com/api/v1/swagger.json	OpenAPI 文档 URL
PKDB_API_TOKEN	(未设置)	可选，用于认证端点的令牌
PKDB_USE_FALLBACK_SPEC	true	实时文档不可用时是否回退至内置规范
PKDB_MCP_TRANSPORT	stdio	MCP 传输方式（stdio、sse 或 streamable-http）
PKDB_MCP_SERVER_NAME	pkdb-mcp	向客户端宣告的 MCP 服务器名称
PKDB_HTTP_TIMEOUT_SECONDS	30	HTTP 请求超时时间（秒）
PKDB_PROXY	(未设置)	可选的 HTTP/SOCKS 代理 URL（如 http://proxy:8080）；SOCKS 需 socks 额外依赖

项目附带 .env.example 作为示例环境配置文件。

工具

生成的接口工具

每个 OpenAPI 操作均以 pkdb_ 为前缀注册为一个工具。例如，statistics_list 操作会生成为：

pkdb_statistics_list

工具名称会被规范化为合法的蛇形命名 Python 标识符。参数为仅关键字参数，类型派生自 OpenAPI 文档。可选参数默认值为 None，必选参数无默认值。当上游文档未提供操作 ID 时，服务器会根据 HTTP 方法和路径自动派生。

辅助工具

无论加载何种规范，以下工具始终可用：

工具	用途
pkdb_list_operations	列出所有已加载的操作及其元数据。支持 tag 和 search 过滤器。
pkdb_describe_operation	展示指定操作的参数、请求体及完整描述。
pkdb_raw_request	对 PK-DB API 执行任意 HTTP 请求。适用于已添加但尚未纳入当前文档的新接口。

响应格式

所有工具均返回一个 JSON 对象，包含以下字段：

• status_code —— HTTP 状态码
• ok —— 请求是否成功（2xx）
• content_type —— 响应内容类型
• data / text / data_base64 —— 相应格式的响应载荷

二进制响应（ZIP、PDF、XLSX 等）以 Base64 编码返回，并附有 encoding 字段和 size_bytes 字段。

架构

src/pkdb_mcp/
├── __init__.py     # 包元数据
├── __main__.py     # 命令行入口
├── server.py       # FastMCP 服务器工厂
├── openapi.py      # OpenAPI 加载、解析与规范化
├── client.py       # PK-DB 操作的 HTTP 客户端
├── registry.py     # MCP 工具注册
├── settings.py     # 基于环境变量的配置
├── errors.py       # 领域特定异常
├── types.py        # JSON 类型别名
└── specs/          # 内置后备规范

项目有意保持精简：OpenAPI 解析、HTTP 执行、MCP 注册和配置之间职责分明，除 MCP Python SDK、httpx 和 pydantic 外不依赖任何重型框架。

开发

# 格式化
uv run ruff format .

# 代码检查
uv run ruff check .

# 类型检查
uv run ty check

# 运行测试
uv run pytest

流水线

项目使用 GitHub Actions —— 详见 .github/workflows/ci.yml。每次推送和拉取请求时，CI 流水线会依次运行 ruff 格式检查、ruff 代码检查、pytest 测试和 ty 类型检查。