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

mcp_client_kit-0.2.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.2.0/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+## [Unreleased] — 0.3.0
+
+## [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.2.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.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-client-kit
-Version: 0.0.4
+Version: 0.2.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.2.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.2.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.2.0}/mcpgen/cli.py

@@ -290,7 +290,9 @@ def _cmd_codegen(ns: argparse.Namespace) -> int:
         shape_json = json.dumps(shape, indent=2)
         probe_note = f"\nObserved response shape of {ns.probe!r} (keys/types/nesting only):\n" + shape_json
 
-    source = codegen.render_module(ns.server, tools, shapes=shapes, probe_note=probe_note)
+    source = codegen.render_module(
+        ns.server, tools, shapes=shapes, probe_note=probe_note, embed_schema=getattr(ns, "embed_schema", False)
+    )
     if ns.out:
         Path(ns.out).write_text(source)
         print(f"[codegen] wrote {ns.out} ({len(source)} bytes)", file=sys.stderr)
@@ -574,7 +576,13 @@ def _cmd_list(ns: argparse.Namespace) -> int:
     except (FileNotFoundError, ValueError) as exc:
         print(f"[list] error: {exc}", file=sys.stderr)
         return 1
-    out = [{"name": t["name"], "description": t.get("description") or ""} for t in tools]
+    if getattr(ns, "schema", False):
+        out = [
+            {"name": t["name"], "description": t.get("description") or "", "inputSchema": t.get("inputSchema") or {}}
+            for t in tools
+        ]
+    else:
+        out = [{"name": t["name"], "description": t.get("description") or ""} for t in tools]
     sys.stdout.write(json.dumps(out, indent=2) + "\n")
 
     candidates = codegen.detect_discriminators(tools)
@@ -743,6 +751,12 @@ def main(argv: list[str] | None = None) -> int:
     cg.add_argument("--probe", help="tool to call live and record response shape (docstring note only)")
     cg.add_argument("--probe-args", help="JSON args for --probe (default: {})")
     cg.add_argument("--stdio", metavar="CMD", help="use stdio transport: 'python server.py' (no auth)")
+    cg.add_argument(
+        "--embed-schema",
+        action="store_true",
+        dest="embed_schema",
+        help="embed raw inputSchema as __schema__ attribute and Args docstring per tool",
+    )
     _add_conn_args(cg)
     cg.set_defaults(func=_cmd_codegen)
 
@@ -794,6 +808,7 @@ def main(argv: list[str] | None = None) -> int:
 
     ls = sub.add_parser("list", help="list tools for a server as JSON [{name, description}]")
     ls.add_argument("server", help="server name (e.g. acme) or URL")
+    ls.add_argument("--schema", action="store_true", help="include raw inputSchema JSON per tool")
     ls.add_argument("--stdio", metavar="CMD", help="use stdio transport: 'python server.py' (no auth)")
     _add_conn_args(ls)
     ls.set_defaults(func=_cmd_list)

{mcp_client_kit-0.0.4 → mcp_client_kit-0.2.0}/mcpgen/codegen.py

@@ -32,6 +32,17 @@ def py_type(schema: dict | None) -> str:
     if any(k in schema for k in ("anyOf", "oneOf", "allOf")):
         return "Any"
 
+    # Enum: emit Literal[...] only when every member is a PEP 586-safe scalar.
+    # Floats, lists, and dicts are not valid Literal parameters; fall through to
+    # the type-based path so we emit the declared type (or Any) instead.
+    enum_vals = schema.get("enum")
+    if isinstance(enum_vals, list) and enum_vals:
+        if all(type(v) in (str, bool, int, bytes, type(None)) for v in enum_vals):
+            t = schema.get("type")
+            nullable = isinstance(t, list) and "null" in t
+            inner = "Literal[" + ", ".join(repr(v) for v in enum_vals) + "]"
+            return f"{inner} | None" if nullable else inner
+
     t = schema.get("type")
     if isinstance(t, list):  # e.g. ["string", "null"]
         non_null = [x for x in t if x != "null"]
@@ -204,7 +215,61 @@ _DIG_LIST = '''def _dig_list(obj: Any, path: tuple[str, ...]) -> list:
     return cur'''
 
 
-def _render_overloaded(tool: dict, fn: str, raw_name: str, props: dict, required: set, shape: dict) -> str:
+def _docstring_with_args(tool: dict, ordered: list[tuple[str, dict]], indent: str) -> str:
+    """Build docstring with description + Args section from inputSchema properties."""
+    desc = (tool.get("description") or "").strip()
+    props_lines = []
+    for pname, pschema in ordered:
+        py = sanitize(pname)
+        parts: list[str] = []
+        if not isinstance(pschema, dict):
+            props_lines.append(f"    {py}:")
+            continue
+        pdesc = (pschema.get("description") or "").strip()
+        if pdesc:
+            parts.append(pdesc)
+        if pschema.get("enum"):
+            parts.append(f"One of: {', '.join(repr(v) for v in pschema['enum'])}")
+        if "default" in pschema:
+            parts.append(f"Default: {pschema['default']!r}")
+        detail = ". ".join(parts)
+        if detail:
+            props_lines.append(f"    {py}: {detail}")
+        else:
+            props_lines.append(f"    {py}:")
+
+    if not props_lines:
+        return _docstring(desc or None, indent)
+
+    if desc:
+        body = desc + "\n\nArgs:\n" + "\n".join(props_lines)
+    else:
+        body = "Args:\n" + "\n".join(props_lines)
+
+    # Use repr() to ensure injection safety (description is server-controlled text)
+    # But we want multi-line docstring format where possible.
+    # Fall back to repr() only if text contains backslash, triple-quotes, or trailing quote.
+    text = body.strip()
+    if "\\" in text or '"""' in text or text.endswith('"'):
+        return f"{indent}{repr(text)}"
+    lines_list = text.splitlines()
+    if len(lines_list) == 1:
+        return f'{indent}"""{lines_list[0]}"""'
+    parts = [lines_list[0]] + [f"{indent}{ln}" if ln else "" for ln in lines_list[1:]]
+    joined = "\n".join(parts)
+    return f'{indent}"""{joined}\n{indent}"""'
+
+
+def _render_overloaded(
+    tool: dict,
+    fn: str,
+    raw_name: str,
+    props: dict,
+    required: set,
+    shape: dict,
+    embed_schema: bool = False,
+    schema: dict | None = None,
+) -> str:
     """Emit @overload stubs (one per discriminator value) + impl signature."""
     disc: str = shape["discriminator"]
     variants: dict = shape["variants"]
@@ -245,7 +310,10 @@ def _render_overloaded(tool: dict, fn: str, raw_name: str, props: dict, required
 
     impl_ret = f"list[{union_ret}]" if container == "list" else union_ret
     impl_lines = [f"async def {fn}({_sig(_build_params('int'))}) -> {impl_ret}:"]
-    impl_lines.append(_docstring(tool.get("description"), "    "))
+    if embed_schema:
+        impl_lines.append(_docstring_with_args(tool, ordered, "    "))
+    else:
+        impl_lines.append(_docstring(tool.get("description"), "    "))
 
     body_args = [(sanitize(pname), pname, pname in required or pname == disc) for pname, _ in ordered]
     req_pairs = [(py, pname) for py, pname, is_req in body_args if is_req]
@@ -274,11 +342,15 @@ def _render_overloaded(tool: dict, fn: str, raw_name: str, props: dict, required
     else:
         impl_lines.append(f'    return cast("{impl_ret}", {call})')
 
-    blocks.append("\n".join(impl_lines))
+    impl_block = "\n".join(impl_lines)
+    if embed_schema:
+        _schema = schema if schema is not None else {}
+        impl_block += f"\n\n{fn}.__schema__ = {repr(_schema)}"
+    blocks.append(impl_block)
     return "\n\n".join(blocks)
 
 
-def render_tool(tool: dict, shape: dict | None = None) -> str:
+def render_tool(tool: dict, shape: dict | None = None, embed_schema: bool = False) -> str:
     """Render one MCP tool into a typed `async def` against the McpCaller seam.
 
     With a probe-derived `shape` (unwrap path / return model / input overrides),
@@ -293,7 +365,7 @@ def render_tool(tool: dict, shape: dict | None = None) -> str:
 
     shape = shape or {}
     if shape.get("discriminator") and shape.get("variants"):
-        return _render_overloaded(tool, fn, raw_name, props, required, shape)
+        return _render_overloaded(tool, fn, raw_name, props, required, shape, embed_schema=embed_schema, schema=schema)
 
     unwrap: list = shape.get("unwrap") or []
     return_model: str | None = shape.get("return_model")
@@ -327,7 +399,10 @@ def render_tool(tool: dict, shape: dict | None = None) -> str:
     sig = ", ".join(sig_params)
 
     lines = [f"async def {fn}({sig}) -> {ret_ann}:"]
-    lines.append(_docstring(tool.get("description"), "    "))
+    if embed_schema:
+        lines.append(_docstring_with_args(tool, ordered, "    "))
+    else:
+        lines.append(_docstring(tool.get("description"), "    "))
 
     req_pairs = [(py, pname) for py, pname, is_req in body_args if is_req]
     opt_pairs = [(py, pname) for py, pname, is_req in body_args if not is_req]
@@ -358,7 +433,10 @@ def render_tool(tool: dict, shape: dict | None = None) -> str:
     else:
         lines.append(f"    return {call}")
 
-    return "\n".join(lines)
+    result = "\n".join(lines)
+    if embed_schema:
+        result += f"\n\n{fn}.__schema__ = {repr(schema)}"
+    return result
 
 
 _HEADER = '''"""Generated MCP wrappers for the {server!r} server. DO NOT hand-edit signatures.
@@ -380,7 +458,9 @@ SERVER = {server!r}
 _PY_BUILTINS = frozenset({"str", "int", "float", "list", "dict", "bool", "bytes", "object", "type", "set", "tuple"})
 
 
-def render_module(server: str, tools: list[dict], shapes: dict | None = None, probe_note: str = "") -> str:
+def render_module(
+    server: str, tools: list[dict], shapes: dict | None = None, probe_note: str = "", embed_schema: bool = False
+) -> str:
     """Render a full wrapper module.
 
     `shapes` maps tool name -> probe-derived shape-spec (see render_tool). When
@@ -392,10 +472,28 @@ def render_module(server: str, tools: list[dict], shapes: dict | None = None, pr
     has_disc = any(s.get("discriminator") and s.get("variants") for s in shapes.values())
     needs_json = bool(shapes) and any((shapes.get(t["name"]) or {}).get("unwrap") for t in tools)
     has_typed_return = has_disc or any(s.get("return_model") for s in shapes.values())
+
+    def _schema_has_enum(s: dict | None) -> bool:
+        if not isinstance(s, dict):
+            return False
+        if s.get("enum"):
+            return True
+        # recurse into array items (py_type can emit Literal for nested enums)
+        items = s.get("items")
+        return isinstance(items, dict) and bool(items.get("enum"))
+
+    has_enum = any(
+        any(_schema_has_enum(pschema) for pschema in (((t.get("inputSchema") or {}).get("properties") or {}).values()))
+        for t in tools
+    )
     if has_disc:
         type_imports = "from typing import Any, Literal, TypedDict, cast, overload"
+    elif has_typed_return and has_enum:
+        type_imports = "from typing import Any, Literal, TypedDict, cast"
     elif has_typed_return:
         type_imports = "from typing import Any, TypedDict, cast"
+    elif has_enum:
+        type_imports = "from typing import Any, Literal"
     else:
         type_imports = "from typing import Any"
     imports = ("import json\n" + type_imports) if needs_json else type_imports
@@ -447,7 +545,7 @@ def render_module(server: str, tools: list[dict], shapes: dict | None = None, pr
             parts.append(_DIG_LIST)
 
     for tool in sorted(tools, key=lambda t: t["name"]):
-        parts.append(render_tool(tool, shapes.get(tool["name"])))
+        parts.append(render_tool(tool, shapes.get(tool["name"]), embed_schema=embed_schema))
     return "\n\n\n".join(parts) + "\n"
 
 

{mcp_client_kit-0.0.4 → mcp_client_kit-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-client-kit"
-version = "0.0.4"
+version = "0.2.0"
 description = "mcp-client-kit — generate typed Python wrappers for any MCP server (codegen skill + CLI)."
 readme = "README.md"
 license = { text = "MIT" }

{mcp_client_kit-0.0.4 → mcp_client_kit-0.2.0}/skills/generate-mcp-wrappers/SKILL.md

@@ -78,31 +78,35 @@ For dispatch mechanics see `superpowers:dispatching-parallel-agents`.
    etc.) to the launched process. `MCPGEN_SERVERS` must prefix the command in the **same
    shell invocation** — it does not persist across calls.
    ```bash
-   MCPGEN_SERVERS=servers.json mcpgen codegen <server> --out <server>/<server>.py
+   MCPGEN_SERVERS=servers.json mcpgen codegen <server> --out <server>/<server>.py --embed-schema
    ```
 
    **Alternative — pass transport values directly, without a config file:**
    ```bash
    # stdio (pass the full launch command):
-   mcpgen codegen <server> --stdio "uvx mcp-server-time" --out <server>/<server>.py
+   mcpgen codegen <server> --stdio "uvx mcp-server-time" --out <server>/<server>.py --embed-schema
 
    # HTTP no-auth:
-   mcpgen codegen <server> --url "https://mcp.example.com/mcp" --out <server>/<server>.py
+   mcpgen codegen <server> --url "https://mcp.example.com/mcp" --out <server>/<server>.py --embed-schema
 
    # HTTP Bearer:
-   mcpgen codegen <server> --url "https://api.example.com/mcp/" --bearer "$MY_TOKEN" --out <server>/<server>.py
+   mcpgen codegen <server> --url "https://api.example.com/mcp/" --bearer "$MY_TOKEN" --out <server>/<server>.py --embed-schema
    ```
    `codegen`, `list`, `probe`, and `call` each require the same transport flags
    (`--stdio` / `--url` / `--bearer` / `--config`) on every invocation — they do **not**
    inherit flags from a prior run. `merge` and `discover` accept no transport flags.
 
-   Parses; every tool typed from `inputSchema`; returns `Any`.
+   Parses; every tool typed from `inputSchema`; returns `Any`. `--embed-schema` (used
+   above) also emits `fn.__schema__ = {<raw inputSchema>}` on each function and an Args
+   docstring section listing each param's description, enum values, and default.
 
 2. **Select tools to probe (interactive gate).**
 
-   a. Run `mcpgen list <server>` → get `[{name, description}]` for every tool.
-      **Probe only tools that appear in this output.** Do not add tools from
-      system-prompt context, documentation, or prior knowledge.
+   a. Run `mcpgen list <server> --schema` → get `[{name, description, inputSchema}]`
+      for every tool. **Probe only tools that appear in this output.** Do not add tools
+      from system-prompt context, documentation, or prior knowledge. The `inputSchema`
+      field in this output is the authoritative source for steps 3's required-arg and
+      enum-constraint checks — no separate schema fetch is needed.
 
    b. Print a report of all tools in this format:
       ```
@@ -257,21 +261,22 @@ For dispatch mechanics see `superpowers:dispatching-parallel-agents`.
    `get_entity_fields` per `entityType`, `get_acme_glossary`); (c) `AskUserQuestion`
    if not discoverable from available tools.
 
-   **Check `inputSchema.required` before constructing probe args.** If the array is
-   non-empty, never probe with `'{}'` — call the tool with minimal valid args on the first
-   attempt. Invent realistic-looking but fake values for required string/ID args that carry
-   no `enum`. For GitHub servers, prefer `owner: "microsoft", repo: "vscode"` as the default
-   probe repo (`octocat/Hello-World` lacks releases/tags/issue fields and produces `[<empty>]`
-   for those tools).
+   **Check `inputSchema.required` before constructing probe args** (read from `list --schema`
+   output). If the array is non-empty, never probe with `'{}'` — call the tool with minimal
+   valid args on the first attempt. Invent realistic-looking but fake values for required
+   string/ID args that carry no `enum`. For GitHub servers, prefer `owner: "microsoft",
+   repo: "vscode"` as the default probe repo (`octocat/Hello-World` lacks releases/tags/issue
+   fields and produces `[<empty>]` for those tools).
 
-   **Inspect `inputSchema` for enum constraints before constructing probe args.** For each
-   required param, check `inputSchema.properties[param].enum`. If an `enum` array is
-   present, use its **first listed value** as the probe arg instead of inventing a value —
+   **Inspect `inputSchema` for enum constraints before constructing probe args** (read from
+   `list --schema` output, field `inputSchema.properties[param].enum`). If an `enum` array
+   is present, use its **first listed value** as the probe arg instead of inventing a value —
    invented values will be rejected with an MCP validation error. Record the chosen value
-   in `probed_args`.
+   in `probed_args`. Note: codegen maps enum params to `Literal[...]` automatically, so the
+   generated signature already encodes the allowed values.
 
    Example: `"city": {"type": "string", "enum": ["New York", "Chicago", "Los Angeles"]}`
-   → probe with `city="New York"`.
+   → probe with `city="New York"` → generated type `Literal['New York', 'Chicago', 'Los Angeles']`.
 
    **JSON-in-string detection.** Some servers serialize structured data as a JSON string
    inside the MCP envelope (e.g. `directory_tree` returns a JSON string, not a parsed
@@ -406,7 +411,7 @@ For dispatch mechanics see `superpowers:dispatching-parallel-agents`.
 
 5. **Regenerate.** (same transport flags as step 1)
    ```bash
-   mcpgen codegen <server> --stdio "uvx mcp-server-time" --out <server>/<server>.py --shapes <server>/<server>.shapes.json
+   mcpgen codegen <server> --stdio "uvx mcp-server-time" --out <server>/<server>.py --shapes <server>/<server>.shapes.json --embed-schema
    # or: --url / --bearer for HTTP servers
    ```
    (`<server>.shapes.json` sitting beside `--out` is auto-detected; `--shapes` is the
@@ -487,3 +492,7 @@ For dispatch mechanics see `superpowers:dispatching-parallel-agents`.
   values or resolved to a base model / `Any`. A single-variant model is a silent lie
   for all other variants — the exact mistake that typed `query_acme` as `list[Person]`
   when entityType=2/7/… return completely different shapes.
+- **Enum params render as `Literal[...]` automatically** — do not hand-widen them to
+  `str`. Codegen's `py_type()` emits `Literal['a', 'b', ...]` for any param whose
+  `inputSchema` carries an `enum` array (no flag required). Widen to `str` only if
+  the server's actual validation rejects values that aren't in the declared enum.

mcp_client_kit-0.2.0/tests/test_cli_list.py

@@ -0,0 +1,173 @@
+"""Tests for `mcpgen list` — network-free; _list_tools is monkeypatched."""
+
+from __future__ import annotations
+
+import json
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, patch
+
+from mcpgen.cli import _cmd_list
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+
+def _ns(server: str, schema: bool = False) -> SimpleNamespace:
+    return SimpleNamespace(
+        server=server,
+        schema=schema,
+        stdio=None,
+        url=None,
+        bearer=None,
+        client_name=None,
+        config=None,
+        cred_backend=None,
+        env=None,
+    )
+
+
+FAKE_TOOLS = [
+    {
+        "name": "get_user",
+        "description": "Get user by ID",
+        "inputSchema": {"type": "object", "properties": {"user_id": {"type": "string"}}, "required": ["user_id"]},
+    },
+    {
+        "name": "list_users",
+        "description": "List all users",
+        "inputSchema": {"type": "object", "properties": {"limit": {"type": "integer"}}},
+    },
+]
+
+
+# ── without --schema ──────────────────────────────────────────────────────────
+
+
+def test_list_without_schema_includes_name_and_description(capsys):
+    """Without --schema, output is {name, description} only."""
+    ns = _ns("acme", schema=False)
+
+    with patch("mcpgen.cli._list_tools", new_callable=AsyncMock, return_value=FAKE_TOOLS):
+        rc = _cmd_list(ns)
+
+    assert rc == 0
+    out = capsys.readouterr().out
+    result = json.loads(out)
+
+    assert len(result) == 2
+    assert result[0] == {"name": "get_user", "description": "Get user by ID"}
+    assert result[1] == {"name": "list_users", "description": "List all users"}
+
+
+def test_list_without_schema_no_inputschema_in_output(capsys):
+    """Without --schema, inputSchema should not be in the output."""
+    ns = _ns("acme", schema=False)
+
+    with patch("mcpgen.cli._list_tools", new_callable=AsyncMock, return_value=FAKE_TOOLS):
+        _cmd_list(ns)
+
+    out = capsys.readouterr().out
+    result = json.loads(out)
+
+    for item in result:
+        assert "inputSchema" not in item
+
+
+def test_list_without_schema_empty_description_fallback(capsys):
+    """When description is None or absent, it should fallback to empty string."""
+    tools = [
+        {"name": "no_desc_none", "description": None, "inputSchema": {}},
+        {"name": "no_desc_absent", "inputSchema": {}},
+    ]
+    ns = _ns("acme", schema=False)
+
+    with patch("mcpgen.cli._list_tools", new_callable=AsyncMock, return_value=tools):
+        _cmd_list(ns)
+
+    out = capsys.readouterr().out
+    result = json.loads(out)
+
+    assert result[0] == {"name": "no_desc_none", "description": ""}
+    assert result[1] == {"name": "no_desc_absent", "description": ""}
+
+
+# ── with --schema ─────────────────────────────────────────────────────────────
+
+
+def test_list_with_schema_includes_inputschema(capsys):
+    """With --schema, output includes inputSchema."""
+    ns = _ns("acme", schema=True)
+
+    with patch("mcpgen.cli._list_tools", new_callable=AsyncMock, return_value=FAKE_TOOLS):
+        rc = _cmd_list(ns)
+
+    assert rc == 0
+    out = capsys.readouterr().out
+    result = json.loads(out)
+
+    assert len(result) == 2
+    assert "inputSchema" in result[0]
+    assert result[0]["inputSchema"] == FAKE_TOOLS[0]["inputSchema"]
+    assert result[1]["inputSchema"] == FAKE_TOOLS[1]["inputSchema"]
+
+
+def test_list_with_schema_includes_name_and_description(capsys):
+    """With --schema, output still includes name and description."""
+    ns = _ns("acme", schema=True)
+
+    with patch("mcpgen.cli._list_tools", new_callable=AsyncMock, return_value=FAKE_TOOLS):
+        _cmd_list(ns)
+
+    out = capsys.readouterr().out
+    result = json.loads(out)
+
+    assert result[0]["name"] == "get_user"
+    assert result[0]["description"] == "Get user by ID"
+    assert result[1]["name"] == "list_users"
+    assert result[1]["description"] == "List all users"
+
+
+def test_list_with_schema_empty_inputschema_fallback(capsys):
+    """When inputSchema is None or absent, it should fallback to empty dict."""
+    tools = [
+        {"name": "no_schema_none", "description": "A tool", "inputSchema": None},
+        {"name": "no_schema_absent", "description": "A tool"},
+    ]
+    ns = _ns("acme", schema=True)
+
+    with patch("mcpgen.cli._list_tools", new_callable=AsyncMock, return_value=tools):
+        _cmd_list(ns)
+
+    out = capsys.readouterr().out
+    result = json.loads(out)
+
+    assert result[0]["inputSchema"] == {}
+    assert result[1]["inputSchema"] == {}
+
+
+def test_list_with_schema_all_fields_present(capsys):
+    """With --schema, each tool has all three fields: name, description, inputSchema."""
+    ns = _ns("acme", schema=True)
+
+    with patch("mcpgen.cli._list_tools", new_callable=AsyncMock, return_value=FAKE_TOOLS):
+        _cmd_list(ns)
+
+    out = capsys.readouterr().out
+    result = json.loads(out)
+
+    for item in result:
+        assert set(item.keys()) == {"name", "description", "inputSchema"}
+
+
+# ── error handling ────────────────────────────────────────────────────────────
+
+
+def test_list_handles_list_tools_error(capsys):
+    """When _list_tools raises an error, _cmd_list should return 1."""
+    ns = _ns("acme", schema=False)
+
+    with patch("mcpgen.cli._list_tools", new_callable=AsyncMock, side_effect=FileNotFoundError("server not found")):
+        rc = _cmd_list(ns)
+
+    assert rc == 1
+    err = capsys.readouterr().err
+    assert "error" in err.lower()

{mcp_client_kit-0.0.4 → mcp_client_kit-0.2.0}/tests/test_codegen.py

@@ -961,3 +961,165 @@ def test_detect_discriminators_denylist_camelcase_compound_forms():
     result = codegen.detect_discriminators(tools)
     for param in compound_params:
         assert param not in result, f"compound param {param!r} must be in denylist"
+
+
+# ---------------------------------------------------------------------------
+# Task C — enum → Literal[...] in py_type and render_module
+# ---------------------------------------------------------------------------
+
+
+def test_py_type_enum_string_literal():
+    assert codegen.py_type({"type": "string", "enum": ["asc", "desc"]}) == "Literal['asc', 'desc']"
+
+
+def test_py_type_enum_int_literal():
+    assert codegen.py_type({"enum": [1, 2, 3]}) == "Literal[1, 2, 3]"
+
+
+def test_py_type_enum_nullable():
+    assert codegen.py_type({"type": ["string", "null"], "enum": ["a", "b"]}) == "Literal['a', 'b'] | None"
+
+
+def test_py_type_enum_empty_falls_through():
+    # Empty enum list must not produce Literal[] (syntax error); fall through to scalar.
+    assert codegen.py_type({"type": "string", "enum": []}) == "str"
+
+
+def test_py_type_enum_float_falls_through_to_type():
+    # Floats are not PEP 586-safe; fall through to declared type.
+    assert codegen.py_type({"type": "number", "enum": [1.5, 2.5]}) == "float"
+
+
+def test_py_type_enum_float_no_type_falls_through_to_any():
+    # No type key + unsafe enum members → Any.
+    assert codegen.py_type({"enum": [1.5, 2.5]}) == "Any"
+
+
+def test_py_type_enum_list_members_falls_through():
+    # List values are not valid Literal parameters.
+    assert codegen.py_type({"enum": [[1, 2], [3, 4]]}) == "Any"
+
+
+def test_py_type_enum_dict_members_falls_through():
+    # Dict values are not valid Literal parameters.
+    assert codegen.py_type({"enum": [{"a": 1}]}) == "Any"
+
+
+def test_py_type_enum_mixed_safe_unsafe_falls_through():
+    # Mixed scalars + float: all-or-nothing, fall through.
+    assert codegen.py_type({"type": "string", "enum": ["ok", 1.5]}) == "str"
+
+
+def test_render_module_enum_param_imports_literal():
+    tools = [
+        {
+            "name": "sort_items",
+            "description": "Sort items.",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "direction": {"type": "string", "enum": ["asc", "desc"]},
+                },
+                "required": ["direction"],
+            },
+        }
+    ]
+    src = codegen.render_module("demo", tools)
+    assert "from typing import Any, Literal" in src
+
+
+def test_render_tool_enum_param_uses_literal():
+    tool = {
+        "name": "sort_items",
+        "description": "Sort items.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "direction": {"type": "string", "enum": ["asc", "desc"]},
+            },
+            "required": ["direction"],
+        },
+    }
+    src = codegen.render_tool(tool)
+    assert "Literal[" in src
+    assert "Literal['asc', 'desc']" in src
+    # Generated source must be valid Python when embedded in a module.
+    tools = [tool]
+    module_src = codegen.render_module("demo", tools)
+    ast.parse(module_src)
+
+
+# ── --embed-schema tests ──────────────────────────────────────────────────────
+
+_EMBED_TOOL = {
+    "name": "get_item",
+    "description": "Fetch an item.",
+    "inputSchema": {
+        "type": "object",
+        "properties": {
+            "item_id": {"type": "string", "description": "The item identifier"},
+            "format": {"type": "string", "enum": ["json", "xml"], "default": "json", "description": "Output format"},
+            "verbose": {"type": "boolean"},
+        },
+        "required": ["item_id"],
+    },
+}
+
+
+def test_render_tool_embed_schema_adds_schema_attr():
+    src = codegen.render_tool(_EMBED_TOOL, embed_schema=True)
+    assert ".__schema__ = " in src
+    # Must be valid Python and the attribute must be accessible.
+    ns: dict = {}
+    # Wrap in a module-like context so the async def can be exec'd.
+    module_src = (
+        "from __future__ import annotations\n"
+        "from typing import Any\n"
+        "from mcpgen.seam import McpCaller\n"
+        "SERVER = 'demo'\n\n" + src
+    )
+    exec(compile(module_src, "<test>", "exec"), ns)
+    fn = ns["get_item"]
+    assert hasattr(fn, "__schema__")
+    assert fn.__schema__ == (_EMBED_TOOL.get("inputSchema") or {})
+
+
+def test_render_tool_embed_schema_adds_args_docstring():
+    src = codegen.render_tool(_EMBED_TOOL, embed_schema=True)
+    assert "Args:" in src
+    assert "item_id:" in src
+    assert "The item identifier" in src
+    assert "One of:" in src
+    assert "'json'" in src
+    assert "Default:" in src
+    # Tighten assertion to check exact indentation
+    assert "    Args:" in src  # 4 spaces (not 8)
+    assert "        item_id:" in src  # 8 spaces (not 12)
+
+
+def test_render_tool_no_embed_schema_unchanged():
+    src_default = codegen.render_tool(_EMBED_TOOL)
+    src_false = codegen.render_tool(_EMBED_TOOL, embed_schema=False)
+    src_no_flag = codegen.render_tool(_EMBED_TOOL)
+    assert src_default == src_false == src_no_flag
+    assert ".__schema__" not in src_default
+    assert "Args:" not in src_default
+
+
+def test_render_module_embed_schema_passes_through():
+    tools = [_EMBED_TOOL]
+    src = codegen.render_module("demo", tools, embed_schema=True)
+    ast.parse(src)
+    assert ".__schema__ = " in src
+
+
+def test_render_tool_embed_schema_no_args_no_args_section():
+    tool = {
+        "name": "ping",
+        "description": "Ping the server.",
+        "inputSchema": {"type": "object", "properties": {}, "required": []},
+    }
+    src = codegen.render_tool(tool, embed_schema=True)
+    assert "Args:" not in src
+    # __schema__ attr should still be present (empty dict).
+    assert ".__schema__ = " in src

{mcp_client_kit-0.0.4 → mcp_client_kit-0.2.0}/uv.lock

@@ -535,7 +535,7 @@ cli = [
 
 [[package]]
 name = "mcp-client-kit"
-version = "0.0.4"
+version = "0.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },