SCMCP

Instructions

Implementation Reference

• src/scmcp/schema/tl.py:155-207 (schema)

  Pydantic model defining the input schema for the draw_graph tool, including parameters like layout, init_pos, root, etc., with validation.

  class DrawGraphModel(JSONParsingModel):
      """Input schema for the force-directed graph drawing tool."""
      
      layout: str = Field(
          default='fa',
          description="Graph layout algorithm ('fa', 'fr', 'kk', etc.)",
      )
      init_pos: Optional[Union[str, bool]] = Field(
          default=None,
          description="Initial position for nodes ('paga'/True, False, or .obsm key)",
      )
      root: Optional[int] = Field(
          default=None,
          description="Root node for tree layouts",
          ge=0
      )
      random_state: int = Field(
          default=0,
          description="Random seed for reproducibility"
      )
      n_jobs: Optional[int] = Field(
          default=None,
          description="Number of jobs for parallel computation",
          gt=0
      )
      key_added_ext: Optional[str] = Field(
          default=None,
          description="Suffix for storing results in .obsm"
      )
      neighbors_key: Optional[str] = Field(
          default=None,
          description="Key for neighbors settings in .uns"
      )
      obsp: Optional[str] = Field(
          default=None,
          description="Key for adjacency matrix in .obsp"
      )
      
      @field_validator('layout')
      def validate_layout(cls, v: str) -> str:
          """Validate layout is supported"""
          valid_layouts = ['fa', 'fr', 'grid_fr', 'kk', 'lgl', 'drl', 'rt']
          if v.lower() not in valid_layouts:
              raise ValueError(f"layout must be one of {valid_layouts}")
          return v.lower()
      
      @field_validator('root', 'n_jobs')
      def validate_positive_integers(cls, v: Optional[int]) -> Optional[int]:
          """Validate positive integers where applicable"""
          if v is not None and v <= 0:
              raise ValueError("must be a positive integer")
          return v

• src/scmcp/tool/tl.py:26-31 (registration)

  Definition of the draw_graph Tool object with name, description, and input schema reference.

  # Add draw_graph tool
  draw_graph_tool = types.Tool(
      name="draw_graph",
      description="Force-directed graph drawing for visualization",
      inputSchema=DrawGraphModel.model_json_schema(),
  )

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

  tl_tools dictionary registers the draw_graph_tool along with other tl tools for use in server.list_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,
  }

• src/scmcp/server.py:59-92 (handler)

  MCP server call_tool handler dispatches draw_graph (in tl_tools) to run_tl_func.

  @server.call_tool()
  async def call_tool(
      name: str, arguments
  ):
      try:
          logger.info(f"Running {name} with {arguments}")
          if name in io_tools.keys():            
              res = run_io_func(ads, name, arguments)
          elif name in pp_tools.keys():
              res = run_pp_func(ads, name, arguments)
          elif name in tl_tools.keys():
              res = run_tl_func(ads, name, arguments) 
          elif name in pl_tools.keys():
              res = run_pl_func(ads, name, arguments)
          elif name in util_tools.keys():            
              res = run_util_func(ads, name, arguments)
          elif name in ccc_tools.keys():            
              res = run_ccc_func(ads.adata_dic[ads.active], name, arguments)
          output = str(res) if res is not None else str(ads.adata_dic[ads.active])
          return [
              types.TextContent(
                  type="text",
                  text=str({"output": output})
              )
          ]
      except Exception as error:
          logger.error(f"{name} with {error}")
          return [
              types.TextContent(
                  type="text",
                  text=str({"Error": error})
              )
          ]

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

  Helper function that executes the tool by calling sc.tl.draw_graph(adata, **kwargs) for func='draw_graph'.

  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