kailash 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

kailash/nodes/mcp/server.py

@@ -0,0 +1,571 @@
+"""MCP Server node for hosting Model Context Protocol resources and tools."""
+
+import json
+from typing import Any, Dict, List
+
+from kailash.nodes.base import Node, NodeParameter, register_node
+
+
+@register_node()
+class MCPServer(Node):
+    """
+    Server node for hosting Model Context Protocol (MCP) resources and tools.
+
+    Design Purpose and Philosophy:
+    The MCPServer node allows workflows to expose their data and functionality as
+    standardized MCP resources and tools. This enables other AI applications and
+    agents to discover and interact with workflow capabilities through the MCP protocol.
+
+    Upstream Dependencies:
+    - Resource data to expose (files, databases, APIs)
+    - Tool implementations to register with the server
+    - Prompt templates to make available to clients
+    - Server configuration and authentication settings
+
+    Downstream Consumers:
+    - MCP clients that connect to discover resources
+    - AI applications that need workflow context
+    - Other Kailash workflows acting as MCP clients
+    - External tools and services supporting MCP
+
+    Usage Patterns:
+    1. Start MCP server with specified resources and tools
+    2. Register dynamic resources that update in real-time
+    3. Expose workflow capabilities as callable tools
+    4. Provide prompt templates for standardized interactions
+    5. Handle client connections and protocol compliance
+
+    Implementation Details:
+    - Uses the FastMCP framework for rapid server development
+    - Supports stdio, SSE, and HTTP transports automatically
+    - Implements proper resource discovery and metadata
+    - Provides authentication and access control mechanisms
+    - Handles concurrent client connections efficiently
+
+    Error Handling:
+    - ServerStartupError: When server fails to initialize
+    - ResourceRegistrationError: When resources cannot be registered
+    - ToolExecutionError: When tool calls fail during execution
+    - ClientConnectionError: When client connections are rejected
+    - ProtocolViolationError: When clients violate MCP protocol
+
+    Side Effects:
+    - Starts a network server process listening on specified ports
+    - Registers resources and tools in the MCP protocol registry
+    - May modify external systems when tools are executed
+    - Logs server events and client interactions
+
+    Examples:
+    ```python
+    # Start a basic MCP server with resources
+    server = MCPServer()
+    result = server.run(
+        server_config={
+            "name": "workflow-server",
+            "transport": "stdio"
+        },
+        resources=[
+            {
+                "uri": "workflow://current/status",
+                "name": "Workflow Status",
+                "content": "Running workflow with 5 active nodes"
+            }
+        ],
+        tools=[
+            {
+                "name": "execute_node",
+                "description": "Execute a specific workflow node",
+                "parameters": {
+                    "node_id": {"type": "string", "required": True}
+                }
+            }
+        ]
+    )
+
+    # Register dynamic resources
+    server_with_dynamic = MCPServer()
+    result = server_with_dynamic.run(
+        server_config={
+            "name": "data-server",
+            "transport": "http",
+            "port": 8080
+        },
+        resource_providers={
+            "database://tables/*": "list_database_tables",
+            "file://workspace/*": "list_workspace_files"
+        }
+    )
+    ```
+    """
+
+    def get_parameters(self) -> Dict[str, NodeParameter]:
+        return {
+            "server_config": NodeParameter(
+                name="server_config",
+                type=dict,
+                required=False,
+                default={},
+                description="MCP server configuration (name, transport, port, etc.)",
+            ),
+            "resources": NodeParameter(
+                name="resources",
+                type=list,
+                required=False,
+                default=[],
+                description="Static resources to expose (list of resource objects)",
+            ),
+            "tools": NodeParameter(
+                name="tools",
+                type=list,
+                required=False,
+                default=[],
+                description="Tools to register with the server (list of tool definitions)",
+            ),
+            "prompts": NodeParameter(
+                name="prompts",
+                type=list,
+                required=False,
+                default=[],
+                description="Prompt templates to make available (list of prompt objects)",
+            ),
+            "resource_providers": NodeParameter(
+                name="resource_providers",
+                type=dict,
+                required=False,
+                default={},
+                description="Dynamic resource providers (URI pattern -> provider function)",
+            ),
+            "authentication": NodeParameter(
+                name="authentication",
+                type=dict,
+                required=False,
+                default={},
+                description="Authentication configuration (type, credentials, etc.)",
+            ),
+            "auto_start": NodeParameter(
+                name="auto_start",
+                type=bool,
+                required=False,
+                default=True,
+                description="Whether to automatically start the server",
+            ),
+            "max_connections": NodeParameter(
+                name="max_connections",
+                type=int,
+                required=False,
+                default=10,
+                description="Maximum number of concurrent client connections",
+            ),
+        }
+
+    def run(self, **kwargs) -> Dict[str, Any]:
+        server_config = kwargs["server_config"]
+        resources = kwargs.get("resources", [])
+        tools = kwargs.get("tools", [])
+        prompts = kwargs.get("prompts", [])
+        resource_providers = kwargs.get("resource_providers", {})
+        authentication = kwargs.get("authentication", {})
+        auto_start = kwargs.get("auto_start", True)
+        max_connections = kwargs.get("max_connections", 10)
+
+        try:
+            # Import MCP SDK (graceful fallback if not installed)
+            try:
+                from mcp.server import Server
+                from mcp.server.fastmcp import FastMCP
+                from mcp.types import Prompt, Resource, Tool
+
+                mcp_available = True
+            except ImportError:
+                mcp_available = False
+
+            if not mcp_available:
+                # Provide mock functionality when MCP SDK is not available
+                return self._mock_mcp_server(
+                    server_config,
+                    resources,
+                    tools,
+                    prompts,
+                    resource_providers,
+                    authentication,
+                    auto_start,
+                    max_connections,
+                )
+
+            # Extract server configuration
+            server_name = server_config.get("name", "kailash-server")
+            transport_type = server_config.get("transport", "stdio")
+            port = server_config.get("port", 8080)
+            host = server_config.get("host", "localhost")
+
+            # For now, provide mock implementation as we need proper MCP server setup
+            return self._mock_fastmcp_server(
+                server_name,
+                transport_type,
+                host,
+                port,
+                resources,
+                tools,
+                prompts,
+                resource_providers,
+                authentication,
+                auto_start,
+                max_connections,
+            )
+
+        except Exception as e:
+            return {
+                "success": False,
+                "error": str(e),
+                "error_type": type(e).__name__,
+                "server_config": server_config,
+            }
+
+    def _mock_mcp_server(
+        self,
+        server_config: dict,
+        resources: List[dict],
+        tools: List[dict],
+        prompts: List[dict],
+        resource_providers: dict,
+        authentication: dict,
+        auto_start: bool,
+        max_connections: int,
+    ) -> Dict[str, Any]:
+        """Mock MCP server when SDK is not available."""
+        server_name = server_config.get("name", "mock-server")
+        transport = server_config.get("transport", "stdio")
+
+        # Validate resources
+        validated_resources = []
+        for resource in resources:
+            if not isinstance(resource, dict):
+                continue
+
+            uri = resource.get("uri")
+            name = resource.get("name", uri)
+            description = resource.get("description", f"Resource: {name}")
+
+            if uri:
+                validated_resources.append(
+                    {
+                        "uri": uri,
+                        "name": name,
+                        "description": description,
+                        "mimeType": resource.get("mimeType", "text/plain"),
+                        "content": resource.get("content"),
+                    }
+                )
+
+        # Validate tools
+        validated_tools = []
+        for tool in tools:
+            if not isinstance(tool, dict):
+                continue
+
+            name = tool.get("name")
+            description = tool.get("description", f"Tool: {name}")
+
+            if name:
+                validated_tools.append(
+                    {
+                        "name": name,
+                        "description": description,
+                        "inputSchema": tool.get("parameters", {}),
+                        "handler": tool.get("handler", f"mock_handler_{name}"),
+                    }
+                )
+
+        # Validate prompts
+        validated_prompts = []
+        for prompt in prompts:
+            if not isinstance(prompt, dict):
+                continue
+
+            name = prompt.get("name")
+            description = prompt.get("description", f"Prompt: {name}")
+
+            if name:
+                validated_prompts.append(
+                    {
+                        "name": name,
+                        "description": description,
+                        "arguments": prompt.get("arguments", []),
+                        "template": prompt.get("template", f"Mock template for {name}"),
+                    }
+                )
+
+        # Mock server status
+        server_status = {
+            "name": server_name,
+            "transport": transport,
+            "status": "running" if auto_start else "configured",
+            "pid": 12345,  # Mock process ID
+            "started_at": "2025-06-01T12:00:00Z",
+            "uptime": "0:00:05",
+            "connections": {"active": 0, "total": 0, "max": max_connections},
+            "capabilities": {
+                "resources": True,
+                "tools": True,
+                "prompts": True,
+                "logging": True,
+            },
+        }
+
+        if transport == "http":
+            host = server_config.get("host", "localhost")
+            port = server_config.get("port", 8080)
+            server_status.update(
+                {
+                    "host": host,
+                    "port": port,
+                    "url": f"http://{host}:{port}",
+                    "endpoints": {
+                        "sse": f"http://{host}:{port}/sse",
+                        "resources": f"http://{host}:{port}/resources",
+                        "tools": f"http://{host}:{port}/tools",
+                        "prompts": f"http://{host}:{port}/prompts",
+                    },
+                }
+            )
+
+        return {
+            "success": True,
+            "server": server_status,
+            "resources": {
+                "registered": validated_resources,
+                "count": len(validated_resources),
+                "providers": (
+                    list(resource_providers.keys()) if resource_providers else []
+                ),
+            },
+            "tools": {"registered": validated_tools, "count": len(validated_tools)},
+            "prompts": {
+                "registered": validated_prompts,
+                "count": len(validated_prompts),
+            },
+            "authentication": {
+                "enabled": bool(authentication),
+                "type": authentication.get("type", "none"),
+            },
+            "mock": True,
+            "message": f"Mock MCP server '{server_name}' configured successfully",
+        }
+
+    def _mock_fastmcp_server(
+        self,
+        server_name: str,
+        transport_type: str,
+        host: str,
+        port: int,
+        resources: List[dict],
+        tools: List[dict],
+        prompts: List[dict],
+        resource_providers: dict,
+        authentication: dict,
+        auto_start: bool,
+        max_connections: int,
+    ) -> Dict[str, Any]:
+        """Mock FastMCP server implementation."""
+
+        # Create mock FastMCP server configuration
+        server_code = f"""
+# Mock FastMCP server code for {server_name}
+from mcp.server.fastmcp import FastMCP
+
+# Create server instance
+mcp = FastMCP("{server_name}")
+
+# Register resources
+{self._generate_resource_code(resources)}
+
+# Register tools
+{self._generate_tool_code(tools)}
+
+# Register prompts
+{self._generate_prompt_code(prompts)}
+
+# Dynamic resource providers
+{self._generate_provider_code(resource_providers)}
+
+if __name__ == "__main__":
+    mcp.run()
+"""
+
+        # Mock server startup
+        startup_info = {
+            "server_name": server_name,
+            "transport": transport_type,
+            "generated_code": server_code,
+            "status": "ready" if auto_start else "configured",
+            "resources_count": len(resources),
+            "tools_count": len(tools),
+            "prompts_count": len(prompts),
+            "providers_count": len(resource_providers),
+        }
+
+        if transport_type == "http":
+            startup_info.update(
+                {
+                    "host": host,
+                    "port": port,
+                    "url": f"http://{host}:{port}",
+                    "sse_endpoint": f"http://{host}:{port}/sse",
+                }
+            )
+
+        return {
+            "success": True,
+            "server": startup_info,
+            "code": server_code,
+            "mock": True,
+            "next_steps": [
+                "Save the generated code to a Python file",
+                "Install MCP dependencies: pip install 'mcp[cli]'",
+                "Run the server: python server_file.py",
+                "Connect clients using the specified transport",
+            ],
+        }
+
+    def _generate_resource_code(self, resources: List[dict]) -> str:
+        """Generate Python code for resource registration."""
+        if not resources:
+            return "# No static resources defined"
+
+        code_lines = []
+        for resource in resources:
+            uri = resource.get("uri", "")
+            content = resource.get("content", "")
+            name = resource.get("name", uri)
+
+            # Escape strings for Python code
+            content_escaped = json.dumps(content) if content else '""'
+
+            code_lines.append(f'@mcp.resource("{uri}")')
+            code_lines.append(f"def get_{self._sanitize_name(uri)}():")
+            code_lines.append(f'    """Resource: {name}"""')
+            code_lines.append(f"    return {content_escaped}")
+            code_lines.append("")
+
+        return "\n".join(code_lines)
+
+    def _generate_tool_code(self, tools: List[dict]) -> str:
+        """Generate Python code for tool registration."""
+        if not tools:
+            return "# No tools defined"
+
+        code_lines = []
+        for tool in tools:
+            name = tool.get("name", "")
+            description = tool.get("description", "")
+            parameters = tool.get("parameters", {})
+
+            # Generate function parameters from schema
+            param_list = []
+
+            # Handle OpenAPI schema format
+            if isinstance(parameters, dict) and "properties" in parameters:
+                properties = parameters.get("properties", {})
+                required = parameters.get("required", [])
+
+                for param_name, param_info in properties.items():
+                    param_type = (
+                        param_info.get("type", "str")
+                        if isinstance(param_info, dict)
+                        else "str"
+                    )
+                    if param_name in required:
+                        param_list.append(f"{param_name}: {param_type}")
+                    else:
+                        param_list.append(f"{param_name}: {param_type} = None")
+            # Handle simple parameter format
+            elif isinstance(parameters, dict):
+                for param_name, param_info in parameters.items():
+                    if isinstance(param_info, dict):
+                        param_type = param_info.get("type", "str")
+                        if param_info.get("required", False):
+                            param_list.append(f"{param_name}: {param_type}")
+                        else:
+                            param_list.append(f"{param_name}: {param_type} = None")
+                    else:
+                        param_list.append(f"{param_name}: str = None")
+
+            param_str = ", ".join(param_list) if param_list else ""
+
+            code_lines.append("@mcp.tool()")
+            code_lines.append(f"def {name}({param_str}):")
+            code_lines.append(f'    """{description}"""')
+            code_lines.append("    # Mock tool implementation")
+            code_lines.append(
+                f'    return {{"tool": "{name}", "status": "executed", "parameters": locals()}}'
+            )
+            code_lines.append("")
+
+        return "\n".join(code_lines)
+
+    def _generate_prompt_code(self, prompts: List[dict]) -> str:
+        """Generate Python code for prompt registration."""
+        if not prompts:
+            return "# No prompts defined"
+
+        code_lines = []
+        for prompt in prompts:
+            name = prompt.get("name", "")
+            template = prompt.get("template", "")
+            arguments = prompt.get("arguments", [])
+
+            # Generate function parameters from arguments
+            param_list = []
+            for arg in arguments:
+                if isinstance(arg, dict):
+                    arg_name = arg.get("name", "")
+                    if arg.get("required", False):
+                        param_list.append(f"{arg_name}: str")
+                    else:
+                        param_list.append(f"{arg_name}: str = ''")
+
+            param_str = ", ".join(param_list) if param_list else ""
+
+            code_lines.append(f'@mcp.prompt("{name}")')
+            code_lines.append(f"def {name}_prompt({param_str}):")
+            code_lines.append(f'    """Prompt: {name}"""')
+            if template:
+                template_escaped = json.dumps(template)
+                code_lines.append(f"    template = {template_escaped}")
+                code_lines.append("    return template.format(**locals())")
+            else:
+                code_lines.append(
+                    f'    return f"Mock prompt: {name} with args: {{locals()}}"'
+                )
+            code_lines.append("")
+
+        return "\n".join(code_lines)
+
+    def _generate_provider_code(self, providers: dict) -> str:
+        """Generate Python code for dynamic resource providers."""
+        if not providers:
+            return "# No dynamic resource providers defined"
+
+        code_lines = []
+        for pattern, provider_func in providers.items():
+            sanitized_pattern = self._sanitize_name(pattern)
+
+            code_lines.append(f'@mcp.resource("{pattern}")')
+            code_lines.append(f"def dynamic_{sanitized_pattern}(**kwargs):")
+            code_lines.append(f'    """Dynamic resource provider for {pattern}"""')
+            code_lines.append("    # Mock dynamic resource implementation")
+            code_lines.append('    return f"Dynamic content for {kwargs}"')
+            code_lines.append("")
+
+        return "\n".join(code_lines)
+
+    def _sanitize_name(self, name: str) -> str:
+        """Sanitize a name for use as Python identifier."""
+        import re
+
+        # Replace non-alphanumeric characters with underscores
+        sanitized = re.sub(r"[^a-zA-Z0-9_]", "_", name)
+        # Ensure it starts with a letter or underscore
+        if sanitized and sanitized[0].isdigit():
+            sanitized = f"r_{sanitized}"
+        return sanitized or "unnamed"

