Metadata-Version: 2.4
Name: ckd-meal-plan-mcp
Version: 1.0.1
Summary: NFYY038 童肾营养师·个体化食谱生成 MCP Server（儿童 CKD / KDIGO 2024 营养目标 · 含克重/餐次/替代方案）
Author: 南方医科大学南方医院 NFYY038 团队
License: MIT
Project-URL: Homepage, https://github.com/rpint/nfyy-ckd-meal-plan-mcp
Project-URL: Repository, https://github.com/rpint/nfyy-ckd-meal-plan-mcp
Project-URL: Documentation, https://github.com/rpint/nfyy-ckd-meal-plan-mcp#readme
Keywords: ckd,pediatric-nephrology,meal-plan,nutrition,kdigo,mcp,agent,nfyy038
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Healthcare Industry
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.0.0
Dynamic: license-file

# NFYY038 童肾营养师 · 个体化食谱生成 MCP Server

> 面向儿童慢性肾脏病（CKD 1–5 期及透析）的**确定性**个体化食谱生成服务。
> 结合患儿年龄、CKD 分期、透析状态、食物过敏、地方饮食文化与 3 天饮食日记，
> 输出符合 **KDIGO 2024 / PRNT 2020 / KRCP 2025** 营养目标的**可执行一日五餐食谱**
> （含克重、餐次、量具换算、替代方案与烹饪去钾/去磷要点）。

团队：南方医科大学南方医院 NFYY038 团队 ｜ 复赛交付物

---

## ✨ 功能特性

- **严格参考权威依据**：能量按 IOM/DRI 2005 EER 方程估算；蛋白按 PRNT 2020 取区间上限促生长、下限为不可破安全底线；钾/磷/钠分层参照 KRCP 2025。
- **确定性计算，零模型幻觉**：所有克重、能量、钠钾磷换算均由代码层硬规则完成，模型不参与任何算术（与 NFYY038 风险预警 Agent 的硬规则范式一致）。
- **覆盖全场景**：15 名模拟患儿覆盖 CKD G1–G5D 全分期、非透析/腹透/血透/HDF 四种透析、10 类过敏原、10 种地方饮食文化。
- **个体化约束**：限钾/限磷时剔除危险食材（高钾主食/水果/蛋白、高磷蛋白源），优先低钾低磷品种，并用焯水/浸泡/水煮弃汤等烹饪折减。
- **零蛋白能量模块**：用粉丝/米粉/藕粉/凉粉等近乎零蛋白淀粉补足能量，避免靠谷物堆热量而冲爆低蛋白上限。
- **可轮换多日食谱**：传入不同 `variant` 即可得到不同食材搭配，便于编排连续多日食谱。
- **饮食日记分析**：对比 KDIGO 目标识别高钾水果、老火汤、加工食品钠磷超标、蛋白不足/过量、隐藏过敏原。

## 🧰 MCP 工具清单（15 个）

| 工具 | 作用 |
| --- | --- |
| `list_patients` | 列出全部模拟患儿 |
| `get_patient_profile` | 患儿完整档案 |
| `get_labs` | 化验记录 |
| `get_diet_diary` | 最近 N 天饮食日记 |
| `record_diet_entry` | **记录某一天某一餐的一种食物，写入 SQLite（可反复追加）** |
| `record_diet_day` | **一次性记录某一天整日饮食（JSON 批量），写入 SQLite** |
| `analyze_diet_diary` | 饮食日记营养风险分析（含新记录的当日数据） |
| `compute_nutrition_targets` | KDIGO 2024 个体化营养目标 |
| `generate_meal_plan` | 生成一日五餐食谱（自动落库） |
| `save_meal_plan` | 手动保存食谱 JSON |
| `list_meal_plans` | 已保存食谱列表 |
| `search_food` | 《中国食物成分表》检索 + 肾友分级 |
| `get_food_profile` | 单食物完整营养素与分级 |
| `get_alternatives` | 同类等效替代 |
| `knowledge_card` | 儿童 CKD 营养知识卡片 |

> 记录链路：`record_diet_entry` / `record_diet_day` → 写入 `diet_diary` 表 → `get_diet_diary` 可随时读回、`analyze_diet_diary` 重新分析（与历史种子日记合并统计）。

## 🛠 技术栈

- **Python 3.10+** · **FastMCP 2.x/3.x** · **stdio** 传输
- `uvx` 经由 `pyproject.toml` 的 `console_scripts` 入口直接拉起
- 内置 SQLite 存储（患者档案、化验、日记、已生成食谱）

## 📦 安装与运行

```bash
# 方式一：从源码
pip install -e .
python -m nfyy_ckd_meal_plan.server          # stdio 模式

# 方式二：uvx（发布到 PyPI 后）
uvx nfyy-ckd-meal-plan-mcp

# 自定义 SQLite 路径（默认 ~/.nfyy-ckd-meal-plan/meal_plan.db）
export NFYY_MEAL_DB=/path/to/meal_plan.db
```

首次运行会自动用内置的 15 名模拟患儿数据播种 SQLite。

## 🔌 与 MCP 客户端对接

服务以 stdio 暴露，任何兼容 MCP 的客户端（Claude Desktop、魔搭社区、自建 Agent）
只需配置启动命令：

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

## 📚 数据来源

- `CKD儿童能量与蛋白质营养管理_KRCP2025知识库.md` —— 营养目标、分级阈值、临床铁律
- `中国食物成分表.xlsx` —— 1752 条食物 × 35 项营养素（已转为 `data/food_data.csv`）
- 15 名患儿为**虚构演示数据**，仅用于复赛功能验证，不构成任何真实诊疗建议。

## 📐 配餐铁律（摘要）

1. 先定蛋白源，再用零蛋白能量补热；能量缺口不靠加肉补。
2. 加餐近零蛋白，只承担能量与愉悦感。
3. 限钾不等于不吃菜：先选低钾品种，再改刀→浸泡→焯水弃汤。
4. 限磷优先砍无机磷（加工食品磷酸盐添加剂吸收率≈100%）。
5. 蛋白下限是绝对安全底线，任何情况不可突破。

## 🚀 部署

详见 [docs/deploy.md](docs/deploy.md)：GitHub（代码）→ PyPI（可安装包）→ 魔搭社区（登记为可调用的 MCP 服务）。

## ⚠️ 合规声明

本服务为**营养管理辅助决策工具**，所有输出不构成医疗建议。蛋白质/钾/磷/钠的最终处方上限
须由儿科肾脏专科医师或注册营养师核定；磷结合剂、钾结合剂、透析处方调整不得依据本服务自行变更。
