bantamkit-mcp 0.28.0 → 0.29.1

package/README.md

@@ -40,7 +40,28 @@ float* below — it is the failure this package makes easiest to hit and hardest
 
 ### Connect it to a host
 
-Every host below runs the same command; only the file and the key around it change.
+**One command, and it writes the entry for you:**
+
+```bash
+npx -y bantamkit-mcp --install claude          # Claude Code
+npx -y bantamkit-mcp --install claude-desktop  # Claude Desktop
+npx -y bantamkit-mcp --install copilot         # GitHub Copilot in VS Code
+npx -y bantamkit-mcp --install cursor          # Cursor
+```
+
+`--install claude` runs `claude mcp add` rather than editing `~/.claude.json` directly:
+that file is the host's, and it carries state that is not MCP configuration. What happens on
+a second run there is Claude Code's decision, not this command's, and `--force` does not
+reach it.
+
+**For the other three**, which are edited directly: it never prompts. A second run that
+finds its own entry says so and changes nothing; an entry that differs is refused, printed
+beside the one it would write, and replaced only with `--force`. Every write backs the file
+up first as `<name>.backup-<date>`, preserves the file's permissions, and a file that does
+not parse is refused rather than replaced.
+
+The rest of this section is what those commands write, for anyone who would rather do it by
+hand. Every host runs the same command; only the file and the key around it change.
 
 **Claude Code** — one command, no file to edit. `-s user` makes it available in every
 project; drop it for this project only.

