ims-mcp 1.0.0__py3-none-any.whl

ims_mcp/__init__.py

@@ -0,0 +1,20 @@
+"""IMS MCP Server - Model Context Protocol server for IMS (Instruction Management Systems).
+
+This package provides a FastMCP server that connects to IMS
+for advanced retrieval-augmented generation capabilities.
+
+Environment Variables:
+    R2R_API_BASE: IMS server URL (default: http://localhost:7272)
+    R2R_COLLECTION: Collection name for queries (optional)
+    R2R_API_KEY: API key for authentication (optional)
+    
+Note: Environment variables use R2R_ prefix for compatibility with underlying R2R SDK.
+"""
+
+__version__ = "1.0.0"
+__author__ = "Igor Solomatov"
+
+from ims_mcp.server import mcp
+
+__all__ = ["mcp", "__version__"]
+

ims_mcp/__main__.py

@@ -0,0 +1,11 @@
+"""Entry point for running ims-mcp as a module.
+
+This allows the package to be executed as:
+    python -m ims_mcp
+"""
+
+from ims_mcp.server import main
+
+if __name__ == "__main__":
+    main()
+

ims_mcp/server.py

@@ -0,0 +1,512 @@
+"""R2R MCP Server - FastMCP server for R2R retrieval system.
+
+This module provides a Model Context Protocol (MCP) server that connects to R2R
+for advanced retrieval-augmented generation capabilities.
+
+Environment Variables:
+    R2R_API_BASE or R2R_BASE_URL: R2R server URL (default: http://localhost:7272)
+    R2R_COLLECTION: Collection name for queries (optional, uses server default)
+    R2R_API_KEY: API key for authentication (optional)
+
+The R2RClient automatically reads these environment variables, so no manual
+configuration is needed when running via uvx or other launchers.
+"""
+
+import uuid
+from r2r import R2RClient
+
+
+def id_to_shorthand(id: str) -> str:
+    """Convert a full ID to shortened version for display."""
+    return str(id)[:7]
+
+
+def format_search_results_for_llm(results) -> str:
+    """
+    Format R2R search results for LLM consumption.
+    
+    Formats vector search, graph search, web search, and document search results
+    into a readable text format with source IDs and relevant metadata.
+    """
+    lines = []
+
+    # 1) Chunk search
+    if results.chunk_search_results:
+        lines.append("Vector Search Results:")
+        for c in results.chunk_search_results:
+            lines.append(f"Source ID [{id_to_shorthand(c.id)}]:")
+            lines.append(c.text or "")  # or c.text[:200] to truncate
+
+    # 2) Graph search
+    if results.graph_search_results:
+        lines.append("Graph Search Results:")
+        for g in results.graph_search_results:
+            lines.append(f"Source ID [{id_to_shorthand(g.id)}]:")
+            if hasattr(g.content, "summary"):
+                lines.append(f"Community Name: {g.content.name}")
+                lines.append(f"ID: {g.content.id}")
+                lines.append(f"Summary: {g.content.summary}")
+            elif hasattr(g.content, "name") and hasattr(
+                g.content, "description"
+            ):
+                lines.append(f"Entity Name: {g.content.name}")
+                lines.append(f"Description: {g.content.description}")
+            elif (
+                hasattr(g.content, "subject")
+                and hasattr(g.content, "predicate")
+                and hasattr(g.content, "object")
+            ):
+                lines.append(
+                    f"Relationship: {g.content.subject}-{g.content.predicate}-{g.content.object}"
+                )
+
+    # 3) Web search
+    if results.web_search_results:
+        lines.append("Web Search Results:")
+        for w in results.web_search_results:
+            lines.append(f"Source ID [{id_to_shorthand(w.id)}]:")
+            lines.append(f"Title: {w.title}")
+            lines.append(f"Link: {w.link}")
+            lines.append(f"Snippet: {w.snippet}")
+
+    # 4) Local context docs
+    if results.document_search_results:
+        lines.append("Local Context Documents:")
+        for doc_result in results.document_search_results:
+            doc_title = doc_result.title or "Untitled Document"
+            doc_id = doc_result.id
+            summary = doc_result.summary
+
+            lines.append(f"Full Document ID: {doc_id}")
+            lines.append(f"Shortened Document ID: {id_to_shorthand(doc_id)}")
+            lines.append(f"Document Title: {doc_title}")
+            if summary:
+                lines.append(f"Summary: {summary}")
+
+            if doc_result.chunks:
+                # Then each chunk inside:
+                for chunk in doc_result.chunks:
+                    lines.append(
+                        f"\nChunk ID {id_to_shorthand(chunk['id'])}:\n{chunk['text']}"
+                    )
+
+    result = "\n".join(lines)
+    return result
+
+
+# Create a FastMCP server
+try:
+    from mcp.server.fastmcp import FastMCP
+
+    mcp = FastMCP("R2R Retrieval System")
+except Exception as e:
+    raise ImportError(
+        "MCP is not installed. Please run `pip install mcp`"
+    ) from e
+
+
+# Search tool with filtering support
+@mcp.tool()
+async def search(
+    query: str,
+    filters: dict | None = None,
+    limit: float | None = None,  # Use float to accept JSON "number" type, convert to int internally
+    use_semantic_search: bool | None = None,
+    use_fulltext_search: bool | None = None,
+) -> str:
+    """
+    Performs a search with optional filtering and configuration
+
+    Args:
+        query: The search query
+        filters: Metadata filters (e.g., {"tags": {"$in": ["agents"]}})
+        limit: Maximum number of results (server default if not specified)
+        use_semantic_search: Enable semantic search (server default if not specified)
+        use_fulltext_search: Enable fulltext search (server default if not specified)
+
+    Returns:
+        Formatted search results from the knowledge base
+    """
+    client = R2RClient()
+
+    # Only build search_settings if user provided any parameters
+    # This preserves original behavior: search("query") → search(query=query) with NO search_settings
+    kwargs = {"query": query}
+
+    if any(
+        param is not None
+        for param in [filters, limit, use_semantic_search, use_fulltext_search]
+    ):
+        search_settings = {}
+
+        if filters is not None:
+            search_settings["filters"] = filters
+        if limit is not None:
+            search_settings["limit"] = int(limit)  # Convert to int for R2R API
+        if use_semantic_search is not None:
+            search_settings["use_semantic_search"] = use_semantic_search
+        if use_fulltext_search is not None:
+            search_settings["use_fulltext_search"] = use_fulltext_search
+
+        kwargs["search_settings"] = search_settings
+
+    search_response = client.retrieval.search(**kwargs)
+    return format_search_results_for_llm(search_response.results)
+
+
+# RAG query tool with filtering and generation config
+@mcp.tool()
+async def rag(
+    query: str,
+    filters: dict | None = None,
+    limit: float | None = None,  # Use float to accept JSON "number" type, convert to int internally
+    model: str | None = None,
+    temperature: float | None = None,
+    max_tokens: float | None = None,  # Use float to accept JSON "number" type, convert to int internally
+) -> str:
+    """
+    Perform RAG query with optional filtering and generation config
+
+    Args:
+        query: The question to answer
+        filters: Metadata filters (e.g., {"tags": {"$in": ["agents"]}})
+        limit: Max search results to use (server default if not specified)
+        model: LLM model to use (server default if not specified)
+        temperature: Response randomness 0-1 (server default if not specified)
+        max_tokens: Max response length (server default if not specified)
+
+    Returns:
+        Generated answer from RAG
+    """
+    client = R2RClient()
+
+    # Only build configs if user provided parameters
+    # This preserves original behavior: rag("query") → rag(query=query) with NO configs
+    kwargs = {"query": query}
+
+    # Build search_settings if any search params provided
+    if any(param is not None for param in [filters, limit]):
+        search_settings = {}
+        if filters is not None:
+            search_settings["filters"] = filters
+        if limit is not None:
+            search_settings["limit"] = int(limit)  # Convert to int for R2R API
+        kwargs["search_settings"] = search_settings
+
+    # Build rag_generation_config if any generation params provided
+    if any(param is not None for param in [model, temperature, max_tokens]):
+        rag_config = {}
+        if model is not None:
+            rag_config["model"] = model
+        if temperature is not None:
+            rag_config["temperature"] = temperature
+        if max_tokens is not None:
+            rag_config["max_tokens"] = int(max_tokens)  # Convert to int for R2R API
+        kwargs["rag_generation_config"] = rag_config
+
+    rag_response = client.retrieval.rag(**kwargs)
+    return rag_response.results.generated_answer  # type: ignore
+
+
+# Document upload tool with upsert semantics
+@mcp.tool()
+async def put_document(
+    content: str,
+    title: str,
+    metadata: dict | None = None,
+    document_id: str | None = None,
+) -> str:
+    """
+    Upload or update a document with upsert semantics
+
+    Args:
+        content: The text content of the document
+        title: Document title (used for ID generation if document_id not provided)
+        metadata: Additional metadata (e.g., {"tags": ["agents"], "domain": "dev"})
+        document_id: Optional document ID for explicit upsert
+
+    Returns:
+        Status message with document_id and operation type
+    """
+    client = R2RClient()
+
+    # Build metadata with title
+    final_metadata = {"title": title}
+    if metadata:
+        final_metadata.update(metadata)
+
+    # Generate UUID from title if not provided (enables upsert by title)
+    if not document_id:
+        # Use UUID5 to create deterministic UUID from title
+        # Same title always generates same UUID for upsert semantics
+        namespace = uuid.UUID("6ba7b810-9dad-11d1-80b4-00c04fd430c8")  # DNS namespace
+        document_id = str(uuid.uuid5(namespace, title))
+
+    # Try to create, if exists then update
+    try:
+        result = client.documents.create(
+            raw_text=content,
+            id=document_id,
+            metadata=final_metadata,
+            run_with_orchestration=True,
+        )
+        return f"Document created successfully.\nDocument ID: {document_id}\nOperation: CREATE"
+    except Exception as e:
+        error_msg = str(e)
+        # Check if document already exists
+        if "already exists" in error_msg.lower():
+            # Document exists, delete and recreate for true upsert
+            try:
+                # Delete existing document
+                client.documents.delete(id=document_id)
+                
+                # Recreate with new content
+                result = client.documents.create(
+                    raw_text=content,
+                    id=document_id,
+                    metadata=final_metadata,
+                    run_with_orchestration=True,
+                )
+                return f"Document updated successfully.\nDocument ID: {document_id}\nOperation: UPDATE (delete + recreate)"
+            except Exception as update_error:
+                return f"Error updating document: {str(update_error)}"
+        else:
+            # Different error, re-raise
+            return f"Error creating document: {error_msg}"
+
+
+# List documents tool
+@mcp.tool()
+async def list_documents(
+    offset: float = 0,  # Use float to accept JSON "number" type, convert to int internally
+    limit: float = 100,  # Use float to accept JSON "number" type, convert to int internally
+    document_ids: list[str] | None = None,
+    compact_view: bool = False,
+    tags: list[str] | None = None,
+    match_all_tags: bool = False,
+) -> str:
+    """
+    List documents in the R2R knowledge base with pagination
+
+    Args:
+        offset: Number of documents to skip (default: 0)
+        limit: Maximum number of documents to return (default: 100, max: 100)
+        document_ids: Optional list of specific document IDs to retrieve
+        compact_view: Show only ID and title (default: False - shows all details)
+        tags: Optional list of tags to filter by (e.g., ["agents", "r1"])
+        match_all_tags: If True, document must have ALL tags; if False (default), document must have ANY tag
+
+    Returns:
+        Formatted list of documents
+    """
+    client = R2RClient()
+
+    # Build kwargs for list call
+    kwargs = {"offset": int(offset), "limit": min(int(limit), 100)}  # Convert to int, cap at 100
+    
+    if document_ids:
+        kwargs["ids"] = document_ids
+
+    # List documents
+    result = client.documents.list(**kwargs)
+    
+    # Filter by tags if provided
+    filtered_results = result.results
+    if tags and len(tags) > 0:
+        provided_tags = set(tags)
+        filtered_results = []
+        
+        for doc in result.results:
+            # Extract tags from document metadata
+            doc_tags = set()
+            if hasattr(doc, 'metadata') and doc.metadata:
+                tags_value = doc.metadata.get('tags')
+                if tags_value:
+                    if isinstance(tags_value, list):
+                        doc_tags = set(tags_value)
+                    elif isinstance(tags_value, str):
+                        doc_tags = {tags_value}
+            
+            # Apply filter based on match mode
+            if match_all_tags:
+                # ALL mode: document must have all provided tags
+                if provided_tags.issubset(doc_tags):
+                    filtered_results.append(doc)
+            else:
+                # ANY mode: document must have at least one provided tag
+                if len(provided_tags.intersection(doc_tags)) > 0:
+                    filtered_results.append(doc)
+    
+    # Format results for display
+    lines = []
+    if tags:
+        tag_mode = "ALL" if match_all_tags else "ANY"
+        lines.append(f"Documents with {tag_mode} tags {tags} (showing {len(filtered_results)} of {result.total_entries} total):\n")
+    else:
+        lines.append(f"Documents (showing {len(filtered_results)} of {result.total_entries} total):\n")
+    
+    for doc in filtered_results:
+        if compact_view:
+            # Compact mode: just ID and title
+            lines.append(f"ID: {doc.id} | Title: {doc.title or 'Untitled'}")
+        else:
+            # Full mode: all details
+            lines.append(f"{'='*60}")
+            lines.append(f"ID: {doc.id}")
+            lines.append(f"Title: {doc.title or 'Untitled'}")
+            
+            # Show all metadata
+            if hasattr(doc, 'metadata') and doc.metadata:
+                lines.append("Metadata:")
+                for key, value in doc.metadata.items():
+                    # Format value based on type
+                    if isinstance(value, list):
+                        lines.append(f"  {key}: {', '.join(str(v) for v in value)}")
+                    elif isinstance(value, dict):
+                        lines.append(f"  {key}: {value}")
+                    else:
+                        lines.append(f"  {key}: {value}")
+            
+            lines.append(f"Status: {doc.ingestion_status}")
+            lines.append(f"Size: {doc.size_in_bytes} bytes")
+            lines.append(f"Created: {doc.created_at}")
+            lines.append(f"Updated: {doc.updated_at}")
+            
+            if hasattr(doc, 'summary') and doc.summary:
+                lines.append(f"Summary: {doc.summary[:200]}...")
+    
+    return "\n".join(lines)
+
+
+# Get document tool
+@mcp.tool()
+async def get_document(
+    document_id: str | None = None,
+    title: str | None = None,
+) -> str:
+    """
+    Retrieve a document by ID or title
+    
+    Args:
+        document_id: Document ID to retrieve
+        title: Document title to search for (if document_id not provided)
+    
+    Returns:
+        Formatted document details
+    """
+    client = R2RClient()
+    
+    # Validate that at least one parameter is provided
+    if not document_id and not title:
+        return "Error: Must provide either document_id or title"
+    
+    # If only title provided, search for document by title using metadata filter
+    if not document_id and title:
+        try:
+            # Use search API with title filter for more efficient lookup
+            search_result = client.retrieval.search(
+                query=title,
+                search_settings={
+                    "filters": {"title": {"$eq": title}},
+                    "limit": 5,
+                    "use_fulltext_search": True,  # Use fulltext for exact match
+                }
+            )
+            
+            # Extract document IDs from search results
+            matching_docs = []
+            if hasattr(search_result, 'results') and hasattr(search_result.results, 'chunk_search_results'):
+                seen_doc_ids = set()
+                for chunk in search_result.results.chunk_search_results:
+                    if hasattr(chunk, 'metadata') and chunk.metadata:
+                        doc_id = chunk.metadata.get('document_id')
+                        doc_title = chunk.metadata.get('title')
+                        if doc_id and doc_id not in seen_doc_ids:
+                            seen_doc_ids.add(doc_id)
+                            matching_docs.append((doc_id, doc_title))
+            
+            # Fallback: Use list API if search didn't work
+            if not matching_docs:
+                list_result = client.documents.list(limit=100)
+                for doc in list_result.results:
+                    if doc.title and doc.title.lower() == title.lower():
+                        matching_docs.append((doc.id, doc.title))
+            
+            if not matching_docs:
+                return f"Error: No document found with title '{title}'"
+            
+            if len(matching_docs) > 1:
+                lines = [f"Warning: Found {len(matching_docs)} documents with title '{title}':"]
+                for doc_id, doc_title in matching_docs:
+                    lines.append(f"  - ID: {doc_id}")
+                lines.append("\nPlease use document_id to retrieve a specific document.")
+                return "\n".join(lines)
+            
+            # Found exactly one match
+            document_id = matching_docs[0][0]
+        except Exception as e:
+            return f"Error searching for document by title: {str(e)}"
+    
+    # Now we have document_id, download the original file
+    try:
+        # Download the original document content
+        file_content = client.documents.download(id=document_id)
+        
+        # Read and decode the content
+        content_bytes = file_content.read()
+        content_text = content_bytes.decode('utf-8')
+        
+        # Build output with just document ID and content
+        output_lines = [f"DOCUMENT ID: {document_id}", content_text]
+        
+        return "\n".join(output_lines)
+        
+    except Exception as e:
+        error_msg = str(e)
+        if "not found" in error_msg.lower():
+            return f"Error: Document with ID '{document_id}' not found"
+        return f"Error downloading document: {error_msg}"
+
+
+# Delete document tool
+@mcp.tool()
+async def delete_document(document_id: str) -> str:
+    """
+    Delete a document by ID
+    
+    Args:
+        document_id: The unique identifier of the document to delete
+    
+    Returns:
+        Status message confirming deletion or describing error
+    """
+    client = R2RClient()
+    
+    try:
+        # Delete the document
+        client.documents.delete(id=document_id)
+        return f"Document deleted successfully.\nDocument ID: {document_id}"
+    except Exception as e:
+        error_msg = str(e)
+        
+        # Handle common error cases with user-friendly messages
+        if "not found" in error_msg.lower():
+            return f"Error: Document with ID '{document_id}' not found"
+        elif "permission" in error_msg.lower() or "denied" in error_msg.lower():
+            return f"Error: Permission denied to delete document '{document_id}'"
+        elif "connection" in error_msg.lower() or "timeout" in error_msg.lower():
+            return f"Error: Unable to communicate with R2R server. Please check connection."
+        else:
+            # Generic error fallback
+            return f"Error deleting document: {error_msg}"
+
+
+def main():
+    """Main entry point for console script."""
+    mcp.run()
+
+
+# Run the server if executed directly
+if __name__ == "__main__":
+    main()
+

