@munhq/codeindex 0.3.2

package/README.md

@@ -0,0 +1,67 @@
+# @munhq/codeindex
+
+Structural code intelligence for AI coding agents, as an MCP server. It answers
+"where is X defined", "show me this function", "what calls it" and "what breaks
+if I change this file" in tens of tokens, instead of the ~1,563 a file read
+costs. tree-sitter across 40+ languages, 16 MCP tools, MIT.
+
+```
+npx -y @munhq/codeindex
+```
+
+No account, no API key, no configuration.
+
+## Add it to a client
+
+Claude Code:
+
+```
+claude mcp add codeindex -- npx -y @munhq/codeindex
+```
+
+Anything that reads a JSON config (Claude Desktop, Cursor, Windsurf, Zed, Cline):
+
+```json
+{
+  "mcpServers": {
+    "codeindex": {
+      "command": "npx",
+      "args": ["-y", "@munhq/codeindex"]
+    }
+  }
+}
+```
+
+## Why this is an npm package when the server is not JavaScript
+
+codeindex is a statically linked binary — no runtime, no node_modules, about
+53 MB per platform. This package is a 4 KB wrapper: on install it resolves the
+release asset for your platform, verifies it against the `SHA256SUMS` published
+beside it, caches it under `~/.cache/codeindex/bin/codeindex-<version>`, and
+executes it. Six platforms are covered: linux and macOS on x86_64 and arm64,
+Windows on x86_64 and arm64.
+
+The cache key carries the version on purpose. An unversioned cache silently keeps
+running an old binary after an upgrade, which is a bug this project has already
+paid for once.
+
+`CODEINDEX_BIN` overrides everything, for a local build. `PATH` is deliberately
+*not* searched: this package declares one version to the MCP registry, and
+running whatever `codeindex` happens to be on `PATH` would make that a lie.
+
+## What the tools cost
+
+| tool | tokens per call |
+|---|---|
+| `Read` (for comparison) | 1,563 |
+| `get_outline` | 113 |
+| `find_symbol` | 102 |
+| `search` | 79 |
+| `find_word` | 41 |
+| `read_symbol` | **35** |
+
+## Everything else
+
+Source, the other install paths (`curl \| bash`, a Claude Code plugin with the
+skill, a prebuilt binary), the 16 tools and the 16 analyses:
+**https://github.com/munhq/codeindex**

package/bin/codeindex-mcp.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// The MCP server entry point: resolve the binary, then become it.
+//
+// `npx -y @munhq/codeindex` lands here. Every argument is passed straight
+// through, so `--workspace`, `--mcp` and anything the server grows later work
+// without this file knowing about them.
+'use strict';
+
+const { spawnSync } = require('child_process');
+const { resolveBinary, log } = require('./resolve.js');
+
+(async () => {
+  let bin;
+  try {
+    bin = await resolveBinary();
+  } catch (err) {
+    log(`could not start: ${err.message}`);
+    process.exit(1);
+  }
+
+  // The client speaks JSON-RPC over this process's stdio, so the child inherits
+  // all three streams untouched. No pipe, no buffering, no wrapper protocol.
+  const args = process.argv.slice(2);
+  // `--mcp` is what the server needs to speak MCP at all. A client that
+  // launches the bin with no arguments gets the CLI's help text on stdout and a
+  // handshake that never completes, which reads as "the server is broken".
+  if (!args.includes('--mcp')) args.unshift('--mcp');
+
+  const res = spawnSync(bin, args, { stdio: 'inherit' });
+  if (res.error) {
+    log(`failed to exec ${bin}: ${res.error.message}`);
+    process.exit(1);
+  }
+  // Relay the child's fate exactly: a signal death must not look like exit 0.
+  if (res.signal) process.kill(process.pid, res.signal);
+  process.exit(res.status === null ? 1 : res.status);
+})();

package/bin/postinstall.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Fetch the binary at install time, so the first MCP handshake does not wait for
+// a 53 MB download and time out inside the client.
+//
+// This is allowed to fail. A CI sandbox with no network, or `npm install
+// --ignore-scripts`, must still produce a working install — codeindex-mcp.js
+// downloads on demand when the cache is empty. So the exit code is always 0 and
+// the reason goes to stderr, where it is visible rather than swallowed.
+'use strict';
+
+const { resolveBinary, log } = require('./resolve.js');
+
+resolveBinary()
+  .then(() => process.exit(0))
+  .catch((err) => {
+    log(`prefetch skipped: ${err.message}`);
+    log('the binary will be fetched on first run instead');
+    process.exit(0);
+  });

package/bin/resolve.js

@@ -0,0 +1,135 @@
+// Resolve a codeindex binary for this platform, downloading the pinned release
+// asset when the cache does not already hold it.
+//
+// Why an npm package at all, for a program that is not JavaScript: every MCP
+// directory installs servers the way npm installs them. The official registry
+// validates an npm version, Smithery runs `npx`, and mcp.so lists the same
+// command. A compiled server with no npm name is invisible to all three, so this
+// package is the thin shim that makes `npx -y @munhq/codeindex` work — about
+// 4 KB of JavaScript that fetches the 53 MB binary the release already publishes.
+//
+// Write NOTHING to stdout. Stdout is the MCP JSON-RPC channel; one stray line
+// there makes the server look broken with no error that explains why. Every
+// diagnostic goes to stderr, which the client logs.
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const https = require('https');
+const crypto = require('crypto');
+
+const REPO = 'munhq/codeindex';
+const { version: VERSION } = require('../package.json');
+
+const log = (msg) => process.stderr.write(`codeindex: ${msg}\n`);
+
+// Map Node's platform/arch onto the asset names the release actually publishes.
+// The release matrix builds Zig target triples — x86_64-linux, aarch64-linux,
+// x86_64-macos, aarch64-macos, x86_64-windows, aarch64-windows — and Node agrees
+// with none of them: process.platform says darwin/win32, process.arch says x64.
+// The shell launcher had this exact bug against uname and every Mac 404'd, so
+// the mapping is spelled out rather than assembled from the raw values.
+// Pure, so plugin/test_platform.sh can drive it for every platform this package
+// claims to support instead of only the one the test runs on. That test already
+// holds install.sh and the shell launcher to the release matrix; this is the
+// third consumer of the same naming and it drifts the same way.
+function assetFor(platform, arch) {
+  const a = { x64: 'x86_64', arm64: 'aarch64' }[arch];
+  const p = { linux: 'linux', darwin: 'macos', win32: 'windows' }[platform];
+  if (!a || !p) return null;
+  return `codeindex-${a}-${p}${p === 'windows' ? '.exe' : ''}`;
+}
+
+function assetName() {
+  return assetFor(process.platform, process.arch);
+}
+
+function cacheDir() {
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+  return path.join(base, 'codeindex', 'bin');
+}
+
+// The cached file carries the version. The shell launcher caches an unversioned
+// `codeindex`, and this repo has already been bitten by that shape: a 0.3.0
+// plugin ran a 0.2.0 binary found first on PATH for days, with both halves
+// reporting their own version and nobody comparing them. A version in the name
+// makes an upgrade a cache miss instead of a silent downgrade.
+function cachedBinary() {
+  const exe = process.platform === 'win32' ? '.exe' : '';
+  return path.join(cacheDir(), `codeindex-${VERSION}${exe}`);
+}
+
+function get(url, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    if (redirects > 5) return reject(new Error(`too many redirects for ${url}`));
+    https
+      .get(url, { headers: { 'user-agent': `codeindex-npm/${VERSION}` } }, (res) => {
+        // GitHub serves release assets as a redirect to object storage.
+        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+          res.resume();
+          return resolve(get(res.headers.location, redirects + 1));
+        }
+        if (res.statusCode !== 200) {
+          res.resume();
+          return reject(new Error(`GET ${url} -> HTTP ${res.statusCode}`));
+        }
+        const chunks = [];
+        res.on('data', (c) => chunks.push(c));
+        res.on('end', () => resolve(Buffer.concat(chunks)));
+        res.on('error', reject);
+      })
+      .on('error', reject);
+  });
+}
+
+// The checksum published beside the binary is not proof on its own — whoever can
+// replace one can replace the other. It is here to catch a truncated download
+// and a mismatched tag, which are the failures that actually happen, and to make
+// the pin auditable: both files come from the tag this package version names.
+async function verifiedDownload(asset) {
+  const base = `https://github.com/${REPO}/releases/download/v${VERSION}`;
+  log(`fetching ${asset} for v${VERSION} (about 53 MB, once per version)`);
+
+  const sums = (await get(`${base}/SHA256SUMS`)).toString('utf8');
+  const line = sums.split('\n').find((l) => l.trim().endsWith(` ${asset}`));
+  if (!line) throw new Error(`SHA256SUMS for v${VERSION} does not list ${asset}`);
+  const want = line.trim().split(/\s+/)[0];
+
+  const body = await get(`${base}/${asset}`);
+  const got = crypto.createHash('sha256').update(body).digest('hex');
+  if (got !== want) throw new Error(`checksum mismatch for ${asset}: want ${want}, got ${got}`);
+
+  const dest = cachedBinary();
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  // Write then rename, so a killed download never leaves a half file that the
+  // next run treats as installed.
+  const tmp = `${dest}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, body, { mode: 0o755 });
+  fs.renameSync(tmp, dest);
+  log(`installed ${dest}`);
+  return dest;
+}
+
+// An explicit override wins, for a local build or an unusual layout. PATH is
+// deliberately NOT consulted: this package declares one version to the registry,
+// and running whatever `codeindex` happens to be on PATH would make that
+// declaration a lie.
+async function resolveBinary() {
+  const override = process.env.CODEINDEX_BIN;
+  if (override && fs.existsSync(override)) return override;
+
+  const cached = cachedBinary();
+  if (fs.existsSync(cached)) return cached;
+
+  const asset = assetName();
+  if (!asset) {
+    throw new Error(
+      `no release build for ${process.platform}/${process.arch}. ` +
+        `Build from source: https://github.com/${REPO}#build-from-source`
+    );
+  }
+  return verifiedDownload(asset);
+}
+
+module.exports = { resolveBinary, cachedBinary, assetName, assetFor, VERSION, log };

package/bin/selftest.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// Print the asset this wrapper would fetch on every platform it claims to
+// support, one per line, as `platform<TAB>arch<TAB>asset`.
+//
+// Two consumers: `npm test`, which checks the table is complete and that the
+// package version looks like a release tag, and plugin/test_platform.sh, which
+// compares these names against the release matrix in
+// .github/workflows/release.yml. The shell launcher and install.sh are already
+// held to that matrix; this wrapper is the third place the same mapping is
+// written, and the Mac 404 it caused once is the reason all three are tested.
+'use strict';
+
+const { assetFor, VERSION } = require('./resolve.js');
+
+const SUPPORTED = [
+  ['linux', 'x64'],
+  ['linux', 'arm64'],
+  ['darwin', 'x64'],
+  ['darwin', 'arm64'],
+  ['win32', 'x64'],
+  ['win32', 'arm64'],
+];
+
+// Platforms with no release build must resolve to nothing rather than to a
+// plausible-looking name that 404s at download time.
+const UNSUPPORTED = [
+  ['freebsd', 'x64'],
+  ['linux', 'ia32'],
+  ['sunos', 'x64'],
+];
+
+let fail = 0;
+
+for (const [platform, arch] of SUPPORTED) {
+  const asset = assetFor(platform, arch);
+  if (!asset) {
+    process.stderr.write(`FAIL ${platform}/${arch} resolves to nothing\n`);
+    fail++;
+    continue;
+  }
+  process.stdout.write(`${platform}\t${arch}\t${asset}\n`);
+}
+
+for (const [platform, arch] of UNSUPPORTED) {
+  const asset = assetFor(platform, arch);
+  if (asset) {
+    process.stderr.write(`FAIL ${platform}/${arch} resolves to ${asset}, but no such build exists\n`);
+    fail++;
+  }
+}
+
+// The wrapper downloads from the tag named by its own version, so a version that
+// is not a plain release number can never find an asset.
+if (!/^\d+\.\d+\.\d+$/.test(VERSION)) {
+  process.stderr.write(`FAIL version ${VERSION} is not a release version, so v${VERSION} is not a tag\n`);
+  fail++;
+}
+
+if (fail) {
+  process.stderr.write(`\n${fail} problem(s)\n`);
+  process.exit(1);
+}
+process.stderr.write(`resolver: ${SUPPORTED.length} platforms, version ${VERSION}\n`);

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@munhq/codeindex",
+  "version": "0.3.2",
+  "description": "Structural code intelligence for AI coding agents over MCP: find a definition, read one function, see what calls a symbol, trace imports and judge a change's blast radius across 40+ languages \u2014 in tens of tokens instead of the ~1,563 a file read costs.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "code-intelligence",
+    "tree-sitter",
+    "ai-agents",
+    "claude",
+    "context-window"
+  ],
+  "homepage": "https://github.com/munhq/codeindex",
+  "bugs": "https://github.com/munhq/codeindex/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/munhq/codeindex.git"
+  },
+  "license": "MIT",
+  "bin": {
+    "codeindex-mcp": "bin/codeindex-mcp.js"
+  },
+  "scripts": {
+    "postinstall": "node bin/postinstall.js",
+    "test": "node bin/selftest.js"
+  },
+  "files": [
+    "bin/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}