elasticsearch-mcp-server 2.0.17__py3-none-any.whl

src/risk_config.py

@@ -0,0 +1,77 @@
+"""
+Configuration for high-risk operations management.
+"""
+import os
+from typing import Set, Dict, Any, Callable
+from functools import wraps
+import logging
+
+# Define default high-risk operations per tool class (all write operations)
+HIGH_RISK_OPERATIONS = {
+    "IndexTools": {
+        "create_index",
+        "delete_index",
+    },
+    "DocumentTools": {
+        "index_document",
+        "delete_document",
+        "delete_by_query",
+    },
+    "DataStreamTools": {
+        "create_data_stream",
+        "delete_data_stream",
+    },
+    "AliasTools": {
+        "put_alias",
+        "delete_alias",
+    },
+    "GeneralTools": {
+        "general_api_request",
+    },
+}
+
+class RiskManager:
+    """Manages high-risk operation filtering and control."""
+    
+    def __init__(self):
+        self.logger = logging.getLogger(__name__)
+        self.high_risk_ops_disabled = self._is_high_risk_disabled()
+        
+        if self.high_risk_ops_disabled:
+            self.disabled_operations = self._get_disabled_operations()
+            self.logger.info("High-risk operations are disabled")
+            self.logger.info(f"Disabled operations: {self.disabled_operations}")
+        else:
+            self.disabled_operations = set()
+            self.logger.info("High-risk operations are not disabled")
+    
+    def _is_high_risk_disabled(self) -> bool:
+        """Check if high-risk operations should be disabled."""
+        return os.environ.get("DISABLE_HIGH_RISK_OPERATIONS", "false").lower() == "true"
+    
+    def _get_disabled_operations(self) -> Set[str]:
+        """Get the set of operations that should be disabled."""
+        # Check for custom disabled operations list
+        custom_ops = os.environ.get("DISABLE_OPERATIONS", "")
+        if custom_ops:
+            # User provided custom list
+            return set(op.strip() for op in custom_ops.split(",") if op.strip())
+        
+        # Use default high-risk operations
+        all_ops = set()
+        for tool_ops in HIGH_RISK_OPERATIONS.values():
+            all_ops.update(tool_ops)
+        return all_ops
+    
+    def is_operation_allowed(self, tool_class_name: str, operation_name: str) -> bool:
+        """Check if an operation is allowed to be executed."""
+        # Only check against the disabled_operations set
+        # (which is either custom or default based on environment variables)
+        if operation_name in self.disabled_operations:
+            self.logger.info(f"Operation '{operation_name}' from {tool_class_name} is disabled")
+            return False
+        
+        return True
+
+# Global risk manager instance
+risk_manager = RiskManager()

src/server.py

