mcp-client-kit 0.0.3__py3-none-any.whl

mcp_client_kit-0.0.3.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+mcpgen/__init__.py,sha256=wGBjWIY7A2BsJRm45A_hbZCIJ4VKKSES-BwS9B743og,438
+mcpgen/_bridge.py,sha256=MtIIGi8P1f_CDOPhR2XaA2NXqWETRLCdDx2KaPSL0Ks,46457
+mcpgen/cli.py,sha256=AhweW2I2_fFcHV1quS418OTiVAOlo8YRl9Yrd6Od0fQ,33006
+mcpgen/codegen.py,sha256=05uQG_8Wi9vav6w65kS9Wl9xPXtgS2u6QQuYotiWkMQ,26894
+mcpgen/discovery.py,sha256=UGmuCJYuHUGfGUXXoUKwNXmYJujcOQjdYAmdcDU7R4M,16130
+mcpgen/seam.py,sha256=Fl3pddVNvGP-0XedeTGUGuvQRqVBtgz2sPlZrTTOLGE,620
+mcp_client_kit-0.0.3.dist-info/METADATA,sha256=nQHMK3yz1LxrhCaT-QzoiI1lPenSlpg_D_4L5MQ-KbQ,9316
+mcp_client_kit-0.0.3.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+mcp_client_kit-0.0.3.dist-info/entry_points.txt,sha256=JFrJbleWV3gemQ863IeTyIa6l5DbcJjOJsay183bSBw,43
+mcp_client_kit-0.0.3.dist-info/licenses/LICENSE,sha256=spQ0BfGkOfbfuyGqXAunPi6dQTgczXrQTHH1OlcSTJo,1076
+mcp_client_kit-0.0.3.dist-info/RECORD,,

mcp_client_kit-0.0.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_client_kit-0.0.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcpgen = mcpgen.cli:main

mcp_client_kit-0.0.3.dist-info/licenses/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.

mcpgen/__init__.py

@@ -0,0 +1,23 @@
+"""mcpgen: typed Python wrapper generator for MCP servers."""
+
+from mcpgen._bridge import (
+    McpBridgeCaller,
+    ReauthenticationRequired,
+    delete_cred,
+    ensure_login,
+    list_creds,
+    login,
+    migrate_creds,
+)
+from mcpgen.seam import McpCaller
+
+__all__ = [
+    "McpBridgeCaller",
+    "McpCaller",
+    "ReauthenticationRequired",
+    "delete_cred",
+    "ensure_login",
+    "list_creds",
+    "login",
+    "migrate_creds",
+]