MedEval MCP (local)

面向私有 MedEval 医疗器械监管工作台的仅本地 Model Context Protocol 网关。

它让 MCP 客户端能够操作 MedEval 工作区、规范化材料、证据检索、CEP/CER 生成与评估、工作流可观测性以及不可变文档修订。MedEval 仍是记录系统；本项目是一个轻量、有边界的适配器。

安全边界

• 仅 stdio 传输；无网络 MCP 监听器

• 默认连接回环地址，对受信任的私网 IP 需显式选择启用

• 显式的工作区/任务标识符

• 白名单化的本地上传根目录

• 无删除、shell、部署或密钥管理工具

• 异步启动返回任务 ID，必须轮询，不可重复启动

• 产品事实不能从外部文献推导

• 文档编辑需要当前的 base_revision_id

参见 SECURITY.md。

要求

• Windows 或其他 Python 3.11+ 环境

• MedEval 运行于 http://127.0.0.1:8000

• 来自 pyproject.toml 的 Python 包依赖

安装

cd C:\path\to\medeval-mcp
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[test]"
Copy-Item .env.example .env

MCP 进程读取普通环境变量。MCP 客户端通常在其服务器配置中提供这些变量，而不是自动加载 .env。

配置

最小本地配置：

MEDEVAL_BASE_URL=http://127.0.0.1:8000
MEDEVAL_PROJECT_ROOT=C:\path\to\medeval
MEDEVAL_ALLOWED_FILE_ROOTS=C:\path\to\medeval;C:\path\to\materials

如果 MedEval 启用了 MEDEVAL_API_TOKEN，请为本 MCP 进程提供相同的 MEDEVAL_API_TOKEN；它将作为 X-API-Token 发送。也可以改用 MEDEVAL_BEARER_TOKEN 提供已签名的浏览器/会话令牌。

macOS 客户端连接受信任的 LAN 后端

当 MedEval 监听同一受信任 LAN 中的另一台计算机时，请使用其字面私网 IP 并显式选择启用：

MEDEVAL_BASE_URL=http://192.168.0.166:8001
MEDEVAL_ALLOW_PRIVATE_NETWORK=true
MEDEVAL_PROJECT_ROOT=/Users/your-name/MedEval
MEDEVAL_ALLOWED_FILE_ROOTS=/Users/your-name/MedEval:/Users/your-name/Documents

MCP 在 Mac 上仍是本地 stdio 进程。公共 IP 地址和域名仍会被拒绝。

从 Codex 连接

使用 examples/codex.mcp.json 作为 MCP 服务器定义。命令必须指向本项目的 .venv Python 并使用：

-m medeval_mcp.server

更改 MCP 配置后重启 Codex，然后请它调用 medeval_health。

手动运行

MCP stdio 使用标准输出传输协议消息，因此手动运行看起来像是空闲的：

.\.venv\Scripts\python.exe -m medeval_mcp.server

使用 MCP 客户端或 Inspector 与之交互。

捆绑的本地启动器会在启动 stdio 之前设置回环后端和上传根目录：

.\scripts\run_local.ps1

协议和后端冒烟测试：

.\.venv\Scripts\python.exe scripts\mcp_smoke.py --health

工具面

首个版本提供 21 个工具：

• workspace：健康检查、项目列表、创建/获取工作区、工作区文档

• observability：运行列表、运行详情、有界代理上下文

• evidence：项目文档、证据搜索、章节上下文

• ingestion：白名单化的本地材料上传与规范化

• generation：模板列表、启动生成、生成/任务状态

• evaluation：启动评估

• revisions：列表、有界读取、差异、乐观锁补丁

medeval_start_generation 默认使用 tag_index_agent，它采用 MedEval 的依赖串行分段写入器。全上下文策略仍为可选启用。

测试

.\.venv\Scripts\python.exe -m pytest

测试使用模拟 HTTP 传输，不会启动 LLM 生成或消耗模型配额。单独的集成冒烟测试会列出 MCP 工具并调用已在运行的本地 /api/health 端点。

尚未包含

• 远程 Streamable HTTP 传输

• xiaoyuu.me 部署

• 多用户 API 密钥和工作区所有权

• 远程上传暂存

• 破坏性的项目/任务删除