bug: heimdall-ledger MCP fails (-32000) — relative path in .mcp.json resolves to project cwd

[SuperMadhavan]

Summary

The heimdall-ledger MCP server fails to start with JSON-RPC error -32000. Root cause: .mcp.json declares the server with a relative args path that resolves against the user's project cwd instead of the plugin root.

Steps to reproduce

1. Install the Heimdall plugin.
2. Open a Claude Code session in any project dir other than the plugin root (e.g. /Users/me/code).
3. Run /doctor or /mcp.
4. Observe plugin:hmd:heimdall-ledger failed to connect; reconnect returns -32000.

Expected behavior

The heimdall-ledger MCP server connects regardless of the session's working directory.

Actual behavior

Claude launches the MCP with cwd = the project dir, not the plugin root. The relative arg bin/heimdall-ledger-mcp resolves to <project>/bin/heimdall-ledger-mcp, which does not exist:

python3 can't open file '<project>/bin/heimdall-ledger-mcp': [Errno 2] No such file or directory

claude mcp list does not list the server at all; /mcp reconnect returns Failed to reconnect to plugin:hmd:heimdall-ledger: -32000.

The current .mcp.json:

{
  "mcpServers": {
    "heimdall-ledger": {
      "command": "python3",
      "args": ["bin/heimdall-ledger-mcp"],
      "env": {}
    }
  }
}

Fix

Use the plugin-root variable (Claude Code expands ${CLAUDE_PLUGIN_ROOT} for plugin MCP servers — the bundled claude-mem MCP relies on process.env.CLAUDE_PLUGIN_ROOT the same way):

"args": ["${CLAUDE_PLUGIN_ROOT}/bin/heimdall-ledger-mcp"]

Verified locally: with CLAUDE_PLUGIN_ROOT set and cwd = project dir, the server returns a clean initialize handshake (6 ledger tools, exit 0).

Additional context

Failure also gets cached in ~/.claude/mcp-needs-auth-cache.json (alongside OAuth servers), adding a 15-min backoff — but that's a symptom; clearing the cache does not fix it since reconnect already bypasses the cache and still hits -32000.

---

Environment

• Plugin: randomittin/superx @ cd03302 (branch main)
• OS: Darwin 25.4.0 (arm64)
• Claude Code: 2.1.177 (Claude Code)
• Session: unknown
• Reported: 2026-06-15T07:43:41Z

Recent plugin commits

cd03302 release: sync artifacts to v2.0.1
321d157 merge(install): guard unset vars under set -u — stranger-env clean install reaches success card
b76b864 fix(install): guard unset vars under set -u — stranger-env clean install reaches success card
3c289b7 merge(statusline): dense symbolic instrument — eyes·phase·gates·token-gauge, four-color
1f5e6b7 feat(statusline): dense symbolic instrument — eyes·phase·gates·token-gauge, four-color

Files modified in cwd (/Users/Madhavan_1/code)

 M livekit-agent-app
 M my-livekit-app
 M schedular
 M super-analytics
 M super-checkout
 M super-websockets
 M superback
 M tatatele