cavemem mcp silent exit + install writes MCP config to wrong file

[patrickfiedler]

Bug Report: cavemem install writes MCP config to wrong file

Date: 2026-04-28
Environment: Claude Code 2.1.121, cavemem 0.1.0, Linux (CachyOS), Node.js 25.9.0

Context

While debugging why cavemem didn't appear in Claude Code's MCP list, two bugs were found. The first (silent exit of cavemem mcp) is already tracked in issue #3 and PR #16. This report covers the second, independent bug.

Symptom

After running cavemem install, cavemem does not appear in Claude Code's /mcp list. The command reports success:

✓ wrote /home/<USERNAME>/.claude/settings.json
cavemem is wired into claude-code

No error shown. claude mcp list shows cavemem absent.

Root Cause

cavemem install writes the mcpServers entry to ~/.claude/settings.json. Per the Claude Code MCP documentation, MCP server configuration must be in ~/.claude.json (home directory root) — not ~/.claude/settings.json. The mcpServers key in settings.json is silently ignored by Claude Code.

Claude Code MCP scopes (from official docs):

Scope	Stored in
Local (default)	~/.claude.json (under project path)
User	~/.claude.json
Project	.mcp.json in project root

Workaround

Register via the Claude Code CLI directly:

claude mcp add --scope user cavemem /usr/lib/node_modules/cavemem/dist/index.js mcp

Root Cause in Source

packages/installers/src/claude-code.ts, settingsFile():

function settingsFile(): string {
  return join(homedir(), '.claude', 'settings.json'); // ← wrong
}

Should be:

function settingsFile(): string {
  return join(homedir(), '.claude.json'); // ← correct
}

Note: hooks can stay in ~/.claude/settings.json — Claude Code reads hooks from there correctly. Only the mcpServers write needs to move to ~/.claude.json.

Note: even after applying the fix from PR #16 (so cavemem mcp starts correctly), the server still won't appear in Claude Code until this config file issue is also resolved.

Note 2: Bug report created with Claude Sonnet. I'm not a programmer.

[ralph-bergmann]

I'm having a similar issue with opencode.
The MCP config is being written to the wrong file and is also in the wrong format.
It should look something like this and must be saved in ~/.config/opencode/opencode.json.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cavemem": {
      "type": "local",
      "command": [
        "/opt/homebrew/bin/node",
        "/opt/homebrew/lib/node_modules/cavemem/dist/index.js",
        "mcp"
      ],
      "enabled": true
    }
  }
}

But even if it's configured correctly, opencode can't connect to the MCP:

❯ opencode mcp list

┌  MCP Servers
│
●  ✓ context7 connected
│      https://mcp.context7.com/mcp
│
●  ✗ cavemem failed
│      MCP error -32000: Connection closed
│      /opt/homebrew/bin/node /opt/homebrew/lib/node_modules/cavemem/dist/index.js mcp
│
└  2 server(s)

❯ cavemem status
cavemem status

settings:   /Users/ralph.bergmann/.cavemem/settings.json ✓
data dir:   /Users/ralph.bergmann/.cavemem
db:         /Users/ralph.bergmann/.cavemem/data.db ✓ (0 observations, 0 sessions)
ides:       opencode
embedding:  local / Xenova/all-MiniLM-L6-v2
backfill:   0 / 0 (0%)  last batch never
worker:     running (pid 41999, up 9s)  http://127.0.0.1:37777