@zeph-to/cli 2.11.0 → 2.12.0

package/README.md

@@ -179,10 +179,15 @@ way. `zeph install` does not wire Hermes either — add the MCP server to
 ```yaml
 mcp_servers:
   zeph:
-    command: "npx"
-    args: ["-y", "@zeph-to/mcp-server"]
+    command: "zeph"
+    args: ["mcp"]
 ```
 
+`zeph mcp` runs the MCP server inside the CLI process. The older
+`command: "npx"` / `args: ["-y", "@zeph-to/mcp-server"]` form still works,
+but leaves an `npm exec` launcher resident beside the server for as long as
+the session lives — `zeph verify` flags a config still on it.
+
 Add the entry; do not replace the file. `mcp_servers` is shared with
 every other server you have configured, and nothing under `~/.hermes` is
 in version control. Then `/reload-mcp` inside Hermes.
@@ -523,6 +528,7 @@ zeph notify --title "Hello" --json
 | `rename <name>` | Set the current agent session's display name in the app — run inside a `zeph cc` session (`--clear` resets). Auto-detects the tmux session + this machine's listener device id, so the alias lands on the right device |
 | `test` | Verify connection and API key |
 | `cc` · `codex` · `gemini` | Run the agent in a `zeph-<project>` tmux session — reattaches a detached session of that project (newest suffix first) when there is one, else auto-suffixes `-2`, `-3`, …. Auto-spawns the background listener on first invocation so the phone picker just works. Trailing args pass through to the agent (`zeph cc --resume "..."`) |
+| `mcp` | Run the MCP server on stdio, in this process. What agent MCP configs launch — `zeph install` registers it and you never type it. Replaces the old `npx -y @zeph-to/mcp-server` registration, which left an `npm exec` launcher resident alongside the server for the life of the session. `@zeph-to/mcp-server` ships as a dependency now, so it updates with the CLI rather than being re-fetched by `npx` on every launch — `zeph check-update` reports the version you actually have |
 | `listener` | (Usually unnecessary — `zeph cc` autospawns it.) Resident daemon: subscribes via WebSocket, reports tmux session inventory every 5 s, injects `agent.command` pushes into the matching session. Run in the foreground for SDK development; otherwise let `zeph cc` manage it |
 
 ### Notify Options

package/dist/check-update.d.ts

@@ -1,4 +1,11 @@
 /** Semver-ish compare: returns true when `latest` is strictly newer than `current`. */
 export declare const isNewer: (latest: string, current: string) => boolean;
+/**
+ * The mcp-server version this CLI will actually run. It ships as a dependency
+ * (see mcp.ts), so it is pinned at install time — no longer "whatever npx
+ * fetched last". Returns null on a broken install rather than throwing; the
+ * report degrades to "latest is vX" the way it always did for this package.
+ */
+export declare const installedMcpServerVersion: () => string | null;
 export declare const handleCheckUpdate: (args: Record<string, string | boolean>) => Promise<number>;
 //# sourceMappingURL=check-update.d.ts.map

package/dist/check-update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-update.d.ts","sourceRoot":"","sources":["../src/check-update.ts"],"names":[],"mappings":"AAsBA,uFAAuF;AACvF,eAAO,MAAM,OAAO,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,OAQzD,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CA4C9F,CAAC"}
+{"version":3,"file":"check-update.d.ts","sourceRoot":"","sources":["../src/check-update.ts"],"names":[],"mappings":"AAuBA,uFAAuF;AACvF,eAAO,MAAM,OAAO,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,OAQzD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,QAAO,MAAM,GAAG,IASrD,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CA4C9F,CAAC"}

package/dist/check-update.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleCheckUpdate = exports.isNewer = void 0;
+exports.handleCheckUpdate = exports.installedMcpServerVersion = exports.isNewer = void 0;
+const fs_1 = require("fs");
 const config_js_1 = require("./config.js");
 // Compares installed versions against the npm registry. Pure read-only —
 // never installs anything; just tells the user if a newer release exists.
@@ -34,19 +35,35 @@ const isNewer = (latest, current) => {
     return false;
 };
 exports.isNewer = isNewer;