package/dist/cli.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { type Host } from './hostinstall.js';
 export interface Options {
     k: number;
     indexBudget: number;
@@ -7,6 +8,8 @@ export interface Options {
     assetsRoot: boolean;
     mcpReport: boolean;
     statusline: boolean;
+    install: Host | null;
+    force: boolean;
 }
 /** `_parse_args`, arm for arm, including the mutually exclusive group and `-h`. */
 export declare function parseArgs(argv: readonly string[]): Options;

package/dist/cli.js

@@ -60,7 +60,9 @@ import { DEFAULT_INDEX_BUDGET } from './memory/store.js';
 import { packFileCount } from './mcp/identity.js';
 import { buildServer } from './mcp/server.js';
 import { RawStdioTransport } from './mcp/transport.js';
-import { ArgvError, formatHelp, formatUsageBlock, HelpRequested, helpWidth, parseArgs as parseWithSpec, pyIntStrict, } from './pyargparse.js';
+import { ArgumentTypeError, ArgvError, formatHelp, formatUsageBlock, HelpRequested, helpWidth, parseArgs as parseWithSpec, pyIntStrict, } from './pyargparse.js';
+import { pyRepr } from './memory/pyfs.js';
+import { HOSTS, install as installHost, InstallError, thisCommand } from './hostinstall.js';
 import { statusLine } from './statusline.js';
 /** `SystemExit("...")`: the message on stderr, exit 1. */
 class Refusal extends Error {
@@ -151,6 +153,40 @@ const PARSER = {
             help: 'print one status line for a host status bar, then exit',
             defaultValue: false,
         },
+        // THE SAME PLACE AND THE SAME REASON AS THE TWO ABOVE, and the position is copied from
+        // the reference rather than chosen: argparse prints optionals in registration order, so
+        // this line decides where `[--install {...}]` sits in the generated usage. After
+        // `--statusline` leaves the FIRST line of the 80-column usage — pinned by the `cli`
+        // conformance suite — byte-identical.
+        //
+        // `choices` is NOT ported for ordinary options (see pyargparse.ts's not-ported list), and
+        // porting it for one flag would be a feature grown to serve a caller. The two things
+        // `choices` is visible through are reproduced directly instead: the metavar argparse
+        // builds, spelled out here, and the invalid-value sentence, thrown as an
+        // `ArgumentTypeError` so it prints VERBATIM after `argument --install: ` exactly as
+        // `_check_value` does.
+        {
+            optionStrings: ['--install'],
+            dest: 'install',
+            metavar: `{${HOSTS.join(',')}}`,
+            kind: 'store',
+            help: "wire this server into a host's MCP configuration, then exit",
+            convert: (raw) => {
+                if (!HOSTS.includes(raw)) {
+                    throw new ArgumentTypeError(`invalid choice: ${pyRepr(raw)} (choose from ${HOSTS.join(', ')})`);
+                }
+                return raw;
+            },
+            typeName: 'str',
+            defaultValue: null,
+        },
+        {
+            optionStrings: ['--force'],
+            dest: 'force',
+            kind: 'storeTrue',
+            help: 'with --install, replace an existing bantamkit entry',
+            defaultValue: false,
+        },
         {
             optionStrings: ['--store'],
             dest: 'store',
@@ -166,7 +202,10 @@ const PARSER = {
             defaultValue: null,
         },
     ],
-    groups: [[6, 7]],
+    // `--store`/`--start` moved from 6/7 to 8/9 when `--install` and `--force` were added
+    // ahead of them. These are POSITIONS, not names, so adding an action above the group and
+    // leaving this line alone would silently make two unrelated flags mutually exclusive.
+    groups: [[8, 9]],
 };
 /** `_parse_args`, arm for arm, including the mutually exclusive group and `-h`. */
 export function parseArgs(argv) {
@@ -179,6 +218,8 @@ export function parseArgs(argv) {
         assetsRoot: values['assets_root'],
         mcpReport: values['mcp_report'],
         statusline: values['statusline'],
+        install: values['install'],
+        force: values['force'],
     };
 }
 /** `_build_memory`, including the two refusals argparse cannot express. */
@@ -236,6 +277,29 @@ async function main(argv) {
         process.stdout.write(`${statusLine(process.env, options.store, options.start)}\n`);
         return 0;
     }
+    // ORDER IS OBSERVABLE, and it is the reference's order. `main` in `mcpserver.py` checks
+    // assets_root, then mcp_report, then statusline, then install, then force — so
+    // `--mcp-report --install cursor` prints a report and writes NOTHING. Dispatching install
+    // earlier here made the same argv write a file on one runtime and not the other: one
+    // command line, two different states on the user's disk. Reviewed and moved.
+    if (options.install !== null && options.install !== undefined) {
+        // Before any store or transport exists, the shape `--assets-root` established.
+        const { command, args } = thisCommand();
+        try {
+            process.stdout.write(`${installHost(options.install, command, args, options.force)}\n`);
+        }
+        catch (e) {
+            if (!(e instanceof InstallError))
+                throw e;
+            process.stderr.write(`error: ${e.message}\n`);
+            return 1;
+        }
+        return 0;
+    }
+    // `--force` alone is a typo with a plausible reading — somebody meant to install and
+    // dropped the flag that says where. Refusing names the missing half.
+    if (options.force)
+        throw new Refusal('--force is only meaningful with --install');
     const memory = buildMemory(options);
     const wire = new RawStdioTransport();
     const server = buildServer(memory, wire, version());

package/dist/hostinstall.d.ts

@@ -0,0 +1,36 @@
+/** The four hosts, in the order they print in `--help`. */
+export declare const HOSTS: readonly ["claude", "claude-desktop", "copilot", "cursor"];
+export type Host = (typeof HOSTS)[number];
+/** The entry name written into every host. */
+export declare const ENTRY = "bantamkit";
+/** A refusal, carrying the sentence the operator should read. Never a stack. */
+export declare class InstallError extends Error {
+}
+/**
+ * The file `--install <host>` would write, on THIS platform.
+ *
+ * Resolved from `homedir()` and `APPDATA` and nothing else — point `HOME`/`USERPROFILE` at a
+ * temporary directory and every path moves with it, which is what makes the tests possible.
+ *
+ * `claude` has no entry here: its arm shells out to `claude mcp add` and never names a path.
+ */
+export declare function hostConfigPath(host: Host): string;
+/** `servers` in VS Code, `mcpServers` everywhere else — the word that silently loses entries. */
+export declare function configKey(host: Host): string;
+/** The server entry, in the shape the host expects. `type` only where the host documents it. */
+export declare function entryFor(host: Host, command: string, args: string[]): Record<string, unknown>;
+/** Register this server with `host`. Returns the report to print; throws `InstallError`. */
+export declare function install(host: Host, command: string, args: string[], force?: boolean): string;
+/**
+ * What a host should run to get THIS server.
+ *
+ * `npx -y bantamkit-mcp` and not this process's own path, and the two are not the same
+ * thing: a global install, an `npx` cache entry and a checkout all have different paths,
+ * while the published name resolves the same everywhere. `-y` because `npx` historically
+ * prompts before installing a package it has not seen, and stdin here is the JSON-RPC
+ * channel — a prompt that ate one frame would look like a server that lost a request.
+ */
+export declare function thisCommand(): {
+    command: string;
+    args: string[];
+};

package/dist/hostinstall.js

@@ -0,0 +1,247 @@
+/**
+ * Wire this server into an MCP host's configuration — `--install <host>`.
+ *
+ * The Node half of `runtime-py/src/bantamkit/hostinstall.py`, sentence for sentence. Read
+ * that file for WHY each decision is what it is; this header records only what porting it
+ * cost.
+ *
+ * EVERY OPERATOR-VISIBLE STRING IS COMPARED BYTE FOR BYTE against the reference, so two
+ * things that look like implementation detail are not:
+ *
+ *   1. The JSON in the conflict message goes through `dumpJson(fromJs(...), {sortKeys})`,
+ *      never `JSON.stringify`. Python writes `{"args": [], "command": "OLD"}` and
+ *      `JSON.stringify` writes `{"args":[],"command":"OLD"}` — same object, different
+ *      bytes, and the separators are the whole difference.
+ *   2. The file is written with the same helper at `indent: 2`, which also reproduces
+ *      `ensure_ascii`. A home directory with a non-ASCII name would otherwise make the two
+ *      runtimes write different bytes for the same install.
+ *
+ * WHAT IS RULED DIFFERENT, and it is one field: the COMMAND. This side records
+ * `npx -y bantamkit-mcp`; the reference records its own console script. The thing installed
+ * should be the thing that answers, and neither side should send a host looking for the
+ * other's runtime. `docs/porting.md` carries the row.
+ */
+import { spawnSync } from 'node:child_process';
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { dumpJson, fromJs } from './pyjson.js';
+/** The four hosts, in the order they print in `--help`. */
+export const HOSTS = ['claude', 'claude-desktop', 'copilot', 'cursor'];
+/** The entry name written into every host. */
+export const ENTRY = 'bantamkit';
+/** A refusal, carrying the sentence the operator should read. Never a stack. */
+export class InstallError extends Error {
+}
+const dumps = (value, indent = null, sortKeys = false) => dumpJson(fromJs(value), { indent, sortKeys });
+/**
+ * The file `--install <host>` would write, on THIS platform.
+ *
+ * Resolved from `homedir()` and `APPDATA` and nothing else — point `HOME`/`USERPROFILE` at a
+ * temporary directory and every path moves with it, which is what makes the tests possible.
+ *
+ * `claude` has no entry here: its arm shells out to `claude mcp add` and never names a path.
+ */
+export function hostConfigPath(host) {
+    const home = homedir();
+    const appdata = process.env.APPDATA;
+    const roaming = appdata !== undefined && appdata !== '' ? appdata : join(home, 'AppData', 'Roaming');
+    if (host === 'claude-desktop') {
+        if (process.platform === 'darwin') {
+            return join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+        }
+        if (process.platform === 'win32')
+            return join(roaming, 'Claude', 'claude_desktop_config.json');
+        return join(home, '.config', 'Claude', 'claude_desktop_config.json');
+    }
+    if (host === 'copilot') {
+        if (process.platform === 'darwin') {
+            return join(home, 'Library', 'Application Support', 'Code', 'User', 'mcp.json');
+        }
+        if (process.platform === 'win32')
+            return join(roaming, 'Code', 'User', 'mcp.json');
+        return join(home, '.config', 'Code', 'User', 'mcp.json');
+    }
+    if (host === 'cursor')
+        return join(home, '.cursor', 'mcp.json');
+    throw new InstallError(`no configuration file is written for ${host}`);
+}
+/** `servers` in VS Code, `mcpServers` everywhere else — the word that silently loses entries. */
+export function configKey(host) {
+    return host === 'copilot' ? 'servers' : 'mcpServers';
+}
+/** The server entry, in the shape the host expects. `type` only where the host documents it. */
+export function entryFor(host, command, args) {
+    return host === 'copilot'
+        ? { type: 'stdio', command, args: [...args] }
+        : { command, args: [...args] };
+}
+/**
+ * `type(x).__name__` for the values `json.loads` can return.
+ *
+ * The reference prints CPython's type name and this sentence is compared byte for byte, so
+ * `typeof` is wrong in five of the six cases: `string`/`str`, `number`/`int`, `boolean`/`bool`.
+ * The first version of this translated only `list` and `NoneType` — and both unit tests used
+ * `[1, 2, 3]`, the ONE input where the two vocabularies happen to agree, so neither suite
+ * could see it. Review measured `"hello"` and `5`.
+ *
+ * `int` vs `float` follows `json`'s own split: a JSON number with no fraction and no exponent
+ * is decoded by `int`, everything else by `float`.
+ */
+function pyTypeName(value) {
+    if (value === null)
+        return 'NoneType';
+    if (Array.isArray(value))
+        return 'list';
+    if (typeof value === 'string')
+        return 'str';
+    if (typeof value === 'boolean')
+        return 'bool';
+    if (typeof value === 'number')
+        return Number.isInteger(value) ? 'int' : 'float';
+    return typeof value;
+}
+function readConfig(path) {
+    if (!existsSync(path))
+        return {};
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (e) {
+        throw new InstallError(`cannot read ${path}: ${e.message}`);
+    }
+    if (text.trim() === '')
+        return {};
+    let loaded;
+    try {
+        loaded = JSON.parse(text);
+    }
+    catch (e) {
+        // The reference reports CPython's message, line and column. `JSON.parse` gives neither
+        // the same wording nor a position, so this is a RULED difference rather than a silent
+        // one: both refuse, both name the file, and the reason after the colon differs.
+        throw new InstallError(`${path} is not valid JSON, so this refuses to touch it: ${e.message}`);
+    }
+    if (loaded === null || typeof loaded !== 'object' || Array.isArray(loaded)) {
+        throw new InstallError(`${path} holds ${pyTypeName(loaded)}, not an object; refusing to touch it`);
+    }
+    return loaded;
+}
+function writeConfig(path, data) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.bantamkit-tmp`;
+    // The mode of the file being replaced, carried onto its replacement. A host config holds
+    // API keys in per-server `env` blocks, and a user who chmod'ed theirs to 0600 had it come
+    // back 0644, because a fresh temp file gets the process umask. Measured on both runtimes
+    // before this line existed.
+    const mode = existsSync(path) ? statSync(path).mode & 0o7777 : null;
+    try {
+        writeFileSync(tmp, `${dumps(data, 2)}\n`, 'utf8');
+        if (mode !== null)
+            chmodSync(tmp, mode);
+        renameSync(tmp, path);
+    }
+    catch (e) {
+        rmSync(tmp, { force: true });
+        throw new InstallError(`cannot write ${path}: ${e.message}`);
+    }
+}
+/** `date.today().isoformat()` — the LOCAL date, which is what the reference takes. */
+function today() {
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+function backup(path) {
+    if (!existsSync(path))
+        return null;
+    const target = `${path}.backup-${today()}`;
+    try {
+        copyFileSync(path, target);
+    }
+    catch (e) {
+        throw new InstallError(`cannot back up ${path}: ${e.message}`);
+    }
+    return target;
+}
+function installViaClaudeCli(command, args) {
+    const argv = ['mcp', 'add', ENTRY, '-s', 'user', '--', command, ...args];
+    // `shell: true` ON WINDOWS ONLY. An npm-installed `claude` is a `claude.cmd` shim, and
+    // `spawnSync` refuses to launch a batch file without a shell — it returns ENOENT, which
+    // this function would report as "not on PATH", the one message guaranteed to send someone
+    // looking in the wrong place. The reference has no such problem: `shutil.which` honours
+    // PATHEXT and `CreateProcess` runs the shim. Arguments are quoted because `shell: true`
+    // hands the string to `cmd.exe`, and a path with a space is the normal case on Windows.
+    const win = process.platform === 'win32';
+    const quoted = win ? argv.map((a) => (/[\s"^&|<>]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a)) : argv;
+    const done = spawnSync('claude', quoted, { encoding: 'utf8', shell: win });
+    if (done.error) {
+        const code = done.error.code;
+        if (code === 'ENOENT') {
+            throw new InstallError('the `claude` command is not on PATH, so this cannot register with Claude Code. ' +
+                'Install Claude Code, or add the entry by hand — `docs/install.md` gives the shape.');
+        }
+        throw new InstallError(`could not run claude: ${done.error.message}`);
+    }
+    if (done.status !== 0) {
+        const detail = (done.stderr || done.stdout || '').trim();
+        throw new InstallError(`\`claude mcp add\` failed (exit ${done.status})${detail ? `\n${detail}` : ''}`);
+    }
+    return argv;
+}
+/** Register this server with `host`. Returns the report to print; throws `InstallError`. */
+export function install(host, command, args, force = false) {
+    if (!HOSTS.includes(host)) {
+        throw new InstallError(`unknown host '${host}'; choose one of: ${HOSTS.join(', ')}`);
+    }
+    if (host === 'claude') {
+        const argv = installViaClaudeCli(command, args);
+        return `installed bantamkit into claude\n  ran    : claude ${argv.join(' ')}`;
+    }
+    const path = hostConfigPath(host);
+    const key = configKey(host);
+    const wanted = entryFor(host, command, args);
+    const data = readConfig(path);
+    const raw = data[key];
+    if (raw !== undefined && (raw === null || typeof raw !== 'object' || Array.isArray(raw))) {
+        throw new InstallError(`${path} has a '${key}' that is not an object; refusing to touch it`);
+    }
+    const servers = (raw ?? {});
+    const existing = servers[ENTRY];
+    if (existing !== undefined && dumps(existing, null, true) === dumps(wanted, null, true)) {
+        return `bantamkit is already installed in ${host} and matches\n  file   : ${path}`;
+    }
+    if (existing !== undefined && !force) {
+        throw new InstallError(`${host} already has a bantamkit entry with different settings\n` +
+            `  file    : ${path}\n` +
+            `  current : ${dumps(existing, null, true)}\n` +
+            `  proposed: ${dumps(wanted, null, true)}\n` +
+            '  re-run with --force to replace it');
+    }
+    const copied = backup(path);
+    servers[ENTRY] = wanted;
+    data[key] = servers;
+    writeConfig(path, data);
+    const lines = [
+        `installed bantamkit into ${host}`,
+        `  file   : ${path}`,
+        `  key    : ${key}`,
+        `  command: ${command} ${args.join(' ')}`.replace(/\s+$/, ''),
+    ];
+    if (copied !== null)
+        lines.push(`  backup : ${copied}`);
+    return lines.join('\n');
+}
+/**
+ * What a host should run to get THIS server.
+ *
+ * `npx -y bantamkit-mcp` and not this process's own path, and the two are not the same
+ * thing: a global install, an `npx` cache entry and a checkout all have different paths,
+ * while the published name resolves the same everywhere. `-y` because `npx` historically
+ * prompts before installing a package it has not seen, and stdin here is the JSON-RPC
+ * channel — a prompt that ate one frame would look like a server that lost a request.
+ */
+export function thisCommand() {
+    return { command: 'npx', args: ['-y', 'bantamkit-mcp'] };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bantamkit-mcp",
-  "version": "0.28.0",
+  "version": "0.29.1",
   "description": "bantamkit MCP server — pure Node, runnable with npx",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "assets"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",