docsif 0.1.0__py3-none-any.whl

sif/mcp/transport_stdio.py

@@ -0,0 +1,292 @@
+"""
+MCP Stdio Transport
+
+This module implements the stdio transport for MCP, suitable for
+use with Claude Desktop and other MCP clients that communicate
+via standard input/output.
+
+The transport uses line-delimited JSON-RPC messages.
+"""
+
+import asyncio
+import json
+import logging
+import sys
+from contextlib import asynccontextmanager
+from typing import Optional, TextIO
+
+from .protocol import JsonRpcNotification, JsonRpcRequest
+from .server import MCPServer, ServerConfig, create_server
+
+
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# Stdio Transport
+# ============================================================================
+
+
+class StdioTransport:
+    """
+    Stdio transport for MCP server.
+
+    Reads JSON-RPC messages from stdin and writes responses to stdout.
+    Uses line-delimited JSON format.
+
+    Example usage:
+        transport = StdioTransport()
+        await transport.run()
+    """
+
+    def __init__(
+        self,
+        server: Optional[MCPServer] = None,
+        stdin: Optional[TextIO] = None,
+        stdout: Optional[TextIO] = None,
+        encoding: str = "utf-8",
+    ):
+        self.server = server or create_server()
+        self.stdin = stdin or sys.stdin
+        self.stdout = stdout or sys.stdout
+        self.encoding = encoding
+        self._running = False
+        self._read_lock = asyncio.Lock()
+        self._write_lock = asyncio.Lock()
+
+    # -------------------------------------------------------------------------
+    # Message I/O
+    # -------------------------------------------------------------------------
+
+    async def _read_message(self) -> Optional[dict]:
+        """
+        Read a single JSON-RPC message from stdin.
+
+        Returns:
+            Parsed JSON object or None if EOF
+        """
+        async with self._read_lock:
+            # Read line from stdin (in executor to avoid blocking)
+            loop = asyncio.get_event_loop()
+            try:
+                line = await loop.run_in_executor(None, self.stdin.readline)
+            except Exception as e:
+                logger.error(f"Error reading from stdin: {e}")
+                return None
+
+            if not line:
+                # EOF reached
+                logger.info("EOF reached on stdin")
+                return None
+
+            line = line.strip()
+            if not line:
+                # Empty line, skip
+                return None
+
+            try:
+                message = json.loads(line)
+                logger.debug(f"Received: {line[:200]}...")
+                return message
+            except json.JSONDecodeError as e:
+                logger.error(f"Invalid JSON: {e}, line: {line[:100]}")
+                # Return error response
+                return {
+                    "jsonrpc": "2.0",
+                    "id": None,
+                    "error": {"code": -32700, "message": f"Parse error: {e}"},
+                }
+
+    async def _write_message(self, message: dict) -> None:
+        """
+        Write a JSON-RPC message to stdout.
+
+        Args:
+            message: The message to write
+        """
+        async with self._write_lock:
+            try:
+                line = json.dumps(message, ensure_ascii=False)
+                logger.debug(f"Sending: {line[:200]}...")
+
+                # Write in executor to avoid blocking
+                loop = asyncio.get_event_loop()
+                await loop.run_in_executor(None, self._write_sync, line)
+
+            except Exception as e:
+                logger.error(f"Error writing to stdout: {e}")
+
+    def _write_sync(self, line: str) -> None:
+        """Synchronous write to stdout."""
+        self.stdout.write(line + "\n")
+        self.stdout.flush()
+
+    # -------------------------------------------------------------------------
+    # Message Processing
+    # -------------------------------------------------------------------------
+
+    async def _process_message(self, message: dict) -> Optional[dict]:
+        """
+        Process a single message.
+
+        Args:
+            message: The parsed JSON message
+
+        Returns:
+            Response dict if it's a request, None for notifications
+        """
+        # Validate JSON-RPC version
+        if message.get("jsonrpc") != "2.0":
+            return {
+                "jsonrpc": "2.0",
+                "id": message.get("id"),
+                "error": {"code": -32600, "message": "Invalid Request: jsonrpc must be '2.0'"},
+            }
+
+        # Check if it's a request or notification
+        msg_id = message.get("id")
+        method = message.get("method")
+
+        if method is None:
+            # This is a response (shouldn't happen in stdio transport)
+            logger.warning("Received response message, ignoring")
+            return None
+
+        if msg_id is None:
+            # This is a notification
+            notification = JsonRpcNotification(
+                jsonrpc="2.0", method=method, params=message.get("params")
+            )
+            await self.server.handle_notification(notification)
+            return None
+        # This is a request
+        request = JsonRpcRequest(
+            jsonrpc="2.0", id=msg_id, method=method, params=message.get("params")
+        )
+        response = await self.server.handle_request(request)
+        return response.model_dump(exclude_none=True)
+
+    # -------------------------------------------------------------------------
+    # Main Loop
+    # -------------------------------------------------------------------------
+
+    async def run(self) -> None:
+        """
+        Run the stdio transport main loop.
+
+        Continuously reads messages from stdin and processes them
+        until EOF is reached or the transport is stopped.
+        """
+        logger.info("Starting stdio transport")
+        self._running = True
+
+        try:
+            while self._running:
+                # Read message
+                message = await self._read_message()
+
+                if message is None:
+                    # EOF or error
+                    break
+
+                # Process message
+                try:
+                    response = await self._process_message(message)
+
+                    # Send response if it's a request (not notification)
+                    if response is not None:
+                        await self._write_message(response)
+
+                except Exception as e:
+                    logger.exception("Error processing message")
+                    # Send error response if we have an ID
+                    msg_id = message.get("id")
+                    if msg_id is not None:
+                        error_response = {
+                            "jsonrpc": "2.0",
+                            "id": msg_id,
+                            "error": {"code": -32603, "message": f"Internal error: {e!s}"},
+                        }
+                        await self._write_message(error_response)
+
+        except asyncio.CancelledError:
+            logger.info("Transport cancelled")
+            raise
+
+        finally:
+            self._running = False
+            logger.info("Stdio transport stopped")
+
+    def stop(self) -> None:
+        """Stop the transport."""
+        logger.info("Stopping stdio transport")
+        self._running = False
+
+    async def shutdown(self) -> None:
+        """Shutdown the transport and server."""
+        self.stop()
+        await self.server.shutdown()
+
+
+# ============================================================================
+# Context Manager
+# ============================================================================
+
+
+@asynccontextmanager
+async def stdio_transport(
+    server: Optional[MCPServer] = None, config: Optional[ServerConfig] = None
+):
+    """
+    Async context manager for stdio transport.
+
+    Example:
+        async with stdio_transport() as transport:
+            await transport.run()
+
+    Args:
+        server: Optional MCPServer instance
+        config: Optional server configuration
+
+    Yields:
+        StdioTransport instance
+    """
+    if server is None:
+        server = create_server(config=config)
+
+    transport = StdioTransport(server=server)
+    try:
+        yield transport
+    finally:
+        await transport.shutdown()
+
+
+# ============================================================================
+# Main Entry Point
+# ============================================================================
+
+
+async def main():
+    """Main entry point for stdio transport."""
+    # Setup logging to stderr (don't pollute stdout)
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        stream=sys.stderr,
+    )
+
+    logger.info("Starting SIF MCP Server (stdio mode)")
+
+    async with stdio_transport() as transport:
+        await transport.run()
+
+    logger.info("SIF MCP Server stopped")
+
+
+def run_stdio():
+    """Run the stdio transport (synchronous entry point)."""
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    run_stdio()

