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 register Pulsar with your agent tools:

uvx --from thema-pulsar pulsar install

pulsar install detects Claude Code, Claude Desktop, Codex CLI, Gemini CLI, GitHub Copilot CLI, Cursor, VS Code, and Google Antigravity, then writes the MCP server entry each client expects (absolute-path uvx by default). Re-run anytime to repair drifted configs. Check status with uvx --from thema-pulsar pulsar status; remove registrations with uvx --from thema-pulsar pulsar uninstall.

The installer prompts on your terminal directly, so it still appears when output is piped (pulsar install | tee install.log). Where there is no console at all — CI, a systemd unit — pass explicit harness ids (claude, claude-desktop, codex, gemini, copilot, cursor, vscode, antigravity) or --all:

uvx --from thema-pulsar pulsar install --all
uvx --from thema-pulsar pulsar uninstall --all --yes

Prefer a persistent server binary? Use pipx install "thema-pulsar[mcp]" and pulsar install --mode pipx.

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

claude mcp add pulsar -- uvx --from "thema-pulsar[mcp]" pulsar-mcp
gemini mcp add --scope user --timeout 60000 pulsar uvx -- --from "thema-pulsar[mcp]" pulsar-mcp

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.

• ingest_dataset(path): Registers a host-visible CSV/Parquet path and returns the stable dataset_id every other tool keys off of.
• 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.
• refine_config: Applies targeted overrides (or deletions) to a config by dotted path instead of regenerating the whole YAML, for iterating after a diagnosis.
• 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.

That's the core loop — there's a much larger surface for longitudinal/temporal panels, graph artifacts, threshold tuning, and HTML/Parquet exports. See the MCP guide for the full tool table, or call get_workflow_guide from the agent itself for the opinionated end-to-end procedure.

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.