docsif 0.1.0__py3-none-any.whl

sif/mcp/README.md

@@ -0,0 +1,258 @@
+# SIF MCP Server
+
+Model Context Protocol (MCP) server implementation for SIF.
+
+## Features
+
+- **Dual Transport Support**: stdio (for Claude Desktop) and HTTP (for web clients)
+- **Six Search Tools**:
+  - `query` - Hybrid search (FTS + Vector + Reranking)
+  - `lex_search` - BM25 full-text search
+  - `vec_search` - Vector semantic search
+  - `get` - Get document by path or doc_id
+  - `multi_get` - Batch get documents by pattern
+  - `status` - Get index status
+- **JSON-RPC 2.0 Protocol**: Full compliance with MCP specification
+- **Server-Sent Events**: Real-time streaming for HTTP transport
+- **FastAPI Integration**: Modern async web framework
+
+## Installation
+
+```bash
+pip install fastapi uvicorn pydantic
+```
+
+## Usage
+
+### Stdio Mode (Claude Desktop)
+
+```python
+from sif.mcp.transport_stdio import run_stdio
+run_stdio()
+```
+
+Or run directly:
+```bash
+python -m sif.mcp.transport_stdio
+```
+
+### HTTP Mode
+
+```python
+from sif.mcp.transport_http import run_http_server
+
+async def main():
+    await run_http_server(host="0.0.0.0", port=8080)
+
+import asyncio
+asyncio.run(main())
+```
+
+Or run directly:
+```bash
+python -m sif.mcp.transport_http --host 0.0.0.0 --port 8080
+```
+
+## API Endpoints (HTTP Mode)
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check |
+| `/mcp/v1/sse` | GET | Server-Sent Events stream |
+| `/mcp/v1/messages` | POST | JSON-RPC message endpoint |
+| `/mcp/v1/batch` | POST | Batch JSON-RPC messages |
+| `/mcp/v1/tools` | GET | List available tools |
+| `/mcp/v1/status` | GET | Get server status |
+
+## Tools
+
+### query
+
+Hybrid search combining full-text search (BM25), vector semantic search, and reranking.
+
+**Input:**
+```json
+{
+  "query": "search terms",
+  "collections": ["default"],
+  "limit": 10,
+  "min_score": 0.0
+}
+```
+
+**Output:**
+```json
+{
+  "results": [
+    {
+      "doc_id": "doc_1",
+      "path": "/docs/file.md",
+      "title": "Document Title",
+      "content": "...",
+      "score": 0.95,
+      "highlights": ["..."],
+      "metadata": {}
+    }
+  ]
+}
+```
+
+### lex_search
+
+BM25 full-text search for keyword-based document retrieval.
+
+**Input:**
+```json
+{
+  "query": "search terms",
+  "collections": ["default"],
+  "limit": 10
+}
+```
+
+### vec_search
+
+Vector semantic search for finding documents with similar meaning.
+
+**Input:**
+```json
+{
+  "query": "search terms",
+  "collections": ["default"],
+  "limit": 10
+}
+```
+
+### get
+
+Get a document by its path or document ID.
+
+**Input:**
+```json
+{
+  "path_or_docid": "/docs/file.md",
+  "from_line": 0,
+  "max_lines": 100
+}
+```
+
+### multi_get
+
+Batch get documents matching a glob pattern.
+
+**Input:**
+```json
+{
+  "pattern": "/docs/*.md",
+  "max_bytes": 1048576
+}
+```
+
+### status
+
+Get the current status of all document collections.
+
+**Input:** `{}`
+
+**Output:**
+```json
+{
+  "collections": [
+    {
+      "name": "default",
+      "document_count": 100,
+      "last_updated": "2024-01-01T00:00:00",
+      "size_bytes": 1024000
+    }
+  ],
+  "total_documents": 100
+}
+```
+
+## Protocol Flow
+
+1. **Initialize**: Client sends `initialize` request
+2. **Ready**: Server responds with capabilities
+3. **Notification**: Client sends `notifications/initialized`
+4. **Tools/List**: Client requests available tools
+5. **Tools/Call**: Client calls tools as needed
+
+## Example JSON-RPC Messages
+
+### Initialize Request
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "2024-11-05",
+    "capabilities": {},
+    "clientInfo": {
+      "name": "claude-desktop",
+      "version": "1.0.0"
+    }
+  }
+}
+```
+
+### Tools/List Request
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/list",
+  "params": {}
+}
+```
+
+### Tools/Call Request
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "query",
+    "arguments": {
+      "query": "machine learning",
+      "limit": 5
+    }
+  }
+}
+```
+
+## Configuration
+
+### ServerConfig
+
+```python
+from sif.mcp import ServerConfig
+
+config = ServerConfig(
+    name="my-mcp-server",
+    version="1.0.0",
+    protocol_version="2024-11-05",
+    enable_logging=True,
+    max_concurrent_requests=100
+)
+```
+
+### Custom Search Backend
+
+```python
+from sif.mcp import ToolRegistry, SearchBackend
+
+class MySearchBackend(SearchBackend):
+    async def hybrid_search(self, query, collections=None, limit=10, min_score=0.0):
+        # Your implementation
+        pass
+    
+    # ... implement other methods
+
+tool_registry = ToolRegistry(backend=MySearchBackend())
+```
+
+## License
+
+MIT

sif/mcp/__init__.py

@@ -0,0 +1,9 @@
+"""SIF MCP (Model Context Protocol) Server."""
+
+from sif.mcp.server import MCPServer, run_stdio_server
+
+
+__all__ = [
+    "MCPServer",
+    "run_stdio_server",
+]

sif/mcp/claude_desktop_config.json

@@ -0,0 +1,16 @@
+{
+  "mcpServers": {
+    "sif": {
+      "command": "python",
+      "args": [
+        "-m",
+        "sif.mcp.transport_stdio"
+      ],
+      "env": {
+        "PYTHONPATH": "/path/to/sif/src"
+      },
+      "description": "SIF MCP Server for document search and retrieval",
+      "disabled": false
+    }
+  }
+}

sif/mcp/cli.py

@@ -0,0 +1,92 @@
+"""
+MCP Server CLI
+
+Command-line interface for running the SIF MCP server.
+"""
+
+import argparse
+import asyncio
+import logging
+import sys
+
+from .transport_http import run_http_server
+from .transport_stdio import run_stdio
+
+
+def setup_logging(level: str = "info"):
+    """Setup logging configuration."""
+    logging.basicConfig(
+        level=getattr(logging, level.upper()),
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        stream=sys.stderr,
+    )
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="SIF MCP Server",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  # Run in stdio mode (for Claude Desktop)
+  %(prog)s stdio
+
+  # Run in HTTP mode
+  %(prog)s http --host 0.0.0.0 --port 8080
+
+  # Run with debug logging
+  %(prog)s http --log-level debug
+        """,
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Transport mode")
+
+    # Stdio mode
+    stdio_parser = subparsers.add_parser("stdio", help="Run in stdio mode (for Claude Desktop)")
+    stdio_parser.add_argument(
+        "--log-level",
+        default="info",
+        choices=["debug", "info", "warning", "error"],
+        help="Log level (default: info)",
+    )
+
+    # HTTP mode
+    http_parser = subparsers.add_parser("http", help="Run in HTTP mode")
+    http_parser.add_argument("--host", default="0.0.0.0", help="Host to bind to (default: 0.0.0.0)")
+    http_parser.add_argument(
+        "--port", type=int, default=8080, help="Port to bind to (default: 8080)"
+    )
+    http_parser.add_argument(
+        "--log-level",
+        default="info",
+        choices=["debug", "info", "warning", "error"],
+        help="Log level (default: info)",
+    )
+    http_parser.add_argument(
+        "--cors-origins", nargs="*", default=["*"], help="CORS allowed origins (default: *)"
+    )
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    setup_logging(args.log_level)
+
+    if args.command == "stdio":
+        run_stdio()
+    elif args.command == "http":
+        asyncio.run(
+            run_http_server(
+                host=args.host,
+                port=args.port,
+                cors_origins=args.cors_origins,
+                log_level=args.log_level,
+            )
+        )
+
+
+if __name__ == "__main__":
+    main()

sif/mcp/protocol.py

@@ -0,0 +1,336 @@
+"""
+MCP (Model Context Protocol) Protocol Definitions
+
+This module defines the message types and protocol structures for MCP,
+following the JSON-RPC 2.0 specification.
+
+Reference: https://modelcontextprotocol.io/
+"""
+
+from enum import Enum
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+# ============================================================================
+# JSON-RPC Base Types
+# ============================================================================
+
+
+class JsonRpcVersion(str, Enum):
+    """JSON-RPC version."""
+
+    V2_0 = "2.0"
+
+
+class JsonRpcRequest(BaseModel):
+    """JSON-RPC 2.0 Request object."""
+
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: Optional[str | int] = None
+    method: str
+    params: Optional[dict[str, Any]] = None
+
+
+class JsonRpcError(BaseModel):
+    """JSON-RPC 2.0 Error object."""
+
+    code: int
+    message: str
+    data: Optional[Any] = None
+
+
+class JsonRpcResponse(BaseModel):
+    """JSON-RPC 2.0 Response object."""
+
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: Optional[str | int] = None
+    result: Optional[Any] = None
+    error: Optional[JsonRpcError] = None
+
+
+class JsonRpcNotification(BaseModel):
+    """JSON-RPC 2.0 Notification object (no id)."""
+
+    jsonrpc: Literal["2.0"] = "2.0"
+    method: str
+    params: Optional[dict[str, Any]] = None
+
+
+# ============================================================================
+# MCP Protocol Types
+# ============================================================================
+
+
+class MCPErrorCode(int, Enum):
+    """MCP-specific error codes."""
+
+    # Standard JSON-RPC errors
+    PARSE_ERROR = -32700
+    INVALID_REQUEST = -32600
+    METHOD_NOT_FOUND = -32601
+    INVALID_PARAMS = -32602
+    INTERNAL_ERROR = -32603
+
+    # MCP-specific errors
+    SERVER_NOT_INITIALIZED = -32002
+    UNKNOWN_TOOL = -32601
+    TOOL_EXECUTION_ERROR = -32000
+
+
+# ============================================================================
+# Initialize
+# ============================================================================
+
+
+class InitializeParams(BaseModel):
+    """Parameters for initialize request."""
+
+    protocolVersion: str = "2024-11-05"
+    capabilities: dict[str, Any] = Field(default_factory=dict)
+    clientInfo: dict[str, str] = Field(default_factory=dict)
+
+
+class ServerCapabilities(BaseModel):
+    """Server capabilities."""
+
+    tools: dict[str, Any] = Field(default_factory=lambda: {"listChanged": False})
+
+
+class InitializeResult(BaseModel):
+    """Result for initialize request."""
+
+    protocolVersion: str = "2024-11-05"
+    capabilities: ServerCapabilities = Field(default_factory=ServerCapabilities)
+    serverInfo: dict[str, str] = Field(
+        default_factory=lambda: {"name": "sif-mcp-server", "version": "1.0.0"}
+    )
+
+
+# ============================================================================
+# Tools
+# ============================================================================
+
+
+class ToolInputSchema(BaseModel):
+    """JSON Schema for tool input."""
+
+    type: str = "object"
+    properties: dict[str, Any] = Field(default_factory=dict)
+    required: list[str] = Field(default_factory=list)
+
+
+class MCPTool(BaseModel):
+    """MCP Tool definition."""
+
+    name: str
+    description: str
+    inputSchema: ToolInputSchema = Field(default_factory=ToolInputSchema)
+
+
+class ToolsListParams(BaseModel):
+    """Parameters for tools/list request."""
+
+    cursor: Optional[str] = None
+
+
+class ToolsListResult(BaseModel):
+    """Result for tools/list request."""
+
+    tools: list[MCPTool] = Field(default_factory=list)
+    nextCursor: Optional[str] = None
+
+
+class ToolsCallParams(BaseModel):
+    """Parameters for tools/call request."""
+
+    name: str
+    arguments: dict[str, Any] = Field(default_factory=dict)
+
+
+class ToolContentItem(BaseModel):
+    """Content item in tool call result."""
+
+    type: Literal["text", "image", "resource"] = "text"
+    text: Optional[str] = None
+    data: Optional[str] = None  # For image base64 data
+    mimeType: Optional[str] = None
+
+
+class ToolsCallResult(BaseModel):
+    """Result for tools/call request."""
+
+    content: list[ToolContentItem] = Field(default_factory=list)
+    isError: bool = False
+
+
+# ============================================================================
+# Notifications
+# ============================================================================
+
+
+class InitializedNotification(BaseModel):
+    """Client notification after initialization."""
+
+    method: Literal["notifications/initialized"] = "notifications/initialized"
+    params: dict[str, Any] = Field(default_factory=dict)
+
+
+class ProgressNotification(BaseModel):
+    """Progress notification."""
+
+    method: Literal["notifications/progress"] = "notifications/progress"
+    params: dict[str, Any]
+
+
+# ============================================================================
+# SIF-specific Types
+# ============================================================================
+
+
+class SearchResult(BaseModel):
+    """Search result item."""
+
+    doc_id: str
+    path: str
+    title: Optional[str] = None
+    content: Optional[str] = None
+    score: float
+    highlights: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class Document(BaseModel):
+    """Document model."""
+
+    doc_id: str
+    path: str
+    title: Optional[str] = None
+    content: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    line_start: Optional[int] = None
+    line_end: Optional[int] = None
+
+
+class CollectionInfo(BaseModel):
+    """Collection information."""
+
+    name: str
+    document_count: int
+    last_updated: Optional[str] = None
+    size_bytes: Optional[int] = None
+
+
+# ============================================================================
+# Tool Input/Output Models
+# ============================================================================
+
+
+class QueryInput(BaseModel):
+    """Input for query tool."""
+
+    query: str
+    collections: Optional[list[str]] = None
+    limit: int = 10
+    min_score: float = 0.0
+
+
+class QueryOutput(BaseModel):
+    """Output for query tool."""
+
+    results: list[SearchResult] = Field(default_factory=list)
+
+
+class LexSearchInput(BaseModel):
+    """Input for lex_search tool."""
+
+    query: str
+    collections: Optional[list[str]] = None
+    limit: int = 10
+
+
+class LexSearchOutput(BaseModel):
+    """Output for lex_search tool."""
+
+    results: list[SearchResult] = Field(default_factory=list)
+
+
+class VecSearchInput(BaseModel):
+    """Input for vec_search tool."""
+
+    query: str
+    collections: Optional[list[str]] = None
+    limit: int = 10
+
+
+class VecSearchOutput(BaseModel):
+    """Output for vec_search tool."""
+
+    results: list[SearchResult] = Field(default_factory=list)
+
+
+class GetInput(BaseModel):
+    """Input for get tool."""
+
+    path_or_docid: str
+    from_line: Optional[int] = None
+    max_lines: Optional[int] = None
+
+
+class GetOutput(BaseModel):
+    """Output for get tool."""
+
+    document: Optional[Document] = None
+
+
+class MultiGetInput(BaseModel):
+    """Input for multi_get tool."""
+
+    pattern: str
+    max_bytes: Optional[int] = None
+
+
+class MultiGetOutput(BaseModel):
+    """Output for multi_get tool."""
+
+    documents: list[Document] = Field(default_factory=list)
+    errors: list[str] = Field(default_factory=list)
+
+
+class StatusInput(BaseModel):
+    """Input for status tool."""
+
+    pass
+
+
+class StatusOutput(BaseModel):
+    """Output for status tool."""
+
+    collections: list[CollectionInfo] = Field(default_factory=list)
+    total_documents: int = 0
+
+
+# ============================================================================
+# Helper Functions
+# ============================================================================
+
+
+def create_success_response(id: str | int | None, result: Any) -> JsonRpcResponse:  # noqa: A002
+    """Create a successful JSON-RPC response."""
+    return JsonRpcResponse(id=id, result=result)
+
+
+def create_error_response(
+    id: str | int | None,
+    code: int,
+    message: str,
+    data: Any = None,  # noqa: A002
+) -> JsonRpcResponse:
+    """Create an error JSON-RPC response."""
+    return JsonRpcResponse(id=id, error=JsonRpcError(code=code, message=message, data=data))
+
+
+def create_notification(method: str, params: dict[str, Any] | None = None) -> JsonRpcNotification:
+    """Create a JSON-RPC notification."""
+    return JsonRpcNotification(method=method, params=params or {})