mcp-client-kit 0.3.0__tar.gz → 0.5.0__tar.gz

mcp_client_kit-0.5.0/CHANGELOG.md

@@ -0,0 +1,188 @@
+# Changelog
+
+## [Unreleased] — 0.6.0
+
+## [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
+
+### Added
+
+- **Headless OAuth login — `mcpgen login <server> --headless`** — logging in no longer requires
+  a browser on the machine running the command. Instead of opening a browser and binding a local
+  callback server, mcpgen prints the authorization URL to stderr, you authorize on any device,
+  and paste the resulting callback URL back on stdin. This is the only workable flow inside
+  containers, over SSH, and in CI, where `webbrowser.open()` silently does nothing and the
+  callback port is unreachable from wherever the browser actually runs. The redirect URI
+  registered in headless mode is port-less (`http://localhost/callback`) — nothing ever fetches
+  it, and keeping it free of an ephemeral port makes the registered value stable across runs for
+  servers that pin `redirect_uris`. Without the flag mcpgen auto-detects: macOS and Windows are
+  always treated as interactive, other platforms are headless when neither `DISPLAY` nor
+  `WAYLAND_DISPLAY` is set. `MCPGEN_HEADLESS=1`/`0` overrides the detection in either direction
+  for environments that guess wrong; an explicit `--headless`/`--no-headless` outranks both.
+
+- **`mcpgen login --callback-timeout SECONDS`** — the 300-second bound on the browser redirect
+  is a guess about how long a consent screen plus MFA takes, and guesses about human latency are
+  wrong for someone: a hardware-token or approve-on-phone flow can outlast it, while a scripted
+  login wants to fail fast. The flag sets that bound per invocation, `0` restores the original
+  unbounded wait as an escape hatch, and anything negative or non-numeric is rejected by argparse
+  with a usage message rather than surfacing as a traceback from inside asyncio. The same value
+  is available in code as `callback_timeout=` on `login()`, `ensure_login()`, and
+  `ensure_login_all()`. Headless logins ignore it — the pasted-URL prompt is never bounded.
+
+- **`ensure_login_all(servers)`** — pre-flight refresh-or-login across several servers in one
+  call, for pipelines that talk to more than one MCP server and want every token settled before
+  work starts. Deliberately sequential: concurrent logins would open several browser tabs at
+  once and, in headless mode, race each other for stdin. Servers with a valid cached token stay
+  silent, so the steady-state cost is zero.
+
+### Fixed
+
+- **An authorization denial in the browser flow now fails with the same clear error as the
+  headless flow.** The local callback server extracted only `code` and `state` and ignored
+  `error`/`error_description`, so declining consent resolved the callback to `(None, None)` and
+  surfaced later as an opaque downstream failure. Both callback paths now share one parser,
+  which raises `ValueError: OAuth authorization failed: <error> — <description>` at the point of
+  failure.
+
+- **`mcpgen login` no longer hangs forever when the browser never comes back.** The error-redirect
+  fix above only helps when the authorization server actually redirects; real ones often don't —
+  cancel the consent screen and the tab simply closes, so no request ever reaches the local
+  callback server and the wait never ends. The interactive flow now bounds that wait at 300s
+  (`_CALLBACK_TIMEOUT`) and raises `TimeoutError` explaining that the browser never returned,
+  with a pointer to `--headless` for pasting the redirect URL by hand. The timeout cancels the
+  pending callback future, so the background server task shuts down cleanly, and it unwinds
+  through the same restore path as any other login failure — a timed-out attempt leaves a
+  previously-working credential intact. Headless logins are deliberately unbounded: a human
+  pasting a URL may take arbitrarily long.
+
+## [0.3.0] — 2026-07-14
+
+### Fixed
+
+- **`mcpgen login` — OAuth token exchange failed with `400 invalid_request`** on authorization
+  servers that strictly enforce RFC 6749 §2.3 (`"Client must not use multiple authentication
+  methods"`). Dynamic client registration omitted `token_endpoint_auth_method`, so the server
+  defaulted us to `client_secret_basic` and issued a `client_secret`; the MCP SDK then sent an
+  `Authorization: Basic` header *and* `client_id` in the form body — two client authentication
+  methods in one request. mcpgen now registers as a public client
+  (`token_endpoint_auth_method: "none"`), which is the correct posture for a distributed CLI
+  (RFC 8252 §8.4) and is fully secured by the PKCE (S256) the SDK already performs on every
+  authorization code grant. No security regression: the discarded `client_secret` was issued
+  per-install by dynamic registration and stored in the same `credentials.json` as the refresh
+  token, so anyone who could read the secret could already read the token — it never added a
+  layer of defense.
+
+- **Discriminated-union codegen mistyped `string` discriminators with numeric-looking
+  enum values as `int`.** Discriminator type was inferred solely by sniffing whether
+  shape-spec variant keys looked numeric (e.g. `"1"`, `"2"`), so a genuinely
+  `type: "string"` discriminator with those enum values got a wrong `int` `Literal`
+  in the generated `@overload` stubs. Discriminator type is now resolved from an
+  explicit `input_overrides` entry, then the tool's declared `inputSchema` type,
+  and only falls back to key-sniffing when neither is available.
+
+- **`mcpgen call`/`probe` crashed on `resource_link` content items** — real MCP SDK
+  `ResourceLink.uri` is a pydantic `AnyUrl`, not `str`; `json.dumps` on the summarized
+  content raised `TypeError`. The summary now coerces `uri` to `str`.
+
+- **`mcpgen probe` reported inflated payload sizes for non-ASCII content** — size was
+  measured as the character count of `json.dumps`'s default `ensure_ascii=True`
+  output, which escapes every non-ASCII character to a `\uXXXX` sequence. Size is
+  now measured as real UTF-8 byte length.
+
+## [0.2.0] — 2026-06-20
+
+### Added
+
+- **`mcpgen list --schema`** — include raw `inputSchema` JSON per tool in list output.
+  Useful for inspecting required params and enum constraints without a separate probe.
+
+- **`mcpgen codegen --embed-schema`** — embed `fn.__schema__ = {<inputSchema>}` on each
+  generated function, plus an Args docstring section (per-param description, enum values,
+  default). Enables introspection at runtime (`mod.get_issue.__schema__`) and richer IDE
+  hover docs.
+
+- **Enum params → `Literal[...]`** (default, no flag) — `py_type()` now maps JSON Schema
+  `enum` arrays to `Literal[v1, v2, ...]` instead of bare `str`/`int`. Applies to direct
+  enum params and array items (`list[Literal[...]]`). Static analysis and call-site type
+  narrowing work without any extra configuration.
+
+## [0.1.0] — initial release
+
+### Added
+
+- **`mcpgen codegen`** — generate typed async Python wrappers from a live MCP server's
+  `tools/list`. Every tool becomes an `async def` typed from `inputSchema`; returns `Any`
+  by default (shape-spec refines to `TypedDict`).
+
+- **Shape-spec sidecar** (`<server>.shapes.json`) — hand-editable file driving typed
+  return models. Fields: `unwrap` (key path), `return_model` (TypedDict name), `fields`,
+  `input_overrides`, `overloads`. Intermediate probe parts land in `.parts/` until `merge`.
+
+- **Discriminator detection + overloads** — `mcpgen list` / `probe` emit a stderr advisory
+  when a param is shared across ≥2 tools (polymorphic-suspect). Codegen emits one
+  `@overload` per discriminator variant (`Literal[<val>]`) plus a union impl.
+
+- **`mcpgen list`** — print all tools on a server as JSON `[{name, description}]`.
+  Includes discriminator advisory on stderr.
+
+- **`mcpgen probe`** — live call(s) → response-shape skeleton. Writes per-probe
+  intermediates to `.parts/` for later merge.
+
+- **`mcpgen merge`** — consolidate `.parts/` into `<server>.shapes.json`; emits a
+  gitignored `verify.json` sidecar with pre-scrub `probed_args`.
+
+- **`mcpgen call`** — single live call, raw payload written to disk; useful for
+  bootstrapping ids and inspecting raw output.
+
+- **`mcpgen discover`** — enumerate MCP servers configured in installed agent hosts
+  (reads Claude Code CLI / `~/.claude.json`).
+
+- **`mcpgen login`** — browser OAuth login; tokens stored at
+  `~/.mcpgen/credentials.json` (chmod 0600) or OS keychain via `--cred-backend keyring`.
+
+- **`mcpgen migrate-creds`** — move stored OAuth tokens between `file` / `keyring`
+  backends.
+
+- **`mcpgen list-creds` / `delete-creds`** — inspect and remove stored credentials.
+
+- **Transport flags** — `--stdio` (launch command), `--url` (HTTP), `--bearer` (PAT),
+  `--config` (config-file server resolution); shared across `codegen`/`list`/`probe`/`call`/`login`.
+
+- **`generate-mcp-wrappers` plugin skill** — agent skill that drives the full
+  probe → shape-spec → codegen workflow interactively.
+
+- **`generate-mcp-runner` plugin skill** — agent skill for building typed runner
+  scripts on top of generated wrappers.

