# NFYY038 童肾家长助手 · 科普与日常咨询 MCP Server

面向**儿童慢性肾脏病（CKD）患儿家长**的确定性咨询服务。把专业医学语言翻译成家长听得懂的话，
回答家长最高频的日常问题：

- **「XX 能不能吃」** —— 先按红黄牌规则拦截，再结合患儿 CKD 分期 / 年龄 / 体重 / 化验结果，算清楚这一顿最多能吃多少克；
- **「化验单怎么解读」** —— 把血肌酐、白蛋白、血钾、血磷、尿蛋白等指标逐条翻译成大白话；
- **「XX 没有了，用什么替」** —— 按蛋白质 / 能量等价自动换算，并评估替换后钾磷钠会不会对孩子更不利；
- **科普答疑** —— 医学术语翻译、医嘱整段翻译、家长高频问题库、厨房去钾去磷控钠实操。

> 团队：南方医科大学南方医院 **NFYY038**（2026 儿童肾病智能体比赛）

---

## 核心设计原则：确定性

所有阈值判断、营养素计算、等价换算**全部在 Python 代码层完成**，不依赖大模型现场心算：

- 同样的输入 → 永远得到同样的输出（已用 `tests/test_engine.py` 验证）；
- 临床阈值（eGFR 分期、贫血 Hb、血钾上限、限钾限磷起始值等）硬编码并标注权威来源；
- 遇到权威指南有分歧处（如血磷参考区间、白蛋白 25 vs 30 g/L），同时列出并提示以本院参考值为准。

---

## 技术栈与运行方式

- **Python 3.10+** + **FastMCP >= 2.0.0**
- **stdio 传输**，靠 `pyproject.toml` 的 console-script 入口支持 `uvx` 拉起

### 方式一：uvx（推荐，免安装）

```bash
uvx nfyy-ckd-parent-guide-mcp
```

### 方式二：本地源码运行

```bash
pip install -e .
python -m nfyy_ckd_parent_guide        # 等同 console-script：nfyy-ckd-parent-guide-mcp
```

### 接入智能体（MCP 客户端配置示例）

```json
{
  "mcpServers": {
    "nfyy-ckd-parent-guide": {
      "command": "uvx",
      "args": ["nfyy-ckd-parent-guide-mcp"]
    }
  }
}
```

若用本地源码，可替换为：

```json
{
  "mcpServers": {
    "nfyy-ckd-parent-guide": {
      "command": "python",
      "args": ["-m", "nfyy_ckd_parent_guide"]
    }
  }
}
```

---

## 提供的工具（12 个）

| 工具 | 用途 | 关键行为 |
| --- | --- | --- |
| `can_eat` | 「XX 能不能吃」 | 红黄牌拦截 → 缺分期主动追问并列出各分期标准 → 算每顿上限（绿/黄/红灯）|
| `find_substitutes` | 「XX 没有了用什么替」 | 蛋白/能量等价换算 + 钾磷钠增量惩罚打分，过滤红黄牌 |
| `interpret_lab_report` | 「化验单怎么看」 | 逐指标翻译，标 red_flags 与 next_actions |
| `explain_terms` | 术语翻译 | 从一段话里识别术语并逐个翻译成大白话 |
| `translate_doctor_note` | 医嘱整段翻译 | 翻译诊断/医嘱 + 生成「复诊该问医生什么」清单 |
| `search_faq` | 高频问题检索 | 低盐、激素、疫苗、复查等 16 个主题 |
| `list_faq_topics` | 问题库总览 | 列出全部主题便于引导提问 |
| `cooking_tips` | 厨房实操 | 去钾 / 去磷 / 控钠 / 补热量 |
| `daily_standards` | CKD 分期每日营养标准 | 能量/蛋白/钠/钾/磷/钙/液体目标 |
| `search_food` | 食物检索 | 《中国食物成分表》模糊检索，确认条目 |
| `ckd_stage_overview` | 分期饮食要点 | 7 个分期的钾/磷/蛋白/钠管理原则 |
| `egfr_calculator` | eGFR 计算 | bedside Schwartz 公式 + KDIGO 分期（<2 岁不套 G1–G5）|

---

## 权威依据（数据来源）

- **食物成分**：《中国食物成分表》（用户提供的 `中国食物成分表.xlsx`，1752 条 × 35 营养素），已转换为 `data/food_data.csv`；
- **能量 / 蛋白目标**：PRNT 2020 共识（SDI 表，按实际年龄）；
- **钙磷 / 钾 / 钠**：PRNT 2020 钙磷共识、PRNT 2021 钾共识、PRNT 钠共识；
- **CKD 分期 / 蛋白尿分级**：KDIGO 2012 / 2024、中华医学会儿科学分会肾脏学组 2017 肾病综合征指南；
- **eGFR 公式**：bedside Schwartz（JASN 2009）、CKiD U25（1–25 岁连续）；
- **贫血 / 代酸 / 检验参考区间**：KDIGO 2012、KDOQI 2008、IOM 年龄参考。

所有引用点在代码 docstring 与返回结果的 `依据 / source` 字段中标注。

---

## 红黄牌规则（不依赖成分表）

- **绝对红灯（不分分期禁用）**：杨桃、低钠盐 / 代盐（含氯化钾）、米浆、含马兜铃酸药材；
- **用药红黄牌**：NSAIDs 类（退烧止痛）红灯、肾毒性药物与造影剂黄牌；
- **黄牌（限量/注意）**：可乐等深色汽水、加工肉、腌菜、老火汤、果干、坚果等；
- **磷酸盐添加剂**：包装上的「磷酸盐 / 焦磷酸钠 / 三聚磷酸钠 / 六偏磷酸钠 / 膨松剂」一律视为无机磷，吸收率 80–90%，必须避免。

---

## 目录结构

```
nfyy038-ckd-parent-guide-mcp/
├── pyproject.toml                  # uvx 入口与依赖
├── README.md
├── LICENSE
├── src/nfyy_ckd_parent_guide/
│   ├── server.py                   # MCP 工具注册 + run() 入口
│   ├── verdict.py                  # 「XX 能不能吃」引擎
│   ├── substitute.py               # 等价替换引擎
│   ├── labs.py                     # 化验单解读引擎
│   ├── stages.py                   # CKD 分期 / 每日营养标准
│   ├── foods.py                    # 食物成分数据层
│   ├── education.py                # 科普层（术语/医嘱/FAQ/厨房）
│   └── data/
│       ├── food_data.csv           # 中国食物成分表（1752 条）
│       ├── food_alias.json         # 家长口语 → 标准条目
│       ├── food_flags.json         # 红黄牌清单
│       ├── portion_reference.json   # 儿童单次食用量
│       ├── glossary.json           # 童肾高频术语词典
│       └── faq.json                # 家长高频问题库
├── tests/test_engine.py            # 确定性引擎冒烟测试
├── scripts/_smoke_stdio.py         # 真实 stdio(JSON-RPC) 冒烟测试
└── docs/
```

---

## 测试

```bash
python tests/test_engine.py          # 确定性引擎测试（8 项全过）
python scripts/_smoke_stdio.py       # 真实 stdio 传输冒烟测试
```

---

## 免责声明

本服务仅用于**家长科普与日常咨询辅助**，所有结论须以主管医生、营养师的个体化处方为准。
涉及用药、急诊、透析通路等问题，请直接联系医疗团队，本工具不提供医疗决策。