Skip to main content
Glama
nfyy-ckd-risk-warning-mcp

nfyy-ckd-risk-warning-mcp

by rpint

童肾营养师·风险预警 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 条硬规则。


Related MCP server: ckd-meal-plan-mcp

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. 免责声明

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

Available Tools

5 tools
evaluate_risk_rulesA

【硬规则引擎】按预警 SOP 硬阈值做确定性研判,返回预警等级与命中规则。

这是防止小模型算术幻觉的关键工具:涨幅计算、阈值比较、等级归并全部由代码完成。 Agent 必须以本工具返回的 level 与 triggered_rule_ids 为唯一判定依据。

两种用法:

  1. 传 patient_id:自动从模拟 LIS 拉取全部数据后研判(推荐)。

  2. 直接传指标数值:用于医生口述/临时录入的场景,未传的项按缺失处理。

Inputs: albumin, potassium, age_months, creatinine, +6 more. Returns: result

get_clinical_sopA

查询预警规则对应的完整临床处置 SOP(医生 / 护理 / 家长三视图)与循证依据。

Inputs: rule_id. Returns: result

list_mock_patientsA

列出模拟 HIS 中全部可用患儿档案,用于 Demo 演示时选择研判对象。

Inputs: scenario_type. Returns: result

trigger_warning_eventA

【北向 Mock 工具②】生成结构化预警报文,抛出至北向接口与消息队列,返回投递回执。

完整流程:拉取模拟 LIS 数据 -> 硬规则研判 -> 组装 CKD-ALERT/1.0 报文 -> 投递至医生工作站 / 家长端微信小程序 -> 返回带 offset 的 MQ 回执。

若 agent_suggested_level 与规则引擎判定不一致,以规则引擎为准, 并在回执 level_correction 字段中记录纠偏,用于防止小模型误判等级。

Inputs: patient_id (required), channels, extra_note, trigger_source, +1 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct step in the clinical warning workflow: patient selection, data retrieval, SOP lookup, rule evaluation, and event dispatch. No overlapping purposes or ambiguous boundaries.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (list_, fetch_, get_, evaluate_, trigger_), making the naming predictable and easy to reason about.

    Tool Count5/5

    Five tools is well-scoped for this server's purpose, covering the entire warning process without redundancy or bloat. Each tool serves a necessary function.

    Completeness5/5

    The tool surface covers the complete workflow from patient list retrieval to risk evaluation and warning dispatch, with SOP lookup as a supporting function. No critical gaps or dead ends.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      MCP server for infant fever management that tracks symptoms, medication, and lab results, providing guideline-based escalation levels, pharmacokinetic predictions, and structured clinical reports.
      -
    • A
      license
      A
      quality
      B
      maintenance
      This MCP server generates individualized meal plans for children with chronic kidney disease (CKD) based on KDIGO 2024/PRNT 2020/KRCP 2025 guidelines, incorporating patient age, CKD stage, allergies, dietary culture, and diet diary analysis. It provides deterministic nutrient computations and tools for meal plan generation, food database lookup, and risk analysis.
      13
      MIT
    • F
      license
      A
      quality
      B
      maintenance
      MCP server for pediatric CKD lab data, providing lab panel queries, critical value alerts, trend analysis, and write operations with role-based permissions.
      5
      -
    • F
      license
      A
      quality
      B
      maintenance
      Read-only MCP server providing pediatric CKD patient master data with tools for patient profiles, diagnosis, nutrition ceilings, guardian verification, and patient lists, designed for the CKDNutri project.
      5
      -