@thenavidm/slipway 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 What changed in Slipway, newest first.
 
+## 0.1.3, 2026-10-04: npx picks the server by name
+
+- **`slipway check` matches npm's real rule.** npx picks a binary named after the package only when the binaries point to different files. When they share one file it starts whichever one the registry lists first, and the registry does not keep the published order: 23 published servers listed their MCP binary first and still started the CLI. 0.1.2's order check could not catch that. The check now requires a binary named after the package on a file of its own, and the README shows the one-line `src/npx.ts` it runs.
+
+## 0.1.2, 2026-10-04: clients always start the server
+
+- **`slipway check` fails a package whose `npx -y` default is the CLI.** With several binaries on one file, npx starts the first one listed. A package that lists its CLI first hands every client launched with `npx -y <package>` the command list instead of a server. The check reads `package.json` and names the fix: list the MCP binary first.
+- **`install` follows `@latest`.** Clients start `npx --package=<package>@latest <name>-mcp`, so they pick up every release on their next start. The binary is still named, so the order in `package.json` cannot pick the wrong one.
+
 ## 0.1.1, 2026-10-04: a safer install check
 
 - **No stranger's package through npx.** An unrelated npm package owns the bare name `slipway`, so a bare `npx slipway` with nothing installed fetched and ran it. SKILL.md now checks the install with `npm ls @thenavidm/slipway`, and every command that may run before an install names the package: `npx -p @thenavidm/slipway slipway <command>`.

package/README.md

@@ -124,7 +124,7 @@ npm install --save-dev ajv
 
 ## 2. Build a server
 
-A server is three files.
+A server is three files, plus a one-line fourth for npx.
 
 **`src/tools.ts`** says what the server can do. `toolkit<Context>()` binds the context type once, so every handler gets `ctx.api` typed:
 
