rustcluster-mcp

rustcluster-mcp is a FastMCP server that acts as a clustering advisor — it doesn't just expose rustcluster's API as tools, it brings domain intelligence to help you converge on the right clustering configuration.

Under the hood is a knowledge graph encoding 7 algorithms, 30+ parameters, their interactions, decision rules, anti-patterns, and diagnostic recipes. The server queries this graph to analyze your data, recommend algorithms, suggest justified configurations, run clustering directly, and diagnose problems.

Quick start

The fastest way to get started — no Python or Rust install needed:

docker pull fbaig4/rustcluster-mcp:latest

Add to your Claude Code config (~/.claude.json):

{
  "mcpServers": {
    "rustcluster": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/path/to/your/data:/data",
        "fbaig4/rustcluster-mcp:latest"
      ]
    }
  }
}

Replace /path/to/your/data with the directory containing your .npy, .npz, or .parquet files. Inside Claude, your data is accessible at /data/.

For other setup options (pip install, from source), see SETUP.md.

How it works

Phase 1 — Plan (advisory tools, no clustering runs)

> analyze my embeddings at /data/embeddings.npy

Profiles dimensionality, normalization, density, intrinsic dimensionality.

> what algorithm should I use? 50K OpenAI embeddings, unknown cluster count

Returns ranked recommendations: "EmbeddingCluster with reduction_dim=128, or HDBSCAN if you want auto-k discovery."

> give me a config for embedding_cluster

Every parameter with a suggested value and data-specific rationale.

Phase 2 — Execute (run clustering directly)

> cluster my data with embedding_cluster, 20 clusters

The fit tool runs clustering and returns labels, metrics (silhouette, CH, DB), and cluster size distribution. No code writing needed.

> find the best k between 5 and 100

Sweeps k values with all three metrics, recommends the best.

Phase 3 — Refine

> my clusters look uneven — one cluster has 80% of the points

Returns pathology signature, likely causes, and specific fix recipes.

Features

• Knowledge graph — 7 algorithms, 30+ parameters, 9 decision rules, 8 anti-patterns, 6 pathology signatures with fix recipes
• Direct clustering — fit tool runs clustering on data files without needing a sandbox or writing code
• Advisor tools — analyze data, recommend algorithms, suggest configs, optimize k, compare configs, evaluate quality, diagnose issues
• Knowledge tools — explain any algorithm or parameter, validate configs, list algorithms by capability
• Sandbox tools — execute custom Python in auditable Marimo notebooks with a pre-injected __cluster__ helper (optional, requires marimo-sandbox)
• Snapshot visualizations — 2D projections, confidence heatmaps, drift radar charts, hierarchical sunbursts
• Data formats — .npy, .npz, and .parquet (parquet requires pyarrow)

Tools reference

Execution tools

Advisor tools

Knowledge tools

Sandbox tools (optional, requires marimo-sandbox)

Knowledge graph

Development

See SETUP.md for detailed setup instructions. Quick version:

git clone https://github.com/mfbaig35r/rustcluster-mcp
cd rustcluster-mcp
uv venv && uv pip install -e ".[dev]"
uv run ruff check src/ tests/
uv run pytest tests/ -m "not slow" -v

License

MIT