py-huckleberry-mcp

# 哈克贝利 MCP 服务器 > **免责声明**: 这是一个非官方的、社区建设的项目。它不被赞助、认可或支持由哈克贝利。按需使用风险自负。 一个使用 FastMCP 构建的模型上下文协议（MCP）服务器，与哈克贝利婴儿跟踪 API 接口，允许克劳德通过自然对话帮助您跟踪婴儿的睡眠、喂养、换尿布和生长测量。 ## 功能 - **儿童管理**: 列出和管理多个儿童档案 - **睡眠跟踪**: 开始、暂停、恢复、完成和取消睡眠会话，自动历史记录 - **喂养跟踪**: 跟踪母乳喂养会话，带有侧面切换 - **换尿布记录**: 记录换尿布类型、数量、颜色和一致性细节 - **生长跟踪**: 记录和检索体重、身高和头围测量值 ## 先决条件 - Python 3.10 或更高版本 - 具有有效凭证的哈克贝利账户 - 克劳德桌面应用程序（用于集成） - `uv` 包管理器（推荐）或 `pip` ## 安装 ### 使用 uv（推荐） ```bash # 克隆或导航到项目目录 cd /path/to/huckleberry-mcp uv sync ``` ### 使用 pip ```bash cd /path/to/huckleberry-mcp pip install -e . ``` ## 架构 该服务器使用 [FastMCP](https://github.com/jlowin/fastmcp) 框架进行快速 MCP 服务器开发。FastMCP 提供： - 通过装饰器自动注册工具 - 从类型提示和文档字符串生成模式 - 内置错误处理和协议合规性 - 支持多种传输类型（STDIO、HTTP） 服务器在 5 个类别中实现了 22 个工具： - 儿童管理（2 个工具） - 睡眠跟踪（7 个工具） - 喂养跟踪（8 个工具） - 换尿布跟踪（2 个工具） - 生长跟踪（3 个工具） 所有工具都使用延迟身份验证 - 凭证在首次使用工具时验证，而不是在服务器启动时。 ## 身份验证设置 服务器需要将您的哈克贝利凭证配置为环境变量。 ### 克劳德桌面配置（推荐） 将服务器添加到克劳德桌面配置文件中，并包含您的凭证： **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` **Linux**: `~/.config/Claude/claude_desktop_config.json` ```json { "mcpServers": { "huckleberry": { "command": "uv", "args": [ "--directory", "/absolute/path/to/huckleberry-mcp", "run", "huckleberry-mcp" ], "env": { "HUCKLEBERRY_EMAIL": "your-email@example.com", "HUCKLEBERRY_PASSWORD": "your-password", "HUCKLEBERRY_TIMEZONE": "America/New_York" } } } } ``` **重要提示**： - 将 `/absolute/path/to/huckleberry-mcp` 替换为该项目的实际绝对路径 - 在 macOS 上，如果使用 Anaconda，请指定 `uv` 的完整路径：`/Users/your-username/anaconda3/bin/uv` - 确保 `uv` 在您的 PATH 中或使用 `uv` 可执行文件的完整路径 ## 可用工具 ### 儿童管理 #### `list_children` 列出所有具有 UID、姓名和出生日期的儿童档案。 **示例**: "列出我的孩子" ### 睡眠跟踪 #### `log_sleep` 直接记录一个完成的睡眠会话，而不使用计时器。适用于回顾性记录或导入过去的睡眠数据。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 - `start_time`（字符串，必填）：睡眠开始时间，ISO 格式。如果未指定时区（例如 "2026-01-30T14:30:00"），则解释为配置的时区。对于 UTC，请使用 "2026-01-30T14:30:00Z"。 - `end_time`（字符串，可选）：睡眠结束时间，ISO 格式（提供此参数或 `duration_minutes`）。与 `start_time` 相同的时区处理。 - `duration_minutes`（整数，可选）：睡眠时长（分钟）（提供此参数或 `end_time`） **时区说明**: 没有时区信息的時間将使用 `HUCKLEBERRY_TIMEZONE` 设置（例如 "America/New_York"）进行解释。这确保时间在哈克贝利应用中正确显示。 **示例**: "记录昨天下午 2 点到 4 点的睡眠会话" #### `start_sleep` 使用实时计时器开始为儿童跟踪睡眠。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 **示例**: "开始爱丽丝的睡眠会话" #### `pause_sleep` 暂停活跃的睡眠跟踪会话。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 **示例**: "暂停睡眠会话" #### `resume_sleep` 恢复暂停的睡眠跟踪会话。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 **示例**: "恢复睡眠会话" #### `complete_sleep` 完成并保存睡眠跟踪会话。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 **示例**: "完成睡眠会话" #### `cancel_sleep` 取消并丢弃睡眠跟踪会话。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 **示例**: "取消睡眠会话" #### `get_sleep_history` 获取儿童在指定日期范围内的睡眠历史（默认为最近 7 天）。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 - `start_date`（字符串，可选）：开始日期，ISO 格式（YYYY-MM-DD），包含 - `end_date`（字符串，可选）：结束日期，ISO 格式（YYYY-MM-DD），排除（数据最多到但不包括此日期） **重要提示**: `end_date` 是独占的。要获取某一天的数据（例如，1 月 30 日），请设置 `start_date='2026-01-30'` 和 `end_date='2026-01-31'`。 **示例**: "显示我上周的睡眠历史" ### 喂养跟踪 #### `log_breastfeeding` 直接记录一个完成的母乳喂养会话，而不使用计时器。适用于回顾性记录或导入过去的喂养数据。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 - `start_time`（字符串，必填）：喂养开始时间，ISO 格式。如果未指定时区，则解释为配置的时区。 - `left_duration_minutes`（整数，可选）：左侧乳房喂养时间，分钟 - `right_duration_minutes`（整数，可选）：右侧乳房喂养时间，分钟 - `end_time`（字符串，可选）：喂养结束时间，ISO 格式（提供此参数或持续时间） - `last_side`（字符串，可选）：完成哪一侧（“left”或“right”）。如果使用 `end_time`，则必填。 **用法模式**: - 使用持续时间：提供 `left_duration_minutes` 和/或 `right_duration_minutes` - 使用结束时间：提供 `end_time` 和 `last_side`（自动计算持续时间） **时区说明**: 没有时区信息的時間将使用 `HUCKLEBERRY_TIMEZONE` 设置进行解释。 **示例**: - "记录昨天下午 2 点到 2:30 的左侧母乳喂养" - "记录母乳喂养：左侧 10 分钟，右侧 15 分钟，从今天下午 3 点开始" #### `start_breastfeeding` 使用实时计时器开始为儿童跟踪母乳喂养。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 - `side`（字符串，必填）：开始哪一侧（“left”或“right”） **示例**: "开始左侧母乳喂养" #### `pause_feeding` 暂停活跃的喂养跟踪会话。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 **示例**: "暂停喂养" #### `resume_feeding` 恢复暂停的喂养跟踪会话。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 **示例**: "恢复喂养" #### `switch_feeding_side` 在母乳喂养期间在左侧和右侧之间切换。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 **示例**: "切换到另一侧" #### `complete_feeding` 完成并保存喂养跟踪会话。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 **示例**: "完成喂养" #### `cancel_feeding` 取消并丢弃喂养跟踪会话。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 **示例**: "取消喂养" #### `get_feeding_history` 获取儿童在指定日期范围内的喂养历史（默认为最近 7 天）。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 - `start_date`（字符串，可选）：开始日期，ISO 格式（YYYY-MM-DD），包含 - `end_date`（字符串，可选）：结束日期，ISO 格式（YYYY-MM-DD），排除（数据最多到但不包括此日期） **重要提示**: `end_date` 是独占的。要获取某一天的数据（例如，1 月 30 日），请设置 `start_date='2026-01-30'` 和 `end_date='2026-01-31'`。 **示例**: "显示我今天的喂养记录" ### 换尿布跟踪 #### `log_diaper` 记录换尿布的详细信息。支持可选的时间戳进行回顾性记录。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 - `mode`（字符串，可选）：换尿布模式（“pee”，“poo”，“both”，“dry”），默认为“both” - `pee_amount`（字符串，可选）：尿量（“little”，“medium”，“big”） - `poo_amount`（字符串，可选）：便量（“little”，“medium”，“big”） - `color`（字符串，可选）：便颜色（如果有）（“yellow”，“brown”，“black”，“green”，“red”，“gray”） - `consistency`（字符串，可选）：便稠度（如果有）（“solid”，“loose”，“runny”，“mucousy”，“hard”，“pebbles”，“diarrhea”） - `diaper_rash`（布尔值，可选）：婴儿是否有尿布疹，默认为 False - `notes`（字符串，可选）：关于换尿布的可选说明 - `timestamp`（字符串，可选）：用于回顾性记录的 ISO 格式时间戳。如果未提供，则使用当前时间。 **时区说明**: 没有时区信息的時間将使用 `HUCKLEBERRY_TIMEZONE` 设置进行解释。 **示例**: - "记录一次带有尿液和便便的换尿布" - "记录一个湿尿布，从 2 小时前开始"（带有回顾性时间戳） #### `get_diaper_history` 获取儿童在指定日期范围内的换尿布历史（默认为最近 7 天）。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 - `start_date`（字符串，可选）：开始日期，ISO 格式（YYYY-MM-DD），包含 - `end_date`（字符串，可选）：结束日期，ISO 格式（YYYY-MM-DD），排除（数据最多到但不包括此日期） **重要提示**: `end_date` 是独占的。要获取某一天的数据（例如，1 月 30 日），请设置 `start_date='2026-01-30'` 和 `end_date='2026-01-31'`。 **示例**: "显示我今天的换尿布记录" ### 生长跟踪 #### `log_growth` 记录生长测量值（体重、身高、头围）。支持可选的时间戳进行回顾性记录。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 - `weight`（数字，可选）：体重（磅，如果使用英制；公斤，如果使用公制） - `height`（数字，可选）：身高（英寸，如果使用英制；厘米，如果使用公制） - `head`（数字，可选）：头围（英寸，如果使用英制；厘米，如果使用公制） - `units`（字符串，可选）：测量系统（“imperial”或“metric”），默认为“imperial” - `timestamp`（字符串，可选）：用于回顾性记录的 ISO 格式时间戳。如果未提供，则使用当前时间。 **时区说明**: 没有时区信息的時間将使用 `HUCKLEBERRY_TIMEZONE` 设置进行解释。 **示例**: - "记录 12.5 磅的体重和 24 英寸的身高" - "记录昨天的医生访视的体重测量值"（带有回顾性时间戳） #### `get_latest_growth` 获取儿童的最新生长测量值。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 **示例**: "最新的生长测量值是什么？" #### `get_growth_history` 获取儿童在指定日期范围内的生长测量历史（默认为最近 30 天）。 **参数**： - `child_uid`（字符串，必填）：儿童的唯一标识符 - `start_date`（字符串，可选）：开始日期，ISO 格式（YYYY-MM-DD），包含 - `end_date`（字符串，可选）：结束日期，ISO 格式（YYYY-MM-DD），排除（数据最多到但不包括此日期） **重要提示**: `end_date` 是独占的。要获取某一天的数据（例如，1 月 30 日），请设置 `start_date='2026-01-30'` 和 `end_date='2026-01-31'`。 **示例**: "显示我过去一个月的生长历史" ## 用法示例 配置好克劳德桌面后，您可以通过自然对话与服务器交互： 1. **列出您的孩子**： - "列出我的孩子" - "显示我所有的孩子" 2. **跟踪睡眠**： - "记录昨天下午 2 点到 4 点的睡眠会话"（直接记录） - "记录爱丽丝今天下午 1 点开始睡了 90 分钟"（直接记录） - "开始爱丽丝的睡眠会话"（实时计时器） - "爱丽丝正在睡觉" - "暂停睡眠计时器" - "爱丽丝醒了，完成睡眠会话" - "显示我上周的睡眠历史" 3. **跟踪喂养**： - "记录昨天下午 2 点到 2:30 的左侧母乳喂养"（直接记录） - "记录母乳喂养：左侧 10 分钟，右侧 15 分钟，从今天下午 3 点开始"（直接记录） - "开始左侧母乳喂养"（实时计时器） - "切换到右侧乳房" - "完成喂养会话" - "显示我今天的喂养记录" 4. **记录换尿布**： - "记录一次带有尿液和便便的换尿布" - "记录一个湿尿布" - "记录一个便便尿布，带有黄色便便和尿布疹" - "记录一个尿布更换，有中量便便和尿布疹" 5. **跟踪生长**： - "记录 12.5 磅的体重" - "记录体重 12.5 磅，身高 24 英寸，头围 16 英寸" - "最近的生长测量值是什么？" - "显示我过去一个月的生长历史" 6. **查看历史记录**： - "显示我上周的睡眠历史" - "今天有多少次换尿布？" - "显示我昨天的所有喂养记录" ## 开发 ### 项目结构 ``` src/huckleberry_mcp/ ├── server.py # FastMCP 服务器实例和工具注册 ├── auth.py # 身份验证处理（延迟单例模式） ├── utils.py # 共享实用程序（ISO 时间戳转换） └── tools/ # 工具实现 ├── children.py # 儿童管理工具 ├── sleep.py # 睡眠跟踪工具 ├── feeding.py # 喂养/母乳喂养工具 ├── diaper.py # 换尿布工具 └── growth.py # 生长测量工具 ``` ### 添加新工具 要添加新工具： 1. 将函数添加到 `tools/` 中的适当模块中 2. 用 `@mcp.tool()` 装饰 3. 添加全面的文档字符串（用于模式生成） 4. 对参数使用类型提示进行验证 5. 在 `server.py` 中注册，如果创建新模块 示例： ```python @mcp.tool() async def my_new_tool(child_uid: str, data: str) -> Dict[str, Any]: """工具描述。 参数： child_uid：儿童的唯一标识符 data：一些数据参数 返回： 状态消息和数据 """ api = await get_authenticated_api() # 实现... return {"success": True, "message": "Done"} ``` ### 运行测试 ```bash # 运行所有测试 uv run pytest tests/ -v # 运行特定测试文件 uv run pytest tests/test_sleep.py -v # 运行覆盖率测试 uv run pytest tests/ --cov=huckleberry_mcp --cov-report=html ``` ### 依赖项 - `fastmcp>=2.0.0,<3.0.0` - FastMCP 框架，用于 MCP 服务器实现 - `huckleberry-api>=0.1.0` - 哈克贝利 API 客户端库 - `python-dotenv>=1.0.0` - 环境变量管理 ## 实现说明 该服务器已完全重构，以匹配实际的 [py-huckleberry-api](https://github.com/Woyken/py-huckleberry-api) 库接口: - 所有历史记录方法内部使用 Unix 时间戳，并在 ISO 日期之间转换 - 计时器操作（睡眠/喂养）直接调用 API 方法，无需状态预检查 - 生长跟踪使用 `head` 参数代替 `head_circumference` - 换尿布记录包括数量字段（`pee_amount`、`poo_amount`），并使用 `color` 代替 `poo_color` - 服务器启动成功，即使凭证无效，在调用工具时返回有帮助的错误 ## 故障排除 ### 身份验证错误 如果您在调用工具时看到身份验证错误： 1. 验证克劳德桌面配置中的凭证是否正确 2. 确保您的哈克贝利账户处于活动状态，并且您可以通过应用程序登录 3. 检查时区是否有效（例如，“America/New_York”，“Europe/London”） 4. 服务器将启动成功，但在调用工具时进行身份验证 ### 克劳德桌面中未出现服务器 1. 验证操作系统的文件路径是否正确 2. 检查 `--directory` 路径是否为绝对路径且正确 3. 在 macOS 上使用 Anaconda 时，请使用 `uv` 的完整路径：`/Users/your-username/anaconda3/bin/uv` 4. 在配置更改后重启克劳德桌面 5. 检查克劳德桌面日志中的错误消息 6. 确保 `uv` 已安装且可访问 ### 服务器启动失败 如果您看到“进程生成失败：没有此类文件或目录”： 1. 未找到 `uv` 命令 - 指定 `uv` 可执行文件的完整路径 2. 在 macOS 上，使用 `which uv` 或检查 `/Users/your-username/anaconda3/bin/uv` 3. 更新配置中的 `command` 字段以使用绝对路径 ### 工具无法正常工作 1. 确保您已先列出孩子，以获取有效的儿童 UID 2. 使用工具时验证儿童 UID 是否正确 3. 可以在不检查状态的情况下启动/停止计时器会话 4. 查看错误消息以获取特定的验证问题（无效的颜色、数量等） ## 安全考虑 - 永远不要将 `.env` 文件或凭证提交到版本控制 - 仅在环境变量或克劳德桌面配置中存储凭证 - `.gitignore` 文件默认排除 `.env` 文件 - 服务器从不记录凭证 - 所有 API 通信都使用 HTTPS ## 贡献 这是个人项目，但欢迎提出建议和错误报告！ ## 许可证 MIT 许可证 - 参见 LICENSE 文件获取详细信息 ## 致谢 - 使用 [模型上下文协议](https://modelcontextprotocol.io/) 构建 - 使用 [py-huckleberry-api](https://github.com/Woyken/py-huckleberry-api) Python 库 - 由 Anthropic 的克劳德提供支持 ## 迁移历史 ### v0.2.0 - FastMCP 迁移（2026-01-31） 从原始 MCP SDK 迁移到 FastMCP 框架： - 将 `server.py` 从 442 行减少到 47 行 - 消除了手动模式定义（270+ 行） - 整合了重复的时间戳实用程序 - 保留延迟身份验证模式 - 保留所有现有功能 所有现有工具和功能对最终用户保持不变。 ## 支持 对于问题： - **此 MCP 服务器**：在此仓库中打开问题 - **哈克贝利 API 库**：参见 [py-huckleberry-api](https://github.com/Woyken/py-huckleberry-api) - **哈克贝利应用**：联系哈克贝利支持 - **克劳德桌面**：参见 [Anthropic 文档](https://docs.anthropic.com/)