forkable-mcp CLAUDE.md

CLAUDE.md

Development guidance for forkable-mcp. User setup belongs in README.md; this file records implementation contracts that coding agents must preserve.

Runtime and layout

This is a Bun + TypeScript MCP server. The MCP client spawns it over stdio and owns its lifecycle. There is no HTTP server.

src/
  index.ts        CLI entry point
  server.ts       stdio lifecycle and keepalive
  tools.ts        MCP tools and Forkable request construction
  write-gate.ts   preview, confirmation, and mutation recovery
  net/            GraphQL transport and error mapping
  auth/           login, browser-cookie ingest, and session storage
  order/          domain types, selections, local guards, formatting, and status
tests/            Bun tests
scripts/smoke.ts  packed-install smoke test

The only durable runtime state is ~/.forkable-mcp/session.json (or FORKABLE_MCP_HOME/session.json). Pending confirmations are process-local and disappear on restart.

Keep one current MCP contract. Do not add legacy argument aliases, confirmation formats, session migrations, or response shims without a demonstrated need; agents can re-read tool schemas and adapt.

Authentication and session state

Forkable uses a Cookie header and CSRF token, not an API key. Sessions can come from email/password, an imported browser cookie, FORKABLE_COOKIE, or an auth file/stdin. Browser import uses @steipete/sweet-cookie on macOS, Linux, and Windows; Arc targeting is macOS-only, and Brave or Chromium on Linux or Windows may require an explicit profile path. Password input must remain hidden (--password-stdin or environment); never print credentials.

Session invariants:

• The store directory is mode 0700; the session file is atomically written with mode 0600.
• A usable session must contain a nonempty _easyorder_session cookie.
• Set-Cookie response deltas are merged into the latest stored Cookie header. Do not persist a client's full stale jar over newer rotations.
• In-process session writes are serialized. Cookie expiry and Max-Age are handled by auth/cookies.ts.
• CSRF and cookie persistence failure is nonfatal after the in-memory client has accepted the response; emit a concise stderr warning and do not replay a mutation.
• delegationSessionId: null is meaningful and must clear delegation rather than preserve an older value.
• Redacted logging may include lengths and metadata, never cookie, CSRF, password, or confirmation token contents.