sif/mcp_server/__init__.py

@@ -0,0 +1,26 @@
+"""MCP (Model Context Protocol) server implementation for SIF.
+
+This package provides MCP server functionality:
+- stdio transport for CLI integration
+- HTTP/SSE transport for web integration
+- MCP protocol handlers
+- Tool and resource definitions
+"""
+
+from sif.mcp_server.handlers import ResourceHandler, ToolHandler
+from sif.mcp_server.server import MCPServer
+from sif.mcp_server.tools import CollectionTool, IndexTool, SearchTool
+from sif.mcp_server.transport import HTTPTransport, StdioTransport, Transport
+
+
+__all__ = [
+    "CollectionTool",
+    "HTTPTransport",
+    "IndexTool",
+    "MCPServer",
+    "ResourceHandler",
+    "SearchTool",
+    "StdioTransport",
+    "ToolHandler",
+    "Transport",
+]

sif/mcp_server/handlers.py

@@ -0,0 +1,68 @@
+"""MCP request handlers."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from sif.utils.logging import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class ToolHandler(ABC):
+    """Abstract base class for MCP tool handlers."""
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Tool name."""
+        ...
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Tool description."""
+        ...
+
+    @property
+    @abstractmethod
+    def input_schema(self) -> dict[str, Any]:
+        """JSON schema for tool input."""
+        ...
+
+    @abstractmethod
+    def handle(self, params: dict[str, Any]) -> dict[str, Any]:
+        """Handle a tool call.
+
+        Args:
+            params: Tool parameters
+
+        Returns:
+            Tool result
+        """
+        ...
+
+
+class ResourceHandler(ABC):
+    """Abstract base class for MCP resource handlers."""
+
+    @property
+    @abstractmethod
+    def uri(self) -> str:
+        """Resource URI."""
+        ...
+
+    @property
+    @abstractmethod
+    def mime_type(self) -> str:
+        """Resource MIME type."""
+        ...
+
+    @abstractmethod
+    def handle(self) -> dict[str, Any]:
+        """Handle a resource request.
+
+        Returns:
+            Resource content
+        """
+        ...

sif/mcp_server/server.py

@@ -0,0 +1,58 @@
+"""MCP server implementation."""
+
+from sif.mcp_server.transport import Transport
+from sif.utils.logging import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class MCPServer:
+    """Model Context Protocol server for SIF.
+
+    Provides MCP-compliant endpoints for integration with
+    AI assistants and other MCP-compatible tools.
+
+    Supports both stdio and HTTP transports.
+    """
+
+    def __init__(
+        self,
+        transport: Transport,
+        # tool_handlers: list[ToolHandler] | None = None,
+        # resource_handlers: list[ResourceHandler] | None = None,
+    ) -> None:
+        """Initialize MCP server.
+
+        Args:
+            transport: Transport layer (stdio or HTTP)
+            tool_handlers: Tool request handlers
+            resource_handlers: Resource request handlers
+        """
+        self._transport = transport
+        # self._tool_handlers = tool_handlers or []
+        # self._resource_handlers = resource_handlers or []
+        self._running = False
+
+    def start(self) -> None:
+        """Start the MCP server."""
+        logger.info("Starting MCP server")
+        self._running = True
+
+        try:
+            self._transport.start()
+        except KeyboardInterrupt:
+            logger.info("Received interrupt signal")
+        finally:
+            self.stop()
+
+    def stop(self) -> None:
+        """Stop the MCP server."""
+        logger.info("Stopping MCP server")
+        self._running = False
+        self._transport.stop()
+
+    @property
+    def is_running(self) -> bool:
+        """Check if server is running."""
+        return self._running

sif/mcp_server/tools.py

@@ -0,0 +1,216 @@
+"""MCP tool implementations."""
+
+from typing import Any
+
+from sif.mcp_server.handlers import ToolHandler
+from sif.utils.logging import get_logger
+
+
+logger = get_logger(__name__)
+
+
+class SearchTool(ToolHandler):
+    """MCP tool for searching documents."""
+
+    def __init__(self, search_service: "SearchService") -> None:  # noqa: F821
+        """Initialize search tool.
+
+        Args:
+            search_service: Search service instance
+        """
+        self._search_service = search_service
+
+    @property
+    def name(self) -> str:
+        return "search"
+
+    @property
+    def description(self) -> str:
+        return "Search indexed documents using full-text and semantic search"
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "Search query",
+                },
+                "collection": {
+                    "type": "string",
+                    "description": "Collection to search (optional)",
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Maximum number of results",
+                    "default": 10,
+                },
+                "search_type": {
+                    "type": "string",
+                    "enum": ["bm25", "vector", "hybrid"],
+                    "description": "Search type",
+                    "default": "hybrid",
+                },
+            },
+            "required": ["query"],
+        }
+
+    def handle(self, params: dict[str, Any]) -> dict[str, Any]:
+        """Handle search tool call."""
+        query = params.get("query", "")
+        collection = params.get("collection")
+        limit = params.get("limit", 10)
+        search_type = params.get("search_type", "hybrid")
+
+        logger.info(f"Search tool called: query='{query}', type='{search_type}'")
+
+        # Placeholder: actual implementation would call search service
+        return {
+            "content": [
+                {
+                    "type": "text",
+                    "text": f"Search results for '{query}':\n\n1. Result 1\n2. Result 2",
+                },
+            ],
+        }
+
+
+class IndexTool(ToolHandler):
+    """MCP tool for indexing documents."""
+
+    def __init__(self, indexer: "DocumentIndexer") -> None:  # noqa: F821
+        """Initialize index tool.
+
+        Args:
+            indexer: Document indexer instance
+        """
+        self._indexer = indexer
+
+    @property
+    def name(self) -> str:
+        return "index"
+
+    @property
+    def description(self) -> str:
+        return "Index documents in a collection"
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "collection": {
+                    "type": "string",
+                    "description": "Collection name",
+                },
+                "path": {
+                    "type": "string",
+                    "description": "Path to index",
+                },
+            },
+            "required": ["collection"],
+        }
+
+    def handle(self, params: dict[str, Any]) -> dict[str, Any]:
+        """Handle index tool call."""
+        collection = params.get("collection", "")
+        path = params.get("path")
+
+        logger.info(f"Index tool called: collection='{collection}'")
+
+        return {
+            "content": [
+                {
+                    "type": "text",
+                    "text": f"Indexing collection '{collection}'...",
+                },
+            ],
+        }
+
+
+class CollectionTool(ToolHandler):
+    """MCP tool for managing collections."""
+
+    def __init__(self, collection_manager: "CollectionManager") -> None:  # noqa: F821
+        """Initialize collection tool.
+
+        Args:
+            collection_manager: Collection manager instance
+        """
+        self._collection_manager = collection_manager
+
+    @property
+    def name(self) -> str:
+        return "collection"
+
+    @property
+    def description(self) -> str:
+        return "List, create, or manage document collections"
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": ["list", "create", "delete"],
+                    "description": "Action to perform",
+                },
+                "name": {
+                    "type": "string",
+                    "description": "Collection name (for create/delete)",
+                },
+                "path": {
+                    "type": "string",
+                    "description": "Path to add (for create)",
+                },
+            },
+            "required": ["action"],
+        }
+
+    def handle(self, params: dict[str, Any]) -> dict[str, Any]:
+        """Handle collection tool call."""
+        action = params.get("action", "list")
+        name = params.get("name")
+        path = params.get("path")
+
+        logger.info(f"Collection tool called: action='{action}'")
+
+        if action == "list":
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": "Collections:\n\n1. my-notes\n2. work-docs",
+                    },
+                ],
+            }
+        if action == "create":
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": f"Created collection '{name}'",
+                    },
+                ],
+            }
+        if action == "delete":
+            return {
+                "content": [
+                    {
+                        "type": "text",
+                        "text": f"Deleted collection '{name}'",
+                    },
+                ],
+            }
+
+        return {
+            "content": [
+                {
+                    "type": "text",
+                    "text": f"Unknown action: {action}",
+                },
+            ],
+        }