Initial commit

Author: mrexodia

.gitignore

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

.python-version

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

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
+```

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.")

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"

src/zeromcp/__init__.py

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