mcp-client-kit 0.4.0__tar.gz → 0.6.0__tar.gz

{mcp_client_kit-0.4.0 → mcp_client_kit-0.6.0}/CHANGELOG.md

@@ -1,6 +1,90 @@
 # Changelog
 
-## [Unreleased] — 0.5.0
+## [Unreleased] — 0.7.0
+
+## [0.6.0] — 2026-08-24
+
+### Fixed
+
+- **A completed login was thrown away whenever the server failed right after it, turning a
+  transient outage into an endless browser re-prompt.** `login()` stashed the existing
+  credential, ran the OAuth flow, then smoke-tested the result with `initialize()` +
+  `list_tools()` — with the whole block under one `except BaseException` that restored the
+  stash. But the SDK's `OAuthClientProvider` saves the exchanged token from inside the auth
+  handshake, before `initialize()` returns, so any failure after that point rolled a valid
+  new token back to the stale one. A `502` from the resource server was indistinguishable
+  from "your login failed", and nothing was ever cached, so the next run re-prompted — one
+  reported batch produced 16 completed browser logins, all discarded, and no useful work.
+  The restore is now conditional: it fires only when the flow produced no token at all. When
+  a token *was* issued it is kept, together with the token endpoint needed to refresh it later,
+  and the failure surfaces as the new `PostLoginCheckFailed` rather than the raw transport
+  error. A login that fails *before* the token exchange — a cancelled consent screen, a
+  callback timeout — still restores the previous credential whole, `client_info` included:
+  pairing a freshly registered `client_id` with a refresh token the authorization server
+  issued to the *old* client would break the refresh the restore exists to preserve.
+
+- **Servers that publish no OAuth discovery document re-prompted at every token expiry.**
+  The token endpoint was cached only when discovery returned metadata, so for those servers
+  `login()` stored a token with no way to renew it, and the next pre-flight refresh had no
+  choice but to demand a new browser login — every hour, forever. The endpoint now comes from
+  the SDK's own resolution, which covers the no-discovery case with its `<origin>/token`
+  fallback, so the cached URL is the one that demonstrably just issued the token rather than a
+  guess.
+
+### Added
+
+- **`PostLoginCheckFailed`**, exported from `mcpgen`. The counterpart to
+  `ReauthenticationRequired`, and deliberately not named for a cause: the token was issued
+  and cached, which says nothing about whether the resource server accepted it. A `502` from
+  the origin, a post-login `401` over scope or audience, and an MCP-level error from
+  `list_tools()` all raise it; what they share is that another browser round cannot fix them.
+  Batch callers can now abort on the first failure instead of walking a user through one
+  browser prompt per item. `mcpgen login` reports it as a single `[login] error: …` line —
+  naming the underlying cause, which anyio otherwise hides behind "unhandled errors in a
+  TaskGroup (1 sub-exception)" — and exits `1`. User interrupts (`KeyboardInterrupt`,
+  `SystemExit`, cancellation) are never relabelled, even when a task group wraps them.
+
+### Changed
+
+- **Generated OAuth runners now stop on `PostLoginCheckFailed` instead of printing a
+  traceback.** The `generate-mcp-runner` skill's HTTP + OAuth template called `ensure_login()`
+  bare, so the one place mcpgen writes caller code did not demonstrate the contract it
+  documents. It now prints the message and exits `1` — the failure is not something a rerun,
+  or another trip through the browser, can clear.
+
+## [0.5.0] — 2026-08-09
+
+### Fixed
+
+- **A caller-supplied credentials path was silently ignored once past login, so tokens were
+  written to one file and read from another.** `login()` and `ensure_login()` accepted
+  `creds_path` and honoured it, but the call path never did: `_http_session()` built its
+  `FileTokenStorage` on the default `~/.mcpgen/credentials.json`, and neither `session()` nor
+  `McpBridgeCaller` even accepted the parameter, so there was no way to route a call to the file
+  the login had just written. Anyone keeping tokens outside the shared store — a project-local
+  credentials file, two identities side by side, a test fixture — logged in successfully and then
+  got `ReauthenticationRequired` on the very next call, in a loop, with both files on disk looking
+  plausible. `creds_path` now flows through `_http_session()`, `session()`, and
+  `McpBridgeCaller`, defaulting to `DEFAULT_CREDS_PATH` when omitted, so existing behaviour is
+  unchanged. The stdio, bearer, static-header, and raw-URL transports do not take it: they store
+  no credentials at all, and a parameter that silently does nothing is worse than its absence.
+
+### Added
+
+- **`--creds PATH`** on every command that touches stored credentials — `codegen`, `list`,
+  `probe`, `call`, `login`, and the management trio `list-creds`, `delete-creds`,
+  `migrate-creds` — the CLI surface for the fix above. `mcpgen login` previously dropped the
+  path entirely, having no flag to drop it from; it now logs in to exactly the file the
+  subsequent calls will read. The management commands were the other half of the same gap: all
+  three already took a `credentials_path` internally but exposed no way to set it, so after a
+  `--creds` login `list-creds` reported an empty store, `delete-creds` deleted nothing while
+  saying so, and `migrate-creds` migrated the wrong file. A flag that exists on half the
+  commands that read a file is worse than no flag at all — it makes the other half look broken.
+
+- **`DEFAULT_CREDS_PATH` is exported from `mcpgen`** — consumers that thread a credentials path
+  through their own CLI need the default as a value. Re-deriving
+  `Path.home() / ".mcpgen" / "credentials.json"` downstream would silently drift the day mcpgen
+  changes it.
 
 ## [0.4.0] — 2026-08-09
 