{mcp_client_kit-0.3.0 → mcp_client_kit-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-client-kit
-Version: 0.3.0
+Version: 0.5.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
@@ -168,11 +168,14 @@ Full workflow and flags: [`doc/USAGE.md`](doc/USAGE.md).
 
 ```bash
 mcpgen login <server>                              # OAuth (most servers)
+mcpgen login <server> --headless                   # no browser: print URL, paste callback URL back
 mcpgen codegen <server> --bearer "$TOKEN" --out s.py  # PAT / bearer
 mcpgen codegen <server> --stdio "python server.py" --out s.py  # local stdio, no auth
 ```
 
-Tokens persist in `~/.mcpgen/credentials.json` (chmod 0600) or your OS keystore via `--cred-backend keyring`. In code, `ensure_login(server, url=...)` refreshes silently and only opens a browser when a real login is required.
+Tokens persist in `~/.mcpgen/credentials.json` (chmod 0600) or your OS keystore via `--cred-backend keyring`. In code, `ensure_login(server, url=...)` refreshes silently and only opens a browser when a real login is required; `ensure_login_all([...])` does the same for several servers, one at a time.
+
+In containers, over SSH, or in CI there is no browser to open. `--headless` prints the authorization URL, you authorize on any device, and paste the callback URL back on stdin. It is auto-detected when neither `DISPLAY` nor `WAYLAND_DISPLAY` is set (never on macOS or Windows); `MCPGEN_HEADLESS=1`/`0` overrides the detection, and `--headless`/`--no-headless` overrides both.
 
 ---
 

{mcp_client_kit-0.3.0 → mcp_client_kit-0.5.0}/README.md

@@ -144,11 +144,14 @@ Full workflow and flags: [`doc/USAGE.md`](doc/USAGE.md).
 
 ```bash
 mcpgen login <server>                              # OAuth (most servers)
+mcpgen login <server> --headless                   # no browser: print URL, paste callback URL back
 mcpgen codegen <server> --bearer "$TOKEN" --out s.py  # PAT / bearer
 mcpgen codegen <server> --stdio "python server.py" --out s.py  # local stdio, no auth
 ```
 
-Tokens persist in `~/.mcpgen/credentials.json` (chmod 0600) or your OS keystore via `--cred-backend keyring`. In code, `ensure_login(server, url=...)` refreshes silently and only opens a browser when a real login is required.
+Tokens persist in `~/.mcpgen/credentials.json` (chmod 0600) or your OS keystore via `--cred-backend keyring`. In code, `ensure_login(server, url=...)` refreshes silently and only opens a browser when a real login is required; `ensure_login_all([...])` does the same for several servers, one at a time.
+
+In containers, over SSH, or in CI there is no browser to open. `--headless` prints the authorization URL, you authorize on any device, and paste the callback URL back on stdin. It is auto-detected when neither `DISPLAY` nor `WAYLAND_DISPLAY` is set (never on macOS or Windows); `MCPGEN_HEADLESS=1`/`0` overrides the detection, and `--headless`/`--no-headless` overrides both.
 
 ---
 

{mcp_client_kit-0.3.0 → mcp_client_kit-0.5.0}/doc/USAGE.md

@@ -79,14 +79,18 @@ uv add mcp-client-kit            # or: pip install mcp-client-kit
 | `probe <server> <tool>` | Live call(s) → shape skeleton | `--args` (repeatable), `--emit-shape <path>` (writes `.parts/`) |
 | `call <server> <tool>` | One live call, raw payload to disk — bootstrap ids / inspect output | `--out <path>` (required) |
 | `merge <server>` | Consolidate `.parts/` → `<server>.shapes.json`; emit gitignored `verify.json` | `--out <path>` |
-| `login <server>` | Browser OAuth login | connection flags below |
-| `migrate-creds` | Copy stored OAuth tokens between `file`/`keyring` backends | `--from`, `--to`, `--servers`, `--purge`, `--set-default` |
+| `login <server>` | Browser OAuth login | `--headless` / `--no-headless`, `--callback-timeout <seconds>`, connection flags below |
+| `migrate-creds` | Copy stored OAuth tokens between `file`/`keyring` backends | `--from`, `--to`, `--servers`, `--purge`, `--set-default`, `--creds <path>` |
 | `discover` | List servers from agent hosts | `--host <id>` (repeatable), `--json` |
 
 Connection flags shared by `codegen`/`list`/`probe`/`call`/`login`: `--url`,
-`--bearer`, `--stdio`, `--config`, `--client-name`, `--cred-backend`
+`--bearer`, `--stdio`, `--config`, `--client-name`, `--cred-backend`, `--creds`
 (see [§ Authenticate](#authenticate)).
 
+`--creds` is also accepted by the credential-management commands — `list-creds`,
+`delete-creds`, `migrate-creds` — so a non-default store stays addressable from every
+command that reads or writes it.
+
 > **PII:** `call` writes the raw, unscrubbed payload. Name the file `*.probe-raw.json`
 > (gitignored) and never commit it.
 
@@ -138,6 +142,47 @@ mcpgen login myserver   # opens browser; token stored at ~/.mcpgen/credentials.j
 
 Re-run when you see `ReauthenticationRequired`.
 
+The browser flow waits up to 300 seconds for the redirect. If you cancel on the consent
+screen, many authorization servers just close the tab without redirecting back, so mcpgen
+never hears anything — the wait then ends with `TimeoutError` instead of hanging. Your
+existing credential is left untouched by a failed or timed-out attempt.
+
+Adjust the bound when the default doesn't fit — a hardware token or an approve-on-phone
+step can outlast it, and a scripted login may want to fail sooner:
+
+```bash
+mcpgen login myserver --callback-timeout 900   # 15 minutes
+mcpgen login myserver --callback-timeout 0     # wait forever (no bound)
+```
+
+Negative or non-numeric values are rejected outright. Headless logins ignore the flag —
+the pasted-URL prompt is never bounded. In code, the same value is `callback_timeout=` on
+`login()`, `ensure_login()`, and `ensure_login_all()`.
+
+**No browser available (container, SSH, CI):**
+
+```bash
+mcpgen login myserver --headless
+```
+
+mcpgen prints the authorization URL instead of opening it, and waits:
+
+```
+Open this URL in your browser:
+
+https://auth.example.com/authorize?response_type=code&client_id=…
+
+After authorizing, paste the full callback URL here (http://localhost.../callback?code=...):
+```
+
+Authorize on any device, then copy the URL from the browser's address bar — the page
+itself will fail to load, which is expected, nothing is listening on that address — and
+paste it at the prompt.
+
+Headless mode is auto-detected when neither `DISPLAY` nor `WAYLAND_DISPLAY` is set (macOS
+and Windows are always treated as interactive). Set `MCPGEN_HEADLESS=1` or `0` to override
+the detection; an explicit `--headless` / `--no-headless` overrides both.
+
 **PAT / Bearer token:**
 
 ```bash
@@ -169,6 +214,23 @@ by `--cred-backend`, then `$MCPGEN_CRED_BACKEND`, then `~/.mcpgen/config.json`
 mcpgen login myserver --cred-backend keyring
 ```
 
+**Credential file location:** `--creds PATH` moves the `file` backend off
+`~/.mcpgen/credentials.json` — useful to keep one project's tokens out of the shared
+store, or to run two identities side by side. Pass the same path to every command
+that touches those tokens; a login written to one file is invisible to a call reading
+another:
+
+```bash
+mcpgen login myserver --creds ./.mcp-creds.json
+mcpgen call myserver whoami --creds ./.mcp-creds.json --out out.json
+mcpgen list-creds --creds ./.mcp-creds.json
+```
+
+The flag has no effect with `--bearer` or `--stdio`, which store no credentials. In
+code the same value is `creds_path=` on `login()`, `ensure_login()`,
+`ensure_login_all()`, `session()`, and `McpBridgeCaller(...)`; `mcpgen.DEFAULT_CREDS_PATH`
+is exported as the default.
+
 **Validate keyring storage** — confirm the token landed in the OS keystore, not the
 fallback file (service `mcpgen`, username `credentials`):
 
@@ -323,6 +385,10 @@ How it works:
   absent), it falls back to a full browser login — the in-code equivalent of
   `mcpgen login <server>`. Credentials are persisted at
   `~/.mcpgen/credentials.json`.
+- **Several servers at once** — `await ensure_login_all(["a", "b"])` runs the same
+  refresh-or-login for each name in turn. Sequential on purpose: parallel logins would
+  open several browser tabs at once and race for stdin in headless mode. Both functions
+  accept `headless=True`/`False` to force the paste-the-URL or browser flow explicitly.
 - **Lower-level alternative** — skip `ensure_login` and catch
   `ReauthenticationRequired` from the first failing `.call()`, then call
   `login(SERVER, url=URL)` and retry. `ReauthenticationRequired` and `login` are

{mcp_client_kit-0.3.0 → mcp_client_kit-0.5.0}/mcpgen/__init__.py

@@ -1,10 +1,12 @@
 """mcpgen: typed Python wrapper generator for MCP servers."""
 
 from mcpgen._bridge import (
+    DEFAULT_CREDS_PATH,
     McpBridgeCaller,
     ReauthenticationRequired,
     delete_cred,
     ensure_login,
+    ensure_login_all,
     list_creds,
     login,
     migrate_creds,
@@ -12,11 +14,13 @@ from mcpgen._bridge import (
 from mcpgen.seam import McpCaller
 
 __all__ = [
+    "DEFAULT_CREDS_PATH",
     "McpBridgeCaller",
     "McpCaller",
     "ReauthenticationRequired",
     "delete_cred",
     "ensure_login",
+    "ensure_login_all",
     "list_creds",
     "login",
     "migrate_creds",