Huckleberry Mcp

Huckleberry MCP 服务

面向 Claude、Cursor、VS Code 和其他 AI 助手的非官方 Huckleberry 婴儿追踪器 MCP 服务。查询和记录宝宝的睡眠、喂养、尿布、吸奶、辅食、如厕和成长记录。

将 Huckleberry 的数据（睡眠、喂养、成长、尿布、辅食）直接提供给 Claude Desktop，或将 MCP 服务集成到其他 AI 应用中。

安装

要求

• Node.js 24+（与 CI 一致；参见 .nvmrc）
• npm 9+

快速开始

npm install -g node-huckleberry-mcp

或者通过 npx 直接使用：

npx node-huckleberry-mcp

从源码安装

git clone https://github.com/KenLSM/node-huckleberry-mcp.git
cd node-huckleberry-mcp
npm install
npm run build
node dist/index.js

配置

环境变量

服务从环境变量中读取凭据：

[email protected]
HUCKLEBERRY_PASSWORD=your-password
HUCKLEBERRY_TIMEZONE=America/New_York

在项目根目录中创建 .env 文件（模板参见 .env.example）：

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

**注意：**切勿将 .env 提交到版本控制中。.gitignore 已将其排除。

Claude Desktop 集成

若要将此服务与 Claude Desktop 配合使用，请将其添加到 claude_desktop_config.json：

macOS/Linux： ~/.config/Claude/claude_desktop_config.json
Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "huckleberry": {
      "command": "npx",
      "args": ["node-huckleberry-mcp"],
      "env": {
        "HUCKLEBERRY_EMAIL": "[email protected]",
        "HUCKLEBERRY_PASSWORD": "your-password",
        "HUCKLEBERRY_TIMEZONE": "America/New_York"
      }
    }
  }
}

更新配置后，重启 Claude Desktop。Huckleberry 工具将显示在工具列表中。

工具

该服务提供 6 个类别共 29 个工具。（不支持活动中的睡眠/喂养计时器——start_sleep、pause_feeding 等；请使用明确的 log_* 工具记录已完成的事件。）

儿童管理（2 个）

工具	输入	输出
get_user	—	用户资料 + 儿童 UID 列表
get_child	child_uid	儿童资料（childsName、gender、birthdate）

睡眠（4 个）

工具	输入	用途
log_sleep	child_uid、start、end（epoch s）、notes?	记录已完成的睡眠时段
get_sleep_history	child_uid、limit?	最近的睡眠时段（含 id）
edit_sleep	child_uid、interval_id，以及 start/duration/notes 中的任意项	编辑已有的睡眠记录
delete_sleep	child_uid、interval_id	永久删除睡眠记录

喂养（10）

工具	输入	用途
log_nursing	child_uid、start、left_duration?、right_duration?、last_side?、notes?	记录一次母乳喂养
log_bottle	child_uid、start、amount、bottle_type、units、notes?	记录一次奶瓶喂养
log_solids	child_uid、start、notes?	记录一次辅食喂养
log_pump	child_uid、start、left_amount/right_amount 或 total_amount、units、duration?、notes?	记录一次吸奶
list_pump_intervals	child_uid、limit?	最近的吸奶记录（含 id）
get_feed_history	child_uid、limit?	最近的喂养记录（含 id），按时间从新到旧排列
edit_feed	child_uid、interval_id，以及以下任意字段：start/amount/bottle_type/units/left_duration/right_duration/last_side/notes	编辑已有的喂养记录
edit_pump	child_uid、interval_id，以及以下任意字段：start/left_amount/right_amount/units/duration/notes	编辑已有的吸奶记录
delete_feed	child_uid、interval_id	永久删除喂养记录
delete_pump	child_uid、interval_id	永久删除吸奶记录

尿布（5）

color 和 consistency 限定为一组固定值 （yellow/brown/green/black/red/white/orange/other； hard/normal/soft/runny/watery/formed/mucousy），以防无法识别的值导致 Huckleberry 应用在记录该条目时崩溃。关于这组值的选取方式，请参阅 TASKS.md → BUG2 — 该组值沿用了旧版移植内容，尚未在实际环境中确认。

工具	输入	用途
log_diaper	child_uid, mode (pee/poo/both/dry), start, color?, consistency?, pee_amount?, poo_amount?, notes?	记录一次换尿布
log_potty	child_uid, mode (pee/poo), start, notes?	记录如厕训练活动
get_diaper_history	child_uid, limit?	尿布 + 如厕历史记录（含 id）
edit_diaper	child_uid, interval_id, + any of start/mode/color/consistency/pee_amount/poo_amount/notes	编辑现有的尿布/如厕记录
delete_diaper	child_uid, interval_id	永久删除尿布/如厕记录

生长（5）

工具	输入	用途
log_growth	child_uid, weight?, height?, head?, units? (metric/imperial), start?, notes?	记录一项生长测量
get_latest_growth	child_uid	最近一次生长测量（含 id）
get_growth_history	child_uid, limit?	生长历史记录（含 id）
edit_growth	child_uid, entry_id, + any of start/weight/height/head/units/notes	编辑现有的生长测量
delete_growth	child_uid, entry_id	永久删除生长测量