kailash/nodes/transform/__init__.py

@@ -1,5 +1,20 @@
 """Transform processing nodes for the Kailash SDK."""
 
+from kailash.nodes.transform.chunkers import HierarchicalChunkerNode
+from kailash.nodes.transform.formatters import (
+    ChunkTextExtractorNode,
+    ContextFormatterNode,
+    QueryTextWrapperNode,
+)
 from kailash.nodes.transform.processors import DataTransformer, Filter, Map, Sort
 
-__all__ = ["Filter", "Map", "Sort", "DataTransformer"]
+__all__ = [
+    "Filter",
+    "Map",
+    "Sort",
+    "DataTransformer",
+    "HierarchicalChunkerNode",
+    "ChunkTextExtractorNode",
+    "QueryTextWrapperNode",
+    "ContextFormatterNode",
+]

kailash/nodes/transform/chunkers.py

@@ -0,0 +1,78 @@
+"""Document chunking nodes for splitting text into manageable pieces."""
+
+from typing import Any, Dict
+
+from kailash.nodes.base import Node, NodeParameter, register_node
+
+
+@register_node()
+class HierarchicalChunkerNode(Node):
+    """Splits documents into hierarchical chunks for better retrieval."""
+
+    def get_parameters(self) -> Dict[str, NodeParameter]:
+        return {
+            "documents": NodeParameter(
+                name="documents",
+                type=list,
+                required=False,
+                description="List of documents to chunk",
+            ),
+            "chunk_size": NodeParameter(
+                name="chunk_size",
+                type=int,
+                required=False,
+                default=200,
+                description="Target size for text chunks",
+            ),
+            "overlap": NodeParameter(
+                name="overlap",
+                type=int,
+                required=False,
+                default=50,
+                description="Overlap between chunks",
+            ),
+        }
+
+    def run(self, **kwargs) -> Dict[str, Any]:
+        documents = kwargs.get("documents", [])
+        chunk_size = kwargs.get("chunk_size", 200)
+        # overlap = kwargs.get("overlap", 50)  # Currently not used in chunking logic
+
+        print(f"Debug Chunker: received {len(documents)} documents")
+
+        all_chunks = []
+
+        for doc in documents:
+            content = doc["content"]
+            doc_id = doc["id"]
+            title = doc["title"]
+
+            # Simple sentence-aware chunking
+            sentences = content.split(". ")
+            chunks = []
+            current_chunk = ""
+
+            for sentence in sentences:
+                if len(current_chunk) + len(sentence) < chunk_size:
+                    current_chunk += sentence + ". "
+                else:
+                    if current_chunk:
+                        chunks.append(current_chunk.strip())
+                    current_chunk = sentence + ". "
+
+            if current_chunk:
+                chunks.append(current_chunk.strip())
+
+            # Create hierarchical chunk structure
+            for i, chunk in enumerate(chunks):
+                chunk_data = {
+                    "chunk_id": f"{doc_id}_chunk_{i}",
+                    "document_id": doc_id,
+                    "document_title": title,
+                    "chunk_index": i,
+                    "content": chunk,
+                    "hierarchy_level": "paragraph",
+                }
+                all_chunks.append(chunk_data)
+
+        return {"chunks": all_chunks}