mseep-rmcp 0.3.3__py3-none-any.whl

rmcp/transport/base.py

@@ -0,0 +1,130 @@
+"""
+Base transport interface for MCP server.
+
+Defines the contract that all transports must implement,
+enabling clean composition at the server edge.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, AsyncIterator, Callable, Awaitable
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class Transport(ABC):
+    """
+    Abstract base class for MCP transports.
+    
+    All transports must implement:
+    - Message receiving (async iterator)
+    - Message sending  
+    - Lifecycle management (startup/shutdown)
+    - Error handling
+    """
+    
+    def __init__(self, name: str):
+        self.name = name
+        self._running = False
+        self._message_handler: Optional[Callable[[Dict[str, Any]], Awaitable[Dict[str, Any]]]] = None
+    
+    def set_message_handler(self, handler: Callable[[Dict[str, Any]], Awaitable[Dict[str, Any]]]) -> None:
+        """Set the message handler that will process incoming messages."""
+        self._message_handler = handler
+    
+    @abstractmethod
+    async def startup(self) -> None:
+        """Initialize the transport."""
+        logger.info(f"Starting {self.name} transport")
+        self._running = True
+    
+    @abstractmethod  
+    async def shutdown(self) -> None:
+        """Clean up the transport."""
+        logger.info(f"Shutting down {self.name} transport")
+        self._running = False
+    
+    @abstractmethod
+    async def receive_messages(self) -> AsyncIterator[Dict[str, Any]]:
+        """
+        Async iterator that yields incoming messages.
+        
+        Messages are already parsed from transport format (JSON-RPC).
+        """
+        pass
+    
+    @abstractmethod
+    async def send_message(self, message: Dict[str, Any]) -> None:
+        """
+        Send a message via the transport.
+        
+        Message will be encoded to transport format (JSON-RPC).
+        """
+        pass
+    
+    async def run(self) -> None:
+        """
+        Run the transport event loop.
+        
+        This is the main entry point that:
+        1. Starts the transport
+        2. Processes incoming messages  
+        3. Handles errors gracefully
+        4. Ensures clean shutdown
+        """
+        if not self._message_handler:
+            raise RuntimeError("Message handler not set")
+        
+        try:
+            await self.startup()
+            
+            async for message in self.receive_messages():
+                try:
+                    # Process message through handler
+                    response = await self._message_handler(message)
+                    
+                    # Send response if there is one
+                    if response:
+                        await self.send_message(response)
+                        
+                except Exception as e:
+                    logger.error(f"Error processing message: {e}")
+                    
+                    # Send error response if possible
+                    error_response = self._create_error_response(message, e)
+                    if error_response:
+                        try:
+                            await self.send_message(error_response)
+                        except Exception as send_error:
+                            logger.error(f"Failed to send error response: {send_error}")
+        
+        except Exception as e:
+            logger.error(f"Transport error: {e}")
+        
+        finally:
+            await self.shutdown()
+    
+    def _create_error_response(self, request: Dict[str, Any], error: Exception) -> Optional[Dict[str, Any]]:
+        """Create an error response for a failed request."""
+        
+        request_id = request.get("id")
+        if request_id is None:
+            # No ID means no response expected (notification)
+            return None
+        
+        return {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "error": {
+                "code": -32603,  # Internal error
+                "message": str(error),
+                "data": {
+                    "type": type(error).__name__
+                }
+            }
+        }
+    
+    @property
+    def is_running(self) -> bool:
+        """Check if transport is running."""
+        return self._running

rmcp/transport/jsonrpc.py

@@ -0,0 +1,243 @@
+"""
+JSON-RPC 2.0 envelope handling.
+
+Implements proper JSON-RPC 2.0 specification:
+- Request/response/notification parsing
+- Error code handling per spec
+- Message validation
+- Single-line encoding for stdio transport
+
+Following the principle: "No hand-rolled JSON-RPC, no 'close enough' message shapes."
+"""
+
+import json
+import logging
+from typing import Any, Dict, Optional, Union
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+class JSONRPCError(Exception):
+    """JSON-RPC error with proper error code."""
+    
+    # Standard JSON-RPC 2.0 error codes
+    PARSE_ERROR = -32700
+    INVALID_REQUEST = -32600  
+    METHOD_NOT_FOUND = -32601
+    INVALID_PARAMS = -32602
+    INTERNAL_ERROR = -32603
+    
+    def __init__(self, code: int, message: str, data: Any = None, request_id: Any = None):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.data = data
+        self.request_id = request_id
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to JSON-RPC error response format."""
+        error_obj = {
+            "code": self.code,
+            "message": self.message
+        }
+        
+        if self.data is not None:
+            error_obj["data"] = self.data
+        
+        response = {
+            "jsonrpc": "2.0",
+            "id": self.request_id,
+            "error": error_obj
+        }
+        
+        return response
+
+
+@dataclass
+class JSONRPCMessage:
+    """Parsed JSON-RPC message."""
+    
+    jsonrpc: str
+    id: Optional[Union[str, int, None]] = None
+    method: Optional[str] = None
+    params: Optional[Union[Dict[str, Any], list]] = None
+    result: Optional[Any] = None
+    error: Optional[Dict[str, Any]] = None
+    
+    @property
+    def is_request(self) -> bool:
+        """Check if this is a request message."""
+        return self.method is not None and self.id is not None
+    
+    @property
+    def is_notification(self) -> bool:
+        """Check if this is a notification message."""
+        return self.method is not None and self.id is None
+    
+    @property
+    def is_response(self) -> bool:
+        """Check if this is a response message."""
+        return self.method is None and (self.result is not None or self.error is not None)
+
+
+class JSONRPCEnvelope:
+    """JSON-RPC 2.0 message envelope handler."""
+    
+    @staticmethod
+    def encode(message: Dict[str, Any]) -> str:
+        """
+        Encode message to single-line JSON for stdio transport.
+        
+        Following the principle: "One JSON-RPC message per line."
+        """
+        try:
+            # Ensure no embedded newlines in the JSON
+            json_str = json.dumps(message, separators=(',', ':'), ensure_ascii=False)
+            
+            # Validate it's actually single line
+            if '\n' in json_str or '\r' in json_str:
+                # This should not happen with separators, but be safe
+                json_str = json_str.replace('\n', '\\n').replace('\r', '\\r')
+            
+            return json_str
+            
+        except (TypeError, ValueError) as e:
+            raise JSONRPCError(
+                JSONRPCError.INTERNAL_ERROR,
+                f"Failed to encode JSON-RPC message: {e}",
+                data={"original_message": str(message)[:200]}  # Truncate for safety
+            )
+    
+    @staticmethod
+    def decode(line: str) -> JSONRPCMessage:
+        """
+        Decode single line of JSON to JSON-RPC message.
+        
+        Validates JSON-RPC 2.0 specification compliance.
+        """
+        if not line.strip():
+            raise JSONRPCError(
+                JSONRPCError.INVALID_REQUEST,
+                "Empty message"
+            )
+        
+        try:
+            data = json.loads(line.strip())
+        except json.JSONDecodeError as e:
+            raise JSONRPCError(
+                JSONRPCError.PARSE_ERROR,
+                f"Invalid JSON: {e}"
+            ) from e
+        
+        # Validate JSON-RPC 2.0 structure
+        if not isinstance(data, dict):
+            raise JSONRPCError(
+                JSONRPCError.INVALID_REQUEST,
+                "JSON-RPC message must be an object"
+            )
+        
+        jsonrpc_version = data.get("jsonrpc")
+        if jsonrpc_version != "2.0":
+            raise JSONRPCError(
+                JSONRPCError.INVALID_REQUEST,
+                f"Invalid JSON-RPC version: {jsonrpc_version}. Must be '2.0'"
+            )
+        
+        # Extract message components
+        message = JSONRPCMessage(
+            jsonrpc=jsonrpc_version,
+            id=data.get("id"),
+            method=data.get("method"),
+            params=data.get("params"),
+            result=data.get("result"),
+            error=data.get("error")
+        )
+        
+        # Validate message type
+        if message.is_request or message.is_notification:
+            if not isinstance(message.method, str):
+                raise JSONRPCError(
+                    JSONRPCError.INVALID_REQUEST,
+                    "Method must be a string",
+                    request_id=message.id
+                )
+            
+            # Params are optional, but if present must be object or array
+            if message.params is not None:
+                if not isinstance(message.params, (dict, list)):
+                    raise JSONRPCError(
+                        JSONRPCError.INVALID_REQUEST,
+                        "Params must be object or array",
+                        request_id=message.id
+                    )
+        
+        elif message.is_response:
+            # Response must have either result or error, not both
+            has_result = message.result is not None
+            has_error = message.error is not None
+            
+            if has_result and has_error:
+                raise JSONRPCError(
+                    JSONRPCError.INVALID_REQUEST,
+                    "Response cannot have both result and error",
+                    request_id=message.id
+                )
+            
+            if not has_result and not has_error:
+                raise JSONRPCError(
+                    JSONRPCError.INVALID_REQUEST,
+                    "Response must have either result or error",
+                    request_id=message.id
+                )
+        
+        else:
+            raise JSONRPCError(
+                JSONRPCError.INVALID_REQUEST,
+                "Invalid message type",
+                request_id=data.get("id")
+            )
+        
+        return message
+    
+    @staticmethod
+    def create_request(method: str, params: Optional[Union[Dict[str, Any], list]] = None, 
+                      request_id: Union[str, int] = "1") -> Dict[str, Any]:
+        """Create a JSON-RPC 2.0 request."""
+        request = {
+            "jsonrpc": "2.0",
+            "method": method,
+            "id": request_id
+        }
+        
+        if params is not None:
+            request["params"] = params
+        
+        return request
+    
+    @staticmethod
+    def create_notification(method: str, params: Optional[Union[Dict[str, Any], list]] = None) -> Dict[str, Any]:
+        """Create a JSON-RPC 2.0 notification."""
+        notification = {
+            "jsonrpc": "2.0",
+            "method": method
+        }
+        
+        if params is not None:
+            notification["params"] = params
+        
+        return notification
+    
+    @staticmethod
+    def create_response(request_id: Union[str, int], result: Any) -> Dict[str, Any]:
+        """Create a JSON-RPC 2.0 success response."""
+        return {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "result": result
+        }
+    
+    @staticmethod
+    def create_error_response(request_id: Union[str, int, None], error: JSONRPCError) -> Dict[str, Any]:
+        """Create a JSON-RPC 2.0 error response."""
+        return error.to_dict()