+/**
+ * The mcp-server version this CLI will actually run. It ships as a dependency
+ * (see mcp.ts), so it is pinned at install time — no longer "whatever npx
+ * fetched last". Returns null on a broken install rather than throwing; the
+ * report degrades to "latest is vX" the way it always did for this package.
+ */
+const installedMcpServerVersion = () => {
+    try {
+        const pkg = JSON.parse((0, fs_1.readFileSync)(require.resolve('@zeph-to/mcp-server/package.json'), 'utf-8'));
+        return pkg.version ?? null;
+    }
+    catch {
+        return null;
+    }
+};
+exports.installedMcpServerVersion = installedMcpServerVersion;
 const handleCheckUpdate = async (args) => {
     const isJson = args.json === true;
-    // The CLI's own installed version is known from package.json.
-    // mcp-server's installed version isn't reliably knowable from here
-    // (it's a separate package, often run via npx), so we only report its
-    // latest — the user compares against whatever they have.
-    const results = [];
-    for (const pkg of PACKAGES) {
-        const latest = await fetchLatest(pkg);
-        const current = pkg === '@zeph-to/cli' ? config_js_1.VERSION : null;
-        const outdated = !!(latest && current && (0, exports.isNewer)(latest, current));
-        results.push({ pkg, current, latest, outdated });
-    }
+    // Both installed versions are knowable: the CLI's from its own
+    // package.json, and mcp-server's because `zeph mcp` runs it in-process,
+    // which makes it a dependency rather than an npx download of unknown age.
+    // Two unrelated registry round-trips — awaiting them one after the other
+    // doubled the command's wall time for nothing.
+    const latestVersions = await Promise.all(PACKAGES.map(fetchLatest));
+    const results = PACKAGES.map((pkg, i) => {
+        const latest = latestVersions[i];
+        const current = pkg === '@zeph-to/cli' ? config_js_1.VERSION : (0, exports.installedMcpServerVersion)();
+        return { pkg, current, latest, outdated: !!(latest && current && (0, exports.isNewer)(latest, current)) };
+    });
     if (isJson) {
         console.log(JSON.stringify({ results }, null, 2));
         return 0;

package/dist/cli.js

@@ -11,6 +11,7 @@ const verify_js_1 = require("./verify.js");
 const check_update_js_1 = require("./check-update.js");
 const ask_js_1 = require("./ask.js");
 const wrapper_js_1 = require("./wrapper.js");
+const mcp_js_1 = require("./mcp.js");
 const listener_js_1 = require("./listener.js");
 const config_js_1 = require("./config.js");
 const gate_js_1 = require("./gate.js");
@@ -84,6 +85,9 @@ ${usageAgentLines()}
                    -2/-3/… only when every existing one has a client
                    attached. Any args after the subcommand are forwarded
                    verbatim, e.g. 'zeph cc --resume')
+  mcp             Run the MCP server on stdio. This is what agent MCP
+                  configs launch — 'zeph install' registers it, you
+                  never type it
   listener        Resident daemon — receives 'agent.command' pushes from
                   the phone picker and injects them into the matching
                   tmux session.
@@ -491,6 +495,8 @@ const main = async () => {
             return handleRename(args);
         case 'test':
             return handleTest(args);
+        case 'mcp':
+            return (0, mcp_js_1.handleMcp)();
         case 'listener':
             return (0, listener_js_1.handleListener)(args);
         case 'remote-hook':

package/dist/installer.d.ts

@@ -12,18 +12,6 @@ export declare const shouldReauth: (currentKey: string | undefined, relogin: boo
 /** Exported for tests (installGemini shells out to the real `gemini` binary,
  *  so the merge semantics can't be covered through it deterministically). */
 export declare const mergeJsonFile: (filePath: string, patch: Record<string, unknown>) => void;
-/**
- * opencode.json's own MCP schema — top-level `mcp` key (not `mcpServers`),
- * `command` as ARRAY (binary + args), `type: "local"`. No `environment` —
- * opencode is a terminal app that inherits shell env, and the MCP server
- * falls back to ~/.zeph/config.json anyway (an unexpanded "${ZEPH_API_KEY}"
- * literal would shadow that fallback with junk). Exported for tests (shape pin).
- */
-export declare const OPENCODE_MCP_ENTRY: {
-    type: string;
-    command: string[];
-    enabled: boolean;
-};
 /** Add the zeph entry under `key` in an MCP registry JSON file, preserving
  *  everything else in it. Exported for tests (merge semantics). */
 export declare const injectMcpEntry: (filePath: string, key: string, entry: Record<string, unknown>) => void;

package/dist/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AA+BzC;;;GAGG;AACH;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,YAAY,MAAM,GAAG,SAAS,EAAE,SAAS,OAAO,KAAG,OACxD,CAAC;AAoBzB;6EAC6E;AAC7E,eAAO,MAAM,aAAa,GAAI,UAAU,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAqBhF,CAAC;AAgDF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB;;;;CAI9B,CAAC;AAEF;mEACmE;AACnE,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,EAAE,KAAK,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAQ9F,CAAC;AAqPF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,KAAK,EAAE,EAAE,MAAM,MAAM,KAAG,KAAK,EAKxE,CAAC;AA8EF;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAC/B,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EACtC,gBAAgB,OAAO,KACtB,KAAK,GAAG,IAAI,GAAG,KAKjB,CAAC;AAgCF,eAAO,MAAM,aAAa,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAuH1F,CAAC"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AA+BzC;;;GAGG;AACH;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,YAAY,MAAM,GAAG,SAAS,EAAE,SAAS,OAAO,KAAG,OACxD,CAAC;AAoBzB;6EAC6E;AAC7E,eAAO,MAAM,aAAa,GAAI,UAAU,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAqBhF,CAAC;AAsCF;mEACmE;AACnE,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,EAAE,KAAK,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAQ9F,CAAC;AAmPF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,KAAK,EAAE,EAAE,MAAM,MAAM,KAAG,KAAK,EAKxE,CAAC;AA8EF;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAC/B,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EACtC,gBAAgB,OAAO,KACtB,KAAK,GAAG,IAAI,GAAG,KAKjB,CAAC;AAgCF,eAAO,MAAM,aAAa,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAuH1F,CAAC"}

package/dist/installer.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleInstall = exports.serviceInstallChoice = exports.filterAgentsByIds = exports.injectMcpEntry = exports.OPENCODE_MCP_ENTRY = exports.mergeJsonFile = exports.shouldReauth = void 0;
+exports.handleInstall = exports.serviceInstallChoice = exports.filterAgentsByIds = exports.injectMcpEntry = exports.mergeJsonFile = exports.shouldReauth = void 0;
 const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const os_1 = require("os");
@@ -10,6 +10,7 @@ const zeph_hook_js_1 = require("./zeph-hook.js");
 const config_js_1 = require("./config.js");
 const login_js_1 = require("./login.js");
 const agents_js_1 = require("./agents.js");
+const mcp_command_js_1 = require("./mcp-command.js");
 const listener_service_js_1 = require("./listener-service.js");
 const templates_js_1 = require("./templates.js");
 const HOME = (0, os_1.homedir)();
@@ -104,27 +105,6 @@ const addAiderReadDirective = (confPath, conventionsPath) => {
     (0, fs_1.writeFileSync)(confPath, (base ? `${base}\n\n` : '') + line);
 };
 // ── Per-Agent Installers ─────────────────────────────────────────
-// Pass through env explicitly so the MCP server doesn't have to rely on
-// process-env inheritance (which behaves differently per IDE — Cursor and
-// Windsurf spawn the MCP from a graphical context that may not inherit
-// shell env). Mirrors plugin/.mcp.json.
-const MCP_SERVERS_ENTRY = {
-    command: 'npx',
-    args: ['-y', '@zeph-to/mcp-server'],
-    env: { ZEPH_API_KEY: '${ZEPH_API_KEY}' },
-};
-/**
- * opencode.json's own MCP schema — top-level `mcp` key (not `mcpServers`),
- * `command` as ARRAY (binary + args), `type: "local"`. No `environment` —
- * opencode is a terminal app that inherits shell env, and the MCP server
- * falls back to ~/.zeph/config.json anyway (an unexpanded "${ZEPH_API_KEY}"
- * literal would shadow that fallback with junk). Exported for tests (shape pin).
- */
-exports.OPENCODE_MCP_ENTRY = {
-    type: 'local',
-    command: ['npx', '-y', '@zeph-to/mcp-server'],
-    enabled: true,
-};
 /** Add the zeph entry under `key` in an MCP registry JSON file, preserving
  *  everything else in it. Exported for tests (merge semantics). */
 const injectMcpEntry = (filePath, key, entry) => {
@@ -153,7 +133,7 @@ const installClaude = () => {
 };
 const installCursor = () => {
     try {
-        (0, exports.injectMcpEntry)((0, path_1.join)(HOME, '.cursor', 'mcp.json'), 'mcpServers', MCP_SERVERS_ENTRY);
+        (0, exports.injectMcpEntry)((0, path_1.join)(HOME, '.cursor', 'mcp.json'), 'mcpServers', mcp_command_js_1.MCP_SERVERS_ENTRY);
         ok('MCP server added');
     }
     catch {
@@ -176,7 +156,7 @@ const installCursor = () => {
 };
 const installWindsurf = () => {
     try {
-        (0, exports.injectMcpEntry)((0, path_1.join)(HOME, '.codeium', 'windsurf', 'mcp_config.json'), 'mcpServers', MCP_SERVERS_ENTRY);
+        (0, exports.injectMcpEntry)((0, path_1.join)(HOME, '.codeium', 'windsurf', 'mcp_config.json'), 'mcpServers', mcp_command_js_1.MCP_SERVERS_ENTRY);
         ok('MCP server added');
     }
     catch {
@@ -201,20 +181,18 @@ const installWindsurf = () => {
 };
 const installGemini = () => {
     try {
-        // gemini ≥0.26 syntax: `mcp add [-s scope] <name> <command> [args…]` —
-        // the default scope is "project" (cwd-local .gemini/), so pin user
-        // scope for a machine-wide install. Older gemini CLIs only accept the
-        // legacy `mcp add zeph -- npx …` form; fall back for those.
-        (0, child_process_1.execSync)('gemini mcp add -s user zeph npx -- -y @zeph-to/mcp-server', { stdio: 'pipe' });
+        // Both forms are built in mcp-command.ts; older gemini CLIs only accept
+        // the legacy one, so try the modern form first and fall back.
+        (0, child_process_1.execSync)(mcp_command_js_1.GEMINI_MCP_ADD, { stdio: 'pipe' });
         ok('MCP server added');
     }
     catch {
         try {
-            (0, child_process_1.execSync)('gemini mcp add zeph -- npx -y @zeph-to/mcp-server', { stdio: 'pipe' });
+            (0, child_process_1.execSync)(mcp_command_js_1.GEMINI_MCP_ADD_LEGACY, { stdio: 'pipe' });
             ok('MCP server added (legacy gemini CLI)');
         }
         catch {
-            fail('MCP add failed. Manual: gemini mcp add -s user zeph npx -- -y @zeph-to/mcp-server');
+            fail(`MCP add failed. Manual: ${mcp_command_js_1.GEMINI_MCP_ADD}`);
         }
     }
     try {
@@ -320,7 +298,7 @@ const installPi = () => {
 };
 const installOpencode = () => {
     try {
-        (0, exports.injectMcpEntry)((0, path_1.join)(HOME, '.config', 'opencode', 'opencode.json'), 'mcp', exports.OPENCODE_MCP_ENTRY);
+        (0, exports.injectMcpEntry)((0, path_1.join)(HOME, '.config', 'opencode', 'opencode.json'), 'mcp', mcp_command_js_1.OPENCODE_MCP_ENTRY);
         ok('MCP server added');
     }
     catch {

package/dist/mcp-command.d.ts

@@ -0,0 +1,45 @@
+/**
+ * How every agent launches the Zeph MCP server — one source, three schemas.
+ *
+ * Registrations used to say `npx -y @zeph-to/mcp-server`, which left an
+ * `npm exec` launcher resident beside the server for the life of the session.
+ * `zeph mcp` (see mcp.ts) runs the server in the CLI's own process instead.
+ *
+ * Cursor/Windsurf, Gemini and OpenCode each want that launch in a different
+ * shape, and the shapes drifted apart when each site spelled the command out
+ * itself. Everything below is derived from MCP_LAUNCH_ARGV.
+ */
+/** What the agents run. `zeph` resolves out of the same global bin dir as `npx`. */
+export declare const MCP_LAUNCH_ARGV: readonly ["zeph", "mcp"];
+/**
+ * `mcpServers.zeph` — what the installer writes for Cursor and Windsurf.
+ * The env block is deliberate: both spawn the MCP server from a graphical
+ * context that may not inherit shell env, so the key is passed through
+ * explicitly rather than left to inheritance.
+ *
+ * `zeph-to/plugin`'s `.mcp.json` holds the same shape but is a HAND-KEPT COPY —
+ * it lives in another repo and cannot import this. Change one, change both.
+ */
+export declare const MCP_SERVERS_ENTRY: {
+    command: "zeph";
+    args: "mcp"[];
+    env: {
+        ZEPH_API_KEY: string;
+    };
+};
+/**
+ * opencode.json's own MCP schema — top-level `mcp` key (not `mcpServers`),
+ * `command` as ARRAY (binary + args), `type: "local"`. No `environment` —
+ * opencode is a terminal app that inherits shell env, and the MCP server
+ * falls back to ~/.zeph/config.json anyway (an unexpanded "${ZEPH_API_KEY}"
+ * literal would shadow that fallback with junk).
+ */
+export declare const OPENCODE_MCP_ENTRY: {
+    type: string;
+    command: ("zeph" | "mcp")[];
+    enabled: boolean;
+};
+export declare const GEMINI_MCP_ADD: string;
+/** Older gemini CLIs only accept `mcp add <name> -- <command…>`, with no scope flag. */
+export declare const GEMINI_MCP_ADD_LEGACY: string;
+//# sourceMappingURL=mcp-command.d.ts.map

package/dist/mcp-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-command.d.ts","sourceRoot":"","sources":["../src/mcp-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,oFAAoF;AACpF,eAAO,MAAM,eAAe,0BAA2B,CAAC;AAIxD;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB;;;;;;CAI7B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB;;;;CAI9B,CAAC;AAMF,eAAO,MAAM,cAAc,QAA0E,CAAC;AAEtG,wFAAwF;AACxF,eAAO,MAAM,qBAAqB,QAAwD,CAAC"}

package/dist/mcp-command.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * How every agent launches the Zeph MCP server — one source, three schemas.
+ *
+ * Registrations used to say `npx -y @zeph-to/mcp-server`, which left an
+ * `npm exec` launcher resident beside the server for the life of the session.
+ * `zeph mcp` (see mcp.ts) runs the server in the CLI's own process instead.
+ *
+ * Cursor/Windsurf, Gemini and OpenCode each want that launch in a different
+ * shape, and the shapes drifted apart when each site spelled the command out
+ * itself. Everything below is derived from MCP_LAUNCH_ARGV.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GEMINI_MCP_ADD_LEGACY = exports.GEMINI_MCP_ADD = exports.OPENCODE_MCP_ENTRY = exports.MCP_SERVERS_ENTRY = exports.MCP_LAUNCH_ARGV = void 0;
+/** What the agents run. `zeph` resolves out of the same global bin dir as `npx`. */
+exports.MCP_LAUNCH_ARGV = ['zeph', 'mcp'];
+const [MCP_BIN, ...MCP_SUBCOMMAND] = exports.MCP_LAUNCH_ARGV;
+/**
+ * `mcpServers.zeph` — what the installer writes for Cursor and Windsurf.
+ * The env block is deliberate: both spawn the MCP server from a graphical
+ * context that may not inherit shell env, so the key is passed through
+ * explicitly rather than left to inheritance.
+ *
+ * `zeph-to/plugin`'s `.mcp.json` holds the same shape but is a HAND-KEPT COPY —
+ * it lives in another repo and cannot import this. Change one, change both.
+ */
+exports.MCP_SERVERS_ENTRY = {
+    command: MCP_BIN,
+    args: [...MCP_SUBCOMMAND],
+    env: { ZEPH_API_KEY: '${ZEPH_API_KEY}' },
+};
+/**
+ * opencode.json's own MCP schema — top-level `mcp` key (not `mcpServers`),
+ * `command` as ARRAY (binary + args), `type: "local"`. No `environment` —
+ * opencode is a terminal app that inherits shell env, and the MCP server
+ * falls back to ~/.zeph/config.json anyway (an unexpanded "${ZEPH_API_KEY}"
+ * literal would shadow that fallback with junk).
+ */
+exports.OPENCODE_MCP_ENTRY = {
+    type: 'local',
+    command: [...exports.MCP_LAUNCH_ARGV],
+    enabled: true,
+};
+// gemini ≥0.26 syntax: `mcp add [-s scope] <name> <command> [args…]`. The
+// server NAME and the BINARY are both "zeph" here, so the doubled word below
+// is correct, not a copy-paste slip. Default scope is "project" (cwd-local
+// .gemini/), so user scope is pinned for a machine-wide install.
+exports.GEMINI_MCP_ADD = `gemini mcp add -s user zeph ${MCP_BIN} -- ${MCP_SUBCOMMAND.join(' ')}`;
+/** Older gemini CLIs only accept `mcp add <name> -- <command…>`, with no scope flag. */
+exports.GEMINI_MCP_ADD_LEGACY = `gemini mcp add zeph -- ${exports.MCP_LAUNCH_ARGV.join(' ')}`;

package/dist/mcp.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `zeph mcp` — run the Zeph MCP server inside THIS process.
+ *
+ * Every registration used to say `npx -y @zeph-to/mcp-server`, which left an
+ * `npm exec` launcher resident for the whole session on top of the server it
+ * spawned — two node processes where one does the work. `@zeph-to/mcp-server`
+ * is a dependency of this package now, so agents register `zeph mcp` and get
+ * exactly one process.
+ */
+/**
+ * Importing `@zeph-to/mcp-server` IS starting it: the package is a bin entry
+ * whose module body wires an McpServer to a StdioServerTransport and exports
+ * nothing. Verified against 2.3.0 (`dist/index.js` ends in `main().catch(…)`).
+ * Injectable so tests don't need the real package resolvable.
+ */
+type McpServerLoader = () => Promise<unknown>;
+export declare const handleMcp: (load?: McpServerLoader) => Promise<number>;
+export {};
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,KAAK,eAAe,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;AAI9C,eAAO,MAAM,SAAS,GAAU,OAAM,eAAiC,KAAG,OAAO,CAAC,MAAM,CAcvF,CAAC"}

package/dist/mcp.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * `zeph mcp` — run the Zeph MCP server inside THIS process.
+ *
+ * Every registration used to say `npx -y @zeph-to/mcp-server`, which left an
+ * `npm exec` launcher resident for the whole session on top of the server it
+ * spawned — two node processes where one does the work. `@zeph-to/mcp-server`
+ * is a dependency of this package now, so agents register `zeph mcp` and get
+ * exactly one process.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleMcp = void 0;
+const importMcpServer = () => import('@zeph-to/mcp-server');
+const handleMcp = async (load = importMcpServer) => {
+    try {
+        await load();
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        console.error(`zeph: could not start the MCP server (@zeph-to/mcp-server): ${reason}`);
+        console.error('zeph: reinstall the CLI with `npm i -g @zeph-to/cli`.');
+        return 1;
+    }
+    // The server owns this process from here: it holds stdio open and decides
+    // when to exit. Resolving would hand cli.ts a code for `process.exit()`,
+    // killing the server the line above just started.
+    return new Promise(() => { });
+};
+exports.handleMcp = handleMcp;

package/dist/verify.d.ts

@@ -1,2 +1,36 @@
+/**
+ * The launch argv a registry file records for zeph, verbatim — null when the
+ * file is absent, unparseable, or has no zeph entry. Two schemas in the wild:
+ * `command` + `args` (Cursor/Windsurf/Gemini) and `command` as a whole array
+ * (opencode). Returned as-is on purpose: a stale entry is only detectable if
+ * the reader does not normalize it into the shape it expects.
+ */
+export declare const registeredMcpArgv: (filePath: string, key: string) => string[] | null;
+/**
+ * Can this launch binary actually be run? Registered commands come out of a
+ * config file, so they can be an absolute path with spaces in it — the shared
+ * `hasCommand` interpolates into `which ${cmd}`, where such a path splits into
+ * two words and reports a perfectly good binary as missing (and where any `;`
+ * in the file would reach the shell). Nothing here touches a shell.
+ */
+export declare const binaryResolves: (bin: string) => boolean;
+/**
+ * What a recorded registration is worth right now. `unresolvable` outranks
+ * `stale`: a stale entry still starts a server (through the npm launcher this
+ * release exists to delete), an unresolvable one starts nothing at all and
+ * takes the agent's whole zeph toolset down with it, silently — the config is
+ * read once at install time and never checked again.
+ */
+export type McpRegistration = {
+    readonly state: 'current';
+} | {
+    readonly state: 'stale';
+    readonly argv: string[];
+} | {
+    readonly state: 'unresolvable';
+    readonly argv: string[];
+};
+/** null = this agent has no zeph registration at all, so there is nothing to report. */
+export declare const classifyMcpRegistration: (argv: string[] | null, isOnPath: (bin: string) => boolean) => McpRegistration | null;
 export declare const handleVerify: (args: Record<string, string | boolean>) => Promise<number>;
 //# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AA4CA,eAAO,MAAM,YAAY,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAiFzF,CAAC"}
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AA6DA;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,EAAE,KAAK,MAAM,KAAG,MAAM,EAAE,GAAG,IAa5E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,OAQ5C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GACrB;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAElE,wFAAwF;AACxF,eAAO,MAAM,uBAAuB,GAChC,MAAM,MAAM,EAAE,GAAG,IAAI,EACrB,UAAU,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,KACnC,eAAe,GAAG,IAMpB,CAAC;AAYF,eAAO,MAAM,YAAY,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CA+GzF,CAAC"}

package/dist/verify.js

@@ -1,13 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleVerify = void 0;
+exports.handleVerify = exports.classifyMcpRegistration = exports.binaryResolves = exports.registeredMcpArgv = void 0;
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
+const child_process_1 = require("child_process");
 const agents_js_1 = require("./agents.js");
 const config_js_1 = require("./config.js");
 const listener_service_js_1 = require("./listener-service.js");
 const zeph_hook_js_1 = require("./zeph-hook.js");
+const mcp_command_js_1 = require("./mcp-command.js");
 const HOME = (0, os_1.homedir)();
 const pass = (msg) => console.log(`    ✓ ${msg}`);
 const warn = (msg) => console.log(`    ! ${msg}`);
@@ -41,6 +43,83 @@ const AGENT_RULE_PRESENT = {
     pi: () => hasManagedBlock((0, path_1.join)(HOME, '.pi', 'agent', 'AGENTS.md')),
     opencode: () => hasManagedBlock((0, path_1.join)(HOME, '.config', 'opencode', 'AGENTS.md')),
 };
+/**
+ * Where each agent records the MCP launch, and under which container key.
+ * `agent` matches the label `detectAgents` uses so one report never names the
+ * same agent two ways. Cursor/Windsurf/OpenCode are files the installer writes
+ * itself; the Gemini row is READ-ONLY — `zeph install` shells out to
+ * `gemini mcp add`, so this path is the gemini CLI's own storage layout,
+ * confirmed by reading the file it produced, not something Zeph chose.
+ */
+const MCP_REGISTRIES = [
+    { agent: 'Cursor', path: (0, path_1.join)(HOME, '.cursor', 'mcp.json'), key: 'mcpServers' },
+    { agent: 'Windsurf', path: (0, path_1.join)(HOME, '.codeium', 'windsurf', 'mcp_config.json'), key: 'mcpServers' },
+    { agent: 'Gemini CLI', path: (0, path_1.join)(HOME, '.gemini', 'settings.json'), key: 'mcpServers' },
+    { agent: 'OpenCode', path: (0, path_1.join)(HOME, '.config', 'opencode', 'opencode.json'), key: 'mcp' },
+];
+/**
+ * The launch argv a registry file records for zeph, verbatim — null when the
+ * file is absent, unparseable, or has no zeph entry. Two schemas in the wild:
+ * `command` + `args` (Cursor/Windsurf/Gemini) and `command` as a whole array
+ * (opencode). Returned as-is on purpose: a stale entry is only detectable if
+ * the reader does not normalize it into the shape it expects.
+ */
+const registeredMcpArgv = (filePath, key) => {
+    let data;
+    try {
+        data = JSON.parse((0, fs_1.readFileSync)(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    const container = data[key];
+    const entry = container?.zeph;
+    if (!entry)
+        return null;
+    if (Array.isArray(entry.command))
+        return entry.command.map(String);
+    if (typeof entry.command !== 'string')
+        return null;
+    return [entry.command, ...(Array.isArray(entry.args) ? entry.args.map(String) : [])];
+};
+exports.registeredMcpArgv = registeredMcpArgv;
+/**
+ * Can this launch binary actually be run? Registered commands come out of a
+ * config file, so they can be an absolute path with spaces in it — the shared
+ * `hasCommand` interpolates into `which ${cmd}`, where such a path splits into
+ * two words and reports a perfectly good binary as missing (and where any `;`
+ * in the file would reach the shell). Nothing here touches a shell.
+ */
+const binaryResolves = (bin) => {
+    try {
+        if (bin.includes('/'))
+            (0, fs_1.accessSync)(bin, fs_1.constants.X_OK);
+        else
+            (0, child_process_1.execFileSync)('which', [bin], { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+exports.binaryResolves = binaryResolves;
+/** null = this agent has no zeph registration at all, so there is nothing to report. */
+const classifyMcpRegistration = (argv, isOnPath) => {
+    if (!argv || argv.length === 0)
+        return null;
+    if (!isOnPath(argv[0]))
+        return { state: 'unresolvable', argv };
+    const isCanonical = argv.length === mcp_command_js_1.MCP_LAUNCH_ARGV.length
+        && argv.every((token, i) => token === mcp_command_js_1.MCP_LAUNCH_ARGV[i]);
+    return isCanonical ? { state: 'current' } : { state: 'stale', argv };
+};
+exports.classifyMcpRegistration = classifyMcpRegistration;
+/** The registries that actually hold a zeph entry, classified. Agents that were
+ *  never installed drop out here so the report has no row for them. */
+const activeMcpRegistrations = (isOnPath) => MCP_REGISTRIES.flatMap((registry) => {
+    const result = (0, exports.classifyMcpRegistration)((0, exports.registeredMcpArgv)(registry.path, registry.key), isOnPath);
+    return result ? [{ agent: registry.agent, result }] : [];
+});
 const handleVerify = async (args) => {
     const doPing = args.ping === true;
     const checks = [];
@@ -64,12 +143,28 @@ const handleVerify = async (args) => {
         ? 'ZEPH_HOOK_ID is set (two-way zeph_ask/prompt/input enabled)'
         : 'ZEPH_HOOK_ID not set (notify-only — set it for remote control)', hookId ? 'pass' : 'warn');
     // ── Runtime ──────────────────────────────────────────────────
+    // One resolution per binary: `zeph` alone was being looked up five times
+    // (twice here, once per registry below), and each lookup is a spawn.
+    const resolved = new Map();
+    const resolves = (bin) => {
+        const cached = resolved.get(bin);
+        if (cached !== undefined)
+            return cached;
+        const found = (0, exports.binaryResolves)(bin);
+        resolved.set(bin, found);
+        return found;
+    };
     console.log('\n  Runtime:');
-    record((0, agents_js_1.hasCommand)('node') ? 'node available' : 'node not found', (0, agents_js_1.hasCommand)('node') ? 'pass' : 'fail');
-    record((0, agents_js_1.hasCommand)('npx') ? 'npx available (MCP server runs via npx)' : 'npx not found', (0, agents_js_1.hasCommand)('npx') ? 'pass' : 'fail');
-    record((0, agents_js_1.hasCommand)('zeph')
-        ? 'zeph CLI on PATH'
-        : 'zeph CLI not on PATH (hooks fall back to npx — slower first call)', (0, agents_js_1.hasCommand)('zeph') ? 'pass' : 'warn');
+    const hasNode = resolves('node');
+    const hasNpx = resolves('npx');
+    const hasZeph = resolves('zeph');
+    record(hasNode ? 'node available' : 'node not found', hasNode ? 'pass' : 'fail');
+    record(hasNpx ? 'npx available (hook fallback when zeph is off PATH)' : 'npx not found', hasNpx ? 'pass' : 'warn');
+    // Not a warning any more: `zeph mcp` IS the MCP server, so a zeph that
+    // isn't on PATH means no MCP tools at all, not just a slower first call.
+    record(hasZeph
+        ? 'zeph CLI on PATH (runs the MCP server and the hooks)'
+        : 'zeph CLI not on PATH — MCP tools will not start. Reinstall: npm i -g @zeph-to/cli', hasZeph ? 'pass' : 'fail');
     // ── Login-time service ───────────────────────────────────────
     // Optional, so a missing one is a warning. A broken one is not: every way
     // it breaks still looks installed from the outside.
@@ -79,6 +174,21 @@ const handleVerify = async (args) => {
         for (const row of serviceRows)
             record(row.label, row.state);
     }
+    // ── MCP registrations ────────────────────────────────────────
+    const registrations = activeMcpRegistrations(resolves);
+    if (registrations.length > 0) {
+        console.log('\n  MCP registrations:');
+        for (const { agent, result } of registrations) {
+            if (result.state === 'current')
+                record(`${agent}: launches \`${mcp_command_js_1.MCP_LAUNCH_ARGV.join(' ')}\``, 'pass');
+            else if (result.state === 'stale') {
+                record(`${agent}: still launches \`${result.argv.join(' ')}\` — one extra resident process per session. Re-run: zeph install`, 'warn');
+            }
+            else {
+                record(`${agent}: launches \`${result.argv[0]}\`, which is not on PATH — zeph tools will not load. Re-run: zeph install`, 'fail');
+            }
+        }
+    }
     // ── Per-agent config ─────────────────────────────────────────
     console.log('\n  Agents:');
     const detected = (0, agents_js_1.detectAgents)().filter((a) => a.detected);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeph-to/cli",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "Zeph CLI + push notification SDK for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -72,6 +72,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.3",
+    "@zeph-to/mcp-server": "^2.3.0",
     "ws": "^8.21.0"
   }
 }