ims_mcp-1.0.0.dist-info/METADATA

@@ -0,0 +1,326 @@
+Metadata-Version: 2.4
+Name: ims-mcp
+Version: 1.0.0
+Summary: Model Context Protocol server for IMS (Instruction Management Systems)
+Author: Igor Solomatov
+License-Expression: MIT
+Project-URL: Homepage, https://pypi.org/project/ims-mcp/
+Keywords: mcp,ims,retrieval,rag,ai,llm,model-context-protocol,knowledge-base
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: r2r>=3.6.0
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Dynamic: license-file
+
+# ims-mcp
+
+**Model Context Protocol (MCP) server for Rosetta (Enterprise Engineering Governance and Instructions Management System)**
+
+*Powered by R2R technology for advanced RAG capabilities*
+
+This package provides a FastMCP server that connects to IMS servers for advanced retrieval-augmented generation (RAG) capabilities. It enables AI assistants like Claude Desktop, Cursor, and other MCP clients to search, retrieve, and manage documents in Rosetta knowledge bases.
+
+## Features
+
+- 🔍 **Semantic Search** - Vector-based and full-text search across documents
+- 🤖 **RAG Queries** - Retrieval-augmented generation with configurable LLM settings
+- 📝 **Document Management** - Upload, update, list, and delete documents with upsert semantics
+- 🏷️ **Metadata Filtering** - Advanced filtering by tags, domain, and custom metadata
+- 🌐 **Environment-Based Config** - Zero configuration, reads from environment variables
+
+## Installation
+
+### Using uvx (recommended)
+
+The easiest way to use ims-mcp is with `uvx`, which automatically handles installation:
+
+```bash
+uvx ims-mcp
+```
+
+### Using pip
+
+Install globally or in a virtual environment:
+
+```bash
+pip install ims-mcp
+```
+
+Then run:
+
+```bash
+ims-mcp
+```
+
+### As a Python Module
+
+You can also run it as a module:
+
+```bash
+python -m ims_mcp
+```
+
+## Configuration
+
+The server automatically reads configuration from environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `R2R_API_BASE` or `R2R_BASE_URL` | IMS server URL | `http://localhost:7272` |
+| `R2R_COLLECTION` | Collection name for queries | Server default |
+| `R2R_API_KEY` | API key for authentication | None |
+
+**Note:** Environment variables use `R2R_` prefix for compatibility with the underlying R2R SDK.
+
+## Usage with MCP Clients
+
+### Cursor IDE
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "KnowledgeBase": {
+      "command": "uvx",
+      "args": ["ims-mcp"],
+      "env": {
+        "R2R_API_BASE": "http://localhost:7272",
+        "R2R_COLLECTION": "aia-r1"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "ims": {
+      "command": "uvx",
+      "args": ["ims-mcp"],
+      "env": {
+        "R2R_API_BASE": "http://localhost:7272",
+        "R2R_COLLECTION": "my-collection"
+      }
+    }
+  }
+}
+```
+
+### Other MCP Clients
+
+Any MCP client can use ims-mcp by specifying the command and environment variables:
+
+```json
+{
+  "command": "uvx",
+  "args": ["ims-mcp"],
+  "env": {
+    "R2R_API_BASE": "http://localhost:7272"
+  }
+}
+```
+
+## Available MCP Tools
+
+### 1. search
+
+Perform semantic and full-text search across documents.
+
+**Parameters:**
+- `query` (str): Search query
+- `filters` (dict, optional): Metadata filters (e.g., `{"tags": {"$in": ["agents"]}}`)
+- `limit` (int, optional): Maximum results
+- `use_semantic_search` (bool, optional): Enable vector search
+- `use_fulltext_search` (bool, optional): Enable full-text search
+
+**Example:**
+```python
+search("machine learning", filters={"tags": {"$in": ["research"]}}, limit=5)
+```
+
+### 2. rag
+
+Retrieval-augmented generation with LLM.
+
+**Parameters:**
+- `query` (str): Question to answer
+- `filters` (dict, optional): Metadata filters
+- `limit` (int, optional): Max search results to use
+- `model` (str, optional): LLM model name
+- `temperature` (float, optional): Response randomness (0-1)
+- `max_tokens` (int, optional): Max response length
+
+**Example:**
+```python
+rag("What is machine learning?", model="gpt-4", temperature=0.7)
+```
+
+### 3. put_document
+
+Upload or update a document with upsert semantics.
+
+**Parameters:**
+- `content` (str): Document text content
+- `title` (str): Document title
+- `metadata` (dict, optional): Custom metadata (e.g., `{"tags": ["research"], "author": "John"}`)
+- `document_id` (str, optional): Explicit document ID
+
+**Example:**
+```python
+put_document(
+    content="Machine learning is...",
+    title="ML Guide",
+    metadata={"tags": ["research", "ml"]}
+)
+```
+
+### 4. list_documents
+
+List documents with pagination and optional tag filtering.
+
+**Parameters:**
+- `offset` (int, optional): Documents to skip (default: 0)
+- `limit` (int, optional): Max documents (default: 100)
+- `document_ids` (list[str], optional): Specific IDs to retrieve
+- `compact_view` (bool, optional): Show only ID and title (default: False)
+- `tags` (list[str], optional): Filter by tags (e.g., `["agents", "r1"]`)
+- `match_all_tags` (bool, optional): If True, document must have ALL tags; if False (default), document must have ANY tag
+
+**Examples:**
+```python
+# List all documents
+list_documents(offset=0, limit=10, compact_view=False)
+
+# Filter by tags (ANY mode - documents with "research" OR "ml")
+list_documents(tags=["research", "ml"])
+
+# Filter by tags (ALL mode - documents with both "research" AND "ml")
+list_documents(tags=["research", "ml"], match_all_tags=True)
+```
+
+**Note:** Tag filtering is performed client-side after fetching results. For large collections with complex filtering needs, consider using the `search()` tool with metadata filters instead.
+
+### 5. get_document
+
+Retrieve a specific document by ID or title.
+
+**Parameters:**
+- `document_id` (str, optional): Document ID
+- `title` (str, optional): Document title
+
+**Example:**
+```python
+get_document(title="ML Guide")
+```
+
+### 6. delete_document
+
+Delete a document by ID.
+
+**Parameters:**
+- `document_id` (str, required): The unique identifier of the document to delete
+
+**Example:**
+```python
+delete_document(document_id="550e8400-e29b-41d4-a716-446655440000")
+```
+
+**Returns:**
+- Success message with document ID on successful deletion
+- Error message if document not found or permission denied
+
+## Metadata Filtering
+
+All filter operators supported:
+
+- `$eq`: Equal
+- `$neq`: Not equal
+- `$gt`, `$gte`: Greater than (or equal)
+- `$lt`, `$lte`: Less than (or equal)
+- `$in`: In array
+- `$nin`: Not in array
+- `$like`, `$ilike`: Pattern matching (case-sensitive/insensitive)
+
+**Examples:**
+
+```python
+# Filter by tags
+filters={"tags": {"$in": ["research", "ml"]}}
+
+# Filter by domain
+filters={"domain": {"$eq": "instructions"}}
+
+# Combined filters
+filters={"tags": {"$in": ["research"]}, "created_at": {"$gte": "2024-01-01"}}
+```
+
+## Development
+
+### Local Installation
+
+Install directly from PyPI:
+
+```bash
+pip install ims-mcp
+```
+
+Or for the latest development version, install from source if you have the code locally:
+
+```bash
+pip install -e .
+```
+
+### Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+### Building for Distribution
+
+```bash
+python -m build
+```
+
+## Requirements
+
+- Python >= 3.10
+- IMS server running and accessible (powered by R2R Light)
+- r2r Python SDK >= 3.6.0
+- mcp >= 1.0.0
+
+## License
+
+MIT License - see LICENSE file for details
+
+This package is built on R2R (RAG to Riches) technology by SciPhi AI, which is licensed under the MIT License. We gratefully acknowledge the R2R project and its contributors.
+
+## Links
+
+- **R2R Technology**: https://github.com/SciPhi-AI/R2R
+- **Model Context Protocol**: https://modelcontextprotocol.io/
+- **FastMCP**: https://github.com/jlowin/fastmcp
+
+## Support
+
+For issues and questions, visit the package page: https://pypi.org/project/ims-mcp/

ims_mcp-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+ims_mcp/__init__.py,sha256=qhmOG7M_udp7EkUXUT-7cXTmD3RoWoC9r9NOv2Kjzn8,631
+ims_mcp/__main__.py,sha256=z4P1aCVfOgS3cTM2wgJd2pxjMmKCkGkiqYDRGgrspxw,191
+ims_mcp/server.py,sha256=Gk3-R8g6E3ULxuMCCfNmqpAa6_cw4boiy5WTWO5smqc,19384
+ims_mcp-1.0.0.dist-info/licenses/LICENSE,sha256=4d1dlH04mbnN3ya4lybcVOUwljRHGy-aSc9MYqGYW44,2534
+ims_mcp-1.0.0.dist-info/METADATA,sha256=X8PxT1G_8is-WbkQOOKIzOfecnKQ65mNxtkiJMbodTY,8350
+ims_mcp-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ims_mcp-1.0.0.dist-info/entry_points.txt,sha256=xCH9I8g1pTTEqrfjnE-ANHaZo4W6EBJVy0Lg5z8SaIQ,48
+ims_mcp-1.0.0.dist-info/top_level.txt,sha256=wEXA33qFr_eov3S1PY2OF6EQBA2rtAWB_ZNJOzNNQuM,8
+ims_mcp-1.0.0.dist-info/RECORD,,

ims_mcp-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ims_mcp-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ims-mcp = ims_mcp.server:main

ims_mcp-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,52 @@
+MIT License
+
+Copyright (c) 2025 Igor Solomatov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+================================================================================
+THIRD-PARTY SOFTWARE NOTICES AND INFORMATION
+================================================================================
+
+This package integrates with and depends on R2R (RAG to Riches), which is
+licensed under the MIT License:
+
+R2R - Advanced AI Retrieval System
+Copyright (c) 2024 SciPhi AI
+Repository: https://github.com/SciPhi-AI/R2R
+License: MIT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

ims_mcp-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ims_mcp