pomera-ai-commander 0.1.0

package/core/mcp/protocol.py

@@ -0,0 +1,288 @@
+"""
+MCP Protocol Module - JSON-RPC 2.0 message handling
+
+This module provides utilities for parsing and creating MCP messages
+following the JSON-RPC 2.0 specification.
+
+Features:
+- Parse incoming JSON-RPC messages
+- Create response/error messages
+- Validate message structure
+- Handle message batching
+"""
+
+import json
+import logging
+from typing import Optional, Any, Dict, List, Union
+
+from .schema import (
+    MCPMessage,
+    MCPError,
+    MCPErrorCode,
+    MCPTool,
+    MCPResource,
+    MCPToolResult,
+    MCPServerCapabilities,
+    MCPServerInfo,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+class MCPProtocolError(Exception):
+    """Exception raised for protocol-level errors."""
+    def __init__(self, code: int, message: str, data: Any = None):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.data = data
+
+
+class MCPProtocol:
+    """
+    MCP Protocol handler for JSON-RPC 2.0 communication.
+    
+    Provides static methods for message parsing, creation, and validation.
+    """
+    
+    # Protocol version
+    JSONRPC_VERSION = "2.0"
+    MCP_PROTOCOL_VERSION = "2024-11-05"
+    
+    @staticmethod
+    def parse(data: str) -> MCPMessage:
+        """
+        Parse a JSON-RPC message from string.
+        
+        Args:
+            data: JSON string to parse
+            
+        Returns:
+            MCPMessage object
+            
+        Raises:
+            MCPProtocolError: If parsing fails or message is invalid
+        """
+        try:
+            obj = json.loads(data)
+        except json.JSONDecodeError as e:
+            raise MCPProtocolError(
+                MCPErrorCode.PARSE_ERROR,
+                f"Invalid JSON: {str(e)}"
+            )
+        
+        # Validate basic structure
+        if not isinstance(obj, dict):
+            raise MCPProtocolError(
+                MCPErrorCode.INVALID_REQUEST,
+                "Message must be a JSON object"
+            )
+        
+        # Check JSON-RPC version
+        if obj.get("jsonrpc") != MCPProtocol.JSONRPC_VERSION:
+            raise MCPProtocolError(
+                MCPErrorCode.INVALID_REQUEST,
+                f"Invalid JSON-RPC version: {obj.get('jsonrpc')}"
+            )
+        
+        return MCPMessage.from_dict(obj)
+    
+    @staticmethod
+    def serialize(msg: MCPMessage) -> str:
+        """
+        Serialize an MCPMessage to JSON string.
+        
+        Args:
+            msg: MCPMessage to serialize
+            
+        Returns:
+            JSON string
+        """
+        return msg.to_json()
+    
+    @staticmethod
+    def create_response(id: int, result: Any) -> MCPMessage:
+        """
+        Create a success response message.
+        
+        Args:
+            id: Request ID to respond to
+            result: Result data
+            
+        Returns:
+            MCPMessage response
+        """
+        return MCPMessage(id=id, result=result)
+    
+    @staticmethod
+    def create_error(id: Optional[int], code: int, message: str, data: Any = None) -> MCPMessage:
+        """
+        Create an error response message.
+        
+        Args:
+            id: Request ID (can be None for parse errors)
+            code: Error code
+            message: Error message
+            data: Optional additional error data
+            
+        Returns:
+            MCPMessage error response
+        """
+        return MCPMessage(
+            id=id,
+            error=MCPError(code=code, message=message, data=data)
+        )
+    
+    @staticmethod
+    def create_notification(method: str, params: Optional[Dict] = None) -> MCPMessage:
+        """
+        Create a notification message (no response expected).
+        
+        Args:
+            method: Method name
+            params: Optional parameters
+            
+        Returns:
+            MCPMessage notification
+        """
+        return MCPMessage(method=method, params=params)
+    
+    # =========================================================================
+    # MCP-specific response creators
+    # =========================================================================
+    
+    @staticmethod
+    def create_initialize_response(
+        id: int,
+        server_info: MCPServerInfo,
+        capabilities: MCPServerCapabilities
+    ) -> MCPMessage:
+        """
+        Create response for 'initialize' request.
+        
+        Args:
+            id: Request ID
+            server_info: Server information
+            capabilities: Server capabilities
+            
+        Returns:
+            MCPMessage response
+        """
+        return MCPProtocol.create_response(id, {
+            "protocolVersion": MCPProtocol.MCP_PROTOCOL_VERSION,
+            "serverInfo": server_info.to_dict(),
+            "capabilities": capabilities.to_dict()
+        })
+    
+    @staticmethod
+    def create_tools_list_response(id: int, tools: List[MCPTool]) -> MCPMessage:
+        """
+        Create response for 'tools/list' request.
+        
+        Args:
+            id: Request ID
+            tools: List of available tools
+            
+        Returns:
+            MCPMessage response
+        """
+        return MCPProtocol.create_response(id, {
+            "tools": [t.to_dict() for t in tools]
+        })
+    
+    @staticmethod
+    def create_tools_call_response(id: int, result: MCPToolResult) -> MCPMessage:
+        """
+        Create response for 'tools/call' request.
+        
+        Args:
+            id: Request ID
+            result: Tool execution result
+            
+        Returns:
+            MCPMessage response
+        """
+        return MCPProtocol.create_response(id, result.to_dict())
+    
+    @staticmethod
+    def create_resources_list_response(id: int, resources: List[MCPResource]) -> MCPMessage:
+        """
+        Create response for 'resources/list' request.
+        
+        Args:
+            id: Request ID
+            resources: List of available resources
+            
+        Returns:
+            MCPMessage response
+        """
+        return MCPProtocol.create_response(id, {
+            "resources": [r.to_dict() for r in resources]
+        })
+    
+    @staticmethod
+    def create_resources_read_response(id: int, contents: List[Dict]) -> MCPMessage:
+        """
+        Create response for 'resources/read' request.
+        
+        Args:
+            id: Request ID
+            contents: List of resource contents
+            
+        Returns:
+            MCPMessage response
+        """
+        return MCPProtocol.create_response(id, {
+            "contents": contents
+        })
+    
+    # =========================================================================
+    # Error response helpers
+    # =========================================================================
+    
+    @staticmethod
+    def method_not_found(id: int, method: str) -> MCPMessage:
+        """Create METHOD_NOT_FOUND error response."""
+        return MCPProtocol.create_error(
+            id,
+            MCPErrorCode.METHOD_NOT_FOUND,
+            f"Method not found: {method}"
+        )
+    
+    @staticmethod
+    def invalid_params(id: int, message: str) -> MCPMessage:
+        """Create INVALID_PARAMS error response."""
+        return MCPProtocol.create_error(
+            id,
+            MCPErrorCode.INVALID_PARAMS,
+            message
+        )
+    
+    @staticmethod
+    def tool_not_found(id: int, tool_name: str) -> MCPMessage:
+        """Create TOOL_NOT_FOUND error response."""
+        return MCPProtocol.create_error(
+            id,
+            MCPErrorCode.TOOL_NOT_FOUND,
+            f"Tool not found: {tool_name}"
+        )
+    
+    @staticmethod
+    def resource_not_found(id: int, uri: str) -> MCPMessage:
+        """Create RESOURCE_NOT_FOUND error response."""
+        return MCPProtocol.create_error(
+            id,
+            MCPErrorCode.RESOURCE_NOT_FOUND,
+            f"Resource not found: {uri}"
+        )
+    
+    @staticmethod
+    def internal_error(id: Optional[int], message: str) -> MCPMessage:
+        """Create INTERNAL_ERROR error response."""
+        return MCPProtocol.create_error(
+            id,
+            MCPErrorCode.INTERNAL_ERROR,
+            message
+        )
+

package/core/mcp/schema.py

@@ -0,0 +1,251 @@
+"""
+MCP Schema Module - Data classes for Model Context Protocol types
+
+This module defines the core data structures used in MCP communication:
+- MCPMessage: JSON-RPC 2.0 message format
+- MCPTool: Tool definition with input schema
+- MCPResource: Resource definition with URI and metadata
+- MCPError: Error response structure
+
+Based on MCP specification: https://modelcontextprotocol.io/
+"""
+
+from dataclasses import dataclass, field, asdict
+from typing import Optional, Dict, Any, List
+from enum import IntEnum
+import json
+
+
+class MCPErrorCode(IntEnum):
+    """Standard JSON-RPC 2.0 and MCP error codes."""
+    # JSON-RPC 2.0 standard errors
+    PARSE_ERROR = -32700
+    INVALID_REQUEST = -32600
+    METHOD_NOT_FOUND = -32601
+    INVALID_PARAMS = -32602
+    INTERNAL_ERROR = -32603
+    
+    # MCP-specific errors
+    RESOURCE_NOT_FOUND = -32001
+    TOOL_NOT_FOUND = -32002
+    TOOL_EXECUTION_ERROR = -32003
+
+
+@dataclass
+class MCPError:
+    """JSON-RPC 2.0 error object."""
+    code: int
+    message: str
+    data: Optional[Any] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        result = {"code": self.code, "message": self.message}
+        if self.data is not None:
+            result["data"] = self.data
+        return result
+
+
+@dataclass
+class MCPMessage:
+    """
+    JSON-RPC 2.0 message structure for MCP communication.
+    
+    Can represent:
+    - Request: has method and optionally params
+    - Response: has result or error
+    - Notification: has method but no id
+    """
+    jsonrpc: str = "2.0"
+    id: Optional[int] = None
+    method: Optional[str] = None
+    params: Optional[Dict[str, Any]] = None
+    result: Optional[Any] = None
+    error: Optional[MCPError] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary, excluding None values."""
+        result = {"jsonrpc": self.jsonrpc}
+        
+        if self.id is not None:
+            result["id"] = self.id
+        if self.method is not None:
+            result["method"] = self.method
+        if self.params is not None:
+            result["params"] = self.params
+        if self.result is not None:
+            result["result"] = self.result
+        if self.error is not None:
+            result["error"] = self.error.to_dict()
+            
+        return result
+    
+    def to_json(self) -> str:
+        """Serialize to JSON string."""
+        return json.dumps(self.to_dict())
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "MCPMessage":
+        """Create MCPMessage from dictionary."""
+        error = None
+        if "error" in data and data["error"] is not None:
+            err_data = data["error"]
+            error = MCPError(
+                code=err_data.get("code", MCPErrorCode.INTERNAL_ERROR),
+                message=err_data.get("message", "Unknown error"),
+                data=err_data.get("data")
+            )
+        
+        return cls(
+            jsonrpc=data.get("jsonrpc", "2.0"),
+            id=data.get("id"),
+            method=data.get("method"),
+            params=data.get("params"),
+            result=data.get("result"),
+            error=error
+        )
+    
+    @classmethod
+    def from_json(cls, json_str: str) -> "MCPMessage":
+        """Parse MCPMessage from JSON string."""
+        return cls.from_dict(json.loads(json_str))
+    
+    def is_request(self) -> bool:
+        """Check if this is a request message."""
+        return self.method is not None and self.id is not None
+    
+    def is_notification(self) -> bool:
+        """Check if this is a notification (request without id)."""
+        return self.method is not None and self.id is None
+    
+    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)
+
+
+@dataclass
+class MCPTool:
+    """
+    MCP Tool definition.
+    
+    Represents a callable tool with its metadata and input schema.
+    """
+    name: str
+    description: str
+    inputSchema: Dict[str, Any] = field(default_factory=lambda: {
+        "type": "object",
+        "properties": {},
+        "required": []
+    })
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to MCP tool definition format."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "inputSchema": self.inputSchema
+        }
+
+
+@dataclass
+class MCPResource:
+    """
+    MCP Resource definition.
+    
+    Represents a readable resource with URI and metadata.
+    """
+    uri: str
+    name: str
+    description: str = ""
+    mimeType: str = "text/plain"
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to MCP resource definition format."""
+        return {
+            "uri": self.uri,
+            "name": self.name,
+            "description": self.description,
+            "mimeType": self.mimeType
+        }
+
+
+@dataclass
+class MCPResourceContent:
+    """Content of a resource when read."""
+    uri: str
+    mimeType: str = "text/plain"
+    text: Optional[str] = None
+    blob: Optional[str] = None  # Base64-encoded binary data
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to MCP resource content format."""
+        result = {"uri": self.uri, "mimeType": self.mimeType}
+        if self.text is not None:
+            result["text"] = self.text
+        if self.blob is not None:
+            result["blob"] = self.blob
+        return result
+
+
+@dataclass
+class MCPToolResult:
+    """Result of a tool execution."""
+    content: List[Dict[str, Any]] = field(default_factory=list)
+    isError: bool = False
+    
+    @classmethod
+    def text(cls, text: str, is_error: bool = False) -> "MCPToolResult":
+        """Create a text result."""
+        return cls(
+            content=[{"type": "text", "text": text}],
+            isError=is_error
+        )
+    
+    @classmethod
+    def error(cls, message: str) -> "MCPToolResult":
+        """Create an error result."""
+        return cls.text(message, is_error=True)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to MCP tool result format."""
+        return {
+            "content": self.content,
+            "isError": self.isError
+        }
+
+
+@dataclass 
+class MCPServerCapabilities:
+    """Server capabilities advertised during initialization."""
+    tools: bool = True
+    resources: bool = True
+    prompts: bool = False
+    logging: bool = False
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to MCP capabilities format."""
+        caps = {}
+        if self.tools:
+            caps["tools"] = {}
+        if self.resources:
+            caps["resources"] = {}
+        if self.prompts:
+            caps["prompts"] = {}
+        if self.logging:
+            caps["logging"] = {}
+        return caps
+
+
+@dataclass
+class MCPServerInfo:
+    """Server information returned during initialization."""
+    name: str = "pomera-mcp-server"
+    version: str = "0.1.0"
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to MCP server info format."""
+        return {
+            "name": self.name,
+            "version": self.version
+        }
+