MCP (Model Context Protocol) server that lets coding agents — Claude Code, Codex, Cursor — query the ChangeBook product memory (the module map and the analyzed change history from your ChangeBook account) instead of re-reading the codebase, plus a CLI that feeds that memory from any terminal: sign in, analyze uncommitted changes, sync the product map. All MCP tools are read-only, and every query is scoped to the signed-in user.

Two ways to run it

Local (npm): the CLI runs the MCP server on stdio — no server to host, works offline against your account. See Quick start below.

Hosted (HTTP, no install): point any client at the hosted endpoint with a Personal Access Token — nothing to install, just a URL:

claude mcp add --transport http changebook \
  https://mcp.changebook.app \
  --header "Authorization: Bearer <your-PAT>"

Generate the PAT in the web app (Account → Access tokens). The token is SHA-256-hashed server-side and revocable; every query is scoped to your account.

Quick start (local)

npx changebook init   # login (browser) + register in Claude Code/Codex + sync

init does four things: opens the browser so you sign in on changebook.app (one Authorize click — no token copy-pasting), registers the MCP server in every coding agent it finds on the machine — Claude Code, Codex, Cursor, Windsurf, Claude Desktop and VS Code (Copilot agent mode) — installs the git hooks (post-commit: the atlas updates itself; pre-commit: the signal guard warns before touching a module with an open alert), and writes the product map into the project's CLAUDE.md/AGENTS.md. It only touches agents that are actually installed, and merges into existing MCP configs without clobbering your other servers.

CLI commands

Command	What it does
`changebook login`	Browser sign-in; stores the session in `~/.changebook/credentials.json` (0600).
`changebook logout`	Forget the stored session.
`changebook analyze [dir]`	Analyze the repo's uncommitted changes (`git diff HEAD`) and update the atlas — same pipeline as the VS Code extension, no editor needed.
`changebook analyze --commit [ref]`	Analyze one commit. Deduped by hash server-side, so re-runs never bill.
`changebook hook install\|uninstall\|status [dir]`	Git hooks: every new commit is analyzed in the background (post-commit, never blocks), and the signal guard warns before you commit to a module with an open alert (pre-commit). One pair of hooks covers Claude Code, Codex and manual commits — they all commit through git.
`changebook hook-context install\|uninstall\|status [dir]`	Claude Code `SessionStart` hook: pushes the fresh atlas map into every session at turn 0 — no tool call to remember, and generated on the spot so it can't go stale. Writes to `.claude/settings.json`; running the command is the consent, and it refuses to touch a config it can't parse.
`changebook hook-impact install\|uninstall\|status [dir]`	Claude Code `PreToolUse` hook: before every edit, tells the agent which modules depend on the file it is about to touch, plus any open alert and repeat-offender history. Never blocks an edit, never touches the network on the critical path (reads a short-lived cache in `.git/` and refreshes it out of band), warns once per file per session, and stays silent when there is nothing to say.
`changebook impact` / `changebook context [dir]`	What those two hooks run. Both read from stdin/disk, print a JSON payload (or nothing) and always exit 0 — you don't call them by hand.
`changebook guard [dir]`	What the pre-commit hook runs: checks staged files against the atlas' open alerts. Warn-only and fail-open by default; `CHANGEBOOK_GUARD=block` makes findings abort the commit (bypass once with `git commit --no-verify`), `CHANGEBOOK_GUARD=off` silences it.
`changebook sync [dir]`	Refresh the product map inside `CLAUDE.md`/`AGENTS.md`.
`changebook init [dir]`	login + register MCP server + install hook + sync, in one go.
`changebook open`	Open the web atlas in the browser.
`changebook serve`	Run the MCP server on stdio (also the default with no arguments).

Every command also works as npx changebook <command> with no install.

MCP tools

Tool	What it does
`atlas_recent_changes`	Recent analyzed changes: business impact, tech summary, modules touched. Supports `limit`, `offset`, `search`.
`atlas_modules`	Aggregated module map: domain, category, risk, change count, last change, files. Optional `domain` filter.
`atlas_module_detail`	One module's history: impact, notes, files and verbatim diff excerpts.

Manual registration (instead of `init`)

claude mcp add --scope user changebook -- npx -y changebook serve

Or in the project's .mcp.json:

{
  "mcpServers": {
    "changebook": {
      "command": "npx",
      "args": ["-y", "changebook", "serve"]
    }
  }
}

Credentials come from changebook login (~/.changebook/credentials.json); the env vars below override them for CI/headless setups.

Environment variables

Variable	Default	Purpose
`CHANGEBOOK_REFRESH_TOKEN`	—	Session token override (CI/headless; wins over the credentials file).
`CHANGEBOOK_ACCESS_TOKEN`	—	Short-lived JWT; refreshed automatically when it expires.
`CHANGEBOOK_PROJECT`	—	Scope every query to one project (matched by slug, then exact name — usually the workspace folder name). Unset = all projects.
`CHANGEBOOK_WEB_URL`	`https://changebook.app`	Web app used by `login`/`open` and printed after `analyze`.

`sync`: product map inside CLAUDE.md / AGENTS.md

npx changebook sync [dir]

Writes (or refreshes, idempotently) an auto-generated section between  /  markers in the target directory's CLAUDE.md and AGENTS.md: the module map, the latest changes and a hint telling agents to use the atlas_* tools. Those files load into every Claude Code / Codex session and get prompt-cached, so the map orients agents at near-zero marginal cost. Content outside the markers is never touched. Re-run after analyzing changes (or wire it to a git hook).

Security notes

MCP tools are read-only; only analyze writes (through the same audited server endpoint as the extension, with the same quotas).
login uses a loopback-only handoff: the web app asks for an explicit Authorize click and redirects the tokens to http://127.0.0.1:<port> in the URL fragment — they never leave your machine, and a state nonce ties the handoff to the CLI process that requested it.
Your session lives in ~/.changebook/credentials.json (0600) — treat it like a password. changebook logout removes it.