固体食物 — 自定义食物（3）

工具	输入	用途
list_curated_foods	—	获取精选食物数据库
list_custom_foods	child_uid	列出某个孩子的自定义食物
create_custom_food	child_uid、name、category?、allergens?、notes?	创建自定义食物条目

所有 start/end 输入均为 Unix 纪元秒数。时间会使用根据 HUCKLEBERRY_TIMEZONE 推导的时区 offset 存储。

每个 log_* 工具都接受可选的自由文本字段 notes，该字段会存储在条目中， 并由对应的历史记录/get_* 工具返回（每个读取的条目都包含其 Firestore id）。 edit_* 工具（edit_sleep、edit_feed、edit_pump、edit_diaper、edit_growth）会更新 现有条目的 notes 和其他字段；delete_* 工具则会删除条目。两者都需要使用 对应读取操作返回的 id/interval_id/entry_id。删除操作不会重新计算跟踪器的 prefs.last* 摘要，因此在下次写入之前，“最近一次”视图可能会短暂显示已删除的条目。

提示词

服务器还会提供 MCP 提示词（在支持提示词的客户端中以斜杠命令形式使用的模板）：huckleberry_usage（加载使用约定）、daily_summary（date?）和 log_event（event）。

Agent 技能

skills/huckleberry/SKILL.md 会教助手如何正确使用这些工具（解析孩子、将自然语言时间转换为 Unix 纪元秒数、使用单位、写入前确认）。将其复制到 Claude 技能目录，即可让 MCP 更易于使用。

开发

脚本

npm run build            # TypeScript → JavaScript (tsc)
npm run lint             # Lint with oxlint
npm run lint:fix         # Lint and auto-fix
npm run format           # Format with oxfmt
npm run format:check     # Check formatting without changes
npm test                 # Run unit tests (Vitest)
npm run test:watch       # Watch mode for tests
npm run test:integration # Live tests (needs HUCKLEBERRY_* creds; skipped otherwise). Read-only by default; set HUCKLEBERRY_ALLOW_WRITES=1 to also run the log_*→delete write round-trip (test account only)
npm run inspect:schema   # Dump real Firestore shapes (needs creds) — see docs/integration-testing.md
npm run smoke            # Build + run the MCP server smoke test
npm run dev              # Run in dev mode (tsx)

工具链

• TypeScript 5.3+，启用严格模式
• oxc（oxlint + oxfmt）——快速的 Rust lint 和格式化工具
• Vitest ——单元测试运行器
• Zod ——运行时数据验证
• Firebase JS SDK ——Firestore + Auth

架构

src/
├── auth/            # Authentication (T1.1)
├── client/          # Huckleberry API operations (T1.2–T1.9)
├── models/          # Zod schemas for Firestore docs (T1.3)
├── server/          # MCP server framework (T2.1–T2.2)
├── tools/           # MCP tool implementations (T2.3–T2.8)
├── __tests__/       # Unit & smoke tests
└── index.ts         # Entry point

架构详情和约定请参阅 AGENTS.md。

测试

单元测试位于 src/__tests__/，使用 Vitest 并模拟 Firebase：

npm test

运行单个测试文件：

npm test -- models.test.ts

监视模式：

npm run test:watch

实时集成测试（受条件控制）会使用真实账户进行验证，没有凭据时会跳过。默认情况下为只读；仅当设置 HUCKLEBERRY_ALLOW_WRITES=1 时，才会选择性运行 log_*→删除的写入往返测试（请使用测试账户）——详见 docs/integration-testing.md：

# read-only schema validation
HUCKLEBERRY_EMAIL=… HUCKLEBERRY_PASSWORD=… npm run test:integration

# also exercise log_*→delete writes (test account only)
HUCKLEBERRY_EMAIL=… HUCKLEBERRY_PASSWORD=… HUCKLEBERRY_ALLOW_WRITES=1 npm run test:integration

许可与归属

本项目是以下两个采用 MIT 许可证的项目的 Node.js 移植版：

• py-huckleberry-api © 2025 Woyken（GitHub，MIT License）
• py-huckleberry-mcp © 2026 Huckleberry MCP Contributors（GitHub，MIT License）

此移植版大量采用了这两个上游项目的设计和实现。

安全与隐私

• 不会在本地存储数据。 所有操作均为经过身份验证的读写操作，目标是你的 Huckleberry Firestore 数据库。
• 凭据通过环境变量配置。 切勿提交 .env 或将凭据硬编码。
• 这是第三方服务的非官方客户端；其 API 是通过逆向工程得出的，可能会发生变化。

支持

• **文档：**贡献指南请参阅 AGENTS.md。
• **问题：**请在 GitHub Issues 上报告错误或请求新功能。
• **上游：**有关 Huckleberry 数据或 API 更改的问题，请参阅原始 Python 项目。

---

本项目以 ❤️ 为爱打造，是 py-huckleberry-api 和 py-huckleberry-mcp 的 Node/TypeScript 移植版。