spark-profiler-mcp

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.

License

MIT. spark is © lucko, GPLv3. Only its .proto schemas are vendored here.