Move proxy to magg.proxy package, remove client.runner

- Create magg.proxy package with server/client/mixin modules
- Remove client.runner - use FastMCPTransport directly
- Rename ServerRunner to MAGGRunner with signal handling
- Update fix_whitespace.py to walk directories itself

Tests pass unchanged.

Signed-off-by: Phillip Sitbon <phillip.sitbon@gmail.com>

Author: sitbon

docs/proxy-spec.md

@@ -8,6 +8,8 @@
 
 This specification defines the Model Context Protocol (MCP) Proxy Extension, which enables dynamic access to MCP capabilities through a single, unified tool interface. The proxy pattern allows MCP servers to aggregate, gateway, and dynamically expose capabilities from other servers without requiring clients to manage multiple connections.
 
+This specification is based on the implementation in MAGG (MCP Aggregator) and serves as a reference for other MCP servers that want to implement similar proxy functionality. The reference implementation can be found in the `magg.proxy` package.
+
 ## 1. Introduction
 
 The MCP Proxy Extension provides a standardized way for MCP servers to expose capabilities from other servers through a single tool. This enables powerful aggregation scenarios while maintaining the simplicity of the MCP protocol.
@@ -395,6 +397,21 @@ Response (tool result):
 - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
 - [MAGG Implementation](https://github.com/sitbon/magg)
 
+## 12. Reference Implementation
+
+The reference implementation in MAGG includes:
+
+1. **Server-side proxy** (`magg/proxy/server.py` and `magg/proxy/mixin.py`):
+   - `ProxyFastMCP` wrapper class that adds proxy capabilities to FastMCP instances
+   - `ProxyMCP` mixin class for servers that want built-in proxy support
+   - Automatic tool registration and capability aggregation
+   - Result transformation and annotation
+
+2. **Client-side wrapper** (`magg/proxy/client.py`):
+   - `ProxyClient` class that provides transparent access to proxied servers
+   - Automatic result unwrapping and type conversion
+   - Lazy connection management
+
 ## Appendix A: Future Considerations
 
 ### A.1 Batch Operations

docs/proxy.md

@@ -136,7 +136,7 @@ All call results include annotations with:
 MAGG provides a `ProxyClient` class that simplifies interaction with proxy-enabled servers:
 
 ```python
-from magg.client.proxy import ProxyClient
+from magg.proxy.client import ProxyClient
 
 # Create a proxy-aware client
 async with ProxyClient("http://localhost:8080/mcp") as client:
@@ -205,7 +205,7 @@ All transparent methods handle result transformation automatically using the tra
 
 ## Server Implementation
 
-MAGG's proxy server implementation (`ProxyMCP` mixin) provides:
+MAGG's proxy server implementation provides:
 
 1. **Self-introspection**: Server can list its own capabilities via FastMCPTransport
 2. **Result transformation**: Automatic conversion between MCP types
@@ -214,12 +214,26 @@ MAGG's proxy server implementation (`ProxyMCP` mixin) provides:
 
 ### Key Classes
 
+#### `ProxyFastMCP`
+
+A wrapper class that adds proxy functionality to FastMCP instances:
+
+```python
+from magg.proxy.server import ProxyFastMCP
+from fastmcp import FastMCP
+
+# Wrap an existing FastMCP instance
+mcp = FastMCP(name="my-server")
+proxy_mcp = ProxyFastMCP(mcp)
+```
+
 #### `ProxyMCP`
 
-A mixin class that adds proxy functionality to MCP servers:
+A mixin class that servers can inherit from:
 
 ```python
-from magg.server.proxy import ProxyMCP, ManagedServer
+from magg.proxy.mixin import ProxyMCP
+from magg.server.manager import ManagedServer
 
 class MyAggregator(ManagedServer, ProxyMCP):
     def __init__(self):
@@ -233,7 +247,7 @@ class MyAggregator(ManagedServer, ProxyMCP):
 Metadata extracted from proxy response annotations:
 
 ```python
-from magg.server.proxy import ProxyResponseInfo
+from magg.proxy.server import ProxyResponseInfo
 
 # Extract metadata from annotations
 info = ProxyResponseInfo.from_annotations(result.annotations)
@@ -275,7 +289,7 @@ MAGG provides transform utilities for working with proxy results:
 from magg.util.transform import (
     tool_result_as_prompt_result,
     tool_result_as_resource_result,
-    embedded_resource_python_object,
+    get_embedded_resource_python_object,
     deserialize_embedded_resource_python_object
 )
 
@@ -286,7 +300,7 @@ prompt_result = tool_result_as_prompt_result(tool_result)
 resource_result = tool_result_as_resource_result(tool_result)
 
 # Get metadata from embedded resource
-python_type, json_data, many = embedded_resource_python_object(embedded_resource)
+python_type, json_data, many = get_embedded_resource_python_object(embedded_resource)
 
 # Deserialize to proper MCP types
 obj = deserialize_embedded_resource_python_object(

magg/__init__.py

@@ -8,3 +8,5 @@
     __version__ = metadata.version("magg")
 except metadata.PackageNotFoundError:
     __version__ = "unknown"
+
+del metadata

magg/cli.py

@@ -11,7 +11,7 @@
 from . import __version__, process
 from .settings import ConfigManager, ServerConfig
 from .util.terminal import (
-    print_success, print_error, print_warning,
+    print_success, print_error, print_warning, print_startup_banner,
     print_info, print_server_list, print_status_summary, confirm_action
 )
 
@@ -23,15 +23,14 @@
 
 async def cmd_serve(args) -> None:
     """Start MAGG server."""
-    from magg.server.runner import print_startup_banner
-    from magg.server.runner import ServerRunner
+    from magg.server.runner import MAGGRunner
 
     logger.info("Starting MAGG server (mode: %s)", 'http' if args.http else 'stdio')
 
     if args.http:
         print_startup_banner()
 
-    runner = ServerRunner(args.config)
+    runner = MAGGRunner(args.config)
 
     if args.http:
         logger.info("Starting HTTP server on %s:%s", args.host, args.port)
@@ -363,7 +362,7 @@ def main():
         sys.exit(130)  # Standard exit code for SIGINT
     except Exception as e:
         print_error(f"Unexpected error: {e}")
-        if os.getenv('MAGG_DEBUG').lower() in {'1', 'true', 'yes'}:
+        if os.getenv('MAGG_DEBUG', '').lower() in {'1', 'true', 'yes'}:
             import traceback
             traceback.print_exc()
         sys.exit(1)

magg/client/__init__.py

@@ -1,10 +1,2 @@
 """Client utilities for running MAGG alongside user applications.
 """
-# from .runner import MAGGRunner, ConnectionInfo
-# from .proxy import ProxyClient
-#
-# __all__ = [
-#     "MAGGRunner",
-#     "ConnectionInfo",
-#     "ProxyClient",
-# ]