honeybook-mcp: Instructions file for Claude Code

honeybook-mcp

MCP server for the HoneyBook client portal — view contracts & invoices from multiple vendors (each vendor = one captured session), with deep-link fallback for signing and paying.

Commands

npm run build        # tsc + esbuild bundle → dist/bundle.js
npm run bundle       # esbuild only (no tsc check)
npm test             # vitest run
npm run test:watch   # vitest in watch mode
npm run dev          # node --env-file=.env dist/index.js (requires built dist)

Architecture

src/
  index.ts               MCP server entry — registers tool modules, stdio transport
  client.ts              HoneyBookClient — per-session auth headers, fetch wrapper,
                         401 + 404/HBUnauthorizedError, 429, HBWrongAPIVersion
                         handling; getActiveClient() resolves
                         a session from sessionStore and caches a client per origin
  auth.ts                captureSessionViaFetchproxy() — one-shot @fetchproxy/bootstrap
                         call that reads localStorage["HONEYBOOK_REACT_CURR_USER"]
                         out of the user's signed-in portal tab, then closes the
                         bridge. See "Auth flow" below.
  flows.ts               Questionnaire ("flow") links: parseFlowLink /
                         isFlowLinkUrl / flowStorageKey, and the flowStore
                         (own file, ~/.honeybook-mcp/flows.json)
  flow-auth.ts           captureFlowCredentialViaFetchproxy() — same lift as
                         auth.ts, pointed at HONEYBOOK_REACT_WEAK_AUTH_<flowId>
  flow-client.ts         FlowClient — weak-auth headers over the shared
                         hbApiRequest; getActiveFlowClient(); plus
                         fetchFlowMinimal() + flowContextId(), the public
                         /minimal hop that yields the ctxc a flow read needs
  feed.ts                Workspace feed (GET /workspaces/<id>/feed): fetch,
                         message vs activity classification, compact
                         summarizers, calendar-item compaction (host link
                         stripped). Shared by messages, meetings tools
  pending-tasks.ts       runClientPendingTask(): POST /client_pending_task +
                         poll /client_pending_tasks?task_ids[]= until Finished.
                         The portal's write protocol (send_message uses it)
  sessions.ts            Thin adapter over the disk-persisted SessionStore from
                         @chrischall/mcp-utils/session (this repo was the donor it
                         was extracted from); re-exports normalizeOrigin and the
                         configured sessionStore singleton
  types.ts               HBListEnvelope<T>, ToolResult, CapturedSession, CapturedFlowCredential, FileType
  tools/
    sessions.ts          use_magic_link, list_active_sessions (both kinds)
    flows.ts             use_flow_link, get_flow
    workspace_files.ts   list_workspace_files, get_workspace_file (+ section
                         filtering + heavy-field pruning to keep responses small)
    workspaces.ts        get_workspace
    payment_methods.ts   list_payment_methods
    contracts.ts         sign_contract (deep-link fallback + confirm guard)
    invoices.ts          pay_invoice (deep-link fallback + confirm guard)
    projects.ts          list_projects (/client/events), get_project
                         (/events/<id>/details, trimmed of the vendor account blob)
    messages.ts          list_messages, get_message, send_message (confirm
                         guard + pending task), mark_messages_seen
    meetings.ts          list_meetings — folded out of feed calendar_item activity
    tasks.ts             list_tasks (/tasks/workspaces/<id> + /counts + /taskgroup)
    notes.ts             list_notes (/notes/workspace/<id>)
    attachments.ts       list_attachments (/workspaces/<id>/attachments)
    payments.ts          list_payments (/workspaces/<id>/payments, per-payment rows)