run_millimap_tool

Instructions

Implementation Reference

• src/millimap_mcp/server.py:342-368 (handler)

  The main handler function for the 'run_millimap_tool' tool. It parses a JSON string of arguments, then delegates to _post_tool with the inner tool name and args.

  @mcp.tool()
  def run_millimap_tool(tool_name: str, tool_args_json: str = "{}") -> str:
      """Escape hatch — run any of MilliMap's 30+ analysis tools by name.
  
      Use when a workflow needs a tool not individually exposed above.
  
      Examples of tool_name:
          run_deg_clusters, run_deg_roi, run_go_enrichment,
          find_spatially_variable_genes, run_neighborhood_enrichment,
          run_co_occurrence, run_centrality_scores, run_interaction_matrix,
          run_ripley, run_ligrec, run_pca, run_louvain, run_diffmap,
          run_draw_graph, run_paga, run_dpt, run_embedding_density,
          run_doublet_detection, normalize_data, find_highly_variable_genes,
          score_cell_cycle, create_dotplot, create_heatmap,
          create_stacked_violin, annotate_clusters.
  
      Args:
          tool_name: Exact tool name from the list above.
          tool_args_json: JSON string of arguments, e.g. '{"group_a": "1", "group_b": "2"}'.
      """
      try:
          inner = json.loads(tool_args_json) if tool_args_json else {}
      except Exception as exc:
          return _fmt_json({"ok": False, "error": f"bad tool_args_json: {exc}"})
      return _fmt_json(_post_tool("run_tool", {
          "tool_name": tool_name, "tool_args": inner,
      }))

• src/millimap_mcp/server.py:33-58 (helper)

  Helper function _post_tool that sends the actual HTTP POST request to the MilliMap desktop application endpoint (http://host:port/tool). Used by run_millimap_tool to proxy the tool execution.

  def _post_tool(name: str, args: dict, timeout: float = 600.0) -> dict:
      ctrl = _load_control()
      if not ctrl or not ctrl.get("port"):
          return {
              "ok": False,
              "error": (
                  f"MilliMap control endpoint not found at {CONTROL_PATH}. "
                  "Make sure MilliMap is running with a dataset loaded."
              ),
          }
      host = ctrl.get("host", "127.0.0.1")
      port = int(ctrl["port"])
      url = f"http://{host}:{port}/tool"
      data = json.dumps({"name": name, "args": args}).encode("utf-8")
      req = urllib.request.Request(
          url, data=data,
          headers={"Content-Type": "application/json"},
          method="POST",
      )
      try:
          with urllib.request.urlopen(req, timeout=timeout) as resp:
              return json.loads(resp.read().decode("utf-8"))
      except urllib.error.URLError as exc:
          return {"ok": False, "error": f"connection failed: {exc.reason}"}
      except Exception as exc:
          return {"ok": False, "error": f"HTTP call failed: {exc}"}

• src/millimap_mcp/server.py:77-78 (helper)

  Helper function _fmt_json that serializes the response payload to a pretty-printed JSON string.

  def _fmt_json(payload: Any) -> str:
      return json.dumps(payload, indent=2, default=str)

• src/millimap_mcp/server.py:342-342 (registration)

  Registration of the tool via the @mcp.tool() decorator on the run_millimap_tool function, which exposes it as an MCP tool named 'run_millimap_tool'.

  @mcp.tool()