nfyy-ckd-risk-warning-mcp 1.1.0

NFYY038 童肾营养师·风险预警 Agent Mock MCP Server（儿童 CKD 营养管理智能体复赛演示版）

童肾营养师·风险预警 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 广场部署用）

# 以 stdio 方式拉起服务（魔搭/Nexent 自定义 MCP 即如此调用）
uvx nfyy-ckd-risk-warning-mcp

服务配置 JSON（魔搭 MCP 广场「自定义创建-可托管部署」填法）：

{ "mcpServers": { "nfyy038-risk-warning": { "command": "uvx", "args": ["nfyy-ckd-risk-warning-mcp"] } } }

方式二：源码安装（开发 / 评测）

python -m venv .venv && source .venv/bin/activate
pip install -e .
nfyy-ckd-risk-warning-mcp            # 等价于 python -m nfyy_ckd_risk_warning

本地 SDK 调用（不依赖 MCP 传输，便于单测/演示）

from nfyy_ckd_risk_warning import server
# 输入今日生化报告 API 新结果，引擎自动对比上一次历史结果并重新研判
out = server.trigger_warning_event("C_8808", today_creatinine=165, today_potassium=5.8, today_albumin=33)
# out["reassessment"] -> 历史 L3 → 本次 L1 对照；out["payload"] / out["markdown"] -> 报文与 SOP

---

4. 复赛 Demo 演示要点

复赛无真实北向接口时，用「研判指令输入 + 今日生化报告 API 模拟** 触发即可证明预警能力：

请对患儿 C_8808 进行风险研判。今日生化报告 API 回传：血肌酐 165 μmol/L，血钾 5.8 mmol/L，血清白蛋白 33 g/L。 （患儿上一次历史结果：肌酐 95、血钾 5.4、白蛋白 43；历史系统判定 L3。）

Agent 经 fetch（历史记录） → trigger（输入今日新报告，引擎自动对比上一次结果并重新研判） 两步，输出：

1. 重新研判对照：历史系统判定 L3 → 本次基于新数据重新研判 L1（肌酐 95→165 +73.7%≥50% → R-01；血钾 5.8>5.5 → R-02；白蛋白 33<35 且体重 Z 连降 → R-04），明确标注「历史等级被新数据推翻」；
2. 推送 JSON 报文（CKD-ALERT/1.0 契约，含等级、命中规则、复查、循证）；
3. 临床处置 SOP（Markdown：主诊医生 / 护理 / 家长 / 饮食红线 / 复查）；
4. 一句话结论摘要（模型组织，附免责声明）。

说明：模拟数据 = 患儿历史记录；今日新血检结果（生化报告 API 模拟）是重新研判的驱动方——新数据优先、不沿用历史等级。本工具不设「以系统/引擎为准」的强制纠偏，历史系统判定仅作对比展示，最终等级由「今日新数据 + 上一次历史基线」的硬规则计算决定。

---

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. 测试

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

---

7. 免责声明

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