nfyy-ckd-risk-warning-mcp
MCP 服务配置
复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用
{
"mcpServers": {
"kidney_hero_care": {
"args": [
"nfyy-ckd-risk-warning-mcp"
],
"command": "uvx"
}
}
}可用工具 （5 个）
该服务在 MCP 协议中暴露的工具，AI 可按需调用
list_mock_patients 1 个参数
列出模拟 HIS 中全部可用患儿档案，用于 Demo 演示时选择研判对象。
该工具无需必填参数，直接调用即可
fetch_patient_biochemical_trends 2 个参数 需填 1 项
【南向 Mock 工具①】模拟调用院内 LIS 系统，获取患儿生化指标趋势数据包。 返回本次检验结果、约 N 个月前的历史基线、逐项变化百分比，以及身高/体重 Z 评分序列。 字段结构与院内 LIS 南向 MCP 接口一致，上线后仅需替换数据源。
必填参数：patient_id
evaluate_risk_rules 10 个参数
【硬规则引擎】按预警 SOP 硬阈值做确定性研判，返回预警等级与命中规则。 这是防止小模型算术幻觉的关键工具：涨幅计算、阈值比较、等级归并全部由代码完成。 三种用法： 1) 仅传 patient_id：评估该患儿「最新历史记录 vs 约 3 个月前基线」的当前系统状态。 2) 传 patient_id + 今日新报告（creatinine / potassium / phosphorus / albumin）： 进入「重新研判」模式——以今日生化报告 API 回传结果作为本次指标，自动拉取患儿 上一次（最新一条）历史结果作为对比基线，重新计算等级。历史系统判定仅作对比， 最终等级一律以「今日新数据 + 上次基线」的硬规则计算为准。 3) 完全手工录入（不传 patient_id）：直接用传入数值研判，未传项按缺失处理。
该工具无需必填参数，直接调用即可
trigger_warning_event 11 个参数 需填 1 项
【北向 Mock 工具②】模拟「今日生化报告 API」回传 -> 对比患儿上一次历史结果 -> 重新研判风险等级 -> 抛出结构化报文至北向接口与消息队列。 复赛「预警能力」证明核心闭环： 1) 今日生化报告 API 返回新结果（today_* 由医生/检验系统录入，等价于 API 推送）； 2) 自动拉取该患儿上一次（最新一条）历史检验结果作为对比基线； 3) 硬规则引擎基于「今日 vs 上次」重新研判等级——新数据优先，覆盖历史系统判定； 4) 组装 CKD-ALERT/1.0 报文并投递，回执含 event_id / MQ topic / 各通道送达状态； 5) 输出同时呈现「历史系统判定 Lx」与「本次重新研判 Ly」，明确等级是否被新数据推翻。 历史系统判定（system_assigned_level）仅作对比展示，最终等级以「今日新数据 + 上次基线」 的硬规则计算为准；本工具不沿用历史等级、不做「以系统/引擎为准」的强制纠偏。
必填参数：patient_id
get_clinical_sop 1 个参数
查询预警规则对应的完整临床处置 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
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 三步，输出：
- 推送 JSON 报文（
CKD-ALERT/1.0契约，含等级、命中规则、复查、循证）； - 临床处置 SOP（Markdown 八段式：主诊医生 / 护理 / 家长 / 饮食红线 / 复查）；
- 一句话结论摘要（模型组织，附免责声明）。
当 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. 测试
pip install -e .
python tests/test_engine.py # 4 项全部通过：15 例预期等级+规则、报文/MQ 契约
python scripts/_smoke_stdio.py # MCP stdio 握手：暴露 5 个工具
7. 免责声明
本项目及全部数据均为虚构合成数据，仅用于「南方医科大学南方医院智能体创新大赛」复赛演示，不可用于任何真实临床决策。所有处方级用药调整须由主诊医生决定。
