卡路里追踪器MCP服务器
🎯 项目概述
一个专为聊天代理（如克劳德）设计的一流公民卡路里跟踪系统，具有MCP（模型上下文协议）集成功能，可实现无缝的人工智能助手交互、持久存储和全面分析。
📋 核心要求
1.MCP服务器功能
- 远程MCP服务器：可从任何地方访问（不仅仅是本地主机）
- 聊天优先设计：通过Claude和其他AI助手优化交互
- 简单API：通过MCP工具将膳食/配料添加到仓库中
- 永久存储：用于长期数据保留的数据库
2.跟踪能力
- 批量卡路里跟踪：使用原子事务在一次操作中记录单餐或多餐
- 体重管理：通过批量操作和日期验证记录每日重量测量值
- 历史数据导入：支持现有数据的CSV导入
3.分析功能
- 每日指标:
- 消耗的总热量 - 热量不足/过剩 - 重量测量
- 趋势分析:
- 移动平均重量（可配置N天） - 每日体重变化 - N天内平均/中位体重变化 - 随时间推移的总体重减轻
- 高级分析:
- 日期范围内的累计赤字计算 - 基于减肥与赤字的代谢率估计 - 能够根据计算更新代谢率
- 导出选项:
- 用于可视化的Google表格集成 - CSV导出功能
🛠 技术栈
后端（MCP服务器）
- 语言：Types/Node.js
- 出色的MCP SDK支持 - 强大的web服务生态系统
- MCP传输:
- 本地：克劳德桌面的标准传输 - 远程：通过Express.js流式传输HTTP（MCP协议2025-03-26）
- 数据库：SQLite
- 简单的基于文件的数据库 - 不需要单独的数据库服务器 - 支持会话隔离的多用户 - 轻松备份（只需复制文件）
- MCP集成：@modelcontextprotocol/sdk
- TypeScript官方MCP SDK - 最新协议支持（2025-03-26） - 双传输能力（stdio+HTTP）
地方发展
- 需求：Node.js，npm/yarn
- 数据库：项目目录中的SQLite文件
- MCP测试：用于本地测试的Claude Desktop应用程序
- 配置：基于环境的配置
- 用于stdio传输的USER_ID（必需） - 用于HTTP测试的可选调试中间件 - 数据库路径和服务器设置
- 构建:
npm run build将TypeScript编译为JavaScript
分析和导出
- CSV导出：SQLite原生
.import命令 - 报告生成：使用移动平均线增强摘要报告
- 移动平均值：可配置的N天权重趋势平滑
- 重量趋势分析：第一天到最后一天的差异计算
🏗 建筑设计
graph TB
Claude[Claude/Chat Agents] --> MCP[MCP Server
TypeScript + Node.js]
MCP --> DB[(SQLite Database)]
subgraph "Core Data"
DB --> Meals[Meals Table]
DB --> Weights[Weights Table]
DB --> Settings[User Settings]
end
subgraph "MCP Tools"
MCP --> AddMeals[add_meals]
MCP --> CheckWeight[check_weight]
MCP --> Summary[get_summary]
MCP --> Settings[update_user_settings]
end
subgraph "Future Export"
MCP -.-> CSV[CSV Export]
CSV -.-> Sheets[Google Sheets]
end📊 数据模型
- 餐食：卡路里、可选宏量（蛋白质/碳水化合物/脂肪）、时间戳
- 权重：具有日期限制的每日重量条目
- 用户设置：代谢率、时区偏好
所有由user_id限定范围的数据，具有完全的多用户支持和会话隔离。
🔧 MCP工具
- \[x\] add_mals: 分批添加膳食 -使用原子操作在单个事务中添加一顿或多顿饭（仅限数组）
- \[x\] 添加重量: 批量重量跟踪 -添加一个或多个带有日期验证和重复处理的重量条目
- \[x\] update_user_settings：更新时区和代谢率
- \[x\] get_summary：JSON格式的多日汇总，包括移动平均线、每日统计数据和权重差异分析
- \[x\] calculate_metapolic_rate：根据7天的历史数据和3天的移动平均值计算代谢率（纯计算工具）
- \[ \] list_recent_mals：列出最近的用餐记录
- \[ \] update_mal：更新现有膳食条目
- \[ \] delete_meal：删除用餐条目
- \[ \] export_csv：数据导出功能（SQLite原生支持可用）
🧪 测试
✅ 电流测试
- 全面的测试套件 Vitest框架包括 分批用餐操作测试
- 数据库层测试 具有内存SQLite和事务回滚验证功能
- MCP服务器集成测试 使用InMemoryTransport进行客户端-服务器通信测试
- 代谢率计算试验 使用类型安全的结果验证助手
- CI/CD集成 配备自动化测试流程
- 并发访问测试 已与多个客户端验证
- 通过Claude Desktop和MCP Inspector进行手动测试
📚 文档
- Developpent.md -运行和调试两种传输模式的完整指南
- CLAUDE.md -开发指南和编码标准
- **** -容器部署配置
✅ 当前状态
- ✅ 使用MCP SDK的TypeScript项目
- ✅ 具有模式和适当异步/等待模式的SQLite数据库
- ✅ 具有移动平均计算功能的增强MCP工具
- ✅ 双传输支持（stdio+HTTP），可正常关闭
- ✅ 支持并发访问的用户上下文架构
- ✅ CI/CD管道的全面测试覆盖
- ✅ 使用Docker实现生产就绪的容器化
💡 为什么选择TypeScript？
我们选择TypeScript而不是Go，因为官方的MCP SDK是TypeScript优先的，为构建MCP服务器提供了更好的稳定性、文档和长期支持。
______________________________________________________________________
📋 剩余待办事项
核心功能
- \[x\] 通过删除连接实现优雅关机
- \[x\] 测试通过两个不同客户端的并发访问
- \[x\] 批量用餐操作 -对于原子批量插入，将add_meal替换为add_meal
- \[x\] 重构索引ts -将MCP服务器实现分离到专用模块中（src/MCP/index.ts）
- \[x\] 膳食预设系统 -通过CLAUDE.md上下文指令解决，以保持最近用餐的上下文（不需要新工具）
分析和报告
- \[x\] 根据历史数据计算代谢率
- \[\]增强的每日摘要工具（任何日期）
- \[\]使用移动平均线进行权重趋势分析
- \[\]日期范围统计工具
- \[\]周/月总结报告
- \[\]体重预测模型
测试与质量
- \[x\] 使用内存SQLite设置Vitest测试框架
- \[x\] 编写全面的数据库层测试
- \[x\] MCP服务器集成测试 使用InMemoryTransport和类型安全结果验证
- \[x\] 代谢率计算测试 实时数据验证
- \[x\] 向CI/CD管道添加测试
生产和部署
- \[x\] 通过自动化测试设置CI/CD管道
- \[\]选择托管平台并部署
- \[\]实施备份策略
- \[\]监控和警报
- \[\]安全强化
- \[\]面向互联网时添加适当的身份验证
可选增强功能
- \[\]Web仪表板
- \[\]谷歌表格直接集成
- \[\]移动应用程序注意事项
- \[\]第三方健身应用同步
______________________________________________________________________