spark-profiler-mcp

npm node license

MCP server that reads spark profiler files so an AI can give accurate Minecraft server tuning advice.

Parses spark's binary protobuf directly: no upload, no protoc. Ships a diagnose engine that knows TPS/MSPT/GC/heap thresholds and call-tree signatures (entity ticking, chunk gen, redstone, blocking I/O, plugin hogs, JVM flags), returns ranked findings with concrete fixes.

Supported files

File	spark command	Contents
`.sparkprofile`	`/spark profiler --stop`	Sampler / call tree
`.sparkheap`	`/spark heapsummary --save-to-file`	Memory (top retained types)
`.sparkhealth`	`/spark health --save-to-file`	TPS/MSPT/CPU/entities over time

Input = local path, https://spark.lucko.me/<key> / bytebin URL, or bare bytebin key. gzip and raw protobuf both auto-handled.

Shared spark.lucko.me links expire (bytebin deletes them). For permanent analysis, --save-to-file.

Most tools (diagnose, get_summary, get_platform_info, get_system_stats, get_health) work on sampler and health files. .sparkheap → get_heap_summary. Call-tree tools = sampler only.

Install (one line)

Published to npm — no clone, no build; npx fetches and runs it:

claude mcp add spark-profiler -- npx -y spark-profiler-mcp

Same thing as an MCP client config block (.mcp.json / claude_desktop_config.json):

{
  "mcpServers": {
    "spark-profiler": { "command": "npx", "args": ["-y", "spark-profiler-mcp"] }
  }
}

Then ask: "Load this.sparkprofile and tell me what to tune." The assistant calls load_profile → diagnose → drills in.

From source (dev / unpublished)

npm install && npm run build
claude mcp add spark-profiler -- node /absolute/path/to/spark-profiler-mcp/dist/index.js

Tools

Tool	Purpose
`load_profile(source)`	Parse file/URL/key → `profileId` + headline.
`get_summary`	Version, TPS, MSPT, heap, GC%, entities, hot methods, top plugins, verdict.
`diagnose`	Ranked findings: evidence → diagnosis → action.
`get_platform_info`	Brand/version, plugins, config highlights (view/sim-distance, spawn limits).
`get_system_stats`	Host CPU/RAM/disk/OS, Java, JVM args (secrets redacted), GC, Aikar check.
`get_health`	TPS 1/5/15m, MSPT percentiles, ping, heap, per-minute time-series (`.sparkhealth`).
`get_world_stats`	Entities, top types, per-world totals, data packs, game rules.
`list_threads`	Sampled threads, busiest first.
`get_top_self_time`	Hottest methods by self time (idle/native excluded).
`get_sources_breakdown`	Self-time per plugin/mod.
`get_call_tree`	Pruned tree. `rootPath` jumps to any frame.
`search_call_tree`	Find frames by substring or `/regex/`.
`get_heap_summary`	`.sparkheap`: largest retained types.

Token-cheap by design. Outputs = summaries + top-N. Full call tree never dumped. Reach it via get_call_tree (depth + minPercent capped) and search_call_tree. Parsed once, cached by profileId.

How it reads spark files

Vendored proto/spark/*.proto (from lucko/spark) loaded at runtime by protobufjs: no codegen.
.sparkprofile = SamplerData. Each thread = flattened call tree: ThreadNode.children is a flat pool, children_refs rebuild it. Self time = node total − Σ children. Native/idle frames flagged so the active hot path shows.
vmArgs surfaced for JVM analysis. Credential-like -D props redacted.

Development

npm run dev        # run from source (tsx)
npm test           # vitest: decode example, check analysis + diagnosis
npm run smoke      # end-to-end over stdio
npm run inspector  # @modelcontextprotocol/inspector

Publishing (maintainer)

Releases are automated via GitHub Actions + npm Trusted Publishing (OIDC) — no npm token is stored anywhere. One-time setup on npmjs.com: the package → Settings → Trusted Publisher → GitHub Actions, with Organization Imanity-Software, Repository spark-profiler-mcp, Workflow publish.yml. Then to cut a release:

# bump "version" in package.json, then:
git tag v0.1.1 && git push origin v0.1.1

.github/workflows/publish.yml builds, tests, and runs npm publish authenticated by OIDC, with provenance generated automatically. (Needs Node ≥ 22.14 + npm ≥ 11.5.1; the workflow upgrades npm itself.)

files ships only dist/ + proto/ (schemas are loaded at runtime, so they must be included); the 24 MB example and tests are excluded.

Manual fallback (no provenance): npm login && npm publish — prepublishOnly builds + tests first.

Prefer not to use npm at all? npx -y github:Imanity-Software/spark-profiler-mcp also works — the prepare hook builds it on install.