Backend Functions Reference

The get_nbm and get_ads functions are essential utility functions in the scmcphub ecosystem that provide access to the backend managers during MCP server execution. These functions are used to retrieve the appropriate backend context based on the execution mode.

Overview

These functions serve as accessors to the backend managers that are injected into the MCP server’s lifespan context. They are crucial for:

Tool Mode: Accessing AdataManager for AnnData operations
Code Mode: Accessing NotebookManager for Jupyter notebook operations

Function Reference

`get_ads()`

Retrieves the AdataManager instance from the current request context.

Signature

def get_ads():
    ctx = get_context()
    ads = ctx.request_context.lifespan_context
    return ads

Returns

Type: AdataManager
Description: The AdataManager instance that manages AnnData objects

Usage Context

Mode: Tool Mode (tool-mode)
Backend: AdataManager
Purpose: Managing AnnData objects for single-cell analysis

Example

from scmcp_shared.util import get_ads
from scmcp_shared.schema import AdataInfo

@mcp.tool()
def read_data(request: AdataInfo):
    """Read AnnData from file."""
    ads = get_ads()  # Get AdataManager instance
    adata = ads.get_adata(adinfo=request)
    return {"message": f"Loaded data with {adata.n_obs} cells"}

`get_nbm()`

Retrieves the NotebookManager instance from the current request context.

Signature

def get_nbm():
    ctx = get_context()
    nbm = ctx.request_context.lifespan_context
    return nbm

Returns

Type: NotebookManager
Description: The NotebookManager instance that manages Jupyter notebooks

Usage Context

Mode: Code Mode (code-mode)
Backend: NotebookManager
Purpose: Managing Jupyter notebook execution

Example

from scmcp_shared.util import get_nbm

@mcp.tool()
def execute_code(code: str):
    """Execute code in Jupyter notebook."""
    nbm = get_nbm()  # Get NotebookManager instance
    jce = nbm.active_notebook
    result = jce.execute(code)
    return result

Backend Managers

AdataManager

The AdataManager is responsible for managing AnnData objects in tool mode.

Key Features

Multi-type Support: Manages different types of AnnData (exp, activity, cnv, splicing)
Active Sample Management: Tracks the currently active sample ID
Sample ID Validation: Ensures data consistency across operations

Main Methods

class AdataManager:
    def get_adata(self, sampleid=None, adtype="exp", adinfo=None):
        """Retrieve AnnData object."""
        
    def set_adata(self, adata, sampleid=None, sdtype="exp", adinfo=None):
        """Store AnnData object."""
        
    @property
    def active_id(self):
        """Get the currently active sample ID."""

Example Usage

def process_data(adinfo: AdataInfo):
    ads = get_ads()
    
    # Get AnnData for current sample
    adata = ads.get_adata(adinfo=adinfo)
    
    # Process the data
    # ... processing logic ...
    
    # Store the processed data
    ads.set_adata(adata, adinfo=adinfo)
    
    return {"message": "Data processed successfully"}

NotebookManager

The NotebookManager is responsible for managing Jupyter notebooks in code mode.

Key Features

Multiple Notebook Support: Manages multiple notebook instances
Active Notebook Tracking: Maintains the currently active notebook
Kernel Management: Handles Jupyter kernel lifecycle

Main Methods

class NotebookManager:
    def create_notebook(self, nbid, path, kernel="python"):
        """Create a new notebook instance."""
        
    def delete_notebook(self, nbid):
        """Delete a notebook instance."""
        
    def switch_notebook(self, nbid):
        """Switch to a different notebook."""
        
    @property
    def active_notebook(self):
        """Get the currently active notebook."""

Example Usage

def run_analysis(code: str):
    nbm = get_nbm()
    
    # Get the active notebook
    jce = nbm.active_notebook
    
    # Execute code
    result = jce.execute(code, add_cell=True)
    
    return {
        "notebook_id": nbm.active_nbid,
        "result": result
    }

Context System

Both functions rely on FastMCP’s context system to access the backend managers.

Context Flow

Server Initialization: Backend manager is created and injected into lifespan context
Request Processing: Context is available during tool execution
Function Call: get_context() retrieves the current request context
Backend Access: Backend manager is extracted from lifespan context

Context Structure

ctx = get_context()
# ctx.request_context.lifespan_context contains the backend manager

Mode-Specific Usage

Tool Mode (Default)

# Server configuration
manager = MyMCPManager(
    name="my-mcp",
    backend=AdataManager  # Uses AdataManager
)

# Tool implementation
@mcp.tool()
def my_tool(request: MyRequest):
    ads = get_ads()  # Get AdataManager
    adata = ads.get_adata(adinfo=request.adinfo)
    # ... tool logic ...

Code Mode

