Huckleberry MCP Server

Неофициальный MCP-сервер для трекера младенцев Huckleberry для Claude, Cursor, VS Code и других ИИ-ассистентов. Запрашивайте и записывайте данные о сне, кормлении, подгузниках, сцеживании, прикорме, приучении к горшку и росте ребенка.

Предоставляйте данные Huckleberry (сон, кормление, рост, подгузники, прикорм) напрямую в Claude Desktop или интегрируйте MCP-сервер в другие ИИ-приложения.

Установка

Требования

• 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

Related MCP server: whoop-ai-mcp

Конфигурация

Переменные окружения

Сервер считывает учетные данные из переменных окружения:

HUCKLEBERRY_EMAIL=you@example.com
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": "you@example.com",
        "HUCKLEBERRY_PASSWORD": "your-password",
        "HUCKLEBERRY_TIMEZONE": "America/New_York"
      }
    }
  }
}

После обновления конфигурации перезапустите Claude Desktop. Инструменты Huckleberry появятся в списке инструментов.

Инструменты

Сервер предоставляет 29 инструментов в 6 категориях. (Таймеры активных сессий сна/кормления — start_sleep, pause_feeding и т. д. — не реализованы; используйте явные инструменты log_* для записи завершенных событий.)

Управление ребенком (2)

Сон (4)

Кормление (10)

Подгузники (5)

color и consistency ограничены фиксированным набором значений (желтый/коричневый/зеленый/черный/красный/белый/оранжевый/другой; твердый/нормальный/мягкий/жидкий/водянистый/оформленный/слизистый), чтобы предотвратить сбой приложения Huckleberry из-за нераспознанного значения на этой записи. См. TASKS.md → BUG2 о том, как был выбран набор — заимствован из устаревшего порта, еще не подтвержден вживую.

Рост (5)

Прикорм — пользовательские продукты (3)

Все входные данные start/end — это секунды эпохи. Время сохраняется с смещением часового пояса offset, полученным из HUCKLEBERRY_TIMEZONE.

Каждый инструмент 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 обучает ассистента правильному использованию этих инструментов (определение ребенка, преобразование времени из естественного языка в секунды эпохи, единицы измерения, подтверждение перед записью). Скопируйте его в каталог навыков 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

• 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

Живая интеграция (ограниченная) проверяет работу с реальной учетной записью и пропускается без учетных данных. По умолчанию она только для чтения; дополнительный цикл записи log_*→delete выполняется только с 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

Лицензирование и атрибуция

Этот проект — порт на Node.js двух проектов под лицензией MIT:

• py-huckleberry-api © 2025 Woyken (GitHub, Лицензия MIT)

• py-huckleberry-mcp © 2026 Huckleberry MCP Contributors (GitHub, Лицензия MIT)

Этот порт включает значительный дизайн и реализацию из обоих вышеуказанных проектов.

Безопасность и конфиденциальность

• Данные не хранятся локально. Все операции — это аутентифицированные чтения/записи в вашу базу данных Huckleberry Firestore.

• Учетные данные основаны на переменных окружения. Никогда не коммитьте .env и не хардкодьте учетные данные.

• Это неофициальный клиент стороннего сервиса; API был реконструирован и может измениться.

Поддержка

• Документация: См. AGENTS.md для руководства для участников.

• Проблемы: Сообщайте об ошибках или запрашивайте функции на GitHub Issues.

• Вышестоящий проект: По вопросам о данных Huckleberry или изменениях API см. оригинальные проекты на Python.

Создано с ❤️ как Node/TypeScript порт py-huckleberry-api и py-huckleberry-mcp.