Jhe Notebook

JHE 笔记本：集成大型语言模型的 Jupyter Health Exchange MCP 客户端

这个项目展示了如何使用模型上下文协议（MCP）将Jupyter笔记本连接到JupyterHealth Exchange服务器，从而能够利用NRP托管的Qwen3模型对健康数据进行大型语言模型（LLM）驱动的查询。

概述

JHE笔记本实现连接：

• MCP 客户端 → JupyterHealth Exchange MCP 服务器 （本地，端口8001）
• OpenAI 客户端 → NRP Qwen3 大语言模型（LLM） （由NRP主办）
• 集成大型语言模型（LLM）使用MCP工具查询健康数据并以自然语言作出回应

建筑学

┌─────────────────┐
│ Jupyter Notebook│
│  (This Project) │
└────┬────────┬───┘
     │        │
     │        └──────────────┐
     │                       │
     ▼                       ▼
┌─────────────────┐    ┌──────────────┐
│  MCP Client     │    │ OpenAI Client│
│  (Python SDK)   │    │  (NRP API)   │
└────┬────────────┘    └──────┬───────┘
     │                        │
     │                        │
     ▼                        ▼
┌─────────────────┐    ┌──────────────┐
│ JHE MCP Server  │    │ NRP Qwen3    │
│ localhost:8001  │    │   Model      │
└────┬────────────┘    └──────────────┘
     │
     ▼
┌─────────────────┐
│ JupyterHealth   │
│ Exchange (JHE)  │
│ localhost:8000  │
└─────────────────┘

先决条件

0. 带有MCP支持的JupyterHealth Exchange

重要的您需要启用MCP的JupyterHealth Exchange版本。

克隆JupyterHealth Exchange仓库并检出MCP功能分支：

git clone https://github.com/jupyterhealth/jupyterhealth-exchange.git
cd jupyterhealth-exchange

# TODO: Update this when PR is merged - for now use the feature branch
git fetch origin pull/XXX/head:mcp-support  # Replace XXX with actual PR number
git checkout mcp-support

按照JupyterHealth Exchange的设置说明进行操作：

• 安装依赖项
• 配置数据库
• 种子测试数据

1. Python 3.10或更高版本

重要的MCP Python SDK 需要 Python 3.10 或更高版本。

检查您的Python版本：

python3 --version  # Should be 3.10 or higher

如有需要，请使用特定版本的Python：

# macOS with Homebrew
brew install python@3.11

# Use specific Python version for venv
python3.11 -m venv .venv

2. 运行中的基础设施

Jupyter健康交换服务器 必须正在运行：

cd /path/to/jupyterhealth-exchange
.venv/bin/python manage.py runserver

MCP服务器 必须正在运行：

cd /path/to/jupyterhealth-exchange
./start_mcp_server.sh

验证服务器状态是否正常：

curl http://localhost:8000/admin/  # Should return 200
curl http://localhost:8001/health  # Should return {"status": "healthy"}

3. NRP API 访问

您需要从国家研究平台获取一个API密钥：

1. 访问 https://portal.nrp.ai/
2. 创建账户或登录
3. 生成一个API令牌
4. 记下模型名称（例如。， qwen3)

4. 异步事件循环兼容性

重要的MCP Python SDK 需要 nest-asyncio 在Jupyter笔记本中工作：

• Jupyter 运行一个活跃的 asyncio 事件循环
• MCP SDK 广泛使用了 async/await
• nest-asyncio 通过打补丁来允许嵌套的异步操作

这是通过requirements.txt文件自动安装的，并在笔记本的第一个单元格中应用。

安全提示所有查询都通过MCP服务器进行，该服务器强制执行OAuth身份验证和权限过滤。切勿直接查询数据库——MCP服务器是确保安全的守门人，它保证：

• 使用JWT验证的OAuth认证
• 根据ID令牌声明中的study_ids进行权限过滤
• SQL注入防护
• 仅限只读操作

5. OAuth 认证

MCP服务器使用OAuth与JHE进行身份验证。您应该已经完成了OAuth流程（令牌已缓存于 ~/.jhe_mcp/token_cache.json）。 如果未进行，则笔记本将引导您完成身份验证。

设置

1. 克隆此仓库

git clone https://github.com/the-commons-project/jhe-notebook.git
cd jhe-notebook

2. 创建虚拟环境

重要的使用 Python 3.10+（例如，python3.11）

