SCMCP

Instructions

Implementation Reference

• src/scmcp/tool/tl.py:164-177 (handler)

  Generic handler function that executes the score_genes tool by retrieving sc.tl.score_genes from tl_func mapping, validating parameters via inspect.signature, calling it on the active AnnData object, and logging the operation.

  def run_tl_func(ads, func, arguments):
      adata = ads.adata_dic[ads.active]
      if func not in tl_func:
          raise ValueError(f"Unsupported function: {func}")
      run_func = tl_func[func]
      parameters = inspect.signature(run_func).parameters
      kwargs = {k: arguments.get(k) for k in parameters if k in arguments}    
      try:
          res = run_func(adata, **kwargs)
          add_op_log(adata, run_func, kwargs)
      except Exception as e:
          logger.error(f"Error running function {func}: {e}")
          raise
      return 

• src/scmcp/schema/tl.py:823-864 (schema)

  Pydantic model defining the input schema and validation for the score_genes tool parameters.

  class ScoreGenesModel(JSONParsingModel):
      """Input schema for the score_genes tool that calculates gene scores based on average expression."""
      
      ctrl_size: int = Field(
          default=50,
          description="Number of reference genes to be sampled from each bin.",
          gt=0
      )
      
      gene_pool: Optional[List[str]] = Field(
          default=None,
          description="Genes for sampling the reference set. Default is all genes."
      )
      
      n_bins: int = Field(
          default=25,
          description="Number of expression level bins for sampling.",
          gt=0
      )
      
      score_name: str = Field(
          default='score',
          description="Name of the field to be added in .obs."
      )
      
      random_state: int = Field(
          default=0,
          description="The random seed for sampling."
      )
      
      use_raw: Optional[bool] = Field(
          default=None,
          description="Whether to use raw attribute of adata. Defaults to True if .raw is present."
      )
      
      @field_validator('ctrl_size', 'n_bins')
      def validate_positive_integers(cls, v: int) -> int:
          """Validate positive integers"""
          if v <= 0:
              raise ValueError("must be a positive integer")
          return v

• src/scmcp/tool/tl.py:110-115 (registration)

  Registers the score_genes tool as an MCP Tool object with name, description, and input schema reference.

  # Add score_genes tool
  score_genes_tool = types.Tool(
      name="score_genes",
      description="Score a set of genes based on their average expression",
      inputSchema=ScoreGenesModel.model_json_schema(),
  )

• src/scmcp/tool/tl.py:125-142 (registration)

  Maps the 'score_genes' tool name to the underlying scanpy function sc.tl.score_genes for execution.

  tl_func = {
      "tsne": sc.tl.tsne,
      "umap": sc.tl.umap,
      "draw_graph": sc.tl.draw_graph,
      "diffmap": sc.tl.diffmap,
      "embedding_density": sc.tl.embedding_density,
      "leiden": sc.tl.leiden,
      "louvain": sc.tl.louvain,
      "dendrogram": sc.tl.dendrogram,
      "dpt": sc.tl.dpt,
      "paga": sc.tl.paga,
      "ingest": sc.tl.ingest,
      "rank_genes_groups": sc.tl.rank_genes_groups,
      "filter_rank_genes_groups": sc.tl.filter_rank_genes_groups,
      "marker_gene_overlap": sc.tl.marker_gene_overlap,
      "score_genes": sc.tl.score_genes,
      "score_genes_cell_cycle": sc.tl.score_genes_cell_cycle,
  }

• src/scmcp/tool/tl.py:145-162 (registration)

  Adds the score_genes_tool to the tl_tools dictionary, which is used by the MCP server to list available tools.

  tl_tools = {
      "tsne": tsne_tool,
      "umap": umap_tool,
      "draw_graph": draw_graph_tool,
      "diffmap": diffmap_tool,
      "embedding_density": embedding_density_tool,
      "leiden": leiden_tool,
      "louvain": louvain_tool,
      "dendrogram": dendrogram_tool,
      "dpt": dpt_tool,
      "paga": paga_tool,
      "ingest": ingest_tool,
      "rank_genes_groups": rank_genes_groups_tool,
      "filter_rank_genes_groups": filter_rank_genes_groups_tool,
      "marker_gene_overlap": marker_gene_overlap_tool,
      "score_genes": score_genes_tool,
      "score_genes_cell_cycle": score_genes_cell_cycle_tool,
  }