@@ -0,0 +1,166 @@
+import logging
+import sys
+import argparse
+
+from fastmcp import FastMCP
+
+from src.clients import create_search_client
+from src.tools.alias import AliasTools
+from src.tools.cluster import ClusterTools
+from src.tools.data_stream import DataStreamTools
+from src.tools.document import DocumentTools
+from src.tools.general import GeneralTools
+from src.tools.index import IndexTools
+from src.tools.register import ToolsRegister
+from src.version import __version__ as VERSION
+
+class SearchMCPServer:
+    def __init__(self, engine_type):
+        # Set engine type
+        self.engine_type = engine_type
+        self.name = f"{self.engine_type}-mcp-server"
+        self.mcp = FastMCP(self.name)
+        
+        # Configure logging
+        logging.basicConfig(
+            level=logging.INFO,
+            format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
+        )
+        self.logger = logging.getLogger(__name__)
+        self.logger.info(f"Initializing {self.name}, Version: {VERSION}")
+        
+        # Create the corresponding search client
+        self.search_client = create_search_client(self.engine_type)
+        
+        # Initialize tools
+        self._register_tools()
+
+    def _register_tools(self):
+        """Register all MCP tools."""
+        # Create a tools register
+        register = ToolsRegister(self.logger, self.search_client, self.mcp)
+        
+        # Define all tool classes to register
+        tool_classes = [
+            IndexTools,
+            DocumentTools,
+            ClusterTools,
+            AliasTools,
+            DataStreamTools,
+            GeneralTools,
+        ]        
+        # Register all tools
+        register.register_all_tools(tool_classes)
+
+
+def run_search_server(engine_type, transport, host, port, path):
+    """Run search server with specified engine type and transport options.
+    
+    Args:
+        engine_type: Type of search engine to use ("elasticsearch" or "opensearch")
+        transport: Transport protocol to use ("stdio", "streamable-http", or "sse")
+        host: Host to bind to when using HTTP transports
+        port: Port to bind to when using HTTP transports
+        path: URL path prefix for HTTP transports
+    """
+    
+    server = SearchMCPServer(engine_type=engine_type)
+    
+    if transport in ["streamable-http", "sse"]:
+        server.logger.info(f"Starting {server.name} with {transport} transport on {host}:{port}{path}")
+        server.mcp.run(transport=transport, host=host, port=port, path=path)
+    else:
+        server.logger.info(f"Starting {server.name} with {transport} transport")
+        server.mcp.run(transport=transport)
+
+def parse_server_args():
+    """Parse command line arguments for the MCP server.
+    
+    Returns:
+        Parsed arguments
+    """
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--transport", "-t",
+        default="stdio",
+        choices=["stdio", "streamable-http", "sse"],
+        help="Transport protocol to use (default: stdio)"
+    )
+    parser.add_argument(
+        "--host", "-H",
+        default="127.0.0.1",
+        help="Host to bind to when using HTTP transports (default: 127.0.0.1)"
+    )
+    parser.add_argument(
+        "--port", "-p",
+        type=int,
+        default=8000,
+        help="Port to bind to when using HTTP transports (default: 8000)"
+    )
+    parser.add_argument(
+        "--path", "-P",
+        help="URL path prefix for HTTP transports (default: /mcp for streamable-http, /sse for sse)"
+    )
+    
+    args = parser.parse_args()
+    
+    # Set default path based on transport type if not specified
+    if args.path is None:
+        if args.transport == "sse":
+            args.path = "/sse"
+        else:
+            args.path = "/mcp"
+            
+    return args
+
+def elasticsearch_mcp_server():
+    """Entry point for Elasticsearch MCP server."""
+    args = parse_server_args()
+    
+    # Run the server with the specified options
+    run_search_server(
+        engine_type="elasticsearch",
+        transport=args.transport,
+        host=args.host,
+        port=args.port,
+        path=args.path
+    )
+
+def opensearch_mcp_server():
+    """Entry point for OpenSearch MCP server."""
+    args = parse_server_args()
+    
+    # Run the server with the specified options
+    run_search_server(
+        engine_type="opensearch",
+        transport=args.transport,
+        host=args.host,
+        port=args.port,
+        path=args.path
+    )
+
+if __name__ == "__main__":
+    # Require elasticsearch-mcp-server or opensearch-mcp-server as the first argument
+    if len(sys.argv) <= 1 or sys.argv[1] not in ["elasticsearch-mcp-server", "opensearch-mcp-server"]:
+        print("Error: First argument must be 'elasticsearch-mcp-server' or 'opensearch-mcp-server'")
+        sys.exit(1)
+        
+    # Determine engine type based on the first argument
+    engine_type = "elasticsearch"  # Default
+    if sys.argv[1] == "opensearch-mcp-server":
+        engine_type = "opensearch"
+        
+    # Remove the first argument so it doesn't interfere with argparse
+    sys.argv.pop(1)
+    
+    # Parse command line arguments
+    args = parse_server_args()
+    
+    # Run the server with the specified options
+    run_search_server(
+        engine_type=engine_type,
+        transport=args.transport,
+        host=args.host,
+        port=args.port,
+        path=args.path
+    )

src/tools/__init__.py

@@ -0,0 +1,15 @@
+from src.tools.alias import AliasTools
+from src.tools.cluster import ClusterTools
+from src.tools.document import DocumentTools
+from src.tools.general import GeneralTools
+from src.tools.index import IndexTools
+from src.tools.register import ToolsRegister
+
+__all__ = [
+    'AliasTools',
+    'ClusterTools',
+    'DocumentTools',
+    'GeneralTools',
+    'IndexTools',
+    'ToolsRegister',
+]

src/tools/alias.py

@@ -0,0 +1,46 @@
+from typing import Dict, List
+
+from fastmcp import FastMCP
+
+class AliasTools:
+    def __init__(self, search_client):
+        self.search_client = search_client
+    def register_tools(self, mcp: FastMCP):
+        @mcp.tool()
+        def list_aliases() -> List[Dict]:
+            """List all aliases."""
+            return self.search_client.list_aliases()
+
+        @mcp.tool()
+        def get_alias(index: str) -> Dict:
+            """
+            Get alias information for a specific index.
+
+            Args:
+                index: Name of the index
+            """
+            return self.search_client.get_alias(index=index)
+
+        @mcp.tool()
+        def put_alias(index: str, name: str, body: Dict) -> Dict:
+            """
+            Create or update an alias for a specific index.
+
+            Args:
+                index: Name of the index
+                name: Name of the alias
+                body: Alias configuration
+            """
+            return self.search_client.put_alias(index=index, name=name, body=body)
+
+        @mcp.tool()
+        def delete_alias(index: str, name: str) -> Dict:
+            """
+            Delete an alias for a specific index.
+
+            Args:
+                index: Name of the index
+                name: Name of the alias
+            """
+            return self.search_client.delete_alias(index=index, name=name)
+        

