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

mcp_client_kit-0.3.0/.claude/skills/releasing-a-version/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: releasing-a-version
+description: Use when releasing, cutting, or shipping a new version of mcp-client-kit — publishing to PyPI, bumping the version for release, or tagging vX.Y.Z / plugin-vX.Y.Z. Covers the engine (PyPI) and plugin-only (marketplace) flows, including the dev-branch dev0→stable→PR→tag→minor+dev sequence.
+---
+
+# Releasing a version
+
+Two artifacts ship from one repo. Full rationale in `doc/DISTRIBUTION.md`.
+
+| Artifact | Version file | Tag form | Fires PyPI | Tag branch |
+|---|---|---|---|---|
+| **engine** | `pyproject.toml` | `vX.Y.Z` | yes | `main` |
+| **plugin** | `.claude-plugin/plugin.json` | `plugin-vX.Y.Z` | no | `main` |
+
+**Pick the flow:**
+- `mcpgen/**` code changed → **Engine release**
+- Skill/docs/SKILL.md only → **Plugin-only release**
+- Both changed → run Engine release first (it implicitly bumps the product too)
+
+---
+
+## Engine release
+
+Run from the `dev` branch.
+
+**1. Precheck**
+```bash
+git checkout dev && git pull
+git status          # must be clean
+gh pr checks        # CI green
+```
+`CHANGELOG.md` must have a `## [Unreleased] — X.Y.Z` entry ready. If not, add one.
+
+**2. Bump to stable**
+```bash
+uv version --bump stable --dry-run   # preview: 0.2.0.dev0 => 0.2.0
+uv version --bump stable             # writes pyproject.toml + uv.lock
+```
+
+**3. Finalize CHANGELOG**
+Change the unreleased header to a dated release header, e.g.:
+```
+## [Unreleased] — 0.2.0
+```
+→
+```
+## [0.2.0] — 2026-06-20
+```
+Add a new blank `## [Unreleased] — 0.3.0` placeholder at the top (you'll fill it during the post-release step).
+
+**4. Commit + PR → main**
+```bash
+git add pyproject.toml uv.lock CHANGELOG.md
+git commit -m "release: engine v0.2.0"
+git push origin dev
+gh pr create --base main --title "release: engine v0.2.0"
+# merge the PR (squash or merge commit)
+```
+
+**5. Tag on main**
+```bash
+git checkout main && git pull
+git tag v0.2.0
+git push --tags   # bare v* tag triggers publish.yml → PyPI
+```
+`publish.yml` asserts the tag (minus `v`) matches `pyproject.toml version` — if they differ the job fails. Fix by ensuring step 2 ran on the same commit.
+
+**6. Re-advance dev**
+```bash
+git checkout dev
+uv version --bump minor              # 0.2.0 → 0.3.0
+uv version --bump dev                # 0.3.0 → 0.3.0.dev0
+# Add fresh unreleased section to CHANGELOG if not already there:
+# ## [Unreleased] — 0.3.0
+git add pyproject.toml uv.lock CHANGELOG.md
+git commit -m "chore: bump version to 0.3.0.dev0"
+git push origin dev
+```
+
+---
+
+## Plugin-only release
+
+Use when only skill files, SKILL.md, or docs changed — no engine code.
+
+**1. Bump plugin product version on dev**
+
+Files to update:
+- `.claude-plugin/plugin.json` → `"version"` field
+- `.claude-plugin/marketplace.json` → `"plugins"[0]["version"]` field only  
+  *(leave top-level `"version"` — that's the catalog version, bumped only when the catalog listing itself changes, not per plugin release)*
+
+Optionally raise the version floor in `skills/generate-mcp-wrappers/SKILL.md` — but only if the skill now requires a CLI feature from a newer engine. Two coupled spots:
+- Line with `mcpgen >= X.Y.Z` in the prose
+- `min=X.Y.Z` in the bash version check below it
+
+**2. Commit + PR → main**
+```bash
+git add .claude-plugin/
+git commit -m "release: plugin v0.1.1 (engine unchanged 0.2.0)"
+git push origin dev
+gh pr create --base main --title "release: plugin v0.1.1"
+# merge the PR
+```
+
+**3. Tag on main**
+```bash
+git checkout main && git pull
+git tag plugin-v0.1.1
+git push origin plugin-v0.1.1   # plugin-v* does NOT trigger PyPI publish
+```
+
+**4. Update the marketplace entry**
+In the `svd-agent-skills` marketplace repo, bump the `mcp-client-kit` entry's `ref` to `plugin-v0.1.1`. This points consumers at the stable `main` tag, not a dev pre-release.
+
+---
+
+## Common mistakes
+
+| Mistake | Effect |
+|---|---|
+| Tag on `dev` instead of `main` | Marketplace/PyPI points at a dev pre-release |
+| Tag version ≠ `pyproject.toml` version | `publish.yml` fails the tag-vs-version assertion |
+| Skip step 6 (re-advance dev) | dev stays at release version, no `.dev0` signal |
+| Bump `pyproject.toml` for plugin-only | Triggers unnecessary PyPI republish |
+| Bump `marketplace.json` top-level `version` for every plugin release | Top-level is catalog metadata, not plugin version — leave it unless the catalog listing changed |
+| Raise SKILL.md floor preemptively | Floor should only move when the skill actually needs the new engine feature |

mcp_client_kit-0.3.0/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+## [Unreleased] — 0.4.0
+
+## [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/CLAUDE.md

@@ -0,0 +1,86 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Setup (once)
+uv venv && uv pip install -e .
+
+# Tests
+uv run pytest                          # all tests
+uv run pytest tests/test_codegen.py    # single file
+uv run pytest -k "test_name"           # single test
+
+# Lint / type-check
+uv run ruff check mcpgen/
+uv run mypy
+
+# Build dist
+uv build
+
+# Run CLI from clone (no install)
+.venv/bin/mcpgen codegen <server> --out <server>.py
+```
+
+## Architecture
+
+Four layers, strict one-way dependency:
+
+```
+CLI (cli.py)
+  └── Bridge (_bridge.py)     ← auth, transport, live MCP sessions
+  └── Codegen (codegen.py)    ← pure functions: JSON Schema → Python source
+  └── Discovery (discovery.py)← pure enumeration of host-configured servers
+Generated wrappers (.py files)
+  └── Seam (seam.py)          ← McpCaller Protocol only; no concrete client
+```
+
+**`seam.py`** — the only thing generated wrappers import from this package. A single `McpCaller` Protocol (`async def call(server, tool, arguments) → Any`). Changing it breaks all generated files.
+
+**`codegen.py`** — pure functions (no I/O). `render_module()` takes tool dicts + optional shape-spec and emits Python source. `summarize_shape()` converts a live response to a shape skeleton. `merge_skeletons()` merges multiple probe skeletons into one.
+
+**`_bridge.py`** — all async/network code. `McpBridgeCaller` implements `McpCaller`. `session()` is the `asynccontextmanager` for raw MCP sessions. Contains OAuth pre-flight refresh logic (critical — see module docstring; bounded to `mcp<2` because SDK `_initialize` never calls `update_token_expiry`).
+
+**`discovery.py`** — sync, no network. Reads Claude Code CLI / `~/.claude.json` to enumerate configured MCP servers.
+
+**`cli.py`** — thin argparse wiring over the above. Each `_cmd_*` function maps to a subcommand.
+
+## Shape-spec sidecar
+
+`<server>.shapes.json` is the hand-editable file that drives typed codegen. Key fields per tool entry: `unwrap` (key path to unwrap), `return_model` (TypedDict name), `fields` (field → Python type), `input_overrides`, `overloads`. The `.parts/` directory holds per-probe intermediates until `mcpgen merge` consolidates them.
+
+## Running the skill locally
+
+```bash
+KIT=~/src/mcp-client-kit
+PATH="$KIT/.venv/bin:$PATH" claude --plugin-dir "$KIT"
+```
+
+The skill is `/mcp-client-kit:generate-mcp-wrappers`. It requires `mcpgen` on PATH.
+
+## Server config
+
+`servers.example.json` → copy to `servers.json` (or set `$MCPGEN_SERVERS`). Config is `{"mcpServers": {"name": {"type": "http", "url": "..."}}}` — same shape as Claude Code's MCP config.
+
+## Credentials
+
+Stored at `~/.mcpgen/credentials.json` (chmod 0600) or OS keychain via `--cred-backend keyring`. `migrate-creds` moves between backends.
+
+## Versioning & release
+
+Two artifacts, independent versions — see `doc/DISTRIBUTION.md` for full spec.
+
+| Artifact | Tag form | Source of truth | Effect |
+|---|---|---|---|
+| engine (CLI) | `vX.Y.Z` | `pyproject.toml` | triggers PyPI publish |
+| plugin (skill) | `plugin-vX.Y.Z` | `.claude-plugin/plugin.json` + `marketplace.json` | marketplace ref only, no publish |
+
+```bash
+# Plugin-only release (skill/SKILL.md change, no engine code change)
+git tag plugin-vX.Y.Z origin/main   # tag on main after PR merge
+git push origin plugin-vX.Y.Z
+
+# Engine release — see doc/DISTRIBUTION.md:108 (fires PyPI publish workflow)
+```

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-client-kit
-Version: 0.0.4
+Version: 0.3.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
@@ -151,8 +151,8 @@ 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. |
-| `list <server>` | Print a server's tools as JSON. |
+| `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. |
+| `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`. |

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

@@ -127,8 +127,8 @@ 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. |
-| `list <server>` | Print a server's tools as JSON. |
+| `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. |
+| `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`. |

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

@@ -74,8 +74,8 @@ uv add mcp-client-kit            # or: pip install mcp-client-kit
 
 | Command | Purpose | Key flags |
 |---------|---------|-----------|
-| `codegen <server>` | Emit typed wrappers | `--out`, `--shapes <path>`, `--probe <tool>` / `--probe-args` |
-| `list <server>` | Tools as JSON `[{name, description}]`; discriminator advisory on stderr | — |
+| `codegen <server>` | Emit typed wrappers | `--out`, `--shapes <path>`, `--probe <tool>` / `--probe-args`, `--embed-schema` |
+| `list <server>` | Tools as JSON `[{name, description}]` (add `--schema` for `inputSchema` per tool); discriminator advisory on stderr | `--schema` |
 | `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>` |
@@ -420,6 +420,15 @@ Caveats: the discriminator is **always required** (even if the tool schema marks
 it optional). An unmodeled discriminator value hits the `int` impl and returns the
 union — it never raises.
 
+### Enum params → `Literal[...]`
+
+Any input param whose `inputSchema` carries an `enum` array is automatically typed as
+`Literal[<v1>, <v2>, ...]` — no flag required. This applies to all scalar enums
+(string, int, …). Use `mcpgen list <server> --schema` to inspect the raw `enum` arrays
+before generating. Do not widen enum params to `str` in your calling code; if the server
+accepts values outside the declared enum, the appropriate fix is to update the shape-spec
+`input_overrides` for that param rather than loosening the call site.
+
 ---
 
 ## Troubleshooting

{mcp_client_kit-0.0.4 → mcp_client_kit-0.3.0}/mcpgen/_bridge.py

@@ -58,7 +58,7 @@ from urllib.parse import parse_qs, urlparse
 
 import httpx
 from mcp import ClientSession
-from mcp.client.auth import OAuthClientProvider, TokenStorage
+from mcp.client.auth import OAuthClientProvider, OAuthRegistrationError, TokenStorage
 from mcp.client.stdio import StdioServerParameters, stdio_client
 from mcp.client.streamable_http import streamable_http_client
 from mcp.shared._httpx_utils import create_mcp_http_client
@@ -330,6 +330,44 @@ def _resolve_client_name(server_name: str) -> str:
     return _client_names_cache.get(server_name) or f"mcpgen ({server_name})"
 
 
+def _client_metadata(server_name: str, callback_uri: str, client_name: str | None = None) -> OAuthClientMetadata:
+    """Dynamic-registration metadata (RFC 7591). Shared by both OAuth entry points.
+
+    `token_endpoint_auth_method="none"` is load-bearing. Omit it and the AS applies
+    the RFC 7591 §2 default of `client_secret_basic` and issues a `client_secret`;
+    the SDK then sends an `Authorization: Basic` header *and* `client_id` in the form
+    body — two client authentication methods in one request, which servers that
+    enforce RFC 6749 §2.3 reject with `400 invalid_request`. Registering as a public
+    client (RFC 8252 §8.4) is the correct posture for a distributed CLI anyway, and
+    the SDK's PKCE (S256, unconditional) is what actually secures the flow.
+    """
+    return OAuthClientMetadata(
+        client_name=client_name or _resolve_client_name(server_name),
+        redirect_uris=[callback_uri],  # type: ignore[list-item]  # Pydantic coerces str→AnyUrl
+        grant_types=["authorization_code", "refresh_token"],
+        response_types=["code"],
+        token_endpoint_auth_method="none",
+    )
+
+
+def _explain_registration_error(exc: OAuthRegistrationError) -> OAuthRegistrationError:
+    """Annotate `invalid_client_metadata` with its most likely cause.
+
+    An AS that does not support public clients MUST reject our registration
+    (RFC 7591 §2) rather than downgrade it. No such server is known, so rather than
+    carry a speculative override flag we make the failure legible if one turns up.
+    """
+    if "invalid_client_metadata" not in str(exc):
+        return exc
+    return OAuthRegistrationError(
+        f"{exc}\n\n"
+        "Likely cause: mcpgen registers as a public client "
+        "(token_endpoint_auth_method=none), and this authorization server appears to "
+        "require a client_secret. Please report this at "
+        "https://github.com/svd/mcp-client-kit/issues with the message above."
+    )
+
+
 # Treat a cached token as expired this many seconds before its real expiry.
 _MARGIN = 120
 
@@ -782,6 +820,12 @@ async def _http_session(
     storage = FileTokenStorage(server_name, backend=resolve_cred_backend(cred_backend))
     await _pre_flight_refresh(server_name, storage)
 
+    # Unlike login(), this does NOT clear a stale confidential-client registration,
+    # and must not: a pre-fix credential still refreshes fine here, because
+    # _pre_flight_refresh sends client_id + client_secret in the body — that is
+    # client_secret_post, a *single* auth method, so it never hit the double-auth
+    # bug. Once the refresh token dies, _no_browser raises ReauthenticationRequired
+    # → "Run: mcpgen login" → which does clear and re-register as a public client.
     data = storage._load()
     redirect_uris = data.get(server_name, {}).get("client_info", {}).get("redirect_uris", [])
     callback_uri = redirect_uris[0] if redirect_uris else "http://localhost:0/callback"
@@ -794,12 +838,7 @@ async def _http_session(
 
     provider = OAuthClientProvider(
         server_url=server_url,
-        client_metadata=OAuthClientMetadata(
-            client_name=client_name or _resolve_client_name(server_name),
-            redirect_uris=[callback_uri],  # type: ignore[list-item]  # Pydantic coerces str→AnyUrl
-            grant_types=["authorization_code", "refresh_token"],
-            response_types=["code"],
-        ),
+        client_metadata=_client_metadata(server_name, callback_uri, client_name),
         storage=storage,
         redirect_handler=_no_browser,
         callback_handler=_no_callback,
@@ -951,20 +990,61 @@ class McpBridgeCaller:
             env=self._env,
         ) as s:
             result = await s.call_tool(tool, arguments)
-            content = [{"type": item.type, "text": getattr(item, "text", "")} for item in result.content]
+            content = [_summarize_content_item(item) for item in result.content]
             return parse(content)
 
 
+def _summarize_content_item(item: Any) -> dict:
+    """Reduce one MCP content block to a compact, JSON-safe dict.
+
+    ``text`` blocks keep today's shape ({"type", "text"}). ``image`` / ``resource`` /
+    ``resource_link`` blocks carry no useful `.text` — capturing only `.text` (as the
+    old code did) silently degrades them to an empty string, hiding the payload from
+    shape inference entirely. Record presence/metadata instead (never the raw
+    base64/blob bytes, to keep shape-specs small).
+    """
+    item_type = getattr(item, "type", None)
+    if item_type == "image":
+        return {
+            "type": "image",
+            "mimeType": getattr(item, "mimeType", None),
+            "has_data": bool(getattr(item, "data", None)),
+        }
+    if item_type == "resource":
+        resource = getattr(item, "resource", None)
+        return {
+            "type": "resource",
+            "mimeType": getattr(resource, "mimeType", None),
+            "has_text": bool(getattr(resource, "text", None)),
+            "has_blob": bool(getattr(resource, "blob", None)),
+        }
+    if item_type == "resource_link":
+        uri = getattr(item, "uri", None)
+        return {
+            "type": "resource_link",
+            "uri": str(uri) if uri is not None else None,
+            "name": getattr(item, "name", None),
+        }
+    return {"type": item_type, "text": getattr(item, "text", "")}
+
+
 def parse(content_items: list) -> Any:
     """Extract and JSON-parse the text payload from an MCP tool result.
 
     Falls back to ``ast.literal_eval`` for Python-repr payloads (e.g. servers
     that return single-quoted dicts like sqlite), then to a plain string as a
     last resort so callers can still inspect the response.
+
+    Non-text content blocks (image / resource / resource_link) carry no `.text`
+    to parse — return the block's own summary dict as-is rather than falling
+    through to an empty string, so the shape-spec records something real.
     """
     if not content_items:
         raise ValueError("MCP tool result has empty content")
     item = content_items[0]
+    item_type = item.get("type") if isinstance(item, dict) else getattr(item, "type", None)
+    if item_type in ("image", "resource", "resource_link"):
+        return item if isinstance(item, dict) else _summarize_content_item(item)
     text = item.get("text", "") if isinstance(item, dict) else getattr(item, "text", "")
     try:
         return json.loads(text)
@@ -1067,35 +1147,33 @@ async def login(
 
         provider = OAuthClientProvider(
             server_url=server_url,
-            client_metadata=OAuthClientMetadata(
-                client_name=client_name or _resolve_client_name(server_name),
-                redirect_uris=[callback_uri],  # type: ignore[list-item]  # Pydantic coerces str→AnyUrl
-                grant_types=["authorization_code", "refresh_token"],
-                response_types=["code"],
-            ),
+            client_metadata=_client_metadata(server_name, callback_uri, client_name),
             storage=storage,
             redirect_handler=redirect_handler,
             callback_handler=callback_handler,
         )
 
         try:
-            async with _open_http(server_url, auth=provider) as (read, write, _):
-                async with ClientSession(read, write) as s:
-                    await s.initialize()
-
-                    # Persist the token endpoint for later pre-flight refresh. Do this
-                    # independently of any tool call — not every server exposes `whoami`.
-                    if provider.context.oauth_metadata is not None:
-                        endpoint_url = str(provider.context.oauth_metadata.token_endpoint)
-                        creds_data = storage._load()
-                        creds_data.setdefault(server_name, {})["token_endpoint"] = endpoint_url
-                        storage._save(creds_data)
-
-                    # Confirm the authenticated session works with a server-agnostic
-                    # call. `list_tools` is part of the MCP protocol — every server
-                    # supports it, unlike any specific tool name.
-                    tools = await s.list_tools()
-                    print(f"Login OK ({server_name}); {len(tools.tools)} tool(s) available")
+            try:
+                async with _open_http(server_url, auth=provider) as (read, write, _):
+                    async with ClientSession(read, write) as s:
+                        await s.initialize()
+
+                        # Persist the token endpoint for later pre-flight refresh. Do this
+                        # independently of any tool call — not every server exposes `whoami`.
+                        if provider.context.oauth_metadata is not None:
+                            endpoint_url = str(provider.context.oauth_metadata.token_endpoint)
+                            creds_data = storage._load()
+                            creds_data.setdefault(server_name, {})["token_endpoint"] = endpoint_url
+                            storage._save(creds_data)
+
+                        # Confirm the authenticated session works with a server-agnostic
+                        # call. `list_tools` is part of the MCP protocol — every server
+                        # supports it, unlike any specific tool name.
+                        tools = await s.list_tools()
+                        print(f"Login OK ({server_name}); {len(tools.tools)} tool(s) available")
+            except OAuthRegistrationError as e:
+                raise _explain_registration_error(e) from e
         finally:
             if not callback_future.done():
                 callback_future.set_result((None, None))