# Use Python 3.11 (or 3.10+)
python3.11 -m venv .venv

# Activate the environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. 安装依赖项

pip install -r requirements.txt

4. 配置环境变量

cp .env.example .env
# Edit .env and add your NRP API key

示例 .env：

JHE_MCP_URL=http://localhost:8001/sse
NRP_BASE_URL=https://ellm.nrp-nautilus.io/v1
NRP_API_KEY=your_actual_api_key_here
NRP_MODEL=qwen3

5. 启动Jupyter

jupyter notebook

导航至 notebooks/jhe_mcp_llm_demo.ipynb 并打开它。

使用方法

演示笔记本显示：

1. MCP 连接通过SSE连接到本地JHE MCP服务器
2. 工具发现列出可用的MCP工具（get_study_count、list_studies、execute_filtered_query等）
3. 大语言模型（LLM）集成使用Qwen3来解析自然语言查询
4. 函数调用LLM决定调用哪个MCP工具
5. 数据检索执行根据用户权限过滤的SQL查询
6. 自然语言响应大型语言模型（LLM）以人类可理解的方式呈现结果

示例查询

# Simple query
"How many studies are in the system?"

# Complex health data query
"Show me all blood pressure readings for patient 40001 on January 1, 2025,
and calculate the average systolic pressure"

# Time-series aggregation
"Give me hourly averages and standard deviations for patient 40001's
blood pressure data over the first week of January"

可用的MCP工具

JHE MCP服务器提供以下工具：

• 获取学习次数统计已认证用户可访问的研究数量
• 列出研究（或“研究列表”）列出所有研究，包括其ID、名称和组织机构
• 获取患者人口统计学信息获取特定研究的患者人口统计学信息
• 获取研究元数据获取关于一项研究的详细元数据
• 获取患者观察数据获取特定患者的FHIR观测数据
• 获取数据库模式获取包含示例的全面数据库架构
• 执行过滤查询执行任意SQL SELECT查询（根据权限自动过滤）

安全与权限

• 所有MCP工具调用均通过OAuth进行身份验证
• SQL查询会根据用户权限自动过滤
• 用户只能访问他们被授权查看的研究/患者信息
• 仅允许SELECT查询（不允许INSERT/UPDATE/DELETE）
• 危险的SQL操作已被阻止

故障排除

单元格2中的取消错误

asyncio.CancelledError: Cancelled via cancel scope...

解决方案确保单元格1中包含nest_asyncio的设置：

import nest_asyncio
nest_asyncio.apply()

如果你看到这个错误，请检查单元格1是否已运行并且包含了nest_asyncio代码。参见 笔记本更新说明.md 以获取详细说明。

MCP连接失败

Error: Connection refused to localhost:8001

解决方案确保MCP服务器正在运行：

curl http://localhost:8001/health

认证错误

Error: Authentication failed

解决方案通过删除令牌缓存进行重新认证：

rm ~/.jhe_mcp/token_cache.json

然后重新启动笔记本 - 这将触发OAuth流程。

NRP API 错误

Error: 401 Unauthorized

解决方案检查你的 .env 文件已正确（无误） NRP_API_KEY.

未返回数据

"row_count": 0

解决方案：

1. 确认您已以具有学习访问权限的用户身份登录（例如，mary@example.com）
2. 检查数据库中是否存在测试数据
3. 确保患者ID正确（例如，40001）

发展

项目结构

jhe-notebook/
├── README.md              # This file
├── requirements.txt       # Python dependencies
├── .env.example          # Environment variable template
├── .env                  # Your actual config (gitignored)
├── .gitignore            # Git ignore rules
└── notebooks/
    └── jhe_mcp_llm_demo.ipynb  # Main demonstration notebook

添加新笔记本

创建新的 .ipynb 文件在（某个地方/文件夹中） notebooks/ 目录。它们将自动访问相同的依赖项和配置。

做出贡献

这是一个展示MCP（可能是指某种特定技术或系统，如“多组件平台”或根据上下文具体定义）集成模式的演示项目。请随意：

• 添加新的示例笔记本
• 创建辅助工具
• 改进错误处理
• 添加数据可视化

仓库（或存储库）

此项目将发布到The Commons Project的GitHub组织中，地址为： https://github.com/the-commons-project/jhe-notebook

许可证

Apache 2.0（与其他Commons项目仓库相同）

资源

• 模型上下文协议文档
• MCP Python SDK
• NRP 文档
• Jupyter健康信息交换平台