SCMCP

Instructions

Implementation Reference

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

  Generic handler function for all tl tools, including score_genes_cell_cycle. It retrieves the Scanpy function from tl_func dict using the tool name, inspects parameters, passes matching arguments, executes on active adata, logs the operation, and handles errors.

  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:866-912 (schema)

  Pydantic model defining the input schema for the score_genes_cell_cycle tool, including required S and G2M gene lists, optional parameters like gene_pool, n_bins, score_name, random_state, use_raw, with validators.

  class ScoreGenesCellCycleModel(JSONParsingModel):
      """Input schema for the score_genes_cell_cycle tool that scores cell cycle genes."""
      
      s_genes: List[str] = Field(
          ...,  # Required field
          description="List of genes associated with S phase."
      )
      g2m_genes: List[str] = Field(
          ...,  # Required field
          description="List of genes associated with G2M phase."
      )
      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: Optional[str] = Field(
          default=None,
          description="Name of the field to be added in .obs. If None, the scores are added as 'S_score' and 'G2M_score'."
      )
      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('s_genes', 'g2m_genes')
      def validate_gene_lists(cls, v: List[str]) -> List[str]:
          """Validate gene lists are not empty"""
          if len(v) == 0:
              raise ValueError("Gene list cannot be empty")
          return v
      
      @field_validator('n_bins')
      def validate_positive_integers(cls, v: int) -> int:
          """Validate positive integers"""
          if v <= 0:
              raise ValueError("n_bins must be a positive integer")
          return v

• src/scmcp/tool/tl.py:117-122 (registration)

  Creates the MCP Tool object for score_genes_cell_cycle, specifying name, description, and input schema from ScoreGenesCellCycleModel.

  # Add score_genes_cell_cycle tool
  score_genes_cell_cycle_tool = types.Tool(
      name="score_genes_cell_cycle",
      description="Score cell cycle genes and assign cell cycle phases",
      inputSchema=ScoreGenesCellCycleModel.model_json_schema(),
  )

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

  Maps the tool name 'score_genes_cell_cycle' to the underlying Scanpy function sc.tl.score_genes_cell_cycle in the tl_func dictionary used by the handler.

  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)

  Registers the score_genes_cell_cycle_tool in the tl_tools dictionary, which is exposed via list_tools() in the MCP server.

  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,
  }