Huckleberry MCP 서버

Huckleberry 아기 트래커의 비공식 MCP 서버로, Claude, Cursor, VS Code 및 기타 AI 어시스턴트에서 사용할 수 있습니다. 아기의 수면, 수유, 기저귀, 유축, 이유식, 배변 훈련, 성장 기록을 조회하고 기록할 수 있습니다.

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

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 도구가 도구 목록에 나타납니다.

도구

서버는 6개 카테고리에 걸쳐 29개의 도구를 제공합니다. (활성 세션 수면/수유 타이머 — start_sleep, pause_feeding 등 — 는 구현되지 않았습니다. 완료된 이벤트를 기록하려면 명시적인 log_* 도구를 사용하세요.)

자녀 관리 (2)

수면 (4)

수유 (10)

기저귀 (5)

color와 consistency는 고정된 값 집합으로 제한됩니다 (yellow/brown/green/black/red/white/orange/other; hard/normal/soft/runny/watery/formed/mucousy) — 인식되지 않은 값이 해당 항목에서 Huckleberry 앱을 충돌시키는 것을 방지하기 위함입니다. 집합이 어떻게 선택되었는지는 TASKS.md → BUG2를 참조하세요 — 레거시 포트에서 채택되었으며 아직 실시간으로 확인되지 않았습니다.

성장 (5)

이유식 — 맞춤 음식 (3)

모든 start/end 입력은 epoch 초입니다. 시간은 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는 어시스턴트가 이러한 도구를 올바르게 사용하는 방법을 가르칩니다 (자녀 해석, 자연어 시간 → epoch 초, 단위, 쓰기 전 확인). 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+ (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 라이선스 프로젝트의 Node.js 포트입니다:

• py-huckleberry-api © 2025 Woyken (GitHub, MIT License)

• py-huckleberry-mcp © 2026 Huckleberry MCP Contributors (GitHub, MIT License)

이 포트는 두 업스트림 프로젝트의 상당한 설계 및 구현을 포함합니다.

안전 및 개인정보 보호

• 로컬에 데이터가 저장되지 않습니다. 모든 작업은 Huckleberry Firestore 데이터베이스에 대한 인증된 읽기/쓰기입니다.

• 자격 증명은 환경 기반입니다. .env를 커밋하거나 자격 증명을 하드코딩하지 마세요.

• 이는 제3자 서비스의 비공식 클라이언트입니다. API는 리버스 엔지니어링되었으며 변경될 수 있습니다.

지원

• 문서: 기여자 지침은 AGENTS.md를 참조하세요.

• 이슈: 버그를 보고하거나 기능을 요청하려면 GitHub Issues를 사용하세요.

• 업스트림: Huckleberry 데이터 또는 API 변경에 대한 질문은 원래 Python 프로젝트를 참조하세요.

❤️로 제작된 py-huckleberry-api 및 py-huckleberry-mcp의 Node/TypeScript 포트입니다.