Huckleberry Mcp

Huckleberry MCP サーバー

Claude、Cursor、VS Code、その他の AI アシスタント向けの、非公式のHuckleberry baby tracker 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、および 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、および 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 入力はエポック秒です。時刻は 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）があります。

エージェントスキル

skills/huckleberry/SKILL.md では、これらのツールを正しく使用する方法（子どもの特定、自然言語の時刻からエポック秒への変換、単位、 書き込み前の確認）をアシスタントに説明しています。MCP をよりスムーズに使えるよう、Claude のスキルディレクトリにコピーしてください。

開発

スクリプト

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+（strict モード）
• oxc（oxlint + oxfmt）— 高速な Rust ベースのリンティングとフォーマット
• 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__/ にあり、Firebase をモックして Vitest で実行します。

npm test

単一のテストファイルを実行する場合：

npm test -- models.test.ts

ウォッチモード：

npm run test:watch

ライブ統合テスト（条件付き）では実際のアカウントに対して検証を行い、認証情報がない場合はスキップされます。デフォルトでは読み取り専用です。オプトインの log_*→削除の書き込みラウンドトリップは、HUCKLEBERRY_ALLOW_WRITES=1 の場合にのみ実行されます（テスト用アカウントを使用してください） — 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 ライセンスの 2 つのプロジェクトを 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 に移植したプロジェクトです。❤️ を込めて開発しました。