# Server configuration
manager = MyMCPManager(
    name="my-mcp",
    backend=NotebookManager,  # Uses NotebookManager
    include_tags=["nb"]  # Include notebook tools
)

# Tool implementation
@mcp.tool(tags=["nb"])
def execute_code(code: str):
    nbm = get_nbm()  # Get NotebookManager
    jce = nbm.active_notebook
    result = jce.execute(code)
    return result

Error Handling

Common Issues

Context Not Available: Ensure the function is called within an MCP tool context
Wrong Backend Type: Verify the correct backend is configured for your use case
Missing Dependencies: Ensure FastMCP dependencies are properly installed

Error Examples

# This will fail if not in MCP context
def standalone_function():
    try:
        ads = get_ads()
    except Exception as e:
        print(f"Context not available: {e}")

# This will fail if wrong backend is used
def wrong_backend_usage():
    # If server uses NotebookManager but tool expects AdataManager
    ads = get_ads()  # Will return NotebookManager, not AdataManager

Best Practices

1. Import Location

Import these functions at the module level:

from scmcp_shared.util import get_ads, get_nbm

2. Error Checking

Always check if the backend is available:

def safe_backend_access():
    try:
        ads = get_ads()
        return ads.get_adata(adinfo=adinfo)
    except Exception as e:
        raise ToolError(f"Failed to access backend: {e}")

3. Type Hints

Use proper type hints for better code clarity:

from scmcp_shared.backend import AdataManager, NotebookManager

def get_ads() -> AdataManager:
    ctx = get_context()
    return ctx.request_context.lifespan_context

def get_nbm() -> NotebookManager:
    ctx = get_context()
    return ctx.request_context.lifespan_context

4. Context Validation

Validate the backend type when needed:

def validate_backend():
    backend = get_ads()  # or get_nbm()
    if not isinstance(backend, AdataManager):
        raise ValueError("Expected AdataManager backend")

Integration Examples

Complete Tool Example

from fastmcp import FastMCP
from scmcp_shared.util import get_ads
from scmcp_shared.schema import AdataInfo
from pydantic import BaseModel

class ReadDataRequest(BaseModel):
    file_path: str
    adinfo: AdataInfo = AdataInfo()

@mcp.tool()
def read_h5ad(request: ReadDataRequest):
    """Read AnnData from H5AD file."""
    try:
        ads = get_ads()
        import scanpy as sc
        
        # Read the data
        adata = sc.read_h5ad(request.file_path)
        
        # Store in backend
        ads.set_adata(adata, adinfo=request.adinfo)
        
        return {
            "message": f"Successfully loaded {adata.n_obs} cells and {adata.n_vars} genes",
            "sampleid": request.adinfo.sampleid or ads.active_id
        }
    except Exception as e:
        raise ToolError(f"Failed to read data: {e}")

Complete Code Mode Example

from fastmcp import FastMCP
from scmcp_shared.util import get_nbm
from pydantic import BaseModel

class ExecuteCodeRequest(BaseModel):
    code: str
    backup_var: str = None

@mcp.tool(tags=["nb"])
def execute_code(request: ExecuteCodeRequest):
    """Execute code in Jupyter notebook."""
    try:
        nbm = get_nbm()
        jce = nbm.active_notebook
        
        # Execute the code
        result = jce.execute(
            request.code, 
            backup_var=request.backup_var
        )
        
        return {
            "notebook_id": nbm.active_nbid,
            "result": result
        }
    except Exception as e:
        raise ToolError(f"Failed to execute code: {e}")

​Backend Functions Reference

​Overview

​Function Reference

​get_ads()

​Signature

​Returns

​Usage Context

​Example

​get_nbm()

​Signature

​Returns

​Usage Context

​Example

​Backend Managers

​AdataManager

​Key Features

​Main Methods

​Example Usage

​NotebookManager

​Key Features

​Main Methods

​Example Usage

​Context System

​Context Flow

​Context Structure

​Mode-Specific Usage

​Tool Mode (Default)

​Code Mode

​Error Handling

​Common Issues

​Error Examples

​Best Practices

​1. Import Location

​2. Error Checking

​3. Type Hints

​4. Context Validation

​Integration Examples

​Complete Tool Example

​Complete Code Mode Example

Backend Functions Reference

Overview

Function Reference

`get_ads()`

Signature

Returns

Usage Context

Example

`get_nbm()`

Signature

Returns

Usage Context

Example

Backend Managers

AdataManager

Key Features

Main Methods

Example Usage

NotebookManager

Key Features

Main Methods

Example Usage

Context System

Context Flow

Context Structure

Mode-Specific Usage

Tool Mode (Default)

Code Mode

Error Handling

Common Issues

Error Examples

Best Practices

1. Import Location

2. Error Checking

3. Type Hints

4. Context Validation

Integration Examples

Complete Tool Example

Complete Code Mode Example