Add stdio transport support

Author: mrexodia

README.md

@@ -10,7 +10,8 @@ A lightweight, handcrafted implementation of the [Model Context Protocol](https:
 - 🎯 **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)
+- 🌐 **HTTP/SSE transport** - Streamable responses
+- 📡 **Stdio transport** - For legacy clients
 - 📦 **Tiny** - Less than 1,000 lines of code
 
 ## Installation
@@ -66,6 +67,37 @@ Once things are working you can configure the `mcp.json`:
 }
 ```
 
+## Stdio Transport
+
+For MCP clients that only support stdio transport:
+
+```python
+from zeromcp import McpServer
+
+mcp = McpServer("my-server")
+
+@mcp.tool
+def greet(name: str) -> str:
+    """Generate a greeting"""
+    return f"Hello, {name}!"
+
+if __name__ == "__main__":
+    mcp.stdio()
+```
+
+Then configure in `mcp.json` (different for every client):
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "python",
+      "args": ["path/to/server.py"]
+    }
+  }
+}
+```
+
 ## Type Annotations
 
 zeromcp uses native Python `Annotated` types for schema generation:
@@ -139,3 +171,21 @@ def divide(
         raise McpToolError("Division by zero")
     return numerator / denominator
 ```
+
+## Supported clients
+
+The following clients have been tested:
+
+- [Claude Code](https://code.claude.com/docs/en/mcp#installing-mcp-servers)
+- [Claude Desktop](https://modelcontextprotocol.io/docs/develop/connect-local-servers#installing-the-filesystem-server) (_stdio only_)
+- [Visual Studio Code](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
+- [Roo Code](https://docs.roocode.com/features/mcp/using-mcp-in-roo) / [Cline](https://docs.cline.bot/mcp/configuring-mcp-servers) / [Kilo Code](https://kilocode.ai/docs/features/mcp/using-mcp-in-kilo-code)
+- [LM Studio](https://lmstudio.ai/docs/app/mcp)
+- [Jan](https://www.jan.ai/docs/desktop/mcp#configure-and-use-mcps-within-jan)
+- [Gemini CLI](https://geminicli.com/docs/tools/mcp-server/#how-to-set-up-your-mcp-server)
+- [Cursor](https://cursor.com/docs/context/mcp)
+- [Windsurf](https://docs.windsurf.com/windsurf/cascade/mcp)
+- [Zed](https://zed.dev/docs/ai/mcp) (_stdio only_)
+- [Warp](https://docs.warp.dev/knowledge-and-collaboration/mcp#adding-an-mcp-server)
+
+_Note_: generally the `/mcp` endpoint is preferred, but not all clients support it correctly.

examples/mcp_example.py

@@ -1,5 +1,6 @@
 """Example MCP server with test tools"""
 import time
+import argparse
 from typing import Annotated, Optional, TypedDict, NotRequired
 from zeromcp import McpToolError, McpServer
 
@@ -78,22 +79,28 @@ def struct_get(
     ]
 
 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__}")
+    parser = argparse.ArgumentParser(description="MCP Example Server")
+    parser.add_argument("--stdio", action="store_true", help="Run MCP server over stdio")
+    args = parser.parse_args()
+    if args.stdio:
+        mcp.stdio()
+    else:
+        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)
+        mcp.serve("127.0.0.1", 5001)
 
-    print("\n" + "="*60)
-    print("Server is running. Press Ctrl+C to stop.")
-    print("="*60)
+        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.")
+        try:
+            while True:
+                time.sleep(1)
+        except KeyboardInterrupt:
+            print("\n\nStopping server...")
+            mcp.stop()
+            print("Server stopped.")

src/zeromcp/mcp.py

@@ -3,8 +3,9 @@
 import json
 import threading
 import traceback
+import sys
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
-from typing import Any, Callable, get_type_hints, Annotated
+from typing import Any, Callable, get_type_hints, Annotated, BinaryIO
 from urllib.parse import urlparse, parse_qs
 from io import BufferedIOBase
 
@@ -244,6 +245,20 @@ def stop(self):
 
         print("[MCP] Server stopped")
 
+    def stdio(self, stdin: BinaryIO = sys.stdin.buffer, stdout: BinaryIO = sys.stdout.buffer):
+        while True:
+            try:
+                request = stdin.readline()
+                if not request: # EOF
+                    break
+
+                response = self.mcp_registry.dispatch(request)
+                if response is not None:
+                    stdout.write(json.dumps(response).encode("utf-8") + b"\n")
+                    stdout.flush()
+            except (BrokenPipeError, KeyboardInterrupt): # Client disconnected
+                break
+
     def _run_server(self, host: str, port: int):
         """Run the HTTP server main loop using ThreadingHTTPServer"""
         # Set the MCPServer instance on the handler class