mcp-twin 1.2.0

package/examples/http-server.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""
+Example MCP Server with HTTP Mode Support for MCP Twin
+
+This template shows how to add HTTP mode to your MCP server for zero-downtime reloads.
+
+Usage:
+    # Stdio mode (default, for Claude Code direct connection)
+    python3 http-server.py
+
+    # HTTP mode (for MCP Twin)
+    python3 http-server.py --http --port 8101
+"""
+
+import sys
+import json
+from http.server import HTTPServer, BaseHTTPRequestHandler
+
+
+# =============================================================================
+# YOUR MCP TOOLS (Replace with your actual tools)
+# =============================================================================
+
+def my_tool(arg1: str, arg2: int = 10) -> dict:
+    """Example tool - replace with your actual implementation."""
+    return {
+        "ok": True,
+        "result": f"Processed {arg1} with value {arg2}"
+    }
+
+
+TOOLS = [
+    {
+        "name": "my_tool",
+        "description": "An example tool that processes input",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "arg1": {"type": "string", "description": "First argument"},
+                "arg2": {"type": "integer", "description": "Second argument", "default": 10}
+            },
+            "required": ["arg1"]
+        }
+    }
+]
+
+
+# =============================================================================
+# MCP PROTOCOL HANDLERS
+# =============================================================================
+
+def send_response(response: dict):
+    """Send JSON-RPC response to stdout."""
+    output = json.dumps(response)
+    sys.stdout.write(output + "\n")
+    sys.stdout.flush()
+
+
+def send_error(request_id, code: int, message: str):
+    """Send JSON-RPC error response."""
+    send_response({
+        "jsonrpc": "2.0",
+        "id": request_id,
+        "error": {"code": code, "message": message}
+    })
+
+
+def handle_initialize(request_id):
+    """Handle MCP initialize request."""
+    send_response({
+        "jsonrpc": "2.0",
+        "id": request_id,
+        "result": {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": "my-mcp-server", "version": "1.0.0"}
+        }
+    })
+
+
+def handle_list_tools(request_id):
+    """Handle tools/list request."""
+    send_response({
+        "jsonrpc": "2.0",
+        "id": request_id,
+        "result": {"tools": TOOLS}
+    })
+
+
+def handle_call_tool(request_id, params: dict):
+    """Handle tools/call request."""
+    tool_name = params.get("name")
+    arguments = params.get("arguments", {})
+
+    try:
+        if tool_name == "my_tool":
+            result = my_tool(**arguments)
+        else:
+            send_error(request_id, -32601, f"Unknown tool: {tool_name}")
+            return
+
+        send_response({
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "result": {
+                "content": [{"type": "text", "text": json.dumps(result)}]
+            }
+        })
+    except Exception as e:
+        send_error(request_id, -32603, str(e))
+
+
+# =============================================================================
+# STDIO MODE (Default for Claude Code)
+# =============================================================================
+
+def main_stdio():
+    """Run MCP server in stdio mode."""
+    print("[INFO] MCP Server starting (stdio mode)", file=sys.stderr)
+
+    for line in sys.stdin:
+        try:
+            request = json.loads(line)
+            method = request.get("method")
+            request_id = request.get("id")
+            params = request.get("params", {})
+
+            if method == "initialize":
+                handle_initialize(request_id)
+            elif method == "tools/list":
+                handle_list_tools(request_id)
+            elif method == "tools/call":
+                handle_call_tool(request_id, params)
+            else:
+                send_error(request_id, -32601, f"Unknown method: {method}")
+
+        except json.JSONDecodeError:
+            send_error(None, -32700, "Parse error")
+        except Exception as e:
+            print(f"[ERROR] {e}", file=sys.stderr)
+            send_error(None, -32603, str(e))
+
+
+# =============================================================================
+# HTTP MODE (For MCP Twin)
+# =============================================================================
+
+def handle_http_request(request_body: str) -> str:
+    """Handle HTTP request body and return response."""
+    import io
+
+    try:
+        request = json.loads(request_body)
+        method = request.get("method")
+        request_id = request.get("id")
+        params = request.get("params", {})
+
+        # Capture stdout
+        old_stdout = sys.stdout
+        sys.stdout = captured = io.StringIO()
+
+        try:
+            if method == "initialize":
+                handle_initialize(request_id)
+            elif method == "tools/list":
+                handle_list_tools(request_id)
+            elif method == "tools/call":
+                handle_call_tool(request_id, params)
+            else:
+                send_error(request_id, -32601, f"Unknown method: {method}")
+        finally:
+            sys.stdout = old_stdout
+
+        return captured.getvalue().strip()
+
+    except json.JSONDecodeError:
+        return json.dumps({
+            "jsonrpc": "2.0",
+            "id": None,
+            "error": {"code": -32700, "message": "Parse error"}
+        })
+    except Exception as e:
+        return json.dumps({
+            "jsonrpc": "2.0",
+            "id": None,
+            "error": {"code": -32603, "message": str(e)}
+        })
+
+
+def run_http_server(port: int):
+    """Run MCP server in HTTP mode for MCP Twin."""
+
+    class MCPHandler(BaseHTTPRequestHandler):
+        def log_message(self, format, *args):
+            print(f"[HTTP] {args[0]}", file=sys.stderr)
+
+        def do_POST(self):
+            if self.path == "/mcp":
+                content_length = int(self.headers.get('Content-Length', 0))
+                body = self.rfile.read(content_length).decode('utf-8')
+
+                response = handle_http_request(body)
+
+                self.send_response(200)
+                self.send_header('Content-Type', 'application/json')
+                self.end_headers()
+                self.wfile.write(response.encode('utf-8'))
+            else:
+                self.send_response(404)
+                self.end_headers()
+
+        def do_GET(self):
+            if self.path == "/health":
+                self.send_response(200)
+                self.send_header('Content-Type', 'application/json')
+                self.end_headers()
+                self.wfile.write(b'{"status": "ok", "server": "my-mcp-server"}')
+            else:
+                self.send_response(404)
+                self.end_headers()
+
+    print(f"[INFO] MCP Server starting (HTTP mode) on port {port}", file=sys.stderr)
+    server = HTTPServer(('localhost', port), MCPHandler)
+
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("[INFO] Server stopping", file=sys.stderr)
+        server.shutdown()
+
+
+# =============================================================================
+# MAIN ENTRY POINT
+# =============================================================================
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="MCP Server with HTTP Mode Support")
+    parser.add_argument("--http", action="store_true", help="Run as HTTP server (for MCP Twin)")
+    parser.add_argument("--port", type=int, default=8101, help="HTTP port (default: 8101)")
+    args = parser.parse_args()
+
+    if args.http:
+        run_http_server(args.port)
+    else:
+        main_stdio()

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "mcp-twin",
+  "displayName": "MCP Twin - Hot Reload",
+  "version": "1.2.0",
+  "description": "Zero-downtime updates for MCP servers. No more restarting Claude Code when you change server code.",
+  "author": {
+    "name": "Prax Labs",
+    "url": "https://prax.chat"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nothinginfinity/mcp-twin"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "mcp",
+    "hot-reload",
+    "zero-downtime",
+    "development",
+    "plugin",
+    "prax",
+    "prax-chat"
+  ],
+  "license": "MIT",
+  "engines": {
+    "claude-code": ">=1.0.0"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mcp-twin": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "jest"
+  },
+  "claudePlugin": {
+    "type": "skill",
+    "commands": [
+      {
+        "name": "twin",
+        "description": "Manage MCP server twins",
+        "subcommands": [
+          {
+            "name": "start",
+            "description": "Start twin servers",
+            "args": "[server]"
+          },
+          {
+            "name": "stop",
+            "description": "Stop twin servers",
+            "args": "[server]"
+          },
+          {
+            "name": "reload",
+            "description": "Reload standby server",
+            "args": "<server>"
+          },
+          {
+            "name": "swap",
+            "description": "Switch to standby server",
+            "args": "<server>"
+          },
+          {
+            "name": "status",
+            "description": "Show twin status",
+            "args": "[server]"
+          }
+        ]
+      }
+    ],
+    "hooks": [
+      {
+        "event": "file:change",
+        "pattern": "**/*_server.py",
+        "handler": "onServerFileChange"
+      }
+    ],
+    "permissions": [
+      "process:spawn",
+      "process:kill",
+      "fs:read",
+      "fs:write",
+      "net:localhost"
+    ]
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.27",
+    "jest": "^29.0.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "chokidar": "^3.5.3"
+  }
+}

package/skills/twin.md

@@ -0,0 +1,186 @@
+# MCP Twin Skill
+
+name: twin
+description: Zero-downtime MCP server management with twin/hot-swap architecture
+version: 1.0.0
+
+## Triggers
+- /twin
+- hot reload mcp
+- reload mcp server
+- swap mcp server
+- mcp twin
+
+## Instructions
+
+You manage MCP server twins for zero-downtime development updates.
+
+### Core Concept
+Twin servers = two instances of the same MCP server running on different ports.
+- One is "active" (receiving traffic)
+- One is "standby" (ready to take over)
+
+When developer edits code:
+1. Reload standby with new code
+2. Verify standby is healthy
+3. Swap traffic to standby
+4. Old active becomes new standby
+
+Result: Zero downtime, no Claude Code restart needed.
+
+### Commands
+
+#### /twin start [server]
+Start twin servers for an MCP server.
+
+If no server specified, show detected servers and let user choose.
+Auto-detect from `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+Example output:
+```
+Started twins for inbox-collab
+
+  Server A: port 8101 (active)
+  Server B: port 8102 (standby)
+
+Edit your code, then: /twin reload inbox-collab
+```
+
+#### /twin reload <server>
+Reload the standby server with updated code.
+
+1. Stop standby process
+2. Start new process with same port
+3. Health check
+4. Report status
+
+Example output:
+```
+Reloaded inbox-collab standby
+
+  Standby (B): port 8102
+  Health: passing
+  Ready to swap
+
+Run: /twin swap inbox-collab
+```
+
+If health check fails:
+```
+Reload failed for inbox-collab
+
+  Standby (B): port 8102
+  Health: FAILED
+
+Check logs: ~/.mcp-twin/logs/inbox-collab_b.log
+```
+
+#### /twin swap <server>
+Switch traffic to the standby server.
+
+Only swap if standby is healthy. Otherwise warn user.
+
+Example output:
+```
+Swapped inbox-collab
+
+  Previous active: A (port 8101)
+  New active: B (port 8102)
+
+Your changes are now live!
+```
+
+#### /twin status [server]
+Show status of twin servers.
+
+If server specified, show detailed view.
+If no server, show summary of all.
+
+Example (all):
+```
+MCP Twin Status
+
+inbox-collab
+  Active:  A (8101) healthy
+  Standby: B (8102) healthy
+  Reloads: 5 | Swaps: 3
+
+phi-proxy
+  Active:  B (8104) healthy
+  Standby: A (8103) healthy
+  Reloads: 2 | Swaps: 1
+
+Not running: zti-server, fsl-compression
+```
+
+#### /twin stop [server]
+Stop twin servers.
+
+Use `--all` to stop all twins.
+
+Example:
+```
+Stopped inbox-collab twins
+
+  Killed: PID 12345, 12346
+  Ports freed: 8101, 8102
+```
+
+### Auto-Detection
+
+Read MCP servers from Claude config:
+```json
+{
+  "mcpServers": {
+    "inbox-collab": {
+      "command": "python3",
+      "args": ["/path/to/server.py"]
+    }
+  }
+}
+```
+
+Extract script path from args, use for file watching and process management.
+
+### Error Handling
+
+**Server not found:**
+```
+Unknown server: foo-bar
+
+Available servers:
+  inbox-collab, phi-proxy, zti-server
+
+Run: /twin start <server>
+```
+
+**Twins not running:**
+```
+No twins running for inbox-collab
+
+Start first: /twin start inbox-collab
+```
+
+**Standby unhealthy:**
+```
+Cannot swap - standby is unhealthy
+
+  Standby (B): port 8102
+  State: failed
+
+Fix the issue and run: /twin reload inbox-collab
+```
+
+### Pro Features (Coming Soon)
+
+When user runs 5+ reloads in a session:
+```
+You're iterating fast! Prax Chat Pro coming soon:
+
+- Auto-reload on file save
+- Auto-swap option
+- Health dashboard
+- Rollback support
+
+[Notify Me] [Maybe Later]
+```