{mcp_client_kit-0.4.0 → mcp_client_kit-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: mcp-client-kit
-Version: 0.4.0
+Version: 0.6.0
 Summary: mcp-client-kit — generate typed Python wrappers for any MCP server (codegen skill + CLI).
 Project-URL: Homepage, https://github.com/svd/mcp-client-kit
 Project-URL: Source, https://github.com/svd/mcp-client-kit
@@ -26,7 +26,9 @@ Description-Content-Type: text/markdown
 
 **Write your MCP server wrappers once — from the live server. Keep them as real Python source you can diff, review, and pin.**
 
-`mcpgen` turns any MCP server into a typed Python module: one `async def` per tool, real return types, no live server needed to read it. Call your tools from code instead of pumping their schemas through the model's context — the pattern Anthropic measured at up to **98% token reduction**.
+`mcpgen` turns an MCP server reachable over **stdio or Streamable HTTP** into a Python module: one `async def` per tool, typed inputs from the start, and typed returns once you've probed the real responses. No live server needed to read it.
+
+`mcpgen` generates the Python wrapper layer for MCP code-mode architectures. Token savings occur when your agent or runtime executes these wrappers instead of loading the full MCP tool catalog into model context. `mcpgen` does not itself alter host tool registration and does not provide a sandbox.
 
 > **Package / repo / plugin:** `mcp-client-kit` · **CLI command:** `mcpgen`
 >
@@ -46,6 +48,8 @@ Every tool definition costs **300–600 tokens** for its name, description, and
 
 Anthropic's validated fix ("Code execution with MCP," Nov 2025): stop routing schemas through the model. Generate wrapper code and call the tools from code instead — an approach Anthropic measured shrinking one workflow from ~150,000 tokens to ~2,000 (**98.7%**), with independent benchmarks landing around **78–85%** on less extreme workloads.
 
+Those numbers describe **the pattern**, as reported by Anthropic and by third-party benchmarks — they are not a measurement of this CLI. mcpgen supplies one piece of that pattern: the wrapper layer. What you save depends on how your runtime uses it.
+
 The catch for Python teams: no good tool generated **standalone, importable, reviewable `.py` wrappers** from a live MCP server. So everyone hand-writes `jira.py`, `github.py`, `slack.py` — slowly, inconsistently, and they silently rot when the server changes.
 
 That's the gap mcpgen fills.
@@ -57,7 +61,7 @@ That's the gap mcpgen fills.
 ```bash
 uv tool install mcp-client-kit          # puts `mcpgen` on your PATH
 mcpgen login github                     # browser OAuth, tokens persisted
-mcpgen codegen github --out github.py   # typed wrappers for every tool
+mcpgen codegen github --out github.py   # one async def per tool, typed inputs
 ```
 
 ```python
@@ -74,31 +78,61 @@ async def main():
 asyncio.run(main())
 ```
 
+The `-> GitHubUser` return type above comes from the full lifecycle — probe the tool, shape the response, regenerate. Straight out of `codegen`, `get_me` takes the same typed arguments but returns `Any`. See [Lifecycle](#lifecycle).
+
 `github.py` is just Python. Open it in your IDE, review it in a PR, pin it to a commit, ship it. No runtime proxy, no framework lock-in, no live server required to read what your tools return.
 
+**One connection for a series of calls.** Each call opens its own session by default. Wrap a run in `connected()` and every call to a server shares one initialized session — one `initialize()`, one stdio subprocess, one OAuth pre-flight refresh:
+
+```python
+caller = McpBridgeCaller(url="https://api.githubcopilot.com/mcp/")
+
+async with caller.connected():
+    me = await github.get_me(caller)
+    issues = await github.list_issues(caller, owner="octocat", repo="hello-world")
+```
+
+Outside the block nothing changes, so existing code keeps working untouched. Details — per-server sessions, concurrency, cleanup — in [`doc/USAGE.md`](doc/USAGE.md#reusing-one-connection-for-a-series-of-calls).
+
 ---
 
 ## Why developers pick it
 
 **Real source you own.** Importable `.py` modules — not `.pyi` stubs (mcp2py), not a runtime proxy, not tied to one execution framework (ipybox). You can diff it, review it, pin it, and read it in your IDE without a server running.
 
-**Types that match reality.** A tool's `inputSchema` describes its *inputs* — it tells you nothing about the *output* shape. mcpgen's `--probe` makes one live call and records the actual response, so your return types reflect what the server really sends. No other generator does this.
+**Types that match reality.** A tool's `inputSchema` describes its *inputs* — it tells you nothing about the *output* shape, so `codegen` alone returns `Any`. mcpgen's `probe` makes a live call and records the actual response; you (or the skill) turn that observation into an output model, and regeneration bakes it in. Return types then reflect what the server really sends, not a guess. No other generator does this.
 
 **OAuth that survives restarts.** Pre-flight token refresh means a fresh process renews a near-expired token silently from the refresh token — no surprise browser pop-up at cold start. (The official SDK's canonical example is in-memory only; every restart re-authenticates.)
 
 **Swap auth without regenerating.** Every wrapper takes an `McpCaller` as its first argument. Change transports or auth backends — bearer, OAuth, stdio, a fake for tests — without touching the generated code.
 
-**Built for production teams.** Works with any MCP server (HTTP URL, stdio, or bearer/PAT). Generated code lives in git like any other module, so it survives code review, audits, and pinning.
+**Built for production teams.** Works with MCP servers reachable over **stdio or Streamable HTTP** (OAuth, bearer/PAT, or no auth). Generated code lives in git like any other module, so it survives code review, audits, and pinning.
 
 ---
 
-## How it works
+## What mcpgen does not do
 
-| Step | Command | What happens |
-|------|---------|--------------|
-| 1. Generate | `mcpgen codegen <server> --out <server>.py` | One typed `async def` per tool. |
-| 2. Probe (optional) | `mcpgen probe <server> <tool> --args '{}' --emit-shape <server>.shapes.json` | Records the *real* response shape from a live call. |
-| 3. Regenerate | `mcpgen codegen <server> --out <server>.py --shapes <server>.shapes.json` | Wrappers now return precise types (`TypedDict`s, unions, lists). |
+- It does not remove tool schemas from Claude Code or Cursor context — host tool registration is not mcpgen's to change.
+- It does not sandbox generated code. Generated wrappers are ordinary Python and run with your process's privileges.
+- It does not infer trustworthy output types from input schemas alone. Output types come from live probes plus a judgment pass (see the lifecycle below).
+- It does not speak SSE. SSE servers are surfaced by `mcpgen discover` but marked unsupported by this version.
+- It does not guarantee a remote server will stay stable. That is what `mcpgen check` is for.
+
+---
+
+## Lifecycle
+
+| Step | Command | Result |
+|------|---------|--------|
+| 1. Generate | `mcpgen codegen <server> --out <server>.py` | One `async def` per tool: typed inputs, `Any` return by default. |
+| 2. Probe | `mcpgen probe <server> <tool> --args '{}' --emit-shape <server>.shapes.json` | Observed response-shape skeleton, written as a per-tool part under `<server>.shapes.json.parts/`. |
+| 3. Merge | `mcpgen merge <server> --out <server>.shapes.json` | Consolidates the parts into the committed, hand-editable shape-spec. |
+| 4. Edit the shape-spec (or run the skill) | edit `<server>.shapes.json` | Output model and `unwrap` decisions — the judgment pass. |
+| 5. Regenerate | `mcpgen codegen <server> --out <server>.py --shapes <server>.shapes.json` | `TypedDict` returns, unions, lists, overloads. |
+
+Step 3 is not optional: `--emit-shape` writes only into `<server>.shapes.json.parts/`, so `<server>.shapes.json` does not exist until you merge.
+
+Typed input wrappers by default; empirically shaped output types after live probes. Steps 2–5 are optional as a group — skip them and you still get working wrappers, just with `Any` returns. Shaping is also per-tool: tools you never probe keep their `Any` return.
 
 Polymorphic tools — ones that return different shapes depending on an input (`entityType=1` → `Person`, `=2` → `Position`) — get typed `@overload`s, so your type checker narrows the return at every call site.
 
@@ -151,19 +185,63 @@ A companion skill, `generate-mcp-runner`, writes a standalone smoke-test `run.py
 
 | Command | What it does |
 |---------|--------------|
-| `codegen <server>` | Emit typed wrappers; `--shapes` applies the shape-spec, `--probe` records a response shape inline, `--embed-schema` embeds `fn.__schema__` + Args docstring per function. |
+| `codegen <server>` | Emit wrappers; `--shapes` applies the shape-spec, `--probe` records a response shape inline, `--embed-schema` embeds `fn.__schema__` + Args docstring per function. Also writes `<out-stem>.mcpgen.json` for `check`. |
+| `check <server>` | Compare the server's live tool inventory against the stored manifest. Exit `0` no drift, `1` drift, `2` operational error. |
 | `list <server>` | Print a server's tools as JSON; `--schema` adds raw `inputSchema` per tool. |
 | `probe <server> <tool>` | Live call(s) → response-shape skeleton. |
 | `call <server> <tool> --out <p>` | One live call, raw payload to disk — bootstrap ids or inspect output. |
 | `merge <server>` | Consolidate probe parts into `<server>.shapes.json`. |
 | `login <server>` | Browser OAuth login; tokens stored at `~/.mcpgen/credentials.json`. |
 | `migrate-creds` | Move stored OAuth tokens between `file` / `keyring` backends. |
-| `discover` | List MCP servers configured in your installed agent hosts. |
+| `discover` | List MCP servers configured in Claude Code. |
+
+`discover` reads Claude Code's configuration — the only host provider implemented today. `discovery.PROVIDERS` is the extension point where more hosts get added.
 
 Full workflow and flags: [`doc/USAGE.md`](doc/USAGE.md).
 
 ---
 
+## Drift detection
+
+`codegen` writes a deterministic, non-secret snapshot of the server's tool inventory
+beside the generated module:
+
+```bash
+mcpgen codegen demo --stdio 'python server.py' --out gen/demo.py
+# writes gen/demo.py and gen/demo.mcpgen.json
+```
+
+Commit both. In CI, verify the server still matches what you generated against:
+
+```bash
+mcpgen check demo --stdio 'python server.py' --manifest gen/demo.mcpgen.json
+```
+
+| Exit | Meaning |
+|---|---|
+| 0 | No drift. Description-only changes print as advisories and do not fail. |
+| 1 | Drift: a tool was added, removed, or its input schema or annotations changed. |
+| 2 | Operational error: manifest missing or unreadable, transport failure, auth failure. |
+
+Exit 2 is never drift, so a broken runner or an expired token cannot be misread as a
+changed tool contract. `--json` emits a structured report. `check` never calls a tool
+and never touches `<server>.shapes.json`.
+
+To accept the new inventory, ask for it explicitly — `check` never writes on its own:
+
+```bash
+mcpgen check demo --stdio 'python server.py' --manifest gen/demo.mcpgen.json --update
+```
+
+GitHub Actions:
+
+```yaml
+- name: Check MCP tool drift
+  run: mcpgen check demo --config .mcp.json --manifest gen/demo.mcpgen.json --json
+```
+
+---
+
 ## Authentication
 
 ```bash
@@ -194,7 +272,7 @@ If you write your agent logic in Python and want generated tool wrappers you can
 
 ## Status
 
-Early access (`v0.x`). The codegen engine, OAuth persistence, live-probe shaping, and both Claude Code skills are working today. On the roadmap: `--check` drift mode, so CI can flag when a server's tools change out from under your wrappers.
+Early access (`v0.x`). The codegen engine, OAuth persistence, live-probe shaping, tool-inventory drift detection (`mcpgen check`), and both Claude Code skills are working today. Transport support is stdio and Streamable HTTP; SSE is discovered but not implemented.
 
 ## License
 

{mcp_client_kit-0.4.0 → mcp_client_kit-0.6.0}/README.md

@@ -2,7 +2,9 @@
 
 **Write your MCP server wrappers once — from the live server. Keep them as real Python source you can diff, review, and pin.**
 
-`mcpgen` turns any MCP server into a typed Python module: one `async def` per tool, real return types, no live server needed to read it. Call your tools from code instead of pumping their schemas through the model's context — the pattern Anthropic measured at up to **98% token reduction**.
+`mcpgen` turns an MCP server reachable over **stdio or Streamable HTTP** into a Python module: one `async def` per tool, typed inputs from the start, and typed returns once you've probed the real responses. No live server needed to read it.
+
+`mcpgen` generates the Python wrapper layer for MCP code-mode architectures. Token savings occur when your agent or runtime executes these wrappers instead of loading the full MCP tool catalog into model context. `mcpgen` does not itself alter host tool registration and does not provide a sandbox.
 
 > **Package / repo / plugin:** `mcp-client-kit` · **CLI command:** `mcpgen`
 >
@@ -22,6 +24,8 @@ Every tool definition costs **300–600 tokens** for its name, description, and
 
 Anthropic's validated fix ("Code execution with MCP," Nov 2025): stop routing schemas through the model. Generate wrapper code and call the tools from code instead — an approach Anthropic measured shrinking one workflow from ~150,000 tokens to ~2,000 (**98.7%**), with independent benchmarks landing around **78–85%** on less extreme workloads.
 
+Those numbers describe **the pattern**, as reported by Anthropic and by third-party benchmarks — they are not a measurement of this CLI. mcpgen supplies one piece of that pattern: the wrapper layer. What you save depends on how your runtime uses it.
+
 The catch for Python teams: no good tool generated **standalone, importable, reviewable `.py` wrappers** from a live MCP server. So everyone hand-writes `jira.py`, `github.py`, `slack.py` — slowly, inconsistently, and they silently rot when the server changes.
 
 That's the gap mcpgen fills.
@@ -33,7 +37,7 @@ That's the gap mcpgen fills.
 ```bash
 uv tool install mcp-client-kit          # puts `mcpgen` on your PATH
 mcpgen login github                     # browser OAuth, tokens persisted
-mcpgen codegen github --out github.py   # typed wrappers for every tool
+mcpgen codegen github --out github.py   # one async def per tool, typed inputs
 ```
 
 ```python
@@ -50,31 +54,61 @@ async def main():
 asyncio.run(main())
 ```
 
+The `-> GitHubUser` return type above comes from the full lifecycle — probe the tool, shape the response, regenerate. Straight out of `codegen`, `get_me` takes the same typed arguments but returns `Any`. See [Lifecycle](#lifecycle).
+
 `github.py` is just Python. Open it in your IDE, review it in a PR, pin it to a commit, ship it. No runtime proxy, no framework lock-in, no live server required to read what your tools return.
 
+**One connection for a series of calls.** Each call opens its own session by default. Wrap a run in `connected()` and every call to a server shares one initialized session — one `initialize()`, one stdio subprocess, one OAuth pre-flight refresh:
+
+```python
+caller = McpBridgeCaller(url="https://api.githubcopilot.com/mcp/")
+
+async with caller.connected():
+    me = await github.get_me(caller)
+    issues = await github.list_issues(caller, owner="octocat", repo="hello-world")
+```
+
+Outside the block nothing changes, so existing code keeps working untouched. Details — per-server sessions, concurrency, cleanup — in [`doc/USAGE.md`](doc/USAGE.md#reusing-one-connection-for-a-series-of-calls).
+
 ---
 
 ## Why developers pick it
 
 **Real source you own.** Importable `.py` modules — not `.pyi` stubs (mcp2py), not a runtime proxy, not tied to one execution framework (ipybox). You can diff it, review it, pin it, and read it in your IDE without a server running.
 
-**Types that match reality.** A tool's `inputSchema` describes its *inputs* — it tells you nothing about the *output* shape. mcpgen's `--probe` makes one live call and records the actual response, so your return types reflect what the server really sends. No other generator does this.
+**Types that match reality.** A tool's `inputSchema` describes its *inputs* — it tells you nothing about the *output* shape, so `codegen` alone returns `Any`. mcpgen's `probe` makes a live call and records the actual response; you (or the skill) turn that observation into an output model, and regeneration bakes it in. Return types then reflect what the server really sends, not a guess. No other generator does this.
 
 **OAuth that survives restarts.** Pre-flight token refresh means a fresh process renews a near-expired token silently from the refresh token — no surprise browser pop-up at cold start. (The official SDK's canonical example is in-memory only; every restart re-authenticates.)
 
 **Swap auth without regenerating.** Every wrapper takes an `McpCaller` as its first argument. Change transports or auth backends — bearer, OAuth, stdio, a fake for tests — without touching the generated code.
 
-**Built for production teams.** Works with any MCP server (HTTP URL, stdio, or bearer/PAT). Generated code lives in git like any other module, so it survives code review, audits, and pinning.
+**Built for production teams.** Works with MCP servers reachable over **stdio or Streamable HTTP** (OAuth, bearer/PAT, or no auth). Generated code lives in git like any other module, so it survives code review, audits, and pinning.
 
 ---
 
-## How it works
+## What mcpgen does not do
 
-| Step | Command | What happens |
-|------|---------|--------------|
-| 1. Generate | `mcpgen codegen <server> --out <server>.py` | One typed `async def` per tool. |
-| 2. Probe (optional) | `mcpgen probe <server> <tool> --args '{}' --emit-shape <server>.shapes.json` | Records the *real* response shape from a live call. |
-| 3. Regenerate | `mcpgen codegen <server> --out <server>.py --shapes <server>.shapes.json` | Wrappers now return precise types (`TypedDict`s, unions, lists). |
+- It does not remove tool schemas from Claude Code or Cursor context — host tool registration is not mcpgen's to change.
+- It does not sandbox generated code. Generated wrappers are ordinary Python and run with your process's privileges.
+- It does not infer trustworthy output types from input schemas alone. Output types come from live probes plus a judgment pass (see the lifecycle below).
+- It does not speak SSE. SSE servers are surfaced by `mcpgen discover` but marked unsupported by this version.
+- It does not guarantee a remote server will stay stable. That is what `mcpgen check` is for.
+
+---
+
+## Lifecycle
+
+| Step | Command | Result |
+|------|---------|--------|
+| 1. Generate | `mcpgen codegen <server> --out <server>.py` | One `async def` per tool: typed inputs, `Any` return by default. |
+| 2. Probe | `mcpgen probe <server> <tool> --args '{}' --emit-shape <server>.shapes.json` | Observed response-shape skeleton, written as a per-tool part under `<server>.shapes.json.parts/`. |
+| 3. Merge | `mcpgen merge <server> --out <server>.shapes.json` | Consolidates the parts into the committed, hand-editable shape-spec. |
+| 4. Edit the shape-spec (or run the skill) | edit `<server>.shapes.json` | Output model and `unwrap` decisions — the judgment pass. |
+| 5. Regenerate | `mcpgen codegen <server> --out <server>.py --shapes <server>.shapes.json` | `TypedDict` returns, unions, lists, overloads. |
+
+Step 3 is not optional: `--emit-shape` writes only into `<server>.shapes.json.parts/`, so `<server>.shapes.json` does not exist until you merge.
+
+Typed input wrappers by default; empirically shaped output types after live probes. Steps 2–5 are optional as a group — skip them and you still get working wrappers, just with `Any` returns. Shaping is also per-tool: tools you never probe keep their `Any` return.
 
 Polymorphic tools — ones that return different shapes depending on an input (`entityType=1` → `Person`, `=2` → `Position`) — get typed `@overload`s, so your type checker narrows the return at every call site.
 
@@ -127,19 +161,63 @@ A companion skill, `generate-mcp-runner`, writes a standalone smoke-test `run.py
 
 | Command | What it does |
 |---------|--------------|
-| `codegen <server>` | Emit typed wrappers; `--shapes` applies the shape-spec, `--probe` records a response shape inline, `--embed-schema` embeds `fn.__schema__` + Args docstring per function. |
+| `codegen <server>` | Emit wrappers; `--shapes` applies the shape-spec, `--probe` records a response shape inline, `--embed-schema` embeds `fn.__schema__` + Args docstring per function. Also writes `<out-stem>.mcpgen.json` for `check`. |
+| `check <server>` | Compare the server's live tool inventory against the stored manifest. Exit `0` no drift, `1` drift, `2` operational error. |
 | `list <server>` | Print a server's tools as JSON; `--schema` adds raw `inputSchema` per tool. |
 | `probe <server> <tool>` | Live call(s) → response-shape skeleton. |
 | `call <server> <tool> --out <p>` | One live call, raw payload to disk — bootstrap ids or inspect output. |
 | `merge <server>` | Consolidate probe parts into `<server>.shapes.json`. |
 | `login <server>` | Browser OAuth login; tokens stored at `~/.mcpgen/credentials.json`. |
 | `migrate-creds` | Move stored OAuth tokens between `file` / `keyring` backends. |
-| `discover` | List MCP servers configured in your installed agent hosts. |
+| `discover` | List MCP servers configured in Claude Code. |
+
+`discover` reads Claude Code's configuration — the only host provider implemented today. `discovery.PROVIDERS` is the extension point where more hosts get added.
 
 Full workflow and flags: [`doc/USAGE.md`](doc/USAGE.md).
 
 ---
 
+## Drift detection
+
+`codegen` writes a deterministic, non-secret snapshot of the server's tool inventory
+beside the generated module:
+
+```bash
+mcpgen codegen demo --stdio 'python server.py' --out gen/demo.py
+# writes gen/demo.py and gen/demo.mcpgen.json
+```
+
+Commit both. In CI, verify the server still matches what you generated against:
+
+```bash
+mcpgen check demo --stdio 'python server.py' --manifest gen/demo.mcpgen.json
+```
+
+| Exit | Meaning |
+|---|---|
+| 0 | No drift. Description-only changes print as advisories and do not fail. |
+| 1 | Drift: a tool was added, removed, or its input schema or annotations changed. |
+| 2 | Operational error: manifest missing or unreadable, transport failure, auth failure. |
+
+Exit 2 is never drift, so a broken runner or an expired token cannot be misread as a
+changed tool contract. `--json` emits a structured report. `check` never calls a tool
+and never touches `<server>.shapes.json`.
+
+To accept the new inventory, ask for it explicitly — `check` never writes on its own:
+
+```bash
+mcpgen check demo --stdio 'python server.py' --manifest gen/demo.mcpgen.json --update
+```
+
+GitHub Actions:
+
+```yaml
+- name: Check MCP tool drift
+  run: mcpgen check demo --config .mcp.json --manifest gen/demo.mcpgen.json --json
+```
+
+---
+
 ## Authentication
 
 ```bash
@@ -170,7 +248,7 @@ If you write your agent logic in Python and want generated tool wrappers you can
 
 ## Status
 
-Early access (`v0.x`). The codegen engine, OAuth persistence, live-probe shaping, and both Claude Code skills are working today. On the roadmap: `--check` drift mode, so CI can flag when a server's tools change out from under your wrappers.
+Early access (`v0.x`). The codegen engine, OAuth persistence, live-probe shaping, tool-inventory drift detection (`mcpgen check`), and both Claude Code skills are working today. Transport support is stdio and Streamable HTTP; SSE is discovered but not implemented.
 
 ## License