src/tools/cluster.py

@@ -0,0 +1,17 @@
+from typing import Dict
+
+from fastmcp import FastMCP
+
+class ClusterTools:
+    def __init__(self, search_client):
+        self.search_client = search_client
+    def register_tools(self, mcp: FastMCP):
+        @mcp.tool()
+        def get_cluster_health() -> Dict:
+            """Returns basic information about the health of the cluster."""
+            return self.search_client.get_cluster_health()
+
+        @mcp.tool()
+        def get_cluster_stats() -> Dict:
+            """Returns high-level overview of cluster statistics."""
+            return self.search_client.get_cluster_stats()

src/tools/data_stream.py

@@ -0,0 +1,47 @@
+from typing import Dict, Optional
+from fastmcp import FastMCP
+
+class DataStreamTools:    
+    def __init__(self, search_client):
+        self.search_client = search_client
+    
+    def register_tools(self, mcp: FastMCP):
+        """Register data stream tools with the MCP server."""
+        
+        @mcp.tool()
+        def create_data_stream(name: str) -> Dict:
+            """Create a new data stream.
+            
+            This creates a new data stream with the specified name.
+            The data stream must have a matching index template before creation.
+            
+            Args:
+                name: Name of the data stream to create
+            """
+            return self.search_client.create_data_stream(name=name)
+        
+        @mcp.tool()
+        def get_data_stream(name: Optional[str] = None) -> Dict:
+            """Get information about one or more data streams.
+            
+            Retrieves configuration, mappings, settings, and other information
+            about the specified data streams.
+            
+            Args:
+                name: Name of the data stream(s) to retrieve.
+                      Can be a comma-separated list or wildcard pattern.
+                      If not provided, retrieves all data streams.
+            """
+            return self.search_client.get_data_stream(name=name)
+        
+        @mcp.tool()
+        def delete_data_stream(name: str) -> Dict:
+            """Delete one or more data streams.
+            
+            Permanently deletes the specified data streams and all their backing indices.
+            
+            Args:
+                name: Name of the data stream(s) to delete.
+                      Can be a comma-separated list or wildcard pattern.
+            """
+            return self.search_client.delete_data_stream(name=name)

src/tools/document.py

@@ -0,0 +1,64 @@
+from typing import Dict, Optional
+
+from fastmcp import FastMCP
+
+class DocumentTools:
+    def __init__(self, search_client):
+        self.search_client = search_client
+    
+    def register_tools(self, mcp: FastMCP):
+        @mcp.tool()
+        def search_documents(index: str, body: Dict) -> Dict:
+            """
+            Search for documents.
+            
+            Args:
+                index: Name of the index
+                body: Search query
+            """
+            return self.search_client.search_documents(index=index, body=body)
+        
+        @mcp.tool()
+        def index_document(index: str, document: Dict, id: Optional[str] = None) -> Dict:
+            """
+            Creates or updates a document in the index.
+            
+            Args:
+                index: Name of the index
+                document: Document data
+                id: Optional document ID
+            """
+            return self.search_client.index_document(index=index, id=id, document=document)
+        
+        @mcp.tool()
+        def get_document(index: str, id: str) -> Dict:
+            """
+            Get a document by ID.
+            
+            Args:
+                index: Name of the index
+                id: Document ID
+            """
+            return self.search_client.get_document(index=index, id=id)
+        
+        @mcp.tool()
+        def delete_document(index: str, id: str) -> Dict:
+            """
+            Delete a document by ID.
+            
+            Args:
+                index: Name of the index
+                id: Document ID
+            """
+            return self.search_client.delete_document(index=index, id=id)
+        
+        @mcp.tool()
+        def delete_by_query(index: str, body: Dict) -> Dict:
+            """
+            Deletes documents matching the provided query.
+            
+            Args:
+                index: Name of the index
+                body: Query to match documents for deletion
+            """
+            return self.search_client.delete_by_query(index=index, body=body)

src/tools/general.py

