Metadata-Version: 2.4
Name: nfyy-ckd-risk-warning-mcp
Version: 1.0.0
Summary: NFYY038 童肾营养师·风险预警 Agent Mock MCP Server（儿童 CKD 营养管理智能体复赛演示版）
Author: 南方医科大学南方医院 NFYY038 团队
License: MIT
Project-URL: Homepage, https://github.com/rpint/nfyy-ckd-risk-warning-mcp
Project-URL: Repository, https://github.com/rpint/nfyy-ckd-risk-warning-mcp
Project-URL: Documentation, https://github.com/rpint/nfyy-ckd-risk-warning-mcp#readme
Keywords: ckd,pediatric-nephrology,risk-warning,mcp,agent,nfyy038
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: pydantic>=2.0.0
Dynamic: license-file

# 童肾营养师·风险预警 Agent —— Mock MCP Server

> **团队编号**：NFYY038　|　**项目**：南方医科大学南方医院「童肾营养师」多智能体辅助决策系统
> **子智能体**：风险预警 Agent（复赛演示版）

本仓库是「童肾营养师」多智能体系统中**风险预警 Agent** 的自定义 MCP（Model Context Protocol）服务实现。它解决复赛阶段**无法接入真实 HIS / LIS、无法通过小程序真实推送**的约束，用**模拟数据 + 确定性硬规则引擎 + 北向报文/MQ 模拟**，完整复现「风险研判 → 等级判定 → 结构化报文推送 → 临床处置 SOP」的预警能力。

---

## 1. 它能做什么

| 能力 | 说明 |
|---|---|
| 南向 Mock·LIS 趋势 | `fetch_patient_biochemical_trends` 模拟调用院内 LIS，返回近 3 个月生化趋势、本次结果、变化百分比、身高/体重 Z 评分序列 |
| 硬规则引擎 | `evaluate_risk_rules` 把**全部阈值与涨幅计算下沉为确定性 Python 代码**，杜绝 8B 小模型算术幻觉 |
| 北向报文 + MQ 模拟 | `trigger_warning_event` 生成 `CKD-ALERT/1.0` 结构化报文，模拟抛出至消息队列并透传医生工作站 / 家长端微信小程序，返回投递回执 |
| 临床处置 SOP | `get_clinical_sop` 查询每条规则的主诊医生 / 护理 / 家长三视图处置建议与循证依据 |

**内置 5 个 MCP 工具**、**15 例虚构患儿**（覆盖 normal / abnormal / boundary / exception 四类场景）、**13 条硬规则**。

---

## 2. 架构与数据流

```
医生「研判指令输入」
        │
        ▼
┌──────────────────────────────────────────────────────────┐
│ 风险预警 Agent（8B 模型，仅组织自然语言）                  │
│   1. list_mock_patients            → 选定患儿              │
│   2. fetch_patient_biochemical_trends (南向 Mock①/LIS)    │
│   3. evaluate_risk_rules          → 硬规则引擎判定等级    │
│   4. trigger_warning_event        (北向 Mock②/推送+MQ)    │
│   5. get_clinical_sop             → 处置 SOP              │
└──────────────────────────────────────────────────────────┘
        │ 结构化 JSON 报文 (CKD-ALERT/1.0)
        ▼
┌──────────────────────────────────────────────────────────┐
│ 北向接口 / 消息队列（模拟 ⇒ 上线替换为 Kafka / 企微网关） │
│   topic: ckd.alert.pediatric                              │
└──────────────────────────────────────────────────────────┘
        │ 透传
        ▼
   医生工作站待办卡片  /  家长端微信小程序订阅消息
```

**硬规则（防幻觉红线）示例**：肌酐较基线涨幅 ≥50% → L1 一级 AKI；血钾 >5.5 mmol/L → L1 高钾危急；白蛋白 <35 g/L 且体重 Z 连续下降 → L2 PEW。完整 13 条见 `src/nfyy_ckd_risk_warning/rules.py` 与 `knowledge/`。

---

## 3. 安装与运行

### 方式一：PyPI / uvx（魔搭 MCP 广场部署用）
```bash
# 以 stdio 方式拉起服务（魔搭/Nexent 自定义 MCP 即如此调用）
uvx nfyy-ckd-risk-warning-mcp
```
> 服务配置 JSON（魔搭 MCP 广场「自定义创建-可托管部署」填法）：
> ```json
> { "mcpServers": { "nfyy038-risk-warning": { "command": "uvx", "args": ["nfyy-ckd-risk-warning-mcp"] } } }
> ```

### 方式二：源码安装（开发 / 评测）
```bash
python -m venv .venv && source .venv/bin/activate
pip install -e .
nfyy-ckd-risk-warning-mcp            # 等价于 python -m nfyy_ckd_risk_warning
```

### 本地 SDK 调用（不依赖 MCP 传输，便于单测/演示）
```python
from nfyy_ckd_risk_warning import server
out = server.trigger_warning_event("C_8801")   # 返回 receipt + payload + markdown
```

---

## 4. 复赛 Demo 演示要点

复赛无真实北向接口时，用「**研判指令输入**」触发即可证明预警能力：

> 请对患儿 C_8801 进行例行风险研判。今日 LIS 检出数据：血肌酐 165 μmol/L（3 个月前 110 μmol/L），血钾 5.8 mmol/L，血清白蛋白 33 g/L。

Agent 经 `fetch → evaluate → trigger` 三步，输出：
1. **推送 JSON 报文**（`CKD-ALERT/1.0` 契约，含等级、命中规则、复查、循证）；
2. **临床处置 SOP**（Markdown 八段式：主诊医生 / 护理 / 家长 / 饮食红线 / 复查）；
3. **一句话结论摘要**（模型组织，附免责声明）。

当 Agent 自报等级与引擎不一致时，`trigger_warning_event` 返回 `level_correction` 强制以引擎为准——这是小模型防误判的关键设计。

---

## 5. 目录结构

```
nfyy038-ckd-risk-warning-mcp/
├── src/nfyy_ckd_risk_warning/
│   ├── data/patients.json        # 15 例模拟患儿数据集（虚构）
│   ├── rules.py                  # 硬规则引擎（13 条）
│   ├── sop.py                    # 临床处置 SOP 文案库 + 循证
│   ├── store.py                  # 模拟 LIS/HIS 南向数据访问层
│   ├── payload.py                # 北向报文 + 消息队列模拟 + Markdown 渲染
│   ├── server.py                 # FastMCP Server（5 个工具）
│   ├── __main__.py / __init__.py
├── scripts/                      # 数据生成 / 测评集生成 / stdio 冒烟
├── prompts/                     # 系统提示词（四模块模板）
├── knowledge/                    # 知识库 SOP 简化版（iData RAG 挂载参考）
├── datasets/                     # 模拟数据集 + 测评数据集 + 数据/测评说明
├── docs/                         # 部署/接入/Demo/材料清单
├── tests/test_engine.py          # 确定性测试套件（15 例全通过）
└── pyproject.toml                # PyPI 发布配置（包名 nfyy-ckd-risk-warning-mcp）
```

---

## 6. 测试

```bash
pip install -e .
python tests/test_engine.py       # 4 项全部通过：15 例预期等级+规则、报文/MQ 契约
python scripts/_smoke_stdio.py    # MCP stdio 握手：暴露 5 个工具
```

---

## 7. 免责声明

本项目及全部数据均为**虚构合成数据**，仅用于「南方医科大学南方医院智能体创新大赛」复赛演示，**不可用于任何真实临床决策**。所有处方级用药调整须由主诊医生决定。
