scmcp-shared 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

scmcp_shared/server/tl.py

@@ -0,0 +1,432 @@
+from fastmcp import FastMCP, Context
+import os
+import scanpy as sc
+from fastmcp.exceptions import ToolError
+from ..schema.tl import *
+from scmcp_shared.util import filter_args, add_op_log, forward_request, get_ads, generate_msg
+from scmcp_shared.logging_config import setup_logger
+logger = setup_logger()
+
+tl_mcp = FastMCP("ScanpyMCP-TL-Server")
+
+
+@tl_mcp.tool()
+async def tsne(
+    request: TSNEModel = TSNEModel() 
+):
+    """t-distributed stochastic neighborhood embedding (t-SNE) for visualization"""
+
+    try:
+        result = await forward_request("tl_tsne", request)
+        if result is not None:
+            return result
+        func_kwargs = filter_args(request, sc.tl.tsne)
+        ads = get_ads()
+        adata = ads.get_adata(request=request)
+        sc.tl.tsne(adata, **func_kwargs)
+        add_op_log(adata, sc.tl.tsne, func_kwargs)
+        return generate_msg(request, adata, ads)
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+
+@tl_mcp.tool()
+async def umap(
+    request: UMAPModel = UMAPModel() 
+):
+    """Uniform Manifold Approximation and Projection (UMAP) for visualization"""
+
+    try:
+        result = await forward_request("tl_umap", request)
+        if result is not None:
+            return result
+        func_kwargs = filter_args(request, sc.tl.umap)
+        ads = get_ads()
+        adata = ads.get_adata(request=request)
+        sc.tl.umap(adata, **func_kwargs)
+        add_op_log(adata, sc.tl.umap, func_kwargs)
+        return [generate_msg(request, adata, ads)]
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+@tl_mcp.tool()
+async def draw_graph(
+    request: DrawGraphModel = DrawGraphModel() 
+):
+    """Force-directed graph drawing"""
+
+    try:
+        result = await forward_request("tl_draw_graph", request)
+        if result is not None:
+            return result    
+        func_kwargs = filter_args(request, sc.tl.draw_graph)
+        ads = get_ads()
+        adata = ads.get_adata(request=request)
+        sc.tl.draw_graph(adata, **func_kwargs)
+        add_op_log(adata, sc.tl.draw_graph, func_kwargs)
+        return [generate_msg(request, adata, ads)]
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+@tl_mcp.tool()
+async def diffmap(
+    request: DiffMapModel = DiffMapModel() 
+):
+    """Diffusion Maps for dimensionality reduction"""
+
+    try:
+        result = await forward_request("tl_diffmap", request)
+        if result is not None:
+            return result    
+        func_kwargs = filter_args(request, sc.tl.diffmap)
+        ads = get_ads()
+        adata = ads.get_adata(request=request)
+        sc.tl.diffmap(adata, **func_kwargs)
+        adata.obsm["X_diffmap"] = adata.obsm["X_diffmap"][:,1:]
+        add_op_log(adata, sc.tl.diffmap, func_kwargs)
+        return [generate_msg(request, adata, ads)]
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+@tl_mcp.tool()
+async def embedding_density(
+    request: EmbeddingDensityModel = EmbeddingDensityModel() 
+):
+    """Calculate the density of cells in an embedding"""
+
+    try:
+        result = await forward_request("tl_embedding_density", request)
+        if result is not None:
+            return result        
+        func_kwargs = filter_args(request, sc.tl.embedding_density)
+        ads = get_ads()
+        adata = ads.get_adata(request=request)
+        sc.tl.embedding_density(adata, **func_kwargs)
+        add_op_log(adata, sc.tl.embedding_density, func_kwargs)
+        return [generate_msg(request, adata, ads)]
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+
+@tl_mcp.tool()
+async def leiden(
+    request: LeidenModel = LeidenModel() 
+):
+    """Leiden clustering algorithm for community detection"""
+
+    try:
+        result = await forward_request("tl_leiden", request)
+        if result is not None:
+            return result            
+        func_kwargs = filter_args(request, sc.tl.leiden)
+        ads = get_ads()
+        adata = ads.get_adata(request=request)
+        sc.tl.leiden(adata, **func_kwargs)
+        add_op_log(adata, sc.tl.leiden, func_kwargs)
+        return [generate_msg(request, adata, ads)]
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+
+@tl_mcp.tool()
+async def louvain(
+    request: LouvainModel = LouvainModel() 
+):
+    """Louvain clustering algorithm for community detection"""
+
+    try:
+        result = await forward_request("tl_louvain", request)
+        if result is not None:
+            return result          
+        func_kwargs = filter_args(request, sc.tl.louvain)
+        ads = get_ads()
+        adata = ads.get_adata(request=request)
+        sc.tl.louvain(adata, **func_kwargs)
+        add_op_log(adata, sc.tl.louvain, func_kwargs)
+        return [generate_msg(request, adata, ads)]
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+@tl_mcp.tool()
+async def dendrogram(
+    request: DendrogramModel,
+):
+    """Hierarchical clustering dendrogram"""
+
+    try:
+        result = await forward_request("tl_dendrogram", request)
+        if result is not None:
+            return result        
+        func_kwargs = filter_args(request, sc.tl.dendrogram)
+        ads = get_ads()
+        adata = ads.get_adata(request=request)
+        sc.tl.dendrogram(adata, **func_kwargs)
+        add_op_log(adata, sc.tl.dendrogram, func_kwargs)
+        return [generate_msg(request, adata, ads)]
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+@tl_mcp.tool()
+async def dpt(
+    request: DPTModel = DPTModel() 
+):
+    """Diffusion Pseudotime (DPT) analysis"""
+
+    try:
+        result = await forward_request("tl_dpt", request)
+        if result is not None:
+            return result          
+        func_kwargs = filter_args(request, sc.tl.dpt)
+        ads = get_ads()
+        adata = ads.get_adata(request=request)
+        sc.tl.dpt(adata, **func_kwargs)
+        add_op_log(adata, sc.tl.dpt, func_kwargs)
+        return [generate_msg(request, adata, ads)]
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+
+@tl_mcp.tool()
+async def paga(
+    request: PAGAModel = PAGAModel() 
+):
+    """Partition-based graph abstraction"""
+
+    try:
+        result = await forward_request("tl_paga", request)
+        if result is not None:
+            return result         
+        func_kwargs = filter_args(request, sc.tl.paga)
+        ads = get_ads()
+        adata = ads.get_adata(request=request)    
+        sc.tl.paga(adata, **func_kwargs)
+        add_op_log(adata, sc.tl.paga, func_kwargs)
+        return [generate_msg(request, adata, ads)]
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+
+@tl_mcp.tool()
+async def ingest(
+    request: IngestModel = IngestModel() 
+):
+    """Map labels and embeddings from reference data to new data"""
+
+    try:
+        result = await forward_request("tl_ingest", request)
+        if result is not None:
+            return result       
+        func_kwargs = filter_args(request, sc.tl.ingest)
+        ads = get_ads()
+        adata = ads.get_adata(request=request)    
+        sc.tl.ingest(adata, **func_kwargs)
+        add_op_log(adata, sc.tl.ingest, func_kwargs)
+        return [generate_msg(request, adata, ads)]
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+@tl_mcp.tool()
+async def rank_genes_groups(
+    request: RankGenesGroupsModel,
+
+):
+    """Rank genes for characterizing groups, for differentially expressison analysis"""
+
+    try:
+        result = await forward_request("tl_rank_genes_groups", request)
+        if result is not None:
+            return result         
+        func_kwargs = filter_args(request, sc.tl.rank_genes_groups)
+        ads = get_ads()
+        adata = ads.get_adata(request=request)
+        sc.tl.rank_genes_groups(adata, **func_kwargs)
+        add_op_log(adata, sc.tl.rank_genes_groups, func_kwargs)
+        return [generate_msg(request, adata, ads)]
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+
+@tl_mcp.tool()
+async def filter_rank_genes_groups(
+    request: FilterRankGenesGroupsModel = FilterRankGenesGroupsModel() 
+):
+    """Filter out genes based on fold change and fraction of genes"""
+
+    try:
+        result = await forward_request("tl_filter_rank_genes_groups", request)
+        if result is not None:
+            return result          
+        func_kwargs = filter_args(request, sc.tl.filter_rank_genes_groups)
+        ads = get_ads()
+        adata = ads.get_adata(request=request)
+        sc.tl.filter_rank_genes_groups(adata, **func_kwargs)
+        add_op_log(adata, sc.tl.filter_rank_genes_groups, func_kwargs)
+        return [generate_msg(request, adata, ads)]
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+
+@tl_mcp.tool()
+async def marker_gene_overlap(
+    request: MarkerGeneOverlapModel = MarkerGeneOverlapModel() 
+):
+    """Calculate overlap between data-derived marker genes and reference markers"""
+
+    try:
+        result = await forward_request("tl_marker_gene_overlap", request)
+        if result is not None:
+            return result         
+        func_kwargs = filter_args(request, sc.tl.marker_gene_overlap)
+        ads = get_ads()
+        adata = ads.get_adata(request=request)
+        sc.tl.marker_gene_overlap(adata, **func_kwargs)
+        add_op_log(adata, sc.tl.marker_gene_overlap, func_kwargs)
+        return [generate_msg(request, adata, ads)]
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+@tl_mcp.tool()
+async def score_genes(
+    request: ScoreGenesModel,
+    
+):
+    """Score a set of genes based on their average expression"""
+    try:
+        result = await forward_request("tl_score_genes", request)
+        if result is not None:
+            return result       
+        func_kwargs = filter_args(request, sc.tl.score_genes)
+        ads = get_ads()
+        adata = ads.get_adata(request=request)
+        sc.tl.score_genes(adata, **func_kwargs)
+        add_op_log(adata, sc.tl.score_genes, func_kwargs)
+        return [generate_msg(request, adata, ads)]
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+@tl_mcp.tool()
+async def score_genes_cell_cycle(
+    request: ScoreGenesCellCycleModel,
+    
+):
+    """Score cell cycle genes and assign cell cycle phases"""
+
+    try:
+        result = await forward_request("tl_score_genes_cell_cycle", request)
+        if result is not None:
+            return result       
+        func_kwargs = filter_args(request, sc.tl.score_genes_cell_cycle)
+        ads = get_ads()
+        adata = ads.get_adata(request=request)
+        sc.tl.score_genes_cell_cycle(adata, **func_kwargs)
+        add_op_log(adata, sc.tl.score_genes_cell_cycle, func_kwargs)
+        return [generate_msg(request, adata, ads)]
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+
+@tl_mcp.tool()
+async def pca(
+    request: PCAModel = PCAModel() 
+):
+    """Principal component analysis"""
+
+    try:
+        result = await forward_request("tl_pca", request)
+        if result is not None:
+            return result
+        func_kwargs = filter_args(request, sc.pp.pca)
+        ads = get_ads()
+        adata = ads.get_adata(request=request)
+        sc.pp.pca(adata, **func_kwargs)
+        add_op_log(adata, sc.pp.pca, func_kwargs)
+        return [
+            generate_msg(request, adata, ads)
+        ]
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)