@@ -0,0 +1,20 @@
+from typing import Dict, Optional
+
+from fastmcp import FastMCP
+
+class GeneralTools:
+    def __init__(self, search_client):
+        self.search_client = search_client
+    def register_tools(self, mcp: FastMCP):
+        @mcp.tool()
+        def general_api_request(method: str, path: str, params: Optional[Dict] = None, body: Optional[Dict] = None):
+            """Perform a general HTTP API request.
+               Use this tool for any Elasticsearch/OpenSearch API that does not have a dedicated tool.
+            
+            Args:
+                method: HTTP method (GET, POST, PUT, DELETE, etc.)
+                path: API endpoint path
+                params: Query parameters
+                body: Request body
+            """
+            return self.search_client.general_api_request(method, path, params, body)

src/tools/index.py

@@ -0,0 +1,44 @@
+from typing import Dict, Optional, List
+
+from fastmcp import FastMCP
+
+class IndexTools:
+    def __init__(self, search_client):
+        self.search_client = search_client
+        
+    def register_tools(self, mcp: FastMCP):
+        @mcp.tool()
+        def list_indices() -> List[Dict]:
+            """List all indices."""
+            return self.search_client.list_indices()
+
+        @mcp.tool()
+        def get_index(index: str) -> Dict:
+            """
+            Returns information (mappings, settings, aliases) about one or more indices.
+            
+            Args:
+                index: Name of the index
+            """
+            return self.search_client.get_index(index=index)
+
+        @mcp.tool()
+        def create_index(index: str, body: Optional[Dict] = None) -> Dict:
+            """
+            Create a new index.
+            
+            Args:
+                index: Name of the index
+                body: Optional index configuration including mappings and settings
+            """
+            return self.search_client.create_index(index=index, body=body)
+
+        @mcp.tool()
+        def delete_index(index: str) -> Dict:
+            """
+            Delete an index.
+            
+            Args:
+                index: Name of the index
+            """
+            return self.search_client.delete_index(index=index)

src/tools/register.py

@@ -0,0 +1,89 @@
+import logging
+from typing import List, Type
+
+from fastmcp import FastMCP
+
+from src.clients import SearchClient
+from src.clients.exceptions import with_exception_handling
+from src.risk_config import risk_manager
+
+class ToolsRegister:
+    """Class to handle registration of MCP tools."""
+    
+    def __init__(self, logger: logging.Logger, search_client: SearchClient, mcp: FastMCP):
+        """
+        Initialize the tools register.
+        
+        Args:
+            logger: Logger instance
+            search_client: Search client instance
+            mcp: FastMCP instance
+        """
+        self.logger = logger
+        self.search_client = search_client
+        self.mcp = mcp
+    
+    def register_all_tools(self, tool_classes: List[Type]):
+        """
+        Register all tools with the MCP server.
+        
+        Args:
+            tool_classes: List of tool classes to register
+        """
+        for tool_class in tool_classes:
+            self.logger.info(f"Registering tools from {tool_class.__name__}")
+            tool_instance = tool_class(self.search_client)
+            
+            # Set logger and client attributes
+            tool_instance.logger = self.logger
+            tool_instance.search_client = self.search_client
+            
+            # Check if risk management is enabled (high-risk operations are disabled)
+            if risk_manager.high_risk_ops_disabled:
+                # Add risk manager attributes for filtering
+                tool_instance.risk_manager = risk_manager
+                tool_instance.tool_class_name = tool_class.__name__
+                # Register tools with risk filtering
+                self._register_with_risk_filter(tool_instance)
+            else:
+                # Register tools with just exception handling (original way)
+                with_exception_handling(tool_instance, self.mcp)
+    
+    def _register_with_risk_filter(self, tool_instance):
+        """
+        Register tools with risk filtering applied.
+        Only called when risk management is enabled.
+        
+        Args:
+            tool_instance: The tool instance to register
+        """
+        # Save the original mcp.tool method
+        original_tool = self.mcp.tool
+        
+        # Create a wrapper that filters based on risk
+        def risk_filter_wrapper(*args, **kwargs):
+            # Get the original decorator
+            decorator = original_tool(*args, **kwargs)
+            
+            def risk_check_decorator(func):
+                operation_name = func.__name__
+                
+                # Check if operation is allowed
+                if not risk_manager.is_operation_allowed(tool_instance.tool_class_name, operation_name):
+                    # Don't register disabled tools - return a no-op function
+                    def no_op(*args, **kwargs):
+                        pass
+                    return no_op
+                
+                # If allowed, use the original decorator
+                return decorator(func)
+            
+            return risk_check_decorator
+        
+        try:
+            self.mcp.tool = risk_filter_wrapper
+            # This will wrap our risk_filter_wrapper with exception handling
+            with_exception_handling(tool_instance, self.mcp)
+        finally:
+            # Restore the original mcp.tool
+            self.mcp.tool = original_tool

src/version.py

@@ -0,0 +1 @@
+__version__ = "2.0.17"