Until now, topological data analysis required a Ph.D. in algebraic topology and a masochistic tolerance for parameter tuning.

By default, Pulsar exposes a rich Python API. This is great when you actually want to build custom pipelines, but when you just want to find out why your dataset is acting weird, writing boilerplate is tedious and unintuitive.

We get lots of complaints about it actually, with people asking things like:

Why is my cosmic graph a hairball? What the hell should my epsilon range be? Why did my PCA just drop 90% of the variance?

We hear you, but we're not convinced that writing a 50-line hyperparameter grid search is what you really want. You don't want to have to manually calculate k-NN distances every time you load a CSV. And I doubt you really want to stare at a raw NetworkX adjacency matrix either — you want answers. You want to point an LLM at your data and say, "Find the natural clusters and tell me why they exist."

The Pulsar MCP (Model Context Protocol) Server is our attempt to give you what you actually want, without any of the downsides of doing something stupid like guessing topological parameters.

Setup

You do not need to clone this repository. Install uv, then point your client at the published package.

For clients configured with JSON (Claude Desktop, Cursor, Windsurf):

{
  "mcpServers": {
    "pulsar": {
      "command": "uvx",
      "args": ["--from", "thema-pulsar[mcp]", "pulsar-mcp"],
      "env": {}
    }
  }
}

For CLI clients, one command:

# Claude Code
claude mcp add pulsar -- uvx --from "thema-pulsar[mcp]" pulsar-mcp

# Gemini CLI — user scope works from any directory; use --scope project to limit it to one project
gemini mcp add --scope user --timeout 60000 pulsar uvx -- --from "thema-pulsar[mcp]" pulsar-mcp

uvx pulls thema-pulsar[mcp] straight from PyPI and runs pulsar-mcp in an isolated environment—no clone, manually managed Python environment, or uv sync required. If you prefer a persistent install, run pipx install "thema-pulsar[mcp]" and use "command": "pulsar-mcp" instead.

Restart your client. Done.

Two things that trip people up: the first launch can take up to a minute while uvx downloads Pulsar (hence Gemini's --timeout 60000), and Gemini will not start stdio MCP servers in an untrusted workspace—choose Trust folder when prompted. The MCP setup guide covers both, per client.

General Overview

What follows from here is the exact workflow we designed to dogfood the pipeline. It covers every sensible step of a topological analysis, from geometry probing to statistical dossiers.

It's important you let the agent follow this exact sequence for a few reasons:

1. We want the graph to actually have signal out of the box.
2. Really just the first reason, that's the whole point of these tools.

Here is the exact loop the agent should run:

1. Ingest the dataset to get a stable dataset_id handle.
2. Create a calibrated config via create_config(dataset_id) — calibrates epsilon and projection dimensions against the processed feature space.
3. Sweep the topology using that config.
4. Diagnose the graph to see if it's a giant useless blob or actually balanced. Use the metrics to decide what to adjust, then iterate via refine_config.
5. Generate the dossier to explain the clusters in plain English.
6. Compare clusters for academic-grade p-values.
7. Export the labeled data.

Tool Fly-By

We didn't just wrap our Python functions in JSON schemas. We built Thick Tools—stateful, workflow-aware engines that pass configuration directly between each other so you don't have to watch the agent screw up file I/O.

• create_config(dataset_id): The primary config generation tool. Analyzes k-NN distances and projection dimensions in the processed feature space (after preprocessing + scaling) to produce a calibrated YAML config. Never let the agent guess parameters.
• run_topological_sweep: Runs the heavy Rust pipeline. Takes inline YAML and returns structured JSON with metrics and experiment diff. Config persistence is opt-in via save_config=True.
• diagnose_cosmic_graph: Returns current graph-state observables: scale, component morphology, weight distribution, sweep support, observed patterns, and risk factors. The agent interprets those measurements against the user's objective.
• generate_cluster_dossier: Returns structured JSON with per-cluster profiles (Z-scores, homogeneity, concentration) plus a Markdown summary. Includes clustering method metadata (method used, silhouette score).
• compare_clusters: Runs Welch's T-tests, KS-tests, and Cohen's d between two specific clusters. Because sometimes your boss wants a p-value.
• export_labeled_data: Maps semantic names to a cluster_assignment_id from generate_cluster_dossier and dumps that exact clustering to a CSV.

Pitfalls & Annoyances

We try to make things foolproof, but some of you goofballs are going to try to break it anyway. Here is what to avoid:

• Don't let the agent write YAML files manually. The tools pass YAML strings directly in memory (suggested_params_yaml -> config_yaml). If you watch the agent try to use write_file to save a params.yaml before running the sweep, stop it. If you make the agent do unnecessary file I/O you belong in prison.
• Don't skip the diagnosis step. If the graph is a giant hairball, your clusters will be garbage. Use diagnose_cosmic_graph to inspect graph-state measurements, then decide whether the user's objective calls for threshold inspection, config refinement, or a different interpretation surface.
• Handle non-numeric data appropriately. Pulsar is a geometric engine. It needs floats. characterize_dataset will automatically tell the agent which low-cardinality strings to one-hot encode and which high-cardinality strings to drop. Don't fight it.