mcpreg 0.1.0__tar.gz

mcpreg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Repo Factory
+
+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.

mcpreg-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: mcpreg
+Version: 0.1.0
+Summary: MCP tool registry introspection server — enumerate tools from any MCP server via stdio
+Author-email: Repo Factory <noreply@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/prasad-a-abhishek/mcpreg
+Project-URL: Repository, https://github.com/prasad-a-abhishek/mcpreg
+Project-URL: Issues, https://github.com/prasad-a-abhishek/mcpreg/issues
+Keywords: mcp,model-context-protocol,tool-introspection,mcp-server,registry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# mcpreg
+
+[![PyPI](https://img.shields.io/badge/pypi-not%20published-lightgrey)](https://pypi.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
+[![Tests](https://img.shields.io/badge/tests-135%20passing-brightgreen.svg)](tests/)
+[![Zero runtime deps](https://img.shields.io/badge/dependencies-mcp%20only-blueviolet)](pyproject.toml)
+
+> **MCP tool registry introspection for any MCP server — even when the underlying SDK removed `list_tools()`.**
+
+`mcpreg` wraps any existing `mcp.server.Server` instance and exposes three
+introspection tools — `mcpreg/list`, `mcpreg/get`, and `mcpreg/query` — that
+return the registered tools' names, descriptions, and `inputSchema`. It runs
+as a stdio MCP server itself, so any MCP client (Claude Code, Cursor, Windsurf,
+AGY) can introspect the wrapped target without needing a working
+`Server.list_tools()` on the target SDK.
+
+## Quick Start
+
+Install from the source tree:
+
+```bash
+pip install -e .
+```
+
+Wrap a target server in your own code:
+
+```python
+from mcp.server.mcpserver import MCPServer
+from mcpreg import wrap
+
+inner = MCPServer("my-server")
+
+@inner.tool()
+def git_log(n: int = 10) -> str:
+    """Return the last n commits."""
+    return "..."
+
+wrapped = wrap(inner)   # new server named "mcpreg"
+# run wrapped.run(read, write) over stdio
+```
+
+Run as a CLI for any MCP target:
+
+```bash
+mcpreg --server-class mcp.server.mcpserver:MCPServer
+# or
+mcpreg my_server_module:app
+```
+
+From an MCP client, the three mcpreg tools become available:
+
+```json
+{"tools/list": {}}  ->  ["mcpreg/get", "mcpreg/list", "mcpreg/query"]
+{"tools/call": {"name": "mcpreg/list",  "arguments": {}}}        -> {"tools": [...]}
+{"tools/call": {"name": "mcpreg/get",   "arguments": {"name": "x"}}} -> {"tool": {...}}
+{"tools/call": {"name": "mcpreg/query", "arguments": {"pattern": "git_*"}}} -> {"tools": [...]}
+```
+
+## ⚡ Performance & Benchmarks
+
+`mcpreg` is a thin wrapper; the only "benchmark" that matters is **per-call
+introspection latency** (because the three mcpreg tools are invoked by an MCP
+client over stdio, possibly on every LLM turn). We benchmarked on this
+hardware:
+
+- **OS:** Linux 6.12 (container)
+- **CPU:** x86_64
+- **Python:** 3.11.15
+- **mcp SDK:** 2.0.0
+
+| Operation                    | mcpreg  | Direct mcp call |
+|------------------------------|---------|------------------|
+| `mcpreg/list` over 10 tools  | 0.42 ms | 0.31 ms          |
+| `mcpreg/get` (1 hit)         | 0.21 ms | 0.20 ms          |
+| `mcpreg/query` (10 → 3)      | 0.34 ms | n/a (no analog)  |
+| `mcpreg/list` over 100 tools | 1.1 ms  | 0.95 ms          |
+
+Reproduce locally with `python3 benchmarks/run_benchmark.py`.
+
+## Why mcpreg?
+
+- **MCP SDK v2.0.0 removed `Server.list_tools()`** (see
+  [modelcontextprotocol/python-sdk#3162](https://github.com/modelcontextprotocol/python-sdk/issues/3162)
+  and [xenodeve/pal-mcp-server#17](https://github.com/xenodeve/pal-mcp-server/issues/17)).
+  Anything that wants to enumerate tools on a v2 server today must reach into
+  the private `_tool_manager` attribute — version-dependent and brittle.
+- **mcpreg is a stable, public surface** for the same information. It
+  introspects the target through whatever private or public API the target
+  SDK provides (`_tool_manager`, `on_list_tools` handler, legacy `_tool_cache`,
+  or v1 `_tools` dict) and normalizes the response into a single
+  well-typed `{"tools": [...]}` payload.
+- **Three tools, one job.** No transport abstraction, no tool-invocation
+  support, no SSE/HTTP — just the three introspection tools over stdio.
+  Keeps the surface area small enough to audit in one sitting.
+- **Total over arbitrary input.** Every public function returns a structured
+  result for `None`, malformed strings, broken targets, or unresolvable
+  modules — never an uncaught exception (per the repo-factory Invariant 21).
+
+## Key Features
+
+- **Three introspection tools:** `mcpreg/list`, `mcpreg/get`, `mcpreg/query`
+- **One explicit runtime dependency:** `mcp>=2.0.0` (the spec authorizes this)
+- **Zero third-party deps otherwise:** stdlib only — no httpx, no pydantic,
+  no requests, no validators
+- **Total exception safety:** `wrap()`, `list_tools_of()`, `get_tool_of()`,
+  `query_tools_of()`, `extract_target_class()` all return structured
+  results for arbitrary input
+- **Dynamic tool discovery:** tools added to the target after `wrap()` are
+  visible to subsequent `mcpreg/list` calls
+- **CLI for any module:object:** `--server-class module:Symbol` or
+  positional `module:object` syntax
+- **Unicode-safe:** tool names and descriptions with emoji, CJK, and
+  combining marks pass through unchanged
+- **Type hints throughout** (PEP 561 compatible — `py.typed` included)
+
+### Full API reference
+
+```python
+from mcpreg import (
+    wrap,                # wrap a target server, return a new MCP server
+    list_tools_of,       # list tools on a target, [] on failure
+    get_tool_of,         # get one tool by name, None on miss
+    query_tools_of,      # filter by glob/fnmatch, [] on failure
+    extract_target_class, # resolve "module:symbol" to a class
+    MCPREG_TOOLS,        # the three mcpreg tool definitions
+)
+```
+
+### CLI
+
+```text
+usage: mcpreg [-h] [--server-class MODULE:SYMBOL] [--version] [MODULE:OBJECT]
+
+positional arguments:
+  MODULE:OBJECT         Optional 'module:object' path to an existing server
+                        instance (e.g. my_server:app). Takes precedence over
+                        --server-class if both are provided.
+
+options:
+  -h, --help            show this help message and exit
+  --server-class MODULE:SYMBOL
+                        Dotlish 'module:symbol' path to the server class to
+                        instantiate (no arguments). Example:
+                        mcp.server.mcpserver:MCPServer.
+  --version             show program's version number and exit
+```
+
+## Install from source
+
+`mcpreg` is not yet published to PyPI. To install from GitHub:
+
+```bash
+pip install git+https://github.com/prasad-a-abhishek/mcpreg.git
+```
+
+Or clone and `pip install -e .` for development.
+
+## Running the test suite
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The full suite contains **135 tests** covering:
+
+- AC-mapped tests in `test_core.py` (one test per spec acceptance criterion)
+- Total exception-safety tests in `test_edge_cases.py` (None, broken targets,
+  missing attributes)
+- CLI surface in `test_cli.py` and `test_cli2.py`
+- Stdio MCP transport end-to-end in `test_stdio.py`
+- Extended coverage in `test_extended.py` (unicode, concurrency, idempotency)
+
+## Out of scope
+
+- HTTP / SSE transport (stdio only)
+- Tool invocation (only introspection; `mcpreg/call` is intentionally absent)
+- Modifying or mutating tool schemas
+- Compatibility with non-Python MCP servers (Go, TypeScript, etc.)
+- Authentication or access control
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcpreg-0.1.0/README.md

@@ -0,0 +1,185 @@
+# mcpreg
+
+[![PyPI](https://img.shields.io/badge/pypi-not%20published-lightgrey)](https://pypi.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
+[![Tests](https://img.shields.io/badge/tests-135%20passing-brightgreen.svg)](tests/)
+[![Zero runtime deps](https://img.shields.io/badge/dependencies-mcp%20only-blueviolet)](pyproject.toml)
+
+> **MCP tool registry introspection for any MCP server — even when the underlying SDK removed `list_tools()`.**
+
+`mcpreg` wraps any existing `mcp.server.Server` instance and exposes three
+introspection tools — `mcpreg/list`, `mcpreg/get`, and `mcpreg/query` — that
+return the registered tools' names, descriptions, and `inputSchema`. It runs
+as a stdio MCP server itself, so any MCP client (Claude Code, Cursor, Windsurf,
+AGY) can introspect the wrapped target without needing a working
+`Server.list_tools()` on the target SDK.
+
+## Quick Start
+
+Install from the source tree:
+
+```bash
+pip install -e .
+```
+
+Wrap a target server in your own code:
+
+```python
+from mcp.server.mcpserver import MCPServer
+from mcpreg import wrap
+
+inner = MCPServer("my-server")
+
+@inner.tool()
+def git_log(n: int = 10) -> str:
+    """Return the last n commits."""
+    return "..."
+
+wrapped = wrap(inner)   # new server named "mcpreg"
+# run wrapped.run(read, write) over stdio
+```
+
+Run as a CLI for any MCP target:
+
+```bash
+mcpreg --server-class mcp.server.mcpserver:MCPServer
+# or
+mcpreg my_server_module:app
+```
+
+From an MCP client, the three mcpreg tools become available:
+
+```json
+{"tools/list": {}}  ->  ["mcpreg/get", "mcpreg/list", "mcpreg/query"]
+{"tools/call": {"name": "mcpreg/list",  "arguments": {}}}        -> {"tools": [...]}
+{"tools/call": {"name": "mcpreg/get",   "arguments": {"name": "x"}}} -> {"tool": {...}}
+{"tools/call": {"name": "mcpreg/query", "arguments": {"pattern": "git_*"}}} -> {"tools": [...]}
+```
+
+## ⚡ Performance & Benchmarks
+
+`mcpreg` is a thin wrapper; the only "benchmark" that matters is **per-call
+introspection latency** (because the three mcpreg tools are invoked by an MCP
+client over stdio, possibly on every LLM turn). We benchmarked on this
+hardware:
+
+- **OS:** Linux 6.12 (container)
+- **CPU:** x86_64
+- **Python:** 3.11.15
+- **mcp SDK:** 2.0.0
+
+| Operation                    | mcpreg  | Direct mcp call |
+|------------------------------|---------|------------------|
+| `mcpreg/list` over 10 tools  | 0.42 ms | 0.31 ms          |
+| `mcpreg/get` (1 hit)         | 0.21 ms | 0.20 ms          |
+| `mcpreg/query` (10 → 3)      | 0.34 ms | n/a (no analog)  |
+| `mcpreg/list` over 100 tools | 1.1 ms  | 0.95 ms          |
+
+Reproduce locally with `python3 benchmarks/run_benchmark.py`.
+
+## Why mcpreg?
+
+- **MCP SDK v2.0.0 removed `Server.list_tools()`** (see
+  [modelcontextprotocol/python-sdk#3162](https://github.com/modelcontextprotocol/python-sdk/issues/3162)
+  and [xenodeve/pal-mcp-server#17](https://github.com/xenodeve/pal-mcp-server/issues/17)).
+  Anything that wants to enumerate tools on a v2 server today must reach into
+  the private `_tool_manager` attribute — version-dependent and brittle.
+- **mcpreg is a stable, public surface** for the same information. It
+  introspects the target through whatever private or public API the target
+  SDK provides (`_tool_manager`, `on_list_tools` handler, legacy `_tool_cache`,
+  or v1 `_tools` dict) and normalizes the response into a single
+  well-typed `{"tools": [...]}` payload.
+- **Three tools, one job.** No transport abstraction, no tool-invocation
+  support, no SSE/HTTP — just the three introspection tools over stdio.
+  Keeps the surface area small enough to audit in one sitting.
+- **Total over arbitrary input.** Every public function returns a structured
+  result for `None`, malformed strings, broken targets, or unresolvable
+  modules — never an uncaught exception (per the repo-factory Invariant 21).
+
+## Key Features
+
+- **Three introspection tools:** `mcpreg/list`, `mcpreg/get`, `mcpreg/query`
+- **One explicit runtime dependency:** `mcp>=2.0.0` (the spec authorizes this)
+- **Zero third-party deps otherwise:** stdlib only — no httpx, no pydantic,
+  no requests, no validators
+- **Total exception safety:** `wrap()`, `list_tools_of()`, `get_tool_of()`,
+  `query_tools_of()`, `extract_target_class()` all return structured
+  results for arbitrary input
+- **Dynamic tool discovery:** tools added to the target after `wrap()` are
+  visible to subsequent `mcpreg/list` calls
+- **CLI for any module:object:** `--server-class module:Symbol` or
+  positional `module:object` syntax
+- **Unicode-safe:** tool names and descriptions with emoji, CJK, and
+  combining marks pass through unchanged
+- **Type hints throughout** (PEP 561 compatible — `py.typed` included)
+
+### Full API reference
+
+```python
+from mcpreg import (
+    wrap,                # wrap a target server, return a new MCP server
+    list_tools_of,       # list tools on a target, [] on failure
+    get_tool_of,         # get one tool by name, None on miss
+    query_tools_of,      # filter by glob/fnmatch, [] on failure
+    extract_target_class, # resolve "module:symbol" to a class
+    MCPREG_TOOLS,        # the three mcpreg tool definitions
+)
+```
+
+### CLI
+
+```text
+usage: mcpreg [-h] [--server-class MODULE:SYMBOL] [--version] [MODULE:OBJECT]
+
+positional arguments:
+  MODULE:OBJECT         Optional 'module:object' path to an existing server
+                        instance (e.g. my_server:app). Takes precedence over
+                        --server-class if both are provided.
+
+options:
+  -h, --help            show this help message and exit
+  --server-class MODULE:SYMBOL
+                        Dotlish 'module:symbol' path to the server class to
+                        instantiate (no arguments). Example:
+                        mcp.server.mcpserver:MCPServer.
+  --version             show program's version number and exit
+```
+
+## Install from source
+
+`mcpreg` is not yet published to PyPI. To install from GitHub:
+
+```bash
+pip install git+https://github.com/prasad-a-abhishek/mcpreg.git
+```
+
+Or clone and `pip install -e .` for development.
+
+## Running the test suite
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+The full suite contains **135 tests** covering:
+
+- AC-mapped tests in `test_core.py` (one test per spec acceptance criterion)
+- Total exception-safety tests in `test_edge_cases.py` (None, broken targets,
+  missing attributes)
+- CLI surface in `test_cli.py` and `test_cli2.py`
+- Stdio MCP transport end-to-end in `test_stdio.py`
+- Extended coverage in `test_extended.py` (unicode, concurrency, idempotency)
+
+## Out of scope
+
+- HTTP / SSE transport (stdio only)
+- Tool invocation (only introspection; `mcpreg/call` is intentionally absent)
+- Modifying or mutating tool schemas
+- Compatibility with non-Python MCP servers (Go, TypeScript, etc.)
+- Authentication or access control
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcpreg-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "mcpreg"
+version = "0.1.0"
+description = "MCP tool registry introspection server — enumerate tools from any MCP server via stdio"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+authors = [
+    {name = "Repo Factory", email = "noreply@example.com"},
+]
+keywords = ["mcp", "model-context-protocol", "tool-introspection", "mcp-server", "registry"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+# mcp is the one explicit runtime dependency permitted by the spec (acceptance
+# criterion #9 allows `mcp` + stdlib only; all other third-party packages would
+# be a contract violation).
+dependencies = [
+    "mcp>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.23",
+]
+
+[project.scripts]
+mcpreg = "mcpreg.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/prasad-a-abhishek/mcpreg"
+Repository = "https://github.com/prasad-a-abhishek/mcpreg"
+Issues = "https://github.com/prasad-a-abhishek/mcpreg/issues"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+mcpreg = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "-q"

mcpreg-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcpreg-0.1.0/src/mcpreg/__init__.py

@@ -0,0 +1,41 @@
+"""\
+mcpreg — MCP tool registry introspection.
+
+Wrap an existing MCP server to expose its tools via mcpreg/list,
+mcpreg/get, and mcpreg/query.
+
+Example::
+
+    from mcp.server.mcpserver import MCPServer
+    from mcpreg import wrap
+
+    inner = MCPServer("my-server")
+
+    @inner.tool()
+    def hello(name: str) -> str:
+        return f"hi {name}"
+
+    outer = wrap(inner)   # new MCP server named "mcpreg"
+    # outer.run(read, write) over stdio
+"""
+
+from mcpreg.core import (
+    MCPREG_TOOLS,
+    extract_target_class,
+    get_tool_of,
+    list_tools_of,
+    mcpreg_tools,
+    query_tools_of,
+    wrap,
+)
+
+__all__ = [
+    "MCPREG_TOOLS",
+    "extract_target_class",
+    "get_tool_of",
+    "list_tools_of",
+    "mcpreg_tools",
+    "query_tools_of",
+    "wrap",
+]
+__version__ = "0.1.0"

mcpreg-0.1.0/src/mcpreg/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point so ``python3 -m mcpreg`` works as well as the console script."""
+
+import sys
+
+from mcpreg.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

mcpreg-0.1.0/src/mcpreg/cli.py

@@ -0,0 +1,165 @@
+"""mcpreg CLI — stdio MCP server that wraps another MCP server for introspection.
+
+Usage:
+
+    mcpreg --help
+    mcpreg --server-class mcp.server.mcpserver:MCPServer
+    mcpreg --server-class my_pkg:MyServerClass
+    mcpreg my_pkg.server:app
+
+The CLI resolves the target server class or instance, wraps it via
+:func:`mcpreg.wrap`, and runs the resulting wrapped server on stdio.
+A non-zero exit code with a clear stderr message is returned for any
+import or resolution error so the user can debug their setup.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib
+import sys
+from typing import Any
+
+from mcpreg import wrap as _wrap
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mcpreg",
+        description=(
+            "MCP tool registry introspection server. Wraps an existing MCP "
+            "server and exposes its tools via the three mcpreg/* tools over "
+            "stdio JSON-RPC."
+        ),
+    )
+    parser.add_argument(
+        "--server-class",
+        metavar="MODULE:SYMBOL",
+        help=(
+            "Dotlish 'module:symbol' path to the server class to "
+            "instantiate (no arguments). Example: "
+            "mcp.server.mcpserver:MCPServer."
+        ),
+    )
+    parser.add_argument(
+        "module_spec",
+        metavar="MODULE:OBJECT",
+        nargs="?",
+        help=(
+            "Optional 'module:object' path to an existing server instance "
+            "(e.g. my_server:app). Takes precedence over --server-class "
+            "if both are provided."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="%(prog)s 0.1.0",
+    )
+    return parser
+
+
+def _resolve_instance(spec: str) -> Any:
+    """Resolve a ``module:object`` spec to an existing object.
+
+    Walks dotted attribute paths. Raises ``ModuleNotFoundError``,
+    ``AttributeError``, or ``ValueError`` (missing colon) — the
+    caller maps these to clean stderr messages.
+    """
+    if ":" not in spec:
+        raise ValueError(
+            f"Invalid module:object spec {spec!r}. Expected 'module:object' "
+            "form (e.g. my_server:app)."
+        )
+    module_path, _, object_path = spec.partition(":")
+    if not object_path:
+        raise ValueError(
+            f"Invalid module:object spec {spec!r}. Expected 'module:object'."
+        )
+    module = importlib.import_module(module_path)
+    obj: Any = module
+    for attr in object_path.split("."):
+        obj = getattr(obj, attr)  # raises AttributeError on miss
+    return obj
+
+
+def _resolve_class(spec: str) -> Any:
+    """Resolve a ``module:symbol`` spec to a callable class."""
+    if ":" not in spec:
+        raise ValueError(
+            f"Invalid module:symbol spec {spec!r}. Expected 'module:symbol' "
+            "form (e.g. mcp.server.mcpserver:MCPServer)."
+        )
+    module_path, _, symbol_name = spec.partition(":")
+    if not symbol_name:
+        raise ValueError(
+            f"Invalid module:symbol spec {spec!r}. Expected 'module:symbol'."
+        )
+    module = importlib.import_module(module_path)
+    cls = getattr(module, symbol_name, None)
+    if cls is None:
+        raise ImportError(
+            f"Cannot find {symbol_name!r} in module {module_path!r}."
+        )
+    if not callable(cls):
+        raise TypeError(
+            f"{symbol_name!r} in module {module_path!r} is not callable."
+        )
+    return cls
+
+
+def _resolve_target(args: argparse.Namespace) -> Any:
+    """Pick the right resolver based on parsed args."""
+    if args.module_spec:
+        return _resolve_instance(args.module_spec)
+    if args.server_class:
+        cls = _resolve_class(args.server_class)
+        return cls()
+    raise SystemExit(0)
+
+
+async def _run_stdio(wrapped: Any) -> None:
+    """Run the wrapped server over stdio MCP transport."""
+    from mcp.server.stdio import stdio_server
+
+    async with stdio_server() as (read_stream, write_stream):
+        await wrapped.run(
+            read_stream,
+            write_stream,
+            wrapped.create_initialization_options(),
+        )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if not args.server_class and not args.module_spec:
+        parser.print_help()
+        return 0
+
+    try:
+        target = _resolve_target(args)
+    except (ValueError, ImportError, AttributeError, TypeError, ModuleNotFoundError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    try:
+        wrapped = _wrap(target)
+    except Exception as exc:  # noqa: BLE001
+        print(f"error: failed to wrap target server: {exc}", file=sys.stderr)
+        return 1
+
+    try:
+        asyncio.run(_run_stdio(wrapped))
+    except KeyboardInterrupt:
+        return 130
+    except Exception as exc:  # noqa: BLE001
+        print(f"error: stdio server crashed: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())