feat: add npm/npx distribution for codedb MCP usage

[idea404]

Goal

Enable users to configure codedb in MCP clients with npx for zero-install setup:

{
  "codedb": {
    "type": "local",
    "command": ["npx", "-y", "@justrach/codedb"],
    "args": ["mcp"],
    "enabled": true
  }
}

Rationale

Many MCP clients (opencode, Claude Code, Cursor) document local servers through npx, especially for zero-install setup. codedb is currently a native Zig binary, which requires users to install it manually and hardcode an absolute binary path in their MCP config.

An npm package can be a thin JS launcher around the native binary. It does not require rewriting codedb in JavaScript.

Requirements

• Publish @justrach/codedb with a bin entry named codedb
• JS wrapper must preserve:
  • process.cwd()
  • stdio (stdout reserved for JSON-RPC in MCP mode)
  • args
  • environment
• Wrapper must not write logs to stdout before MCP starts
• Provide platform binaries through either:
  • optional platform packages (preferred — @justrach/codedb-darwin-arm64, etc.)
  • or postinstall download from GitHub Releases
• Keep version aligned with codedb release version

Suggested layout

npm/
  package.json
  bin/
    codedb.js        # thin launcher, execs native binary
  postinstall.js     # or rely on optionalDependencies

Platform packages approach (recommended)

Top-level package.json:

{
  "name": "@justrach/codedb",
  "version": "0.2.5820",
  "bin": { "codedb": "./bin/codedb.js" },
  "optionalDependencies": {
    "@justrach/codedb-darwin-arm64": "0.2.5820",
    "@justrach/codedb-darwin-x64": "0.2.5820",
    "@justrach/codedb-linux-x64": "0.2.5820",
    "@justrach/codedb-linux-arm64": "0.2.5820"
  }
}

Launcher (bin/codedb.js)

#!/usr/bin/env node
const { spawnSync } = require("node:child_process");
const path = require("node:path");

const exe = process.platform === "win32" ? "codedb.exe" : "codedb";
const bin = path.join(__dirname, "..", "vendor", `${process.platform}-${process.arch}`, exe);

const result = spawnSync(bin, process.argv.slice(2), {
  stdio: "inherit",
  cwd: process.cwd(),
  env: process.env
});
process.exit(result.status ?? 1);

Acceptance criteria

1. This works from any directory:

   npx -y @justrach/codedb mcp

2. This works in opencode/Claude Code MCP config:

   {
     "codedb": {
       "type": "local",
       "command": ["npx", "-y", "@justrach/codedb"],
       "args": ["mcp"],
       "enabled": true
     }
   }

3. codedb_status reports files from the current repo, not the npm cache directory

Scope estimate

Size	Conditions
Small	GitHub Actions already builds per-platform release binaries, maintainer has npm org access, package name available, no Windows initially
Medium	Need release asset naming convention, npm workspace setup, CI publish workflow, multi-platform optional packages
Large	Need full cross-platform binary build pipeline, signing/checksums, installer migration

Notes

• This is a packaging/distribution feature, not a code change to the Zig server
• Keep separate from MCP behavior fixes (e.g. fix: robust MCP startup root resolution and deferred scan fallback #500)
• The hard part is reliable native binary distribution through npm, not MCP itself

[justrach]

Resolved. Published as codedeebee@0.2.5820 on npm — the bare codedb name is restricted by the npm registry (too similar to the existing code.db package), so we shipped under codedeebee. The CLI it installs is still called codedb.

Install

# zero-install via npx
npx -y codedeebee mcp

# or globally
npm install -g codedeebee
codedb mcp

MCP client config

{
  "codedb": {
    "type": "local",
    "command": ["npx", "-y", "codedeebee"],
    "args": ["mcp"],
    "enabled": true
  }
}

How it works

• Single npm package (codedeebee), no platform sub-packages for v1
• postinstall detects process.platform/process.arch, downloads the matching binary from the GitHub Release tagged v<package.json version>, verifies it against checksums.sha256, chmods +x
• bin/codedb.js is a thin spawnSync launcher — preserves cwd, stdio, args, env
• Stdout stays pure JSON-RPC for MCP; info logs go to stderr

Verified end-to-end:

• npx -y codedeebee mcp from a cold sandbox → binary downloaded + verified → MCP initialize handshake → tools/list returns all 22 codedb tools

Supported: macOS arm64 / x64, Linux arm64 / x64. Windows not yet supported — open a follow-up if you need it.

Source: npm/ directory in this repo.