Skip to main content

​
BaseMCPManager Reference

The BaseMCPManager is the foundational class for creating MCP (Model Context Protocol) servers in the scmcphub ecosystem. It provides a standardized way to manage and organize multiple MCP modules, with built-in filtering capabilities for both modules and tools.

​
Overview

BaseMCPManager serves as an abstract base class that handles:
  • Module registration and management
  • Tool filtering (include/exclude)
  • Module filtering (include/exclude)
  • Backend integration
  • FastMCP lifecycle management

​
Class Definition

class BaseMCPManager:
    """Base class for MCP module management."""

​
Constructor

​
__init__(name, instructions=None, include_modules=None, exclude_modules=None, include_tools=None, exclude_tools=None, include_tags=None, exclude_tags=None, backend=None)

Initializes a new BaseMCPManager instance.

​
Parameters

ParameterTypeDefaultDescription
namestrRequiredName of the MCP server
instructionsOptional[str]NoneInstructions for the MCP server
include_modulesOptional[List[str]]NoneList of module names to include. If None, all modules are included
exclude_modulesOptional[List[str]]NoneList of module names to exclude. If None, no modules are excluded
include_toolsOptional[List[str]]NoneDictionary mapping module names to lists of tool names to include
exclude_toolsOptional[List[str]]NoneDictionary mapping module names to lists of tool names to exclude
include_tagsOptional[List[str]]NoneList of tags to include
exclude_tagsOptional[List[str]]NoneList of tags to exclude
backendOptional[NotebookManager]NoneBackend manager class (e.g., AdataManager, NotebookManager)

​
Instance Attributes

AttributeTypeDescription
exec_backendNotebookManagerBackend instance for execution
mcpFastMCPThe main FastMCP instance
include_modulesOptional[List[str]]Modules to include
exclude_modulesOptional[List[str]]Modules to exclude
include_toolsOptional[List[str]]Tools to include per module
exclude_toolsOptional[List[str]]Tools to exclude per module
available_modulesDict[str, Any]Dictionary of available modules

​
Methods

​
init_mcp()

Abstract method - Must be implemented by subclasses. Initializes the available_modules dictionary with module instances. 
def init_mcp(self):
    """Initialize available modules. To be implemented by subclasses."""
    raise NotImplementedError("Subclasses must implement init_mcp")

​
register_mcp()

Registers modules based on include/exclude filters and imports them into the main MCP server. 
def register_mcp(self):
    """Register modules based on include/exclude filters."""

​
exec_lifespan(server)

Async context manager that provides the execution backend during the server’s lifespan. 
@asynccontextmanager
async def exec_lifespan(self, server: FastMCP) -> AsyncIterator[Any]:
    yield self.exec_backend

​
Usage Examples

​
Basic Implementation

from scmcp_shared.mcp_base import BaseMCPManager
from scmcp_shared.backend import AdataManager

class MyMCPManager(BaseMCPManager):
    """Manager class for My MCP modules."""
    
    def init_mcp(self):
        """Initialize available MCP modules."""
        self.available_modules = {
            "io": io_mcp,
            "pp": pp_mcp,
            "tl": tl_mcp,
            "pl": pl_mcp,
        }

# Usage
manager = MyMCPManager(
    name="my-mcp",
    backend=AdataManager
)
mcp = manager.mcp

​
With Module Filtering

# Include only specific modules
manager = MyMCPManager(
    name="my-mcp",
    include_modules=["io", "pp"],
    backend=AdataManager
)

# Exclude specific modules
manager = MyMCPManager(
    name="my-mcp",
    exclude_modules=["auto"],
    backend=AdataManager
)

​
With Tool Filtering

# Include specific tools from specific modules
manager = MyMCPManager(
    name="my-mcp",
    include_tools={
        "io": ["read_h5ad", "write_h5ad"],
        "pp": ["normalize_total", "log1p"],
    },
    backend=AdataManager
)

# Exclude specific tools from specific modules
manager = MyMCPManager(
    name="my-mcp",
    exclude_tools={
        "auto": ["search_tool", "run_tool"],
    },
    backend=AdataManager
)

​
With Tag Filtering

# Include only tools with specific tags
manager = MyMCPManager(
    name="my-mcp",
    include_tags=["nb", "rag"],
    backend=AdataManager
)

# Exclude tools with specific tags
manager = MyMCPManager(
    name="my-mcp",
    exclude_tags=["experimental"],
    backend=AdataManager
)

​
Complete Example

from scmcp_shared.mcp_base import BaseMCPManager
from scmcp_shared.backend import AdataManager
from .preset import io_mcp, pp_mcp, tl_mcp, pl_mcp

class ScanpyMCPManager(BaseMCPManager):
    """Manager class for Scanpy MCP modules."""
    
    def init_mcp(self):
        """Initialize available Scanpy MCP modules."""
        self.available_modules = {
            "io": io_mcp,
            "pp": pp_mcp,
            "tl": tl_mcp,
            "pl": pl_mcp,
        }

# Create manager with comprehensive filtering
manager = ScanpyMCPManager(
    name="scanpy-mcp",
    instructions="Scanpy MCP server for single-cell analysis",
    include_modules=["io", "pp", "tl"],
    exclude_modules=["auto"],
    include_tools={
        "io": ["read_h5ad", "write_h5ad"],
        "pp": ["normalize_total", "log1p", "highly_variable_genes"],
    },
    exclude_tools={
        "auto": ["search_tool", "run_tool"],
    },
    backend=AdataManager
)

# Get the MCP instance
mcp = manager.mcp

​
Real-World Examples

​
ScanpyMCPManager

class ScanpyMCPManager(BaseMCPManager):
    """Manager class for Scanpy MCP modules."""
    
    def init_mcp(self):
        """Initialize available Scanpy MCP modules."""
        self.available_modules = {
            "io": ScanpyIOMCP().mcp,
            "pp": ScanpyPreprocessingMCP().mcp,
            "tl": ScanpyToolsMCP().mcp,
            "pl": ScanpyPlottingMCP().mcp,
            "ul": ul_mcp,
            "auto": auto_mcp,
            "nb": nb_mcp
        }

​
CellrankMCPManager

class CellrankMCPManager(BaseMCPManager):
    """Manager class for Cellrank MCP modules."""
    
    def init_mcp(self):
        """Initialize available Cellrank MCP modules."""
        self.available_modules = {
            "io": io_mcp,
            "pp": pp_mcp,
            "kernel": kernel_mcp,
            "estimator": estimator_mcp,
            "pl": pl_mcp,
            "tl": tl_mcp,
            "ul": ul_mcp,
            "nb": nb_mcp,
        }

​
Best Practices

​
1. Module Naming Convention

Use consistent module names across your MCP server:
  • io - Input/Output operations
  • pp - Preprocessing
  • tl - Tools
  • pl - Plotting
  • ul - Utilities
  • auto - Auto-completion tools
  • nb - Notebook integration

​
2. Backend Selection

Choose the appropriate backend based on your use case:
  • AdataManager - For AnnData-based operations/tool-mode
  • NotebookManager - For notebook-based execution/code-mode

​
3. Filtering Strategy

  • Use include_modules when you want to limit to specific modules
  • Use exclude_modules when you want to exclude specific modules from a larger set
  • Use include_tools for fine-grained control over which tools are available
  • Use exclude_tools to remove specific tools from modules