@@ -179,12 +179,21 @@ import { app } from "./app.js";
 await app.main();
 ```
 
+**`src/npx.ts`** is what `npx -y @you/notes-mcp-cli` runs:
+
+```ts
+#!/usr/bin/env node
+import "./index.js";
+```
+
 ```json
 {
-  "bin": { "notes-mcp": "dist/index.js", "notes-cli": "dist/index.js" }
+  "bin": { "notes-mcp": "dist/index.js", "notes-cli": "dist/index.js", "notes-mcp-cli": "dist/npx.js" }
 }
 ```
 
+npx picks a binary named after the package only when the binaries point to different files. When they all share one file it starts whichever one the registry lists first, and the registry does not keep the order they were published in, so a client could get the CLI's command list instead of a server. The fourth binary, on its own file, is picked every time, and `slipway check` fails a package without it.
+
 `notes-mcp` with no arguments serves MCP over stdio and stays silent on stdout. `notes-cli` with no arguments lists the commands. Any argument on either binary is a command, so a typo is reported instead of starting a server that waits on stdin.
 
 The context is built on the first call that needs it, never at startup. `--help` works with nothing configured, and the server answers a client at once and explains what is missing instead of exiting.
@@ -444,7 +453,7 @@ notes-cli install cursor --dry-run
 | `vscode` | `.vscode/mcp.json` | VS Code asks for each credential once and stores it securely |
 | `gemini` | `~/.gemini/settings.json`, or `.gemini/settings.json` | `${NAME}` references, which Gemini CLI needs to pass anything named like a key |
 
-A published server is started with `npx --package=<package>@<version> <name>-mcp`, pinned to the version you installed, with Codex's startup timeout raised for the first download. Without `package`, or with `--local`, the client starts this copy on disk. Installing again updates the entry in place: anything you added to it by hand stays, and the old file is kept as a backup.
+A published server is started with `npx --package=<package>@latest <name>-mcp`, so a client picks up every release on its next start, with Codex's startup timeout raised for the download. The binary is named, because npx alone starts whichever binary a package lists first. Without `package`, or with `--local`, the client starts this copy on disk. Installing again updates the entry in place: anything you added to it by hand stays, and the old file is kept as a backup.
 
 ## 11. Large catalogs
 
@@ -476,7 +485,7 @@ Run it in a project that has `@thenavidm/slipway` installed, where npx uses that
 | Parity | A tool, schema, annotation or approval flag that differs between MCP and the CLI |
 | Docs | A command or flag in your README or SKILL.md that does not exist |
 | Startup | A built server that exits or hangs when nothing is configured |
-| Install | No `package`, so `install` cannot point clients at the published server |
+| Install | No `package`, or a package.json whose `npx -y` default starts the CLI instead of the server |
 
 Parity runs on both protocol revisions a client may open with. `slipway docs dist/app.js` prints the command table, every argument and the settings as Markdown, from the same definitions. `slipway inspect dist/app.js` lists the tools exactly as a client receives them, and `slipway openapi <file|url>` previews what an OpenAPI document becomes.
 

package/SKILL.md

@@ -23,8 +23,9 @@ Run `npm ls @thenavidm/slipway` in the repo. If it does not list a version, STOP
 | `src/tools.ts` | The tools, from `toolkit<Context>().defineTool` | One `defineTool` per action |
 | `src/app.ts` | `export const app = slipway({...})` | Describes only. Never calls `main()`, so checks and tests can import it |
 | `src/index.ts` | `await app.main()` | The only file that starts anything. Both binaries point at it |
+| `src/npx.ts` | `import "./index.js";` | What `npx -y <package>` runs. Its binary is named after the package |
 
-`package.json` declares both binaries on the same file: `"<name>-mcp"` and `"<name>-cli"`, both `dist/index.js`.
+`package.json` declares `"<name>-mcp"` and `"<name>-cli"` on `dist/index.js`, and a third binary named after the package (`"<name>-mcp-cli"`) on `dist/npx.js`. npx only picks a binary by name when they point to different files; otherwise it takes whichever one the registry lists first, which may be the CLI.
 
 ## Defining a tool
 

package/dist/bin.js

@@ -95,7 +95,13 @@ async function main(argv) {
     if (command === "check") {
         const docs = option(rest, "--docs")?.split(",").filter(Boolean);
         const bin = option(rest, "--bin");
-        const report = await checkApp(app, { env: process.env, ...(docs ? { docs } : {}), ...(bin ? { bin: resolve(bin) } : {}) });
+        const packageJson = resolve("package.json");
+        const report = await checkApp(app, {
+            env: process.env,
+            ...(docs ? { docs } : {}),
+            ...(bin ? { bin: resolve(bin) } : {}),
+            ...(existsSync(packageJson) ? { packageJson } : {}),
+        });
         const strict = rest.includes("--strict");
         const failed = report.errors > 0 || (strict && report.warnings > 0);
         if (rest.includes("--json")) {

package/dist/check.d.ts

@@ -25,6 +25,8 @@ export type CheckOptions = {
         warnBytes: number;
         errorBytes: number;
     };
+    /** The app's package.json, to check that `npx -y <package>` starts the MCP server. */
+    packageJson?: string;
 };
 export type CheckReport = {
     ok: boolean;

package/dist/check.js

@@ -108,6 +108,8 @@ export async function checkApp(app, options = {}) {
     if (!app.definition.package) {
         add("warn", "install", "No package is set, so `install` points clients at this copy on disk instead of the published one. Set package to the npm name.");
     }
+    if (options.packageJson)
+        checkBins(app, options.packageJson, add);
     const instructions = app.instructions ?? "";
     if (!instructions)
         add("warn", "instructions", "No server instructions. Clients use them to decide when to reach for these tools.");
@@ -215,6 +217,44 @@ async function checkParityIn(era, app, env, tools, add) {
         await client.close().catch(() => undefined);
     }
 }
+/**
+ * `npx -y <package>` is how most people install a server, and npx starts one
+ * binary without being told which. npm's rule: when every binary points to
+ * the same file, it starts whichever one the registry lists first, and the
+ * registry does not keep the order they were published in. Only a binary
+ * named after the package, on a file of its own, is picked every time.
+ */
+function checkBins(app, file, add) {
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        add("error", "install", `Could not read ${file}: ${error.message}`);
+        return;
+    }
+    if (app.definition.package && pkg.name && pkg.name !== app.definition.package) {
+        add("warn", "install", `The app's package is ${app.definition.package} but package.json is ${pkg.name}.`);
+    }
+    if (!pkg.bin || typeof pkg.bin === "string")
+        return;
+    const bins = pkg.bin;
+    if (!(app.bins.mcp in bins)) {
+        add("error", "install", `package.json has no ${app.bins.mcp} binary, so clients cannot start the server by name.`);
+        return;
+    }
+    const unscoped = (pkg.name ?? "").split("/").pop() ?? "";
+    const fix = `Add "${unscoped}": "dist/npx.js" to bin, where src/npx.ts holds only: import "./index.js";`;
+    if (new Set(Object.values(bins)).size === 1) {
+        add("error", "install", `Every binary runs the same file, so npx -y ${pkg.name} starts whichever one the registry lists first, which may be ${app.bins.cli}. ${fix}`);
+    }
+    else if (!(unscoped in bins)) {
+        add("error", "install", `npx -y ${pkg.name} cannot choose between ${Object.keys(bins).join(", ")}. ${fix}`);
+    }
+    else if (unscoped === app.bins.cli || unscoped.startsWith(app.bins.cli)) {
+        add("error", "install", `npx -y ${pkg.name} starts ${unscoped}, which runs as the CLI. Name the package so it does not start with ${app.bins.cli}.`);
+    }
+}
 /** Every command and flag a README or SKILL.md tells someone to type must exist. */
 function checkDocs(app, file, add) {
     if (!existsSync(file)) {

package/dist/install.d.ts

@@ -59,7 +59,8 @@ export type InstallPlan = {
 };
 /**
  * How a client should start this server: the published package through npx,
- * pinned to this version, or this copy on disk.
+ * at `@latest` so a client picks up every release on its next start, or this
+ * copy on disk.
  *
  * npx needs the binary named: a package with an MCP and a CLI binary leaves
  * npx to pick one otherwise, and the CLI started with no arguments prints its

package/dist/install.js

@@ -27,7 +27,8 @@ export const CLIENTS = {
 };
 /**
  * How a client should start this server: the published package through npx,
- * pinned to this version, or this copy on disk.
+ * at `@latest` so a client picks up every release on its next start, or this
+ * copy on disk.
  *
  * npx needs the binary named: a package with an MCP and a CLI binary leaves
  * npx to pick one otherwise, and the CLI started with no arguments prints its
@@ -37,7 +38,7 @@ export function launchFor(app, options) {
     const platform = options.platform ?? process.platform;
     let launch;
     if (app.definition.package && !options.local) {
-        launch = { command: "npx", args: ["--yes", `--package=${app.definition.package}@${app.version}`, app.bins.mcp] };
+        launch = { command: "npx", args: ["--yes", `--package=${app.definition.package}@latest`, app.bins.mcp] };
     }
     else {
         const entry = options.entry ?? (process.argv[1] ? realpathSync(process.argv[1]) : undefined);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thenavidm/slipway",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Slipway, the TypeScript framework for MCP servers and agent-native CLIs. One tool definition ships an MCP server and a CLI, with write safety, typed results and release checks built in.",
   "type": "module",
   "license": "Apache-2.0",