scmcp_shared/server/util.py

@@ -0,0 +1,251 @@
+import os
+import inspect
+from pathlib import Path
+import scanpy as sc
+from fastmcp import FastMCP , Context
+from fastmcp.exceptions import ToolError
+from ..schema.util import *
+from ..util import filter_args, forward_request, get_ads, generate_msg,add_op_log
+
+
+ul_mcp = FastMCP("SCMCP-Util-Server")
+
+
+@ul_mcp.tool()
+async def query_op_log(request: QueryOpLogModel = QueryOpLogModel()):
+    """Query the adata operation log"""
+    adata = get_ads().get_adata(request=request)
+    op_dic = adata.uns["operation"]["op"]
+    opids = adata.uns["operation"]["opid"][-n:]
+    op_list = []
+    for opid in opids:
+        op_list.append(op_dic[opid])
+    return op_list
+
+
+@ul_mcp.tool()
+async def mark_var(
+    request: MarkVarModel = MarkVarModel() 
+):
+    """
+    Determine if each gene meets specific conditions and store results in adata.var as boolean values.
+    For example: mitochondrion genes startswith MT-.
+    The tool should be called first when calculate quality control metrics for mitochondrion, ribosomal, harhemoglobin genes, or other qc_vars.
+    """
+    try:
+        result = await forward_request("ul_mark_var", request)
+        if result is not None:
+            return result
+        adata = get_ads().get_adata(request=request)
+        var_name = request.var_name
+        gene_class = request.gene_class
+        pattern_type = request.pattern_type
+        patterns = request.patterns
+        if gene_class is not None:
+            if gene_class == "mitochondrion":
+                adata.var["mt"] = adata.var_names.str.startswith(('MT-', 'Mt','mt-'))
+                var_name = "mt"
+            elif gene_class == "ribosomal":
+                adata.var["ribo"] = adata.var_names.str.startswith(("RPS", "RPL", "Rps", "Rpl"))
+                var_name = "ribo"
+            elif gene_class == "hemoglobin":
+                adata.var["hb"] = adata.var_names.str.contains("^HB[^(P)]", case=False)
+                var_name = "hb"    
+        elif pattern_type is not None and patterns is not None:
+            if pattern_type == "startswith":
+                adata.var[var_name] = adata.var_names.str.startswith(patterns)
+            elif pattern_type == "endswith":
+                adata.var[var_name] = adata.var_names.str.endswith(patterns)
+            elif pattern_type == "contains":
+                adata.var[var_name] = adata.var_names.str.contains(patterns)
+            else:
+                raise ValueError(f"Did not support pattern_type: {pattern_type}")
+        else:
+            raise ValueError(f"Please provide validated parameter")
+    
+        res = {var_name: adata.var[var_name].value_counts().to_dict(), "msg": f"add '{var_name}' column in adata.var"}
+        func_kwargs = {"var_name": var_name, "gene_class": gene_class, "pattern_type": pattern_type, "patterns": patterns}
+        add_op_log(adata, "mark_var", func_kwargs)
+        return res
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+
+@ul_mcp.tool()
+async def list_var(
+    request: ListVarModel = ListVarModel() 
+):
+    """List key columns in adata.var. It should be called for checking when other tools need var key column names as input."""
+    try:
+        result = await forward_request("ul_list_var", request)
+        if result is not None:
+            return result
+        adata = get_ads().get_adata(request=request)
+        columns = list(adata.var.columns)
+        add_op_log(adata, list_var, {})
+        return columns
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+@ul_mcp.tool()
+async def list_obs(
+    request: ListObsModel = ListObsModel() 
+):
+    """List key columns in adata.obs. It should be called before other tools need obs key column names input."""
+    try:
+        result = await forward_request("ul_list_obs", request)
+        if result is not None:
+            return result    
+        adata = get_ads().get_adata(request=request)
+        columns = list(adata.obs.columns)
+        add_op_log(adata, list_obs, {})
+        return columns
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+@ul_mcp.tool()
+async def check_var(
+    request: VarNamesModel = VarNamesModel() 
+):
+    """Check if genes/variables exist in adata.var_names. This tool should be called before gene expression visualizations or color by genes."""
+    try:
+        result = await forward_request("ul_check_var", request)
+        if result is not None:
+            return result     
+        adata = get_ads().get_adata(request=request)
+        var_names = request.var_names
+        result = {v: v in adata.var_names for v in var_names}
+        add_op_log(adata, check_var, {"var_names": var_names})
+        return result
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+@ul_mcp.tool()
+async def merge_adata(
+    request: ConcatAdataModel = ConcatAdataModel() 
+):
+    """Merge multiple adata objects."""
+     
+    try:
+        result = await forward_request("ul_merge_adata", request)
+        if result is not None:
+            return result
+        ads = get_ads()
+        adata = ads.get_adata(request=request)
+        kwargs = {k: v for k, v in request.model_dump().items() if v is not None}
+        merged_adata = adata.concat(list(ads.adata_dic[dtype].values()), **kwargs)
+        ads.adata_dic[dtype] = {}
+        ads.active_id = "merged_adata"
+        add_op_log(merged_adata, ad.concat, kwargs)
+        ads.adata_dic[ads.active_id] = merged_adata
+        return {"status": "success", "message": "Successfully merged all AnnData objects"}
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+
+@ul_mcp.tool()
+async def set_dpt_iroot(
+    request: DPTIROOTModel,
+    
+):
+    """Set the iroot cell"""
+    try:
+        result = await forward_request("ul_set_dpt_iroot", request)
+        if result is not None:
+            return result     
+        adata = get_ads().get_adata(request=request)
+        diffmap_key = request.diffmap_key
+        dimension = request.dimension
+        direction = request.direction
+        if diffmap_key not in adata.obsm:
+            raise ValueError(f"Diffusion map key '{diffmap_key}' not found in adata.obsm")
+        if direction == "min":
+            adata.uns["iroot"] = adata.obsm[diffmap_key][:, dimension].argmin()
+        else:  
+            adata.uns["iroot"] = adata.obsm[diffmap_key][:, dimension].argmax()
+        
+        func_kwargs = {"diffmap_key": diffmap_key, "dimension": dimension, "direction": direction}
+        add_op_log(adata, "set_dpt_iroot", func_kwargs)
+        
+        return {"status": "success", "message": f"Successfully set root cell for DPT using {direction} of dimension {dimension}"}
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+@ul_mcp.tool()
+async def add_layer(
+    request: AddLayerModel,
+):
+    """Add a layer to the AnnData object.
+    """
+    try:
+        result = await forward_request("ul_add_layer", request)
+        if result is not None:
+            return result         
+        adata = get_ads().get_adata(request=request)
+        layer_name = request.layer_name
+        
+        # Check if layer already exists
+        if layer_name in adata.layers:
+            raise ValueError(f"Layer '{layer_name}' already exists in adata.layers")
+        # Add the data as a new layer
+        adata.layers[layer_name] = adata.X.copy()
+
+        func_kwargs = {"layer_name": layer_name}
+        add_op_log(adata, "add_layer", func_kwargs)
+        
+        return {
+            "status": "success", 
+            "message": f"Successfully added layer '{layer_name}' to adata.layers"
+        }
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)
+
+@ul_mcp.tool()
+async def check_samples():
+    """check the stored samples    
+    """
+    try:
+        ads = get_ads()
+        return {"sampleid": [list(ads.adata_dic[dk].keys()) for dk in ads.adata_dic.keys()]}
+    except ToolError as e:
+        raise ToolError(e)
+    except Exception as e:
+        if hasattr(e, '__context__') and e.__context__:
+            raise ToolError(e.__context__)
+        else:
+            raise ToolError(e)