bantamkit-mcp 0.26.0 → 0.28.0

package/README.md

@@ -38,6 +38,49 @@ than reading stdin, but that is version-dependent and `-y` costs nothing.
 machines can run different builds from one identical config line. See *Silent version
 float* below — it is the failure this package makes easiest to hit and hardest to see.
 
+### Connect it to a host
+
+Every host below 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.
+
+```bash
+claude mcp add bantamkit -s user -- npx -y bantamkit-mcp
+```
+
+**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`
+on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows. Top-level key
+`mcpServers`; each entry takes `command`, `args` and an optional `env`.
+
+```json
+{"mcpServers": {"bantamkit": {"command": "npx", "args": ["-y", "bantamkit-mcp"]}}}
+```
+
+**GitHub Copilot in VS Code** — `.vscode/mcp.json` for one workspace, or the user
+profile via the **MCP: Open User Configuration** command. Note the top-level key is
+`servers`, not `mcpServers`.
+
+```json
+{"servers": {"bantamkit": {"type": "stdio", "command": "npx", "args": ["-y", "bantamkit-mcp"]}}}
+```
+
+There is a CLI equivalent: `code --add-mcp '{"name":"bantamkit","command":"npx","args":["-y","bantamkit-mcp"]}'`.
+
+**Cursor** — `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` globally. Back
+to `mcpServers`.
+
+```json
+{"mcpServers": {"bantamkit": {"command": "npx", "args": ["-y", "bantamkit-mcp"]}}}
+```
+
+**Anything else that speaks MCP over stdio** runs `npx -y bantamkit-mcp` and talks
+JSON-RPC on its stdin and stdout. Nothing about this package is host-specific.
+
+The Claude Code and Claude Desktop forms were taken from this machine — `claude mcp add
+--help` and an existing config file. The VS Code and Cursor forms are from those
+projects' own documentation, not from a host installed here.
+
 ### Measured: what a cold start costs
 
 `node tools/conformance/npx-cold-start.mjs` in the repo packs the tarball, installs it

package/dist/cli.js

@@ -51,12 +51,13 @@
  * reaches for is answered on the wire instead, by `build_identity`. `runtime-ts/README.md`
  * and `docs/install.md` carry the same correction in their own words.
  */
-import { readFileSync, readdirSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { assetsRoot } from './assets.js';
 import { BantamError } from './errors.js';
 import { buildReport, resolveEventLogPath } from './mcpreport.js';
 import { Memory } from './memory/component.js';
 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';
@@ -207,12 +208,10 @@ async function main(argv) {
     const options = parseArgs(argv);
     if (options.assetsRoot) {
         const root = assetsRoot();
-        let files = 0;
-        for (const entry of readdirSync(root, { withFileTypes: true, recursive: true })) {
-            if (entry.isFile())
-                files += 1;
-        }
-        process.stdout.write(`${root}\n${files} files\n`);
+        // `packFileCount`, not a second walk: the count printed here and the count
+        // `build_identity` reports must be the same number for the same pack, and on a
+        // `pip install` the unfiltered version made one process contradict itself.
+        process.stdout.write(`${root}\n${packFileCount(root)} files\n`);
         return 0;
     }
     if (options.mcpReport) {

package/dist/mcp/identity.d.ts

@@ -10,10 +10,43 @@ export declare const SERVER_NAME = "bantamkit";
  * `as_posix()` is why the parts are joined with `/` here and not with `path.sep`: on Windows
  * the walk yields the same components and the digest must not change with the separator.
  */
-export declare function treeDigest(root: string): {
+export declare function treeDigest(root: string, keep?: (parts: string[]) => boolean): {
     digest: string;
     files: number;
 };
+/**
+ * Fingerprint the asset pack this build would load — every file, not just the loaded ones.
+ *
+ * `contracts/default.yaml` is the reason: `RB-P84` measured it as the one asset that differed
+ * between two live builds while no resource template exposed it, so it was invisible on every
+ * probed surface. It is also why N1 ships all 84 files rather than the 20 that are read.
+ *
+ * EXCEPT bytecode caches, and that exception is the whole point of this field. The pack ships
+ * `.py` fixture files, so `pip install` byte-compiles them into `__pycache__` on the way in and
+ * the digest of an INSTALLED Python pack stopped matching the digest of the identical npm pack
+ * — measured on the published 0.27.0 artifacts, `sha256:fa8372f6…` over 98 files against
+ * `sha256:d47dcf4b…` over 87, and deleting `__pycache__` from the wheel's pack reproduced the
+ * npm digest byte for byte. `cross_runtime` tells the caller to compare `assets_digest` across
+ * runtimes; without this rule that instruction returned a false "different" on every real
+ * install. The pack is what was SHIPPED, never what an interpreter later wrote beside it.
+ *
+ * The rule is spelled identically in `runtime-py`'s `_assets_fingerprint`, and it has to be:
+ * this side never creates a `__pycache__`, so a Node-only exclusion would still agree today
+ * and diverge again the moment a pack carrying one reached both runtimes.
+ */
+export declare const notBytecodeCache: (parts: string[]) => boolean;
+/**
+ * The pack as SHIPPED, counted — what `--assets-root` prints.
+ *
+ * Exported so the CLI shares this walk rather than keeping a second one. There are TWO
+ * walks over this directory and a rule spelled twice is a rule that gets fixed once: the
+ * first version of this fix filtered the digest alone, and a `pip install` then had one
+ * process contradicting itself, `build_identity` answering 87 files while `--assets-root`
+ * printed 98 for the pack it had just loaded. The CLI's own `readdirSync(recursive)` is
+ * gone with it — `walkFiles` is the walk that mirrors CPython's `rglob`, which is what the
+ * reference's printer uses and what the conformance case compares the count against.
+ */
+export declare function packFileCount(root: string): number;
 /** `sha256(json.dumps(inputs, sort_keys=True, separators=(",", ":")))` — the identity. */
 export declare function buildIdFor(inputs: Record<string, string>): string;
 /**

package/dist/mcp/identity.js

@@ -108,8 +108,9 @@ function walkFiles(root) {
  * `as_posix()` is why the parts are joined with `/` here and not with `path.sep`: on Windows
  * the walk yields the same components and the digest must not change with the separator.
  */
-export function treeDigest(root) {
-    const files = walkFiles(root);
+export function treeDigest(root, keep) {
+    const walked = walkFiles(root);
+    const files = keep === undefined ? walked : walked.filter(keep);
     const running = createHash('sha256');
     for (const parts of files) {
         const payload = readFileSync(join(root, ...parts));
@@ -164,7 +165,35 @@ function codeFingerprint() {
  * `contracts/default.yaml` is the reason: `RB-P84` measured it as the one asset that differed
  * between two live builds while no resource template exposed it, so it was invisible on every
  * probed surface. It is also why N1 ships all 84 files rather than the 20 that are read.
+ *
+ * EXCEPT bytecode caches, and that exception is the whole point of this field. The pack ships
+ * `.py` fixture files, so `pip install` byte-compiles them into `__pycache__` on the way in and
+ * the digest of an INSTALLED Python pack stopped matching the digest of the identical npm pack
+ * — measured on the published 0.27.0 artifacts, `sha256:fa8372f6…` over 98 files against
+ * `sha256:d47dcf4b…` over 87, and deleting `__pycache__` from the wheel's pack reproduced the
+ * npm digest byte for byte. `cross_runtime` tells the caller to compare `assets_digest` across
+ * runtimes; without this rule that instruction returned a false "different" on every real
+ * install. The pack is what was SHIPPED, never what an interpreter later wrote beside it.
+ *
+ * The rule is spelled identically in `runtime-py`'s `_assets_fingerprint`, and it has to be:
+ * this side never creates a `__pycache__`, so a Node-only exclusion would still agree today
+ * and diverge again the moment a pack carrying one reached both runtimes.
+ */
+export const notBytecodeCache = (parts) => !parts.includes('__pycache__');
+/**
+ * The pack as SHIPPED, counted — what `--assets-root` prints.
+ *
+ * Exported so the CLI shares this walk rather than keeping a second one. There are TWO
+ * walks over this directory and a rule spelled twice is a rule that gets fixed once: the
+ * first version of this fix filtered the digest alone, and a `pip install` then had one
+ * process contradicting itself, `build_identity` answering 87 files while `--assets-root`
+ * printed 98 for the pack it had just loaded. The CLI's own `readdirSync(recursive)` is
+ * gone with it — `walkFiles` is the walk that mirrors CPython's `rglob`, which is what the
+ * reference's printer uses and what the conformance case compares the count against.
  */
+export function packFileCount(root) {
+    return walkFiles(root).filter(notBytecodeCache).length;
+}
 function assetsFingerprint() {
     let root;
     try {
@@ -177,7 +206,7 @@ function assetsFingerprint() {
     }
     let walked;
     try {
-        walked = treeDigest(root);
+        walked = treeDigest(root, notBytecodeCache);
     }
     catch (e) {
         const error = e instanceof PyOSError ? e : asPyOSError(e, root);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bantamkit-mcp",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "bantamkit MCP server — pure Node, runnable with npx",
   "type": "module",
   "bin": {