huckleberry-mcp-worker

A Model Context Protocol server for the Huckleberry baby-tracking app, running as a Cloudflare Worker.

This is a TypeScript port of bckenstler/py-huckleberry-mcp. The original is a Python stdio server that talks to Firestore through google-cloud-firestore, which speaks gRPC and therefore cannot run on Workers. This port reaches the same backend over the Firebase REST API using fetch, and serves MCP over Streamable HTTP.

The practical difference: it is always on. No laptop has to be awake for a client to log a nap.

Tools

All 23 tools from the Python server are implemented, plus delete_record.

Every history tool reports each record's interval_id, which is what delete_record takes.

Fixes relative to the Python server

Four defects were found while porting and are corrected here.

Breastfeeding durations were written in the wrong unit. The backend stores leftDuration / rightDuration in seconds — that is what the app's own timer writes — but log_breastfeeding passed the caller's minutes straight through. Logging a 5 minute feed recorded 5 seconds. Callers previously had to pass 300 to mean 5 minutes; here left_duration_minutes: 5 means five minutes.

Single-day history queries returned nothing. Both ends of a date range were resolved to midnight, so start_date == end_date produced an empty window and the server reported no records for a day that had plenty. Ranges are now half-open [start_of_start_date, start_of_end_date + 1 day), making both ends inclusive.

end_time in sleep history was always null. The code read an end field that the backend never writes. It is now derived from start + duration.

birth_date in list_children was always null. The backend field is birthdate; the server read birthDate.

get_feeding_history also now returns each record's mode, plus the details that go with it: amount and type for bottles, food names and reactions for solids. Without them a solids record is an empty row, indistinguishable from a zero-length nursing session — which is exactly how a perfectly good record gets mistaken for a missing one.

Setup

Requires Node 18+ and a Cloudflare account.

npm install
npx wrangler login

Set the secrets — they are stored encrypted by Cloudflare and never live in the repository:

npx wrangler secret put HUCKLEBERRY_EMAIL
npx wrangler secret put HUCKLEBERRY_PASSWORD
npx wrangler secret put MCP_AUTH_TOKEN     # a long random string you generate
npx wrangler secret put HUCKLEBERRY_TIMEZONE   # e.g. America/Sao_Paulo

HUCKLEBERRY_TIMEZONE defaults to America/New_York. It decides how naive datetimes like "2026-08-17T15:47:00" are interpreted, so setting it correctly matters.

Deploy:

npm run deploy

Authentication

The Worker URL is public, and the server holds credentials to a child's health record, so every request must carry the bearer token:

Authorization: Bearer <MCP_AUTH_TOKEN>

Requests without a valid token get a 401 before any Huckleberry call is made. Generate a token with something like openssl rand -base64 32.

Clients that cannot send headers

Some MCP clients accept only a URL — claude.ai custom connectors, for one, take a URL and optional OAuth credentials with no field for Authorization. For those, the server also accepts the token as the last path segment:

POST https://<your-worker>.workers.dev/mcp/<MCP_URL_TOKEN>

MCP_URL_TOKEN is a separate secret from MCP_AUTH_TOKEN, and deliberately so: request paths end up in access logs, browser history, and referrers in a way headers do not. Keeping them apart means a leak through a URL does not compromise the header credential, and either can be rotated on its own. If MCP_URL_TOKEN is unset the route falls back to MCP_AUTH_TOKEN, which is convenient but gives up that separation.

npx wrangler secret put MCP_URL_TOKEN

Prefer the header route wherever the client supports it.

Client configuration

For Claude Code:

claude mcp add --transport http huckleberry https://<your-worker>.workers.dev/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Local development

cp .dev.vars.example .dev.vars   # then fill it in; .dev.vars is gitignored
npm run dev

curl -X POST http://localhost:8787/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Design notes

Stateless. Each request builds a fresh McpServer via createMcpHandler from Cloudflare's agents SDK. No Durable Objects and no session storage are involved, because every tool is a self-contained read or write.

Token caching. Firebase ID tokens last an hour and are cached in module scope, so requests landing on a warm isolate skip re-authentication. A cold isolate costs one extra round trip. A token rejected mid-flight triggers one re-authentication and retry.

Numeric types. Firestore distinguishes integers from doubles, and the app writes some fields as one and some as the other. Values that must be stored as doubles are wrapped in dbl() so records written here match records written by the app.

Multi-entry documents. History lives in two shapes: ordinary documents with a top-level start, and batch documents holding many entries under data. Nested starts cannot be filtered server-side, so batch documents are fetched whole and filtered in the Worker. Records report which shape they came from via is_multi_entry.

Deleting records

The Python server had no delete, and the received wisdom was that the backend did not allow one. It does: a DELETE on the document path returns 200. What was actually missing was the record's id, which the history tools never reported.

So history tools now return interval_id, and delete_record removes the record it names. Batched entries — several records packed into one document under data — are addressed as <documentId>#<entryKey> and removed as a field of their parent.

Deleting also repoints prefs.last* at the newest surviving record. The app reads those pointers directly, so a delete without the repoint leaves it showing a record that no longer exists.

Known limitations

• Deletes are permanent. There is no undo. Confirm with a history query before calling delete_record.

• Solids are read-only. get_feeding_history reports solids entries with their food names and reactions, but there is no tool to create one.

• start_sleep does not guard against an already-running timer. The Python server documented that it would fail in that case but never checked; the behaviour is preserved here rather than silently changed.

• Notes do not round-trip into sleep records. The details field is a fixed structure of checkboxes, not free text.

License

MIT