mseep-rmcp 0.3.3__py3-none-any.whl

rmcp/registries/prompts.py

@@ -0,0 +1,316 @@
+"""
+Prompts registry for MCP server.
+
+Implements mature MCP patterns:
+- Templated workflows that teach LLMs tool chaining
+- Parameterized prompts with typed arguments
+- Statistical analysis playbooks
+
+Following the principle: "Ship prompts as workflows."
+"""
+
+from typing import Any, Dict, List, Optional, Callable
+from dataclasses import dataclass
+import logging
+
+from ..core.context import Context
+from ..core.schemas import validate_schema, SchemaError
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PromptDefinition:
+    """Prompt template metadata and content."""
+    
+    name: str
+    title: str
+    description: str
+    arguments_schema: Optional[Dict[str, Any]]
+    template: str
+    annotations: Optional[Dict[str, Any]] = None
+
+
+class PromptsRegistry:
+    """Registry for MCP prompts with templating support."""
+    
+    def __init__(self):
+        self._prompts: Dict[str, PromptDefinition] = {}
+    
+    def register(
+        self,
+        name: str,
+        title: str,
+        description: str,
+        template: str,
+        arguments_schema: Optional[Dict[str, Any]] = None,
+        annotations: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Register a prompt template."""
+        
+        if name in self._prompts:
+            logger.warning(f"Prompt '{name}' already registered, overwriting")
+        
+        self._prompts[name] = PromptDefinition(
+            name=name,
+            title=title,
+            description=description,
+            template=template,
+            arguments_schema=arguments_schema,
+            annotations=annotations or {},
+        )
+        
+        logger.debug(f"Registered prompt: {name}")
+    
+    async def list_prompts(self, context: Context) -> Dict[str, Any]:
+        """List available prompts for MCP prompts/list."""
+        
+        prompts = []
+        for prompt_def in self._prompts.values():
+            prompt_info = {
+                "name": prompt_def.name,
+                "title": prompt_def.title,
+                "description": prompt_def.description,
+            }
+            
+            if prompt_def.arguments_schema:
+                prompt_info["argumentsSchema"] = prompt_def.arguments_schema
+            
+            if prompt_def.annotations:
+                prompt_info["annotations"] = prompt_def.annotations
+            
+            prompts.append(prompt_info)
+        
+        await context.info(f"Listed {len(prompts)} available prompts")
+        
+        return {"prompts": prompts}
+    
+    async def get_prompt(
+        self, 
+        context: Context, 
+        name: str, 
+        arguments: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Get a rendered prompt for MCP prompts/get."""
+        
+        if name not in self._prompts:
+            raise ValueError(f"Unknown prompt: {name}")
+        
+        prompt_def = self._prompts[name]
+        arguments = arguments or {}
+        
+        try:
+            # Validate arguments if schema provided
+            if prompt_def.arguments_schema:
+                validate_schema(
+                    arguments, 
+                    prompt_def.arguments_schema, 
+                    f"prompt '{name}' arguments"
+                )
+            
+            # Render template
+            rendered_content = self._render_template(prompt_def.template, arguments)
+            
+            await context.info(f"Rendered prompt: {name}", arguments=arguments)
+            
+            return {
+                "messages": [
+                    {
+                        "role": "user",
+                        "content": {
+                            "type": "text", 
+                            "text": rendered_content
+                        }
+                    }
+                ]
+            }
+        
+        except SchemaError as e:
+            await context.error(f"Schema validation failed for prompt '{name}': {e}")
+            raise
+        
+        except Exception as e:
+            await context.error(f"Failed to render prompt '{name}': {e}")
+            raise
+    
+    def _render_template(self, template: str, arguments: Dict[str, Any]) -> str:
+        """Render template with arguments using simple string formatting."""
+        
+        try:
+            # Use simple string formatting for now
+            # Could be enhanced with Jinja2 or similar
+            return template.format(**arguments)
+        except KeyError as e:
+            raise ValueError(f"Missing template argument: {e}")
+        except Exception as e:
+            raise ValueError(f"Template rendering error: {e}")
+
+
+def prompt(
+    name: str,
+    title: str,
+    description: str,
+    arguments_schema: Optional[Dict[str, Any]] = None,
+    annotations: Optional[Dict[str, Any]] = None,
+):
+    """
+    Decorator to register a prompt template.
+    
+    Usage:
+        @prompt(
+            name="analyze_workflow", 
+            title="Statistical Analysis Workflow",
+            description="Guide for comprehensive statistical analysis",
+            arguments_schema={
+                "type": "object",
+                "properties": {
+                    "dataset_name": {"type": "string"},
+                    "analysis_type": {"type": "string", "enum": ["descriptive", "inferential", "predictive"]}
+                },
+                "required": ["dataset_name"]
+            }
+        )
+        def analyze_workflow():
+            return '''
+            I'll help you analyze the {dataset_name} dataset using {analysis_type} methods.
+            
+            Let me start by examining the data structure and then proceed with the analysis.
+            '''
+    """
+    
+    def decorator(func: Callable[[], str]):
+        
+        # Extract template content from function
+        template_content = func()
+        
+        # Store prompt metadata on function
+        func._mcp_prompt_name = name
+        func._mcp_prompt_title = title
+        func._mcp_prompt_description = description
+        func._mcp_prompt_template = template_content
+        func._mcp_prompt_arguments_schema = arguments_schema
+        func._mcp_prompt_annotations = annotations
+        
+        return func
+    
+    return decorator
+
+
+def register_prompt_functions(registry: PromptsRegistry, *functions) -> None:
+    """Register multiple functions decorated with @prompt."""
+    
+    for func in functions:
+        if hasattr(func, '_mcp_prompt_name'):
+            registry.register(
+                name=func._mcp_prompt_name,
+                title=func._mcp_prompt_title,
+                description=func._mcp_prompt_description,
+                template=func._mcp_prompt_template,
+                arguments_schema=func._mcp_prompt_arguments_schema,
+                annotations=func._mcp_prompt_annotations,
+            )
+        else:
+            logger.warning(f"Function {func.__name__} not decorated with @prompt, skipping")
+
+
+# Built-in statistical analysis workflow prompts
+
+@prompt(
+    name="statistical_workflow",
+    title="Statistical Analysis Workflow", 
+    description="Comprehensive workflow for statistical data analysis",
+    arguments_schema={
+        "type": "object",
+        "properties": {
+            "dataset_name": {"type": "string"},
+            "analysis_goals": {"type": "string"},
+            "variables_of_interest": {"type": "array", "items": {"type": "string"}},
+        },
+        "required": ["dataset_name", "analysis_goals"]
+    }
+)
+def statistical_workflow_prompt():
+    return """I'll help you conduct a comprehensive statistical analysis of the {dataset_name} dataset.
+
+Analysis Goals: {analysis_goals}
+Variables of Interest: {variables_of_interest}
+
+Let me guide you through a systematic analysis workflow:
+
+**Phase 1: Data Exploration**
+1. First, I'll examine the dataset structure and summary statistics
+2. Check for missing values, outliers, and data quality issues  
+3. Visualize distributions and relationships between variables
+
+**Phase 2: Analysis Selection**
+Based on your goals and data characteristics, I'll recommend:
+- Appropriate statistical tests or models
+- Required assumptions and validation steps
+- Visualization strategies
+
+**Phase 3: Statistical Analysis**
+I'll execute the analysis using appropriate tools and provide:
+- Statistical results with interpretation
+- Effect sizes and confidence intervals
+- Diagnostic plots and assumption checking
+
+**Phase 4: Results & Recommendations**
+Finally, I'll summarize:
+- Key findings and their practical significance
+- Limitations and caveats
+- Recommendations for next steps
+
+Let's begin by examining your dataset. Please provide the data or specify how to access it."""
+
+
+@prompt(
+    name="model_diagnostic_workflow",
+    title="Model Diagnostics Workflow",
+    description="Systematic model validation and diagnostics",
+    arguments_schema={
+        "type": "object", 
+        "properties": {
+            "model_type": {"type": "string", "enum": ["linear", "logistic", "time_series", "ml"]},
+            "focus_areas": {"type": "array", "items": {"type": "string"}},
+        },
+        "required": ["model_type"]
+    }
+)
+def model_diagnostic_prompt():
+    return """I'll help you conduct thorough diagnostics for your {model_type} model.
+
+Focus Areas: {focus_areas}
+
+**Model Diagnostic Workflow**
+
+**1. Residual Analysis**
+- Plot residuals vs fitted values
+- Check for patterns indicating model misspecification
+- Assess homoscedasticity assumptions
+
+**2. Distribution Checks**
+- Q-Q plots for normality assessment
+- Histogram of residuals
+- Statistical tests for distributional assumptions
+
+**3. Influence & Outliers**  
+- Identify high-leverage points
+- Cook's distance for influential observations
+- Studentized residuals analysis
+
+**4. Model Assumptions**
+- Linearity checks (for linear models)
+- Independence verification
+- Multicollinearity assessment (VIF)
+
+**5. Predictive Performance**
+- Cross-validation results
+- Out-of-sample performance metrics  
+- Calibration plots (for probabilistic models)
+
+**6. Interpretation & Validation**
+- Coefficient stability
+- Bootstrap confidence intervals
+- Sensitivity analysis
+
+Let's start the diagnostic process. Please provide your model results or specify how to access the fitted model."""

rmcp/registries/resources.py

@@ -0,0 +1,266 @@
+"""
+Resources registry for MCP server.
+
+Implements mature MCP patterns:
+- Read-only endpoints for files and in-memory objects
+- URI-based addressing (file://, mem://)
+- Resource templates for parameterized access
+- VFS integration for security
+
+Following the principle: "Keeps data access explicit and auditable."
+"""
+
+from typing import Any, Dict, List, Optional, Union, Callable, Awaitable
+from urllib.parse import urlparse, parse_qs
+from pathlib import Path
+import base64
+import logging
+
+from ..core.context import Context
+from ..security.vfs import VFS, VFSError
+
+logger = logging.getLogger(__name__)
+
+
+class ResourcesRegistry:
+    """Registry for MCP resources with VFS security."""
+    
+    def __init__(self):
+        self._static_resources: Dict[str, Dict[str, Any]] = {}
+        self._memory_objects: Dict[str, Any] = {}
+        self._resource_templates: Dict[str, str] = {}
+    
+    def register_static_resource(
+        self,
+        uri: str,
+        name: str,
+        description: Optional[str] = None,
+        mime_type: Optional[str] = None,
+    ) -> None:
+        """Register a static resource."""
+        
+        self._static_resources[uri] = {
+            "uri": uri,
+            "name": name, 
+            "description": description or f"Resource: {name}",
+            "mimeType": mime_type,
+        }
+        
+        logger.debug(f"Registered static resource: {uri}")
+    
+    def register_memory_object(
+        self,
+        name: str,
+        data: Any,
+        description: Optional[str] = None,
+        mime_type: str = "application/json",
+    ) -> None:
+        """Register an in-memory object as a resource."""
+        
+        uri = f"mem://object/{name}"
+        self._memory_objects[name] = data
+        
+        self._static_resources[uri] = {
+            "uri": uri,
+            "name": name,
+            "description": description or f"Memory object: {name}",
+            "mimeType": mime_type,
+        }
+        
+        logger.debug(f"Registered memory object: {name}")
+    
+    def register_resource_template(
+        self,
+        uri_template: str,
+        name: str,
+        description: Optional[str] = None,
+    ) -> None:
+        """Register a parameterized resource template."""
+        
+        self._resource_templates[uri_template] = name
+        
+        logger.debug(f"Registered resource template: {uri_template}")
+    
+    async def list_resources(self, context: Context) -> Dict[str, Any]:
+        """List available resources for MCP resources/list."""
+        
+        resources = []
+        
+        # Static resources
+        for resource_info in self._static_resources.values():
+            resources.append(resource_info)
+        
+        # Resource templates
+        for uri_template, name in self._resource_templates.items():
+            resources.append({
+                "uri": uri_template,
+                "name": name,
+                "description": f"Template: {name}",
+            })
+        
+        # File system resources (if VFS configured)
+        if hasattr(context.lifespan, 'vfs') and context.lifespan.vfs:
+            for mount_name, mount_path in context.lifespan.resource_mounts.items():
+                resources.append({
+                    "uri": f"file://{mount_name}/",
+                    "name": f"Files: {mount_name}",
+                    "description": f"File system mount: {mount_path}",
+                })
+        
+        await context.info(f"Listed {len(resources)} available resources")
+        
+        return {"resources": resources}
+    
+    async def read_resource(self, context: Context, uri: str) -> Dict[str, Any]:
+        """Read a resource for MCP resources/read."""
+        
+        try:
+            parsed_uri = urlparse(uri)
+            scheme = parsed_uri.scheme
+            
+            if scheme == "file":
+                return await self._read_file_resource(context, parsed_uri)
+            elif scheme == "mem":
+                return await self._read_memory_resource(context, parsed_uri)
+            else:
+                # Check static resources
+                if uri in self._static_resources:
+                    return await self._read_static_resource(context, uri)
+                else:
+                    raise ValueError(f"Unsupported resource scheme or unknown URI: {uri}")
+        
+        except Exception as e:
+            await context.error(f"Failed to read resource {uri}: {e}")
+            raise
+    
+    async def _read_file_resource(self, context: Context, parsed_uri) -> Dict[str, Any]:
+        """Read file:// resource using VFS."""
+        
+        # Extract path from URI
+        file_path = Path(parsed_uri.path)
+        
+        try:
+            # Use VFS for secure file access
+            if hasattr(context.lifespan, 'vfs') and context.lifespan.vfs:
+                vfs = context.lifespan.vfs
+            else:
+                # Fallback to direct path validation
+                context.require_path_access(file_path)
+                content = file_path.read_bytes()
+                mime_type = "application/octet-stream"
+            
+            if 'vfs' in locals():
+                content = vfs.read_file(file_path)
+                file_info = vfs.file_info(file_path)
+                mime_type = file_info.get("mime_type", "application/octet-stream")
+            
+            # Determine if content should be base64 encoded
+            is_text = mime_type and mime_type.startswith("text/")
+            
+            if is_text:
+                try:
+                    text_content = content.decode('utf-8')
+                    return {
+                        "contents": [
+                            {
+                                "uri": str(parsed_uri.geturl()),
+                                "mimeType": mime_type,
+                                "text": text_content,
+                            }
+                        ]
+                    }
+                except UnicodeDecodeError:
+                    # Fall back to binary
+                    pass
+            
+            # Binary content
+            b64_content = base64.b64encode(content).decode('ascii')
+            return {
+                "contents": [
+                    {
+                        "uri": str(parsed_uri.geturl()),
+                        "mimeType": mime_type,
+                        "blob": b64_content,
+                    }
+                ]
+            }
+        
+        except (VFSError, PermissionError, FileNotFoundError) as e:
+            raise ValueError(f"File access error: {e}")
+    
+    async def _read_memory_resource(self, context: Context, parsed_uri) -> Dict[str, Any]:
+        """Read mem:// resource from memory objects."""
+        
+        # Extract object name from URI path
+        path_parts = parsed_uri.path.strip('/').split('/')
+        if len(path_parts) < 2 or path_parts[0] != "object":
+            raise ValueError(f"Invalid memory resource URI: {parsed_uri.geturl()}")
+        
+        object_name = path_parts[1]
+        
+        if object_name not in self._memory_objects:
+            raise ValueError(f"Memory object not found: {object_name}")
+        
+        data = self._memory_objects[object_name]
+        
+        # Serialize object to JSON text
+        import json
+        try:
+            text_content = json.dumps(data, indent=2, default=str)
+            return {
+                "contents": [
+                    {
+                        "uri": parsed_uri.geturl(),
+                        "mimeType": "application/json",
+                        "text": text_content,
+                    }
+                ]
+            }
+        except (TypeError, ValueError) as e:
+            raise ValueError(f"Failed to serialize memory object {object_name}: {e}")
+    
+    async def _read_static_resource(self, context: Context, uri: str) -> Dict[str, Any]:
+        """Read a pre-registered static resource."""
+        
+        resource_info = self._static_resources[uri]
+        
+        # Static resources would need their content defined somewhere
+        # For now, return placeholder
+        return {
+            "contents": [
+                {
+                    "uri": uri,
+                    "mimeType": resource_info.get("mimeType", "text/plain"),
+                    "text": f"Static resource: {resource_info['name']}",
+                }
+            ]
+        }
+
+
+def resource(
+    uri: str,
+    name: str,
+    description: Optional[str] = None,
+    mime_type: Optional[str] = None,
+):
+    """
+    Decorator to register a static resource.
+    
+    Usage:
+        @resource(
+            uri="static://example",
+            name="Example Resource",
+            description="An example static resource"
+        )
+        def example_resource():
+            return "resource content"
+    """
+    
+    def decorator(func):
+        func._mcp_resource_uri = uri
+        func._mcp_resource_name = name
+        func._mcp_resource_description = description
+        func._mcp_resource_mime_type = mime_type
+        return func
+    
+    return decorator