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

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.

Related MCP server: javaperf

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

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.