SCMCP

Instructions

Implementation Reference

• src/scmcp/schema/tl.py:8-67 (schema)

  Pydantic model defining the input schema and validation for the tsne tool.

  class TSNEModel(JSONParsingModel):
      """Input schema for the t-SNE dimensionality reduction tool."""
      n_pcs: Optional[int] = Field(
          default=None,
          description="Number of PCs to use. If None, automatically determined.",
          ge=0
      )
      use_rep: Optional[str] = Field(
          default=None,
          description="Key for .obsm to use as representation."
      )
      perplexity: Union[float, int] = Field(
          default=30,
          description="Related to number of nearest neighbors, typically between 5-50.",
          gt=0
      )
      early_exaggeration: Union[float, int] = Field(
          default=12,
          description="Controls space between natural clusters in embedded space.",
          gt=0
      )
      learning_rate: Union[float, int] = Field(
          default=1000,
          description="Learning rate for optimization, typically between 100-1000.",
          gt=0
      )
      random_state: int = Field(
          default=0,
          description="Random seed for reproducibility."
      )
      use_fast_tsne: bool = Field(
          default=False,
          description="Whether to use Multicore-tSNE implementation."
      )
      n_jobs: Optional[int] = Field(
          default=None,
          description="Number of jobs for parallel computation.",
          gt=0
      )
      metric: str = Field(
          default='euclidean',
          description="Distance metric to use."
      )
      
      @field_validator('n_pcs', 'perplexity', 'early_exaggeration', 
                     'learning_rate', 'n_jobs')
      def validate_positive_numbers(cls, v: Optional[Union[int, float]]) -> Optional[Union[int, float]]:
          """Validate positive numbers where applicable"""
          if v is not None and v <= 0:
              raise ValueError("must be a positive number")
          return v
      
      @field_validator('metric')
      def validate_metric(cls, v: str) -> str:
          """Validate distance metric is supported"""
          valid_metrics = ['euclidean', 'cosine', 'manhattan', 'l1', 'l2']
          if v.lower() not in valid_metrics:
              raise ValueError(f"metric must be one of {valid_metrics}")
          return v.lower()

• src/scmcp/tool/tl.py:12-17 (registration)

  Definition of the MCP Tool object for 'tsne', including name, description, and schema reference.

  # Define t-SNE tool
  tsne_tool = types.Tool(
      name="tsne",
      description="t-distributed stochastic neighborhood embedding (t-SNE), for visualizating single-cell data",
      inputSchema=TSNEModel.model_json_schema(),
  )

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

  Dictionary mapping 'tsne' tool name to the underlying scanpy function sc.tl.tsne used in 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)

  Dictionary registering the tsne_tool (and other tl tools) that is used by the MCP server for tool listing and dispatch.

  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/tool/tl.py:164-177 (handler)

  Handler function that executes tl tools like tsne by calling the mapped scanpy function with validated arguments and logging.

  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