pl_dotplot

Instructions

Implementation Reference

• src/scmcp/tool/pl.py:179-217 (handler)

  Generic handler function for all pl_ tools including pl_dotplot. Dispatches to sc.pl.dotplot based on func='pl_dotplot', prepares arguments, executes the plot, saves figure to path, and logs the operation.

  def run_pl_func(ads, func, arguments):
      """
      Execute a Scanpy plotting function with the given arguments.
      
      Parameters
      ----------
      adata : AnnData
          Annotated data matrix.
      func : str
          Name of the plotting function to execute.
      arguments : dict
          Arguments to pass to the plotting function.
          
      Returns
      -------
      The result of the plotting function.
      """
      adata = ads.adata_dic[ads.active]
      if func not in pl_func:
          raise ValueError(f"Unsupported function: {func}")
  
      run_func = pl_func[func]
      parameters = inspect.signature(run_func).parameters
      kwargs = {k: arguments.get(k) for k in parameters if k in arguments}    
  
      if "title" not in parameters:
          kwargs.pop("title", False)    
      kwargs.pop("return_fig", True)
      kwargs["show"] = False
      kwargs["save"] = ".png"
      try:
          fig = run_func(adata, **kwargs)
          fig_path = set_fig_path(func, **kwargs)
          add_op_log(adata, run_func, kwargs)
          return fig_path 
      except Exception as e:
          raise e
      return fig_path

• src/scmcp/schema/pl.py:524-575 (schema)

  Pydantic model defining the input schema and validation for the pl_dotplot tool parameters, extending BaseMatrixModel with dotplot-specific fields like expression_cutoff, dot_max, etc.

  class DotplotModel(BaseMatrixModel):
      """Input schema for the dotplot plotting tool."""
      
      expression_cutoff: float = Field(
          default=0.0,
          description="Expression cutoff that is used for binarizing the gene expression."
      )
      
      mean_only_expressed: bool = Field(
          default=False,
          description="If True, gene expression is averaged only over the cells expressing the given genes."
      )
      
      standard_scale: Optional[Literal['var', 'group']] = Field(
          default=None,
          description="Whether or not to standardize that dimension between 0 and 1."
      )
      
      swap_axes: bool = Field(
          default=False,
          description="By default, the x axis contains var_names and the y axis the groupby categories. By setting swap_axes then x are the groupby categories and y the var_names."
      )
      
      dot_max: Optional[float] = Field(
          default=None,
          description="The maximum size of the dots."
      )
      
      dot_min: Optional[float] = Field(
          default=None,
          description="The minimum size of the dots."
      )
      
      smallest_dot: Optional[float] = Field(
          default=None,
          description="The smallest dot size."
      )
      var_group_rotation: Optional[float] = Field(
          default=None,
          description="Label rotation degrees. By default, labels larger than 4 characters are rotated 90 degrees."
      )
      
      colorbar_title: Optional[str] = Field(
          default='Mean expression\nin group',
          description="Title for the color bar. New line character (\\n) can be used."
      )
      
      size_title: Optional[str] = Field(
          default='Fraction of cells\nin group (%)',
          description="Title for the size legend. New line character (\\n) can be used."
      )

• src/scmcp/tool/pl.py:48-52 (registration)

  Registers the pl_dotplot tool object with MCP types.Tool, specifying name, description, and input schema from DotplotModel.

  pl_dotplot = types.Tool(
      name="pl_dotplot",
      description="Plot dot plot of expression values per gene for each group.",
      inputSchema=DotplotModel.model_json_schema(),
  )

• src/scmcp/tool/pl.py:121-138 (registration)

  Maps tool name 'pl_dotplot' to the underlying Scanpy function sc.pl.dotplot, used by the handler to dispatch execution.

  pl_func = {
      "pl_pca": sc.pl.pca,
      "pl_embedding": sc.pl.embedding,  # Add the new embedding function
      "diffmap": sc.pl.diffmap,
      "pl_violin": sc.pl.violin,
      "pl_stacked_violin": sc.pl.stacked_violin,
      "pl_heatmap": sc.pl.heatmap,
      "pl_dotplot": sc.pl.dotplot,
      "pl_matrixplot": sc.pl.matrixplot,
      "pl_tracksplot": sc.pl.tracksplot,
      "pl_scatter": sc.pl.scatter,
      "embedding_density": sc.pl.embedding_density,
      "rank_genes_groups": sc.pl.rank_genes_groups,
      "pl_rank_genes_groups_dotplot": sc.pl.rank_genes_groups_dotplot,  # Add function mapping
      "pl_clustermap": sc.pl.clustermap,
      "pl_highly_variable_genes": sc.pl.highly_variable_genes,
      "pl_pca_variance_ratio": sc.pl.pca_variance_ratio,
  }

• src/scmcp/server.py:60-92 (registration)

  MCP server call_tool handler dispatches 'pl_dotplot' (in pl_tools) to run_pl_func(ads, 'pl_dotplot', arguments), providing the execution entrypoint for the 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})
              )
          ]