mcp-client-kit 0.0.3__tar.gz

mcp_client_kit-0.0.3/.claude-plugin/marketplace.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+  "name": "mcp-client-kit",
+  "version": "0.1.0",
+  "description": "Marketplace for the mcpgen plugin — typed Python wrappers for any MCP server.",
+  "owner": {
+    "name": "Sviatoslav Sviridov",
+    "email": "sviridov@gmail.com"
+  },
+  "plugins": [
+    {
+      "name": "mcp-client-kit",
+      "displayName": "mcp-client-kit",
+      "source": "./",
+      "version": "0.1.0",
+      "description": "Generate typed Python wrappers for any MCP server (skill: generate-mcp-wrappers).",
+      "author": {
+        "name": "Sviatoslav Sviridov",
+        "email": "sviridov@gmail.com"
+      },
+      "keywords": ["mcp", "codegen", "typed-wrappers", "python", "oauth"],
+      "license": "MIT"
+    }
+  ]
+}

mcp_client_kit-0.0.3/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "mcp-client-kit",
+  "description": "mcpgen — generate typed Python wrappers for MCP servers (codegen skill + CLI).",
+  "version": "0.1.0"
+}

mcp_client_kit-0.0.3/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        run: uv run pytest
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Lint (ruff check)
+        run: uv run ruff check .
+
+      - name: Format (ruff format)
+        run: uv run ruff format --check .
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Type check (mypy)
+        run: uv run mypy mcpgen

mcp_client_kit-0.0.3/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish engine to PyPI
+
+# Fires only on bare engine tags (vX.Y.Z). 'plugin-v*' tags never publish.
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]+"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi          # must match the PyPI Trusted Publisher config
+    permissions:
+      id-token: write          # OIDC token for Trusted Publishing (no API token needed)
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Verify tag matches package version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          pkg=$(grep -m1 -E '^version *= *"' pyproject.toml | sed -E 's/.*"(.*)".*/\1/')
+          if [ "$tag" != "$pkg" ]; then
+            echo "Tag v$tag does not match pyproject version $pkg"; exit 1
+          fi
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check dist/*
+
+      - name: Publish to PyPI (Trusted Publishing)
+        run: uv publish --trusted-publishing always

mcp_client_kit-0.0.3/.gitignore

@@ -0,0 +1,11 @@
+deep-research-wf_*.js
+*.probe-raw.json
+*.verify.json
+*.shapes.json.parts/
+*.pyc
+__pycache__/
+.venv/
+.mcp.json
+eval_preflight.py
+eval/
+.codegraph/

mcp_client_kit-0.0.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sviatoslav Sviridov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_client_kit-0.0.3/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: mcp-client-kit
+Version: 0.0.3
+Summary: mcpgen — 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
+Project-URL: Issues, https://github.com/svd/mcp-client-kit/issues
+Author-email: Sviatoslav Sviridov <sviridov@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28
+Requires-Dist: keyring>=24
+Requires-Dist: mcp[cli]<2,>=1.27
+Description-Content-Type: text/markdown
+
+# mcpgen
+
+**Write your MCP server wrappers once — from the live server. Keep them as real Python source you can diff, review, and pin.**
+
+`mcpgen` turns any MCP server into a typed Python module: one `async def` per tool, real return types, no live server needed to read it. Call your tools from code instead of pumping their schemas through the model's context — the pattern Anthropic measured at up to **98% token reduction**.
+
+> Two artifacts, one repo: a **CLI** (`mcpgen`) you run anywhere, and a **Claude Code plugin** (`generate-mcp-wrappers` skill) that drives it for the parts that need judgment.
+
+---
+
+## The problem
+
+MCP tool schemas eat your context window before the agent does any work.
+
+Every tool definition costs **300–600 tokens** for its name, description, and JSON schema. That adds up fast:
+
+- The **GitHub MCP server alone** burns ~55,000 tokens across its 93 tools.
+- One developer measured **66,000 tokens consumed at conversation start** — a third of a 200k window, gone before the first query.
+- A SaaS server with 50+ endpoints can spend **30,000+ tokens just describing what it *could* do.**
+
+Anthropic's validated fix ("Code execution with MCP," Nov 2025): stop routing schemas through the model. Generate wrapper code and call the tools from code instead — an approach Anthropic measured shrinking one workflow from ~150,000 tokens to ~2,000 (**98.7%**), with independent benchmarks landing around **78–85%** on less extreme workloads.
+
+The catch for Python teams: no good tool generated **standalone, importable, reviewable `.py` wrappers** from a live MCP server. So everyone hand-writes `jira.py`, `github.py`, `slack.py` — slowly, inconsistently, and they silently rot when the server changes.
+
+That's the gap mcpgen fills.
+
+---
+
+## What you get
+
+```bash
+uv tool install mcp-client-kit          # puts `mcpgen` on your PATH
+mcpgen login github                     # browser OAuth, tokens persisted
+mcpgen codegen github --out github.py   # typed wrappers for every tool
+```
+
+```python
+import asyncio
+from mcpgen import McpBridgeCaller
+import github  # the file you just generated
+
+async def main():
+    caller = McpBridgeCaller(url="https://api.githubcopilot.com/mcp/")
+    me = await github.get_me(caller)                                  # -> GitHubUser
+    issues = await github.list_issues(caller, owner="octocat", repo="hello-world")
+    print(me, issues)
+
+asyncio.run(main())
+```
+
+`github.py` is just Python. Open it in your IDE, review it in a PR, pin it to a commit, ship it. No runtime proxy, no framework lock-in, no live server required to read what your tools return.
+
+---
+
+## Why developers pick it
+
+**Real source you own.** Importable `.py` modules — not `.pyi` stubs (mcp2py), not a runtime proxy, not tied to one execution framework (ipybox). You can diff it, review it, pin it, and read it in your IDE without a server running.
+
+**Types that match reality.** A tool's `inputSchema` describes its *inputs* — it tells you nothing about the *output* shape. mcpgen's `--probe` makes one live call and records the actual response, so your return types reflect what the server really sends. No other generator does this.
+
+**OAuth that survives restarts.** Pre-flight token refresh means a fresh process renews a near-expired token silently from the refresh token — no surprise browser pop-up at cold start. (The official SDK's canonical example is in-memory only; every restart re-authenticates.)
+
+**Swap auth without regenerating.** Every wrapper takes an `McpCaller` as its first argument. Change transports or auth backends — bearer, OAuth, stdio, a fake for tests — without touching the generated code.
+
+**Built for production teams.** Works with any MCP server (HTTP URL, stdio, or bearer/PAT). Generated code lives in git like any other module, so it survives code review, audits, and pinning.
+
+---
+
+## How it works
+
+| Step | Command | What happens |
+|------|---------|--------------|
+| 1. Generate | `mcpgen codegen <server> --out <server>.py` | One typed `async def` per tool. |
+| 2. Probe (optional) | `mcpgen probe <server> <tool> --args '{}' --emit-shape <server>.shapes.json` | Records the *real* response shape from a live call. |
+| 3. Regenerate | `mcpgen codegen <server> --out <server>.py --shapes <server>.shapes.json` | Wrappers now return precise types (`TypedDict`s, unions, lists). |
+
+Polymorphic tools — ones that return different shapes depending on an input (`entityType=1` → `Person`, `=2` → `Position`) — get typed `@overload`s, so your type checker narrows the return at every call site.
+
+The full reference, including the shape-spec format and credential backends, is in [`doc/USAGE.md`](doc/USAGE.md).
+
+---
+
+## Install
+
+> The PyPI package is **`mcp-client-kit`**; the command it installs is **`mcpgen`**.
+
+**CLI on your PATH:**
+
+```bash
+uv tool install mcp-client-kit
+```
+
+**One-off, no install:**
+
+```bash
+uvx --from mcp-client-kit mcpgen codegen <server> --out <server>.py
+```
+
+**As a project dependency:**
+
+```bash
+uv add mcp-client-kit      # or: pip install mcp-client-kit
+```
+
+Requires Python 3.11+.
+
+---
+
+## Claude Code plugin
+
+The plugin bundles the `generate-mcp-wrappers` skill, which drives the CLI through the 20% that needs judgment — curating which tools matter, probing live responses, and editing the shape-spec — then regenerates and verifies the module.
+
+The CLI is not bundled with the plugin — install it separately (`uv add mcp-client-kit`, see [Install](#install) above). The skill requires **mcpgen >= 0.1.0** and checks this before running; a local editable install (`uv pip install -e .`) satisfies it for development. This is a version floor, not an exact pin, so the skill and CLI can be upgraded independently as long as the CLI stays at or above the floor.
+
+```
+/plugin marketplace add svd/mcpgen
+/mcp-client-kit:generate-mcp-wrappers
+```
+
+A companion skill, `generate-mcp-runner`, writes a standalone smoke-test `run.py` that exercises the generated wrappers end-to-end.
+
+---
+
+## Command reference
+
+| 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. |
+| `probe <server> <tool>` | Live call(s) → response-shape skeleton. |
+| `call <server> <tool> --out <p>` | One live call, raw payload to disk — bootstrap ids or inspect output. |
+| `merge <server>` | Consolidate probe parts into `<server>.shapes.json`. |
+| `login <server>` | Browser OAuth login; tokens stored at `~/.mcpgen/credentials.json`. |
+| `migrate-creds` | Move stored OAuth tokens between `file` / `keyring` backends. |
+| `discover` | List MCP servers configured in your installed agent hosts. |
+
+Full workflow and flags: [`doc/USAGE.md`](doc/USAGE.md).
+
+---
+
+## Authentication
+
+```bash
+mcpgen login <server>                              # OAuth (most servers)
+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.
+
+---
+
+## Who it's for
+
+Python developers building AI agent pipelines on MCP servers — especially Claude Code users who've already hand-written at least one `<server>.py` wrapper and felt the pain. And platform teams running multi-server MCP environments where token cost and auth reliability are production concerns.
+
+If you write your agent logic in Python and want generated tool wrappers you can actually own — review, pin, and keep in git — this is built for you.
+
+---
+
+## Docs
+
+- [`doc/USAGE.md`](doc/USAGE.md) — full end-user guide: install paths, server config, auth, the shape-spec, and calling generated wrappers.
+- [`doc/RUNNING_LOCALLY.md`](doc/RUNNING_LOCALLY.md) — run from a local clone without installing.
+
+## Status
+
+Early access (`v0.x`). The codegen engine, OAuth persistence, live-probe shaping, and both Claude Code skills are working today. On the roadmap: `--check` drift mode, so CI can flag when a server's tools change out from under your wrappers.
+
+## License
+
+MIT.

mcp_client_kit-0.0.3/README.md

@@ -0,0 +1,172 @@
+# mcpgen
+
+**Write your MCP server wrappers once — from the live server. Keep them as real Python source you can diff, review, and pin.**
+
+`mcpgen` turns any MCP server into a typed Python module: one `async def` per tool, real return types, no live server needed to read it. Call your tools from code instead of pumping their schemas through the model's context — the pattern Anthropic measured at up to **98% token reduction**.
+
+> Two artifacts, one repo: a **CLI** (`mcpgen`) you run anywhere, and a **Claude Code plugin** (`generate-mcp-wrappers` skill) that drives it for the parts that need judgment.
+
+---
+
+## The problem
+
+MCP tool schemas eat your context window before the agent does any work.
+
+Every tool definition costs **300–600 tokens** for its name, description, and JSON schema. That adds up fast:
+
+- The **GitHub MCP server alone** burns ~55,000 tokens across its 93 tools.
+- One developer measured **66,000 tokens consumed at conversation start** — a third of a 200k window, gone before the first query.
+- A SaaS server with 50+ endpoints can spend **30,000+ tokens just describing what it *could* do.**
+
+Anthropic's validated fix ("Code execution with MCP," Nov 2025): stop routing schemas through the model. Generate wrapper code and call the tools from code instead — an approach Anthropic measured shrinking one workflow from ~150,000 tokens to ~2,000 (**98.7%**), with independent benchmarks landing around **78–85%** on less extreme workloads.
+
+The catch for Python teams: no good tool generated **standalone, importable, reviewable `.py` wrappers** from a live MCP server. So everyone hand-writes `jira.py`, `github.py`, `slack.py` — slowly, inconsistently, and they silently rot when the server changes.
+
+That's the gap mcpgen fills.
+
+---
+
+## What you get
+
+```bash
+uv tool install mcp-client-kit          # puts `mcpgen` on your PATH
+mcpgen login github                     # browser OAuth, tokens persisted
+mcpgen codegen github --out github.py   # typed wrappers for every tool
+```
+
+```python
+import asyncio
+from mcpgen import McpBridgeCaller
+import github  # the file you just generated
+
+async def main():
+    caller = McpBridgeCaller(url="https://api.githubcopilot.com/mcp/")
+    me = await github.get_me(caller)                                  # -> GitHubUser
+    issues = await github.list_issues(caller, owner="octocat", repo="hello-world")
+    print(me, issues)
+
+asyncio.run(main())
+```
+
+`github.py` is just Python. Open it in your IDE, review it in a PR, pin it to a commit, ship it. No runtime proxy, no framework lock-in, no live server required to read what your tools return.
+
+---
+
+## Why developers pick it
+
+**Real source you own.** Importable `.py` modules — not `.pyi` stubs (mcp2py), not a runtime proxy, not tied to one execution framework (ipybox). You can diff it, review it, pin it, and read it in your IDE without a server running.
+
+**Types that match reality.** A tool's `inputSchema` describes its *inputs* — it tells you nothing about the *output* shape. mcpgen's `--probe` makes one live call and records the actual response, so your return types reflect what the server really sends. No other generator does this.
+
+**OAuth that survives restarts.** Pre-flight token refresh means a fresh process renews a near-expired token silently from the refresh token — no surprise browser pop-up at cold start. (The official SDK's canonical example is in-memory only; every restart re-authenticates.)
+
+**Swap auth without regenerating.** Every wrapper takes an `McpCaller` as its first argument. Change transports or auth backends — bearer, OAuth, stdio, a fake for tests — without touching the generated code.
+
+**Built for production teams.** Works with any MCP server (HTTP URL, stdio, or bearer/PAT). Generated code lives in git like any other module, so it survives code review, audits, and pinning.
+
+---
+
+## How it works
+
+| Step | Command | What happens |
+|------|---------|--------------|
+| 1. Generate | `mcpgen codegen <server> --out <server>.py` | One typed `async def` per tool. |
+| 2. Probe (optional) | `mcpgen probe <server> <tool> --args '{}' --emit-shape <server>.shapes.json` | Records the *real* response shape from a live call. |
+| 3. Regenerate | `mcpgen codegen <server> --out <server>.py --shapes <server>.shapes.json` | Wrappers now return precise types (`TypedDict`s, unions, lists). |
+
+Polymorphic tools — ones that return different shapes depending on an input (`entityType=1` → `Person`, `=2` → `Position`) — get typed `@overload`s, so your type checker narrows the return at every call site.
+
+The full reference, including the shape-spec format and credential backends, is in [`doc/USAGE.md`](doc/USAGE.md).
+
+---
+
+## Install
+
+> The PyPI package is **`mcp-client-kit`**; the command it installs is **`mcpgen`**.
+
+**CLI on your PATH:**
+
+```bash
+uv tool install mcp-client-kit
+```
+
+**One-off, no install:**
+
+```bash
+uvx --from mcp-client-kit mcpgen codegen <server> --out <server>.py
+```
+
+**As a project dependency:**
+
+```bash
+uv add mcp-client-kit      # or: pip install mcp-client-kit
+```
+
+Requires Python 3.11+.
+
+---
+
+## Claude Code plugin
+
+The plugin bundles the `generate-mcp-wrappers` skill, which drives the CLI through the 20% that needs judgment — curating which tools matter, probing live responses, and editing the shape-spec — then regenerates and verifies the module.
+
+The CLI is not bundled with the plugin — install it separately (`uv add mcp-client-kit`, see [Install](#install) above). The skill requires **mcpgen >= 0.1.0** and checks this before running; a local editable install (`uv pip install -e .`) satisfies it for development. This is a version floor, not an exact pin, so the skill and CLI can be upgraded independently as long as the CLI stays at or above the floor.
+
+```
+/plugin marketplace add svd/mcpgen
+/mcp-client-kit:generate-mcp-wrappers
+```
+
+A companion skill, `generate-mcp-runner`, writes a standalone smoke-test `run.py` that exercises the generated wrappers end-to-end.
+
+---
+
+## Command reference
+
+| 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. |
+| `probe <server> <tool>` | Live call(s) → response-shape skeleton. |
+| `call <server> <tool> --out <p>` | One live call, raw payload to disk — bootstrap ids or inspect output. |
+| `merge <server>` | Consolidate probe parts into `<server>.shapes.json`. |
+| `login <server>` | Browser OAuth login; tokens stored at `~/.mcpgen/credentials.json`. |
+| `migrate-creds` | Move stored OAuth tokens between `file` / `keyring` backends. |
+| `discover` | List MCP servers configured in your installed agent hosts. |
+
+Full workflow and flags: [`doc/USAGE.md`](doc/USAGE.md).
+
+---
+
+## Authentication
+
+```bash
+mcpgen login <server>                              # OAuth (most servers)
+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.
+
+---
+
+## Who it's for
+
+Python developers building AI agent pipelines on MCP servers — especially Claude Code users who've already hand-written at least one `<server>.py` wrapper and felt the pain. And platform teams running multi-server MCP environments where token cost and auth reliability are production concerns.
+
+If you write your agent logic in Python and want generated tool wrappers you can actually own — review, pin, and keep in git — this is built for you.
+
+---
+
+## Docs
+
+- [`doc/USAGE.md`](doc/USAGE.md) — full end-user guide: install paths, server config, auth, the shape-spec, and calling generated wrappers.
+- [`doc/RUNNING_LOCALLY.md`](doc/RUNNING_LOCALLY.md) — run from a local clone without installing.
+
+## Status
+
+Early access (`v0.x`). The codegen engine, OAuth persistence, live-probe shaping, and both Claude Code skills are working today. On the roadmap: `--check` drift mode, so CI can flag when a server's tools change out from under your wrappers.
+
+## License
+
+MIT.

mcp_client_kit-0.0.3/doc/CODEGEN_SKILL_IDEA.md

@@ -0,0 +1,73 @@
+# Idea 2: Claude Code skill that generates typed Python wrappers for any MCP server
+
+## What it would do
+
+Given an MCP server (URL or local command), the skill:
+
+1. Connects via the extracted client library, calls `tools/list`.
+2. For each tool, reads `name`, `description`, `inputSchema` (JSON Schema).
+3. Generates a module like `acme.py`: one `async def` per tool, typed
+   arguments derived from the schema, docstring from the description,
+   `parse_tool_result` unwrapping.
+4. Optionally probes one real call per tool (with user-supplied sample args)
+   to record the actual response shape — the key lesson: schemas describe
+   *inputs* well, but response shapes need empirical validation.
+5. Writes a `servers.toml` entry (URL, verify tool, auth mode) so the
+   generated module is runnable immediately.
+
+## Why a skill and not a pure codegen CLI
+
+Two-phase reality:
+
+- **Deterministic part** (tools/list → function stubs) could be a plain
+  `mcpgen codegen` CLI command — no LLM needed. This should live in the
+  library, not the skill.
+- **Judgment part** (which fields to project, how to unwrap vendor envelopes,
+  which tools matter for the user's pipeline, sample-call validation) needs an
+  LLM in the loop. That's the skill: it drives the CLI, probes live responses,
+  and edits the generated code to match observed shapes.
+
+Recommended split: CLI generates 80% mechanically; skill does the empirical
+validation pass and trims/curates. This mirrors how the origin project evolved
+(projections were validated one by one against live responses).
+
+## Token-economics argument (why colleagues should care)
+
+The pattern this enables — confirmed by the landscape research (see
+LANDSCAPE.md): "code execution with MCP" — LLM writes/uses code that calls
+tools, instead of tool schemas + tool results flowing through the model
+context every time.
+
+The origin project as case study: stages 1–4 moved from LLM tool-calls to
+Python, eliminating per-record JSON payloads (100–500 KB each) from model
+context entirely.
+
+## Locked architecture: the client seam (2026-06-14)
+
+Generated wrappers depend on an **injected client Protocol**, never a concrete
+import. This keeps generated modules reusable for colleagues and lets the auth
+backend swap without regenerating:
+
+```python
+from typing import Any, Protocol
+
+class McpCaller(Protocol):
+    async def call(self, server: str, tool: str, arguments: dict) -> Any: ...
+```
+
+Each generated `async def` takes the caller as its first argument and forwards to
+`caller.call(SERVER, "<tool>", {...})`. Behind the seam today sits `mcpgen/_bridge.py` over the official `mcp`
+SDK (`ClientSession` + `streamablehttp_client`). FastMCP was evaluated and
+rejected as the backend. Wrappers don't change. See VERDICT.md §Correction.
+
+## Risks specific to the skill
+
+- **Schema drift**: generated wrappers go stale when the server changes.
+  Mitigation: `mcpgen codegen --check` mode that re-lists tools and diffs
+  against generated code; CI-able.
+- **Response-shape assumptions**: generation from inputSchema alone produces
+  wrappers that lie about outputs. Mitigation: validation pass is mandatory in
+  the skill procedure, optional in CLI.
+- **Auth variance**: corporate servers (OAuth PKCE) vs local stdio servers vs
+  API-key headers. Library must support all three before the skill can claim
+  "any MCP server".