rmcp/transport/stdio.py

@@ -0,0 +1,201 @@
+"""
+Stdio transport for MCP server.
+
+Implements JSON-RPC 2.0 over stdin/stdout with proper hygiene:
+- Never prints to stdout (only stderr for logging)
+- One JSON message per line
+- Proper error handling and cleanup
+- Async I/O for non-blocking operation
+
+Following mature MCP patterns: "stdio servers never print to stdout."
+"""
+
+import asyncio
+import sys
+import logging
+from typing import Any, Dict, AsyncIterator
+from ..transport.base import Transport
+from ..transport.jsonrpc import JSONRPCEnvelope, JSONRPCError, JSONRPCMessage
+
+# Configure logging to stderr only (never stdout)
+logger = logging.getLogger(__name__)
+
+
+class StdioTransport(Transport):
+    """
+    Stdio transport using JSON-RPC 2.0 over stdin/stdout.
+    
+    Key characteristics:
+    - Reads JSON-RPC messages from stdin (one per line)
+    - Writes JSON-RPC responses to stdout (one per line) 
+    - Logs only to stderr (never stdout)
+    - Non-blocking async I/O
+    - Graceful error handling
+    """
+    
+    def __init__(self):
+        super().__init__("stdio")
+        self._stdin_reader: asyncio.StreamReader = None
+        self._stdout_writer: asyncio.StreamWriter = None
+        self._shutdown_event = asyncio.Event()
+    
+    async def startup(self) -> None:
+        """Initialize stdin/stdout streams."""
+        await super().startup()
+        
+        # Set up async stdin/stdout
+        loop = asyncio.get_event_loop()
+        
+        # Create stdin reader
+        self._stdin_reader = asyncio.StreamReader()
+        stdin_protocol = asyncio.StreamReaderProtocol(self._stdin_reader)
+        await loop.connect_read_pipe(lambda: stdin_protocol, sys.stdin)
+        
+        # Create stdout writer
+        stdout_transport, stdout_protocol = await loop.connect_write_pipe(
+            asyncio.streams.FlowControlMixin, sys.stdout
+        )
+        self._stdout_writer = asyncio.StreamWriter(stdout_transport, stdout_protocol, None, loop)
+        
+        logger.info("Stdio transport initialized", file=sys.stderr)
+    
+    async def shutdown(self) -> None:
+        """Clean up streams."""
+        await super().shutdown()
+        
+        if self._stdout_writer:
+            self._stdout_writer.close()
+            await self._stdout_writer.wait_closed()
+        
+        self._shutdown_event.set()
+        logger.info("Stdio transport shutdown complete", file=sys.stderr)
+    
+    async def receive_messages(self) -> AsyncIterator[Dict[str, Any]]:
+        """
+        Read JSON-RPC messages from stdin.
+        
+        Yields parsed and validated JSON-RPC messages.
+        """
+        if not self._stdin_reader:
+            raise RuntimeError("Transport not started")
+        
+        logger.info("Starting to read messages from stdin", file=sys.stderr)
+        
+        try:
+            while self._running and not self._shutdown_event.is_set():
+                try:
+                    # Read one line from stdin
+                    line = await asyncio.wait_for(
+                        self._stdin_reader.readline(), 
+                        timeout=0.1  # Short timeout to check shutdown
+                    )
+                    
+                    if not line:
+                        # EOF reached
+                        logger.info("EOF reached on stdin", file=sys.stderr)
+                        break
+                    
+                    line_str = line.decode('utf-8').rstrip('\n\r')
+                    if not line_str:
+                        continue  # Skip empty lines
+                    
+                    logger.debug(f"Received message: {line_str[:100]}...", file=sys.stderr)
+                    
+                    # Parse JSON-RPC message
+                    try:
+                        message = JSONRPCEnvelope.decode(line_str)
+                        
+                        # Convert to dict for handler
+                        message_dict = {
+                            "jsonrpc": message.jsonrpc,
+                            "id": message.id,
+                        }
+                        
+                        if message.method:
+                            message_dict["method"] = message.method
+                        
+                        if message.params is not None:
+                            message_dict["params"] = message.params
+                        
+                        if message.result is not None:
+                            message_dict["result"] = message.result
+                        
+                        if message.error is not None:
+                            message_dict["error"] = message.error
+                        
+                        yield message_dict
+                        
+                    except JSONRPCError as e:
+                        logger.error(f"JSON-RPC parse error: {e}", file=sys.stderr)
+                        
+                        # Send error response if we can determine request ID
+                        error_response = e.to_dict()
+                        await self.send_message(error_response)
+                
+                except asyncio.TimeoutError:
+                    # Timeout is expected, just check if we should continue
+                    continue
+                
+                except Exception as e:
+                    logger.error(f"Error reading from stdin: {e}", file=sys.stderr)
+                    break
+        
+        except Exception as e:
+            logger.error(f"Fatal error in message reception: {e}", file=sys.stderr)
+        
+        finally:
+            logger.info("Stopped reading messages", file=sys.stderr)
+    
+    async def send_message(self, message: Dict[str, Any]) -> None:
+        """
+        Send JSON-RPC message to stdout.
+        
+        Encodes message as single line JSON and writes to stdout.
+        """
+        if not self._stdout_writer:
+            raise RuntimeError("Transport not started")
+        
+        try:
+            # Encode to single-line JSON
+            json_line = JSONRPCEnvelope.encode(message)
+            
+            logger.debug(f"Sending message: {json_line[:100]}...", file=sys.stderr)
+            
+            # Write to stdout with newline
+            self._stdout_writer.write((json_line + '\n').encode('utf-8'))
+            await self._stdout_writer.drain()
+            
+        except Exception as e:
+            logger.error(f"Error sending message: {e}", file=sys.stderr)
+            raise
+    
+    async def send_notification(self, method: str, params: Any = None) -> None:
+        """Send a JSON-RPC notification."""
+        notification = JSONRPCEnvelope.create_notification(method, params)
+        await self.send_message(notification)
+    
+    async def send_progress_notification(self, token: str, value: int, total: int, message: str = "") -> None:
+        """Send MCP progress notification."""
+        await self.send_notification("notifications/progress", {
+            "progressToken": token,
+            "progress": value,
+            "total": total,
+            "message": message
+        })
+    
+    async def send_log_notification(self, level: str, message: str, data: Any = None) -> None:
+        """Send MCP log notification."""
+        log_params = {
+            "level": level,
+            "message": message
+        }
+        
+        if data:
+            log_params["data"] = data
+        
+        await self.send_notification("notifications/message", log_params)
+    
+    def request_shutdown(self) -> None:
+        """Request graceful shutdown."""
+        logger.info("Shutdown requested", file=sys.stderr)
+        self._shutdown_event.set()