zeromcp 0.1.0__tar.gz

zeromcp-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

zeromcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

zeromcp-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,141 @@
+# 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/examples/mcp_example.py

@@ -0,0 +1,99 @@
+"""Example MCP server with test tools"""
+import time
+from typing import Annotated, Optional, TypedDict, NotRequired
+from zeromcp import McpToolError, McpServer
+
+mcp = McpServer("example")
+
+class SystemInfo(TypedDict):
+    platform: Annotated[str, "Operating system platform"]
+    python_version: Annotated[str, "Python version"]
+    machine: Annotated[str, "Machine architecture"]
+    timestamp: Annotated[float, "Current timestamp"]
+
+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 divide(
+    numerator: Annotated[float, "Numerator"],
+    denominator: Annotated[float, "Denominator"]
+) -> float:
+    """Divide two numbers (no zero check - tests natural exceptions)"""
+    return numerator / denominator
+
+@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
+    }
+
+@mcp.tool
+def get_system_info() -> SystemInfo:
+    """Get system information"""
+    import platform
+    return {
+        "platform": platform.system(),
+        "python_version": platform.python_version(),
+        "machine": platform.machine(),
+        "timestamp": time.time()
+    }
+
+@mcp.tool
+def failing_tool(message: Annotated[str, "Error message to raise"]) -> str:
+    """Tool that always fails (for testing error handling)"""
+    raise McpToolError(message)
+
+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 [
+        StructInfo({
+            "name": name,
+            "size": 128,  # Dummy size
+            "fields": ["field1", "field2", "field3"]  # Dummy fields
+        })
+        for name in (names if isinstance(names, list) else [names])
+    ]
+
+if __name__ == "__main__":
+    print("Starting MCP Example Server...")
+    print("\nAvailable tools:")
+    for name in mcp.tools.methods.keys():
+        func = mcp.tools.methods[name]
+        print(f"  - {name}: {func.__doc__}")
+
+    mcp.start("127.0.0.1", 5001)
+
+    print("\n" + "="*60)
+    print("Server is running. Press Ctrl+C to stop.")
+    print("="*60)
+
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        print("\n\nStopping server...")
+        mcp.stop()
+        print("Server stopped.")

zeromcp-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "zeromcp"
+version = "0.1.0"
+description = "Zero-dependency MCP server implementation"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+license = "MIT"
+
+[project.urls]
+Homepage = "https://github.com/mrexodia/zeromcp"
+Repository = "https://github.com/mrexodia/zeromcp"
+Issues = "https://github.com/mrexodia/zeromcp/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

zeromcp-0.1.0/src/zeromcp/__init__.py

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

zeromcp-0.1.0/src/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,
+        }