Nutri MCP

NutriMCP-个人营养追踪系统

一个无头个人营养跟踪系统，其中LLM聊天充当UI，通过连接到Supabase数据库的MCP服务器进行通信。

概述

架构： LLM↔ FastMCP服务器↔ Supabase（PostgreSQL）

• 没有前端，没有UI -所有交互都通过任何兼容MCP的LLM进行对话
• MCP工具中的所有逻辑 -业务逻辑存在于MCP服务器中
• Supabase中的所有数据 -PostgreSQL数据库，实现可靠持久性
• 单用户系统 -简化为个人使用

功能（第一阶段）

✅ 用餐记录 -记录多种食物和份量的膳食\ ✅ 食品管理 -使用灵活的营养数据创建定制食品\ ✅ 每日总结 -查看营养总量和目标进展\ ✅ 膳食编辑 -更新或删除已记录的餐食\ ✅ 膳食模板 -保存和重复使用常见的膳食配置\ ✅ 用户档案 -设定并跟踪每日营养目标

技术栈

• FastMCP -Python MCP服务器框架
• Supabase -带有REST API的PostgreSQL数据库
• 派丹蒂克 -数据验证和序列化

快速开始

🚀 NutriMCP新手？ 跟随 QUICKSTART.md 分步设置说明指南！

太长，读不下去了

# 1. Install UV (fast package manager)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

# 2. Install dependencies
uv sync

# 3. Configure Supabase (use system env vars or .env file)
# Set SUPABASE_URL and SUPABASE_KEY

# 4. Start server (migrations run automatically)
uv run python mcp_server.py

pip/venv的替代方案：

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
python mcp_server.py

安装

1.克隆和安装依赖项

git clone 
cd NutriMCP
pip install -r requirements.txt

2.设置数据库

1. 在以下位置创建新项目 网站 supabase.com
2. 复制项目URL和匿名密钥
3. 创建一个 .env 文件：

cp .env.example .env
# Edit .env with your credentials

3.数据库模式和迁移

数据库模式通过以下方式管理 自动迁移。当您第一次启动服务器时，它将尝试自动应用所有挂起的迁移。

选项A：自动（建议用于本地/测试）

只需启动服务器（下面的步骤4）-迁移将自动运行！

选项B：手动（Supabase托管需要）

由于Supabase Python客户端的限制，您可能需要手动运行迁移：

1. 转到您的Supabase仪表板→ SQL 编辑器
2. 从运行每个迁移文件 migrations/ 目录顺序：

- migrations/000_migrations_table.sql - migrations/001_initial_schema.sql

或者，使用组合模式文件：

# Copy the content of schema.sql and paste it into Supabase SQL Editor

看 migrations/README.md 有关迁移工作原理的更多详细信息。

4.运行MCP服务器

python mcp_server.py

服务器将启动并可用于MCP连接。

营养单位

所有营养数据都存储在 国际标准单位:

• 卡路里：千卡（千卡）
• 蛋白质：克（g）
• 碳水化合物：克（g）
• 脂肪：克（g）
• 纤维：克（g）
• 糖：克（g）
• 饱和脂肪：克（g）

单位转换支持

这 create_food 该工具接受各种输入单位并自动转换：

重量单位：

• g、 克，克（基本单位）
• 公斤，千克，千克
• mg，毫克，毫克
• 盎司，盎司，盎司
• 磅，磅，磅

卡路里单位：

• kcal，cal，卡路里，卡路里

例子：

{
  "name": "Protein Powder",
  "serving_size": "1 scoop (30g)",
  "protein": 25.0,
  "macro_unit": "g"
}

MCP工具参考

食品管理

create_food

根据营养信息定制食物。

参数：

• name （str）-食品名称
• serving_size （str）-食用说明（例如“100克”、“1杯”）
• calories （浮动，可选）-每份卡路里
• protein （浮子，可选）-每份蛋白质
• carbs （浮动，可选）-每份碳水化合物
• fat （浮子，可选）-每份脂肪
• fiber （浮动，可选）-每份纤维
• sugar （浮动，可选）-每份糖
• saturated_fat （浮动，可选）-每份饱和脂肪
• calories_unit （str，默认值“kcal”）-卡路里单位
• macro_unit （str，默认“g”）-所有宏的单位

例子：

{
  "name": "Grilled Chicken Breast",
  "serving_size": "100g",
  "calories": 165,
  "protein": 31,
  "carbs": 0,
  "fat": 3.6,
  "macro_unit": "g"
}

list_foods

通过可选搜索列出所有定制食品。

参数：

• search （str，可选）-按食物名称过滤

delete_food

删除自定义食物。

参数：

• food_id （str）-食物的UUID

餐饮管理

log_meal

用食物和数量记录新餐。

参数：

• meal_name （str）-餐点名称（例如“早餐”）
• foods （列表）-列表 {food_id, quantity} 物体
• meal_time （str，可选）-ISO时间戳（默认为现在）
• notes （str，可选）-用餐注意事项

例子：

{
  "meal_name": "Breakfast",
  "foods": [
    {"food_id": "uuid-1", "quantity": 2},
    {"food_id": "uuid-2", "quantity": 1.5}
  ],
  "notes": "Post-workout meal"
}

get_meals

使用可选过滤功能获取记录的餐食。

参数：

• start_date （str，可选）-ISO日期/日期时间
• end_date （str，可选）-ISO日期/日期时间
• limit （int，可选）-最大结果数

edit_meal

更新现有膳食。

参数：

• meal_id （str）-用餐的UUID
• meal_name （str，可选）-新餐名
• meal_time （str，可选）-新时间戳
• foods （列表，可选）-新食物列表（替换所有）
• notes （str，可选）-新注释

delete_meal

删除已记录的餐食。

参数：

• meal_id （str）-用餐的UUID

get_daily_summary

获取特定日期的营养总结。

参数：

• target_date （str，可选）-YYYY-MM-DD格式的日期（默认为今天）

退货：

• 一天的总营养
• 用餐人数
• 目标进度百分比

模板管理

create_meal_template

将膳食配置保存为可重复使用的模板。

参数：

• template_name （str）-模板名称
• foods （列表）-列表 {food_id, quantity} 物体

list_meal_templates

列出所有已保存的模板。

use_meal_template

从模板中记录一顿饭。

参数：

• template_id （str）-模板的UUID
• meal_name （str）-记录的餐食名称
• meal_time （str，可选）-ISO时间戳
• notes （str，可选）-用餐注意事项

delete_meal_template

删除模板。

参数：

• template_id （str）-模板的UUID

用户档案

get_user_profile

获取用户资料和营养目标。

update_user_profile

更新用户资料和目标。

参数：

• name （str，可选）-用户名
• daily_calorie_goal （int，可选）-每日卡路里目标（kcal）
• daily_protein_goal （int，可选）-每日蛋白质目标（g）
• daily_carbs_goal （int，可选）-每日碳水化合物目标（g）
• daily_fat_goal （int，可选）-每日脂肪目标（g）

用法示例

以下是通过对话式交互的典型工作流程：

1. 设置配置文件：

   "Set my daily goals to 2000 calories, 150g protein, 200g carbs, and 65g fat"

1. 添加定制食品：

   "Add a food: Grilled Chicken Breast, 100g serving, 165 calories, 31g protein, 0g carbs, 3.6g fat"

1. 记录一顿饭：

   "Log breakfast: 2 servings of oatmeal and 1 banana"

1. 检查进度：

   "Show me today's nutrition summary"

1. 创建模板：

   "Save my current breakfast as a template called 'Standard Breakfast'"

1. 稍后使用模板：

   "Log tomorrow's breakfast using my Standard Breakfast template"

数据模型

关系

users (1)
foods (many) ──┐
               ├── meal_foods ── meals (many)
               └── meal_template_foods ── meal_templates (many)

关键设计决策

1. 灵活的营养数据 -除卡路里外，所有营养领域都是可选的
2. 基于数量的系统 -食物按份定义；膳食使用量乘数
3. 级联删除 -删除膳食/模板会自动删除相关食物
4. 单个用户 -查询中不需要user_id
5. 基于时间戳 -所有日期查询都使用 meal_time 为了准确性
6. 不可变模板 -模板是快照；改变食物不会影响现有的模板

故障排除

连接问题

如果您遇到连接错误：

1. 验证 .env 文件具有正确的Supabase凭据
2. 检查您的Supabase项目是否处于活动状态
3. 确保您的IP在Supabase设置中被允许

数据库错误

如果查询失败：

1. 确认所有表都是使用提供的SQL架构创建的
2. 检查是否正确设置了外键关系
3. 验证连接表上是否启用了级联删除

单位转换

所有宏值都以克为单位存储。如果您看到意外值：

1. 检查您是否使用了支持的单位名称
2. 记住卡路里默认值为“kcal”
3. 所有常量营养素默认为“g”（克）

发展

有关详细的开发指南、测试实践和贡献说明，请参阅 Developpent.md.

项目结构

NutriMCP/
├── mcp_server.py          # FastMCP app with all 14 MCP tools
├── database.py            # Supabase client and query functions
├── models.py              # Pydantic models with validation
├── migrations.py          # Database migration runner
├── config.py              # Environment configuration
├── migrations/            # SQL migration files
│   ├── README.md          # Migration documentation
│   ├── 000_migrations_table.sql
│   └── 001_initial_schema.sql
├── tests/                 # Test suite (TDD)
│   ├── conftest.py        # Shared test fixtures
│   ├── README.md          # Testing documentation
│   ├── unit/              # Unit tests
│   │   ├── test_models.py
│   │   └── test_database.py
│   ├── integration/       # Integration tests
│   │   └── test_mcp_tools.py
│   └── migrations/        # Migration tests
│       └── test_migrations.py
├── requirements.txt       # Python dependencies
├── pytest.ini             # Pytest configuration
├── schema.sql             # Combined schema (for manual setup)
├── .cursor/               # Cursor AI configuration
│   └── rules/             # Modular development rules (.mdc files)
├── .env.example           # Example environment file
├── .gitignore             # Git ignore rules
├── README.md              # Project overview (this file)
└── DEVELOPMENT.md         # Development guide and best practices

数据库迁移

该项目使用一个简单的迁移系统来管理模式更改：

它是如何工作的：

1. 迁移文件存储在 migrations/ 目录
2. 每次迁移都有编号（000、001、002等）
3. 服务器启动时，将自动应用挂起的迁移
4. 在中跟踪应用的迁移 schema_migrations 桌子

添加新迁移：

1. 创建新文件： migrations/002_your_change_description.sql
2. 编写SQL架构更改
3. 重新启动服务器以自动应用

迁移示例：

-- migrations/002_add_water_tracking.sql
CREATE TABLE IF NOT EXISTS water_logs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    amount_ml INTEGER NOT NULL,
    logged_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

手动迁移记录： 如果您通过Supabase SQL编辑器手动应用迁移，请记录它们：

INSERT INTO schema_migrations (version, name) 
VALUES (2, 'add_water_tracking');

看 migrations/README.md 了解更多详情。

测试

自动化测试套件

该项目遵循测试驱动开发（TDD），具有全面的测试覆盖率。

运行所有测试：

pytest

使用覆盖率报告运行测试：

pytest --cov=. --cov-report=html

测试结构：

• tests/unit/ -模型和数据库操作的单元测试（带模拟）
• tests/integration/ -MCP工具的端到端集成测试
• tests/migrations/ -迁移幂等性和结构检验

看 tests/README.md 详细的测试文档和TDD工作流程。

手动集成测试

通过LLM界面测试每个MCP工具：

1. 创建具有目标的用户配置文件
2. 添加3-5种定制食品
3. 用多种食物记录膳食
4. 去拿今天的饭菜
5. 获取目标进展的每日总结
6. 编辑一顿饭
7. 从食物中创建模板
8. 使用模板记录新餐
9. 删除测试条目

未来增强功能（第2+阶段）

未来阶段的潜在特征：

• 每周/每月总结和趋势
• 配料配方管理
• 膳食计划和安排
• 从营养原料药进口（美国农业部，Nutritionix）
• 条形码扫描集成
• 水和补充剂跟踪
• 体重跟踪和相关性
• 将数据导出为CSV/JSON

许可证

个人项目-随意使用。

贡献

这是一个个人项目，但欢迎提出建议和改进！