zeromcp 0.1.0__py3-none-any.whl

zeromcp/__init__.py

@@ -0,0 +1,3 @@
+from .mcp import McpServer, McpToolError
+
+__all__ = ["McpServer", "McpToolError"]

zeromcp/jsonrpc.py

@@ -0,0 +1,223 @@
+import json
+import types
+import inspect
+import traceback
+from typing import Any, Callable, get_type_hints, get_origin, get_args, Union, TypedDict, TypeAlias, NotRequired
+
+JsonRpcId: TypeAlias = str | int | float | None
+JsonRpcParams: TypeAlias = dict[str, Any] | list[Any] | None
+
+class JsonRpcRequest(TypedDict):
+    jsonrpc: str
+    method: str
+    params: NotRequired[JsonRpcParams]
+    id: NotRequired[JsonRpcId]
+
+class JsonRpcError(TypedDict):
+    code: int
+    message: str
+    data: NotRequired[Any]
+
+class JsonRpcResponse(TypedDict):
+    jsonrpc: str
+    result: NotRequired[Any]
+    error: NotRequired[JsonRpcError]
+    id: JsonRpcId
+
+class JsonRpcException(Exception):
+    def __init__(self, code: int, message: str, data: Any = None):
+        self.code = code
+        self.message = message
+        self.data = data
+
+class JsonRpcRegistry:
+    def __init__(self):
+        self.methods: dict[str, Callable] = {}
+
+    def method(self, func: Callable, name: str | None = None) -> Callable:
+        self.methods[name or func.__name__] = func # type: ignore
+        return func
+
+    def dispatch(self, request: dict | str | bytes | bytearray) -> JsonRpcResponse | None:
+        try:
+            if not isinstance(request, dict):
+                request = json.loads(request)
+            if not isinstance(request, dict):
+                return self._error(None, -32600, "Invalid request: must be a JSON object")
+        except Exception as e:
+            return self._error(None, -32700, "JSON parse error", str(e))
+
+        if request.get("jsonrpc") != "2.0":
+            return self._error(None, -32600, "Invalid request: 'jsonrpc' must be '2.0'")
+
+        method = request.get("method")
+        if method is None:
+            return self._error(None, -32600, "Invalid request: 'method' is required")
+        if not isinstance(method, str):
+            return self._error(None, -32600, "Invalid request: 'method' must be a string")
+
+        request_id: JsonRpcId = request.get("id")
+        is_notification = "id" not in request
+        params: JsonRpcParams = request.get("params")
+        try:
+            result = self._call(method, params)
+            if is_notification:
+                return None
+            return {
+                "jsonrpc": "2.0",
+                "result": result,
+                "id": request_id,
+            }
+        except JsonRpcException as e:
+            if is_notification:
+                return None
+            return self._error(request_id, e.code, e.message, e.data)
+        except Exception as e:
+            if is_notification:
+                return None
+            error = self.map_exception(e)
+            return self._error(request_id, error["code"], error["message"], error.get("data"))
+
+    def map_exception(self, e: Exception) -> JsonRpcError:
+        return {
+            "code": -32603,
+            "message": "\n".join(traceback.format_exception(e)).strip() + "\n\nPlease report a bug!",
+        }
+
+    def _call(self, method: str, params: Any) -> Any:
+        if method not in self.methods:
+            raise JsonRpcException(-32601, f"Method '{method}' not found")
+
+        func = self.methods[method]
+        sig = inspect.signature(func)
+        hints = get_type_hints(func)
+        hints.pop("return", None)
+
+        # Determine required vs optional parameters
+        required_params = []
+        for param_name, param in sig.parameters.items():
+            if param.default is inspect.Parameter.empty:
+                required_params.append(param_name)
+
+        # Handle None params
+        if params is None:
+            if len(required_params) == 0:
+                return func()
+            else:
+                raise JsonRpcException(-32602, "Missing required params")
+
+        # Convert list params to dict by parameter names
+        if isinstance(params, list):
+            if len(params) < len(required_params):
+                raise JsonRpcException(
+                    -32602,
+                    f"Invalid params: expected at least {len(required_params)} arguments, got {len(params)}"
+                )
+            if len(params) > len(hints):
+                raise JsonRpcException(
+                    -32602,
+                    f"Invalid params: expected at most {len(hints)} arguments, got {len(params)}"
+                )
+            params = dict(zip(hints.keys(), params))
+
+        # Validate dict params
+        if isinstance(params, dict):
+            # Check all required params are present
+            missing = set(required_params) - set(params.keys())
+            if missing:
+                raise JsonRpcException(
+                    -32602,
+                    f"Invalid params: missing required parameters: {list(missing)}"
+                )
+
+            # Check no extra params
+            extra = set(params.keys()) - set(hints.keys())
+            if extra:
+                raise JsonRpcException(
+                    -32602,
+                    f"Invalid params: unexpected parameters: {list(extra)}"
+                )
+
+            validated_params = {}
+            for param_name, expected_type in hints.items():
+                if param_name not in params:
+                    continue  # Skip optional params not provided
+
+                value = params[param_name]
+
+                # Inline type validation
+                origin = get_origin(expected_type)
+                args = get_args(expected_type)
+
+                # Handle None/null
+                if value is None:
+                    if expected_type is not type(None):
+                        # Check if None is allowed in a Union
+                        if not (origin is Union and type(None) in args):
+                            raise JsonRpcException(-32602, f"Invalid params: {param_name} cannot be null")
+                    validated_params[param_name] = None
+                    continue
+
+                # Handle Union types (int | str, Optional[int], etc.)
+                if origin is Union or (hasattr(types, 'UnionType') and origin is types.UnionType):
+                    type_matched = False
+                    for arg_type in args:
+                        if arg_type is type(None):
+                            continue
+
+                        arg_origin = get_origin(arg_type)
+                        check_type = arg_origin if arg_origin is not None else arg_type
+
+                        if isinstance(value, check_type):
+                            type_matched = True
+                            break
+
+                    if not type_matched:
+                        raise JsonRpcException(-32602, f"Invalid params: {param_name} has invalid type")
+                    validated_params[param_name] = value
+                    continue
+
+                # Handle generic types (list[X], dict[K,V])
+                if origin is not None:
+                    if not isinstance(value, origin):
+                        raise JsonRpcException(
+                            -32602,
+                            f"Invalid params: {param_name} expected {origin.__name__}, got {type(value).__name__}"
+                        )
+                    validated_params[param_name] = value
+                    continue
+
+                # Handle basic types
+                if isinstance(expected_type, type):
+                    # Allow int -> float conversion
+                    if expected_type is float and isinstance(value, int):
+                        validated_params[param_name] = float(value)
+                        continue
+                    if not isinstance(value, expected_type):
+                        raise JsonRpcException(
+                            -32602,
+                            f"Invalid params: {param_name} expected {expected_type.__name__}, got {type(value).__name__}"
+                        )
+                    validated_params[param_name] = value
+                    continue
+
+                # Fallback for Any or unknown
+                validated_params[param_name] = value
+
+            return func(**validated_params)
+
+        else:
+            raise JsonRpcException(-32602, "Invalid params: must be array or object")
+
+    def _error(self, request_id: JsonRpcId, code: int, message: str, data: Any = None) -> JsonRpcResponse | None:
+        error: JsonRpcError = {
+            "code": code,
+            "message": message,
+        }
+        if data is not None:
+            error["data"] = data
+        return {
+            "jsonrpc": "2.0",
+            "error": error,
+            "id": request_id,
+        }

zeromcp/mcp.py

@@ -0,0 +1,466 @@
+import time
+import uuid
+import json
+import threading
+import traceback
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any, Callable, get_type_hints, Annotated
+from urllib.parse import urlparse, parse_qs
+from io import BufferedIOBase
+
+from zeromcp.jsonrpc import JsonRpcRegistry, JsonRpcError
+
+class McpToolError(Exception):
+    def __init__(self, message: str):
+        super().__init__(message)
+
+class McpToolRegistry(JsonRpcRegistry):
+    """JSON-RPC registry with custom error handling for MCP tools"""
+    def map_exception(self, e: Exception) -> JsonRpcError:
+        if isinstance(e, McpToolError):
+            return {
+                "code": -32000,
+                "message": e.args[0] or "MCP Tool Error",
+            }
+        return super().map_exception(e)
+
+class _McpSseConnection:
+    """Manages a single SSE client connection"""
+    def __init__(self, wfile):
+        self.wfile: BufferedIOBase = wfile
+        self.session_id = str(uuid.uuid4())
+        self.alive = True
+
+    def send_event(self, event_type: str, data):
+        """Send an SSE event to the client
+
+        Args:
+            event_type: Type of event (e.g., "endpoint", "message", "ping")
+            data: Event data - can be string (sent as-is) or dict (JSON-encoded)
+        """
+        if not self.alive:
+            return False
+
+        try:
+            # SSE format: "event: type\ndata: content\n\n"
+            if isinstance(data, str):
+                data_str = f"data: {data}\n\n"
+            else:
+                data_str = f"data: {json.dumps(data)}\n\n"
+            message = f"event: {event_type}\n{data_str}".encode("utf-8")
+            self.wfile.write(message)
+            self.wfile.flush()  # Ensure data is sent immediately
+            return True
+        except (BrokenPipeError, OSError):
+            self.alive = False
+            return False
+
+class _McpHttpRequestHandler(BaseHTTPRequestHandler):
+    mcp_server: "McpServer"
+
+    def log_message(self, format, *args):
+        """Override to suppress default logging or customize"""
+        pass
+
+    def handle(self):
+        """Override to add error handling for connection errors"""
+        try:
+            super().handle()
+        except (ConnectionAbortedError, ConnectionResetError, BrokenPipeError):
+            # Client disconnected - normal, suppress traceback
+            pass
+
+    def do_GET(self):
+        match urlparse(self.path).path:
+            case "/mcp":
+                self.send_error(405, "Method Not Allowed")
+            case "/sse":
+                self._handle_sse_get()
+            case _:
+                self.send_error(404, "Not Found")
+
+    def do_POST(self):
+        # Read request body (TODO: do we need to handle chunked encoding and what about no Content-Length?)
+        content_length = int(self.headers.get("Content-Length", 0))
+        body = self.rfile.read(content_length) if content_length > 0 else b""
+
+        match urlparse(self.path).path:
+            case "/mcp":
+                self._handle_mcp_post(body)
+            case "/sse":
+                self._handle_sse_post(body)
+            case _:
+                self.send_error(404, "Not Found")
+
+    def do_OPTIONS(self):
+        """Handle CORS preflight requests"""
+        self.send_response(200)
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Access-Control-Allow-Methods", "POST, GET, OPTIONS")
+        self.send_header("Access-Control-Allow-Headers", "Content-Type, Accept, X-Requested-With, Mcp-Session-Id, Mcp-Protocol-Version")
+        self.send_header("Access-Control-Max-Age", "86400")
+        self.end_headers()
+
+    def _handle_mcp_post(self, body: bytes):
+        # Dispatch to MCP registry
+        response = self.mcp_server.mcp_registry.dispatch(body)
+
+        def send_response(status: int, body: bytes):
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.send_header("Access-Control-Allow-Methods", "POST, GET, OPTIONS")
+            self.send_header("Access-Control-Allow-Headers", "Content-Type, Mcp-Session-Id, Mcp-Protocol-Version")
+            self.end_headers()
+            self.wfile.write(body)
+
+        # Check if notification (returns None)
+        if response is None:
+            send_response(202, b"Accepted")
+        else:
+            send_response(200, json.dumps(response).encode("utf-8"))
+
+    def _handle_sse_get(self):
+        # Create SSE connection wrapper
+        conn = _McpSseConnection(self.wfile)
+        self.mcp_server.sse_connections[conn.session_id] = conn
+
+        try:
+            # Send SSE headers
+            self.send_response(200)
+            self.send_header("Content-Type", "text/event-stream")
+            self.send_header("Cache-Control", "no-cache")
+            self.send_header("Connection", "keep-alive")
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.end_headers()
+
+            # Send endpoint event with session ID for routing
+            conn.send_event("endpoint", f"/sse?session={conn.session_id}")
+
+            # Keep connection alive with periodic pings
+            last_ping = time.time()
+            while conn.alive and self.mcp_server.running:
+                now = time.time()
+                if now - last_ping > 30:  # Ping every 30 seconds
+                    if not conn.send_event("ping", {}):
+                        break
+                    last_ping = now
+                time.sleep(1)
+
+        finally:
+            conn.alive = False
+            if conn.session_id in self.mcp_server.sse_connections:
+                del self.mcp_server.sse_connections[conn.session_id]
+
+    def _handle_sse_post(self, body: bytes):
+        query_params = parse_qs(urlparse(self.path).query)
+        session_id = query_params.get("session", [None])[0]
+        if session_id is None:
+            self.send_error(400, "Missing ?session for SSE POST")
+            return
+
+        # Dispatch to MCP registry
+        response = self.mcp_server.mcp_registry.dispatch(body)
+
+        # Send SSE response if necessary
+        if response is not None:
+            sse_conn = self.mcp_server.sse_connections.get(session_id)
+            if sse_conn is None or not sse_conn.alive:
+                # No SSE connection found
+                error_msg = f"No active SSE connection found for session {session_id}"
+                print(f"[MCP SSE ERROR] {error_msg}")
+                self.send_error(400, error_msg)
+                return
+
+            # Send response via SSE event stream
+            sse_conn.send_event("message", response)
+
+        # Return 202 Accepted to acknowledge POST
+        self.send_response(202)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.end_headers()
+        self.wfile.write(body)
+
+class McpServer:
+    def __init__(self, name: str):
+        self.name = name
+        self.tools = McpToolRegistry()
+
+        self.http_server = None
+        self.server_thread = None
+        self.running = False
+        self.sse_connections: dict[str, _McpSseConnection] = {}
+
+        # Register MCP protocol methods with correct names
+        self.mcp_registry = JsonRpcRegistry()
+        self.mcp_registry.methods["ping"] = self._mcp_ping
+        self.mcp_registry.methods["initialize"] = self._mcp_initialize
+        self.mcp_registry.methods["tools/list"] = self._mcp_tools_list
+        self.mcp_registry.methods["tools/call"] = self._mcp_tools_call
+
+    def tool(self, func: Callable) -> Callable:
+        return self.tools.method(func)
+
+    def start(self, host: str, port: int):
+        if self.running:
+            print("[MCP] Server is already running")
+            return
+
+        self.server_thread = threading.Thread(target=self._run_server, daemon=True, args=(host, port))
+        self.running = True
+        self.server_thread.start()
+
+    def stop(self):
+        if not self.running:
+            return
+
+        self.running = False
+
+        # Close all SSE connections
+        for conn in self.sse_connections.values():
+            conn.alive = False
+        self.sse_connections.clear()
+
+        # Shutdown the HTTP server
+        if self.http_server:
+            # shutdown() must be called from a different thread
+            # than the one running serve_forever()
+            self.http_server.shutdown()
+            self.http_server.server_close()
+            self.http_server = None
+
+        if self.server_thread:
+            self.server_thread.join(timeout=2)
+
+        print("[MCP] Server stopped")
+
+    def _run_server(self, host: str, port: int):
+        """Run the HTTP server main loop using ThreadingHTTPServer"""
+        # Set the MCPServer instance on the handler class
+        _McpHttpRequestHandler.mcp_server = self
+
+
+        # Create HTTP server with threading support and exclusive binding
+        self.http_server = ThreadingHTTPServer(
+            (host, port),
+            _McpHttpRequestHandler
+        )
+        self.http_server.allow_reuse_address = False
+
+        print("[MCP] Server started:")
+        print(f"  Streamable HTTP: http://{host}:{port}/mcp")
+        print(f"  SSE: http://{host}:{port}/sse")
+
+        try:
+            # Serve until shutdown() is called
+            self.http_server.serve_forever()
+        except Exception as e:
+            print(f"[MCP] Server error: {e}")
+            traceback.print_exc()
+        finally:
+            self.running = False
+
+    def _mcp_ping(self, _meta: dict | None = None) -> dict:
+        """MCP ping method"""
+        return {}
+
+    def _mcp_initialize(self, protocolVersion: str, capabilities: dict, clientInfo: dict, _meta: dict | None = None) -> dict:
+        """MCP initialize method"""
+        return {
+            "protocolVersion": protocolVersion,
+            "capabilities": {
+                "tools": {}
+            },
+            "serverInfo": {
+                "name": self.name,
+                "version": "1.0.0"
+            },
+        }
+
+    def _mcp_tools_list(self, _meta: dict | None = None) -> dict:
+        """MCP tools/list method"""
+        return {
+            "tools": [
+                self._generate_tool_schema(func_name, func)
+                for func_name, func in self.tools.methods.items()
+            ]
+        }
+
+    def _mcp_tools_call(self, name: str, arguments: dict | None = None, _meta: dict | None = None) -> dict:
+        """MCP tools/call method"""
+        # Wrap tool call in JSON-RPC request
+        tool_response = self.tools.dispatch({
+            "jsonrpc": "2.0",
+            "method": name,
+            "params": arguments,
+            "id": None,
+        })
+
+        # Check for error response
+        if tool_response and "error" in tool_response:
+            error = tool_response["error"]
+            return {
+                "content": [{"type": "text", "text": error.get("message", "Unknown error")}],
+                "isError": True
+            }
+
+        result = tool_response.get("result") if tool_response else None
+        return {
+            "content": [{"type": "text", "text": json.dumps(result, indent=2)}],
+            "structuredContent": result if isinstance(result, dict) else {"value": result},
+            "isError": False
+        }
+
+    def _type_to_json_schema(self, py_type: Any) -> dict:
+        """Convert Python type hint to JSON schema object"""
+        from typing import get_origin, get_args, Union
+
+        # Handle Annotated[Type, "description"]
+        if get_origin(py_type) is Annotated:
+            args = get_args(py_type)
+            actual_type = args[0]
+            description = args[1] if len(args) > 1 else None
+            schema = self._type_to_json_schema(actual_type)
+            if description:
+                schema["description"] = description
+            return schema
+
+        # Handle Union/Optional types
+        if get_origin(py_type) is Union:
+            union_args = get_args(py_type)
+            non_none = [t for t in union_args if t is not type(None)]
+            if len(non_none) == 1:
+                return self._type_to_json_schema(non_none[0])
+            # Multiple types -> anyOf
+            return {"anyOf": [self._type_to_json_schema(t) for t in non_none]}
+
+        # Primitives
+        if py_type == int:
+            return {"type": "integer"}
+        if py_type == float:
+            return {"type": "number"}
+        if py_type == str:
+            return {"type": "string"}
+        if py_type == bool:
+            return {"type": "boolean"}
+
+        # Handle list types
+        if py_type == list or get_origin(py_type) is list:
+            args = get_args(py_type)
+            schema: dict[str, Any] = {"type": "array"}
+            if args:
+                schema["items"] = self._type_to_json_schema(args[0])
+            return schema
+
+        # Handle dict types
+        if py_type == dict or get_origin(py_type) is dict:
+            return {"type": "object"}
+
+        # TypedDict detection
+        if hasattr(py_type, "__annotations__"):
+            if hasattr(py_type, "__required_keys__") or hasattr(py_type, "__optional_keys__"):
+                return self._typed_dict_to_schema(py_type)
+
+        # Fallback
+        return {"type": "object"}
+
+    def _typed_dict_to_schema(self, typed_dict_class) -> dict:
+        """Convert TypedDict to JSON schema"""
+        try:
+            from typing_extensions import NotRequired
+        except ImportError:
+            from typing import NotRequired
+
+        from typing import get_origin, get_args
+
+        hints = get_type_hints(typed_dict_class, include_extras=True)
+        properties = {}
+        required = []
+
+        for field_name, field_type in hints.items():
+            # Check if field is NotRequired
+            is_not_required = get_origin(field_type) is NotRequired
+            if is_not_required:
+                field_type = get_args(field_type)[0]
+
+            properties[field_name] = self._type_to_json_schema(field_type)
+
+            # Add to required if not NotRequired
+            if not is_not_required:
+                # Also check __required_keys__ if available
+                if hasattr(typed_dict_class, "__required_keys__"):
+                    if field_name in typed_dict_class.__required_keys__:
+                        if field_name not in required:
+                            required.append(field_name)
+                else:
+                    # Default to required if no __required_keys__
+                    required.append(field_name)
+
+        schema = {
+            "type": "object",
+            "properties": properties
+        }
+        if required:
+            schema["required"] = required
+
+        return schema
+
+    def _generate_tool_schema(self, func_name: str, func: Callable) -> dict:
+        """Generate MCP tool schema from a function"""
+        import inspect
+
+        hints = get_type_hints(func, include_extras=True)
+        return_type = hints.pop("return", None)
+        sig = inspect.signature(func)
+
+        # Build parameter schema
+        properties = {}
+        required = []
+
+        for param_name, param_type in hints.items():
+            # Check if parameter has default value
+            param = sig.parameters.get(param_name)
+            has_default = param and param.default is not inspect.Parameter.empty
+
+            # Use _type_to_json_schema to handle all type conversions including Union
+            properties[param_name] = self._type_to_json_schema(param_type)
+
+            # Only add to required if no default value
+            if not has_default:
+                required.append(param_name)
+
+        # Get docstring as description
+        description = func.__doc__ or f"Call {func_name}"
+        if description:
+            description = description.strip()
+
+        schema: dict[str, Any] = {
+            "name": func_name,
+            "description": description,
+            "inputSchema": {
+                "type": "object",
+                "properties": properties,
+                "required": required
+            }
+        }
+
+        # Add outputSchema if return type exists and is not None
+        if return_type and return_type is not type(None):
+            return_schema = self._type_to_json_schema(return_type)
+            # MCP spec requires outputSchema to always be type: object
+            # Wrap primitives in an object with a "value" property
+            if return_schema.get("type") != "object":
+                schema["outputSchema"] = {
+                    "type": "object",
+                    "properties": {
+                        "value": return_schema
+                    },
+                    "required": ["value"]
+                }
+            else:
+                schema["outputSchema"] = return_schema
+
+        return schema

zeromcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: zeromcp
+Version: 0.1.0
+Summary: Zero-dependency MCP server implementation
+Project-URL: Homepage, https://github.com/mrexodia/zeromcp
+Project-URL: Repository, https://github.com/mrexodia/zeromcp
+Project-URL: Issues, https://github.com/mrexodia/zeromcp/issues
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# zeromcp
+
+**Minimal MCP server implementation in pure Python.**
+
+A lightweight, handcrafted implementation of the [Model Context Protocol](https://modelcontextprotocol.io/) focused on what most users actually need: exposing tools with clean Python type annotations.
+
+## Features
+
+- ✨ **Zero dependencies** - Pure Python, standard library only
+- 🎯 **Type-safe** - Native Python type annotations for everything
+- 🚀 **Fast** - Minimal overhead, maximum performance
+- 🛠️ **Handcrafted** - Written by a human, verified against the spec
+- 🌐 **HTTP/SSE transport** - Streamable responses (stdio planned)
+- 📦 **Tiny** - Less than 1,000 lines of code
+
+## Installation
+
+```bash
+pip install zeromcp
+```
+
+Or with uv:
+
+```bash
+uv add zeromcp
+```
+
+## Quick Start
+
+```python
+from typing import Annotated
+from zeromcp import McpServer
+
+mcp = McpServer("my-server")
+
+@mcp.tool
+def greet(
+    name: Annotated[str, "Name to greet"],
+    age: Annotated[int | None, "Age of person"] = None
+) -> str:
+    """Generate a greeting message"""
+    if age:
+        return f"Hello, {name}! You are {age} years old."
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    mcp.start("127.0.0.1", 8000)
+```
+
+Then manually test your MCP server with the [inspector](https://github.com/modelcontextprotocol/inspector):
+
+```bash
+npx -y @modelcontextprotocol/inspector
+```
+
+Once things are working you can configure the `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "type": "http",
+      "url": "http://127.0.0.1/mcp"
+    }
+  }
+}
+```
+
+## Type Annotations
+
+zeromcp uses native Python `Annotated` types for schema generation:
+
+```python
+from typing import Annotated, Optional, TypedDict, NotRequired
+
+class GreetingResponse(TypedDict):
+    message: Annotated[str, "Greeting message"]
+    name: Annotated[str, "Name that was greeted"]
+    age: Annotated[NotRequired[int], "Age if provided"]
+
+@mcp.tool
+def greet(
+    name: Annotated[str, "Name to greet"],
+    age: Annotated[Optional[int], "Age of person"] = None
+) -> GreetingResponse:
+    """Generate a greeting message"""
+    if age is not None:
+        return {
+            "message": f"Hello, {name}! You are {age} years old.",
+            "name": name,
+            "age": age
+        }
+    return {
+        "message": f"Hello, {name}!",
+        "name": name
+    }
+```
+
+## Union Types
+
+Tools can accept multiple input types:
+
+```python
+from typing import Annotated, TypedDict
+
+class StructInfo(TypedDict):
+    name: Annotated[str, "Structure name"]
+    size: Annotated[int, "Structure size in bytes"]
+    fields: Annotated[list[str], "List of field names"]
+
+@mcp.tool
+def struct_get(
+    names: Annotated[list[str], "Array of structure names"]
+         | Annotated[str, "Single structure name"]
+) -> list[StructInfo]:
+    """Retrieve structure information by names"""
+    return [
+        {
+            "name": name,
+            "size": 128,
+            "fields": ["field1", "field2", "field3"]
+        }
+        for name in (names if isinstance(names, list) else [names])
+    ]
+```
+
+## Error Handling
+
+```python
+from zeromcp import McpToolError
+
+@mcp.tool
+def divide(
+    numerator: Annotated[float, "Numerator"],
+    denominator: Annotated[float, "Denominator"]
+) -> float:
+    """Divide two numbers"""
+    if denominator == 0:
+        raise McpToolError("Division by zero")
+    return numerator / denominator
+```

zeromcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+zeromcp/__init__.py,sha256=ukyvFUDieMQ7RxpBJg_Bvk8vIQV9k4s8WJwBOTthr6Y,82
+zeromcp/jsonrpc.py,sha256=B-W7BjTBaFC78e3tOudlBDYVkC1EJDAOM8KKkMJAkCg,8750
+zeromcp/mcp.py,sha256=9xttMgav4wrHFbey9sPRAiEGx7U8oguKhVDYtjO4r0Y,17462
+zeromcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zeromcp-0.1.0.dist-info/METADATA,sha256=mG7zwAbOqm89freH8XMnjzrVBJsLDZWls1mljoOc6hI,3752
+zeromcp-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+zeromcp-0.1.0.dist-info/RECORD,,

zeromcp-0.1.0.dist-info/WHEEL

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