@heliyos/heliyos-mcp 1.0.3 → 1.0.4

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "heliyos",
   "displayName": "Heliyos",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Heliyos, the AI operating system for revenue, for your agent: customer records, notes, tasks, Scouts, reviews, knowledge and AI workers, through the Heliyos API with an API key.",
   "author": {
     "name": "Heliyos",

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "heliyos",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Heliyos, the AI operating system for revenue, for your agent: customer records, notes, tasks, Scouts, reviews, knowledge and AI workers.",
   "author": {
     "name": "Heliyos"

package/README.md

@@ -83,13 +83,15 @@ Every client runs the same command, `npx -y @heliyos/heliyos-mcp`, with your key
 
 ### Claude Code
 
-Install the plugin. It asks for your key and keeps it in your system's secure credential store, and it adds a skill that teaches Claude when to use which tool.
+Install the plugin and set your key in one go. The key goes into your system's secure credential store, never into a file, and the plugin adds a skill that teaches Claude when to use which tool.
 
 ```sh
 claude plugin marketplace add heliyos-ai/heliyos-mcp
-claude plugin install heliyos@heliyos
+claude plugin install heliyos@heliyos --config api_key=YOUR_HELIYOS_API_KEY
 ```
 
+If you installed without `--config`, the server stays off until the key is set: run `/plugin configure heliyos@heliyos` inside Claude Code and enter it there. Then `/mcp` lists `heliyos`, or restart Claude Code if it does not.
+
 Or add only the MCP server:
 
 ```sh
@@ -431,7 +433,8 @@ Report a security issue privately through [GitHub security advisories](https://g
 | `FORBIDDEN_ACTION` | The workspace plan or billing status does not allow the action, or the action is not available to API keys. |
 | `RATE_LIMITED` | You are above 60 requests per minute. Wait a minute, and prefer list calls over many single gets. |
 | `heliyos_ask` times out | Raise the client's tool timeout (see [Tool timeout](#tool-timeout)). The run keeps going; follow it with `heliyos_runs_get`. |
-| The server does not start or shows no tools | Check `node -v` is 20 or later. The first start downloads the package, which can take longer than a 10 second startup timeout; raise it (Codex `startup_timeout_sec`, Claude Code `MCP_TIMEOUT`). Apps opened from the dock may not find `npx`; use its full path from `which npx`. |
+| The server shows "connecting" on its first start | The first `npx -y @heliyos/heliyos-mcp` downloads the package, which can take 20 to 30 seconds on a slow connection and outlast a client's startup timeout. Warm the cache once from a terminal with `npx -y @heliyos/heliyos-mcp --version`, then reconnect; later starts take about a second. Or raise the timeout (Codex `startup_timeout_sec`, Claude Code `MCP_TIMEOUT=60000`). |
+| `Node 16.x is too old` or tools fail with `fetch is not defined` | The client started `npx` with an old Node, usually a version manager's default. The server needs Node 20 or newer and restarts itself on the newest suitable Node it finds (nvm, fnm, n, Volta, Homebrew, PATH); the message names which one. If it finds none, install Node 20+ or run `nvm install 20 && nvm alias default 20`, then restart the client. Apps opened from the dock may not find `npx` at all; use its full path from `which npx`. |
 | Experimental tools are missing | Set `HELIYOS_MCP_EXPERIMENTAL=1` and restart the client. |
 
 Still stuck? Open an issue at [github.com/heliyos-ai/heliyos-mcp/issues](https://github.com/heliyos-ai/heliyos-mcp/issues). Never paste your key.

package/dist/src/bin/nodeRuntime.d.ts

@@ -0,0 +1,18 @@
+/** The lowest Node.js major the server supports (global fetch, Web Streams). */
+export declare const MIN_NODE_MAJOR = 20;
+/** The major version of a `vX.Y.Z` or `X.Y.Z` string, or 0 when unparsable. */
+export declare function majorOf(version: string): number;
+/** Compares two `vX.Y.Z` strings numerically; positive when `a` is newer. */
+export declare function compareVersions(a: string, b: string): number;
+/** Every `node` executable this machine is likely to have, deduplicated, unverified. */
+export declare function candidateNodes(env?: NodeJS.ProcessEnv, home?: string): string[];
+/** `node -v` of an executable, or undefined when it cannot be run. Bounded to a second. */
+export declare function versionOf(executable: string): string | undefined;
+/**
+ * The newest Node at or above `minMajor` among `candidates`, as `{path, version}`,
+ * or undefined when none qualifies. `probe` is injectable for tests.
+ */
+export declare function findNewerNode(candidates: string[], minMajor?: number, probe?: (executable: string) => string | undefined): {
+    path: string;
+    version: string;
+} | undefined;

package/dist/src/bin/nodeRuntime.js

@@ -0,0 +1,106 @@
+/**
+ * Picks a Node.js runtime the server can run on. Clients start the server with
+ * `npx`, which uses whatever `node` is first on their PATH; version managers
+ * such as nvm often leave an old default there (Node 16 has no global fetch),
+ * and the server would die before the MCP handshake with no useful message.
+ *
+ * `findNewerNode` looks in the places version managers and package managers
+ * install Node, verifies each candidate's version, and returns the newest one
+ * that meets the minimum. Everything here must run on old Node too, so it uses
+ * only long-standing APIs.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+/** The lowest Node.js major the server supports (global fetch, Web Streams). */
+export const MIN_NODE_MAJOR = 20;
+/** The major version of a `vX.Y.Z` or `X.Y.Z` string, or 0 when unparsable. */
+export function majorOf(version) {
+    const match = /^v?(\d+)\./.exec(version.trim());
+    return match ? Number(match[1]) : 0;
+}
+/** Compares two `vX.Y.Z` strings numerically; positive when `a` is newer. */
+export function compareVersions(a, b) {
+    const pa = a.replace(/^v/, "").split(".").map(Number);
+    const pb = b.replace(/^v/, "").split(".").map(Number);
+    for (let i = 0; i < 3; i += 1) {
+        const diff = (pa[i] || 0) - (pb[i] || 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+const EXE = process.platform === "win32" ? "node.exe" : "node";
+/** Directories that may hold one Node install each (`<dir>/<version>/bin/node`). */
+function versionManagerRoots(env, home) {
+    const fnmRoots = [
+        env.FNM_DIR,
+        join(home, ".fnm"),
+        join(home, ".local", "share", "fnm"),
+        join(home, "Library", "Application Support", "fnm"),
+        env.APPDATA ? join(env.APPDATA, "fnm") : undefined,
+    ].filter((p) => !!p);
+    return [
+        // nvm: ~/.nvm/versions/node/v20.15.0/bin/node
+        { root: join(env.NVM_DIR || join(home, ".nvm"), "versions", "node"), bin: process.platform === "win32" ? "" : "bin" },
+        // nvm-windows: %NVM_HOME%\v20.15.0\node.exe
+        ...(env.NVM_HOME ? [{ root: env.NVM_HOME, bin: "" }] : []),
+        // fnm: <root>/node-versions/v20.15.0/installation/bin/node
+        ...fnmRoots.map((r) => ({ root: join(r, "node-versions"), bin: join("installation", process.platform === "win32" ? "" : "bin") })),
+        // n: /usr/local/n/versions/node/20.15.0/bin/node
+        { root: join(env.N_PREFIX || "/usr/local", "n", "versions", "node"), bin: "bin" },
+        // Volta's shared tool images
+        { root: join(env.VOLTA_HOME || join(home, ".volta"), "tools", "image", "node"), bin: process.platform === "win32" ? "" : "bin" },
+    ];
+}
+/** Every `node` executable this machine is likely to have, deduplicated, unverified. */
+export function candidateNodes(env = process.env, home = homedir()) {
+    const found = [];
+    const add = (p) => {
+        if (p && !found.includes(p) && existsSync(p))
+            found.push(p);
+    };
+    for (const { root, bin } of versionManagerRoots(env, home)) {
+        let entries = [];
+        try {
+            entries = readdirSync(root);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries)
+            add(join(root, entry, bin, EXE));
+    }
+    for (const fixed of ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/opt/local/bin", join(home, ".volta", "bin")])
+        add(join(fixed, EXE));
+    for (const dir of (env.PATH || "").split(delimiter))
+        if (dir)
+            add(join(dir, EXE));
+    return found;
+}
+/** `node -v` of an executable, or undefined when it cannot be run. Bounded to a second. */
+export function versionOf(executable) {
+    try {
+        const out = execFileSync(executable, ["-v"], { encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "ignore"] });
+        return /^v\d+\.\d+\.\d+/.test(out.trim()) ? out.trim() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The newest Node at or above `minMajor` among `candidates`, as `{path, version}`,
+ * or undefined when none qualifies. `probe` is injectable for tests.
+ */
+export function findNewerNode(candidates, minMajor = MIN_NODE_MAJOR, probe = versionOf) {
+    let best;
+    for (const path of candidates) {
+        const version = probe(path);
+        if (!version || majorOf(version) < minMajor)
+            continue;
+        if (!best || compareVersions(version, best.version) > 0)
+            best = { path, version };
+    }
+    return best;
+}

package/dist/src/bin/serve.d.ts

@@ -0,0 +1,2 @@
+/** Reads the configuration from the environment and serves until the client disconnects. */
+export declare function main(): void;

package/dist/src/bin/serve.js

@@ -0,0 +1,30 @@
+/**
+ * Starts the MCP server over stdio. Loaded by bin/stdio.ts only after the Node
+ * version check, because the imports below need Node 20 or newer.
+ */
+import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { createClient } from "../client/http.js";
+import { ConfigError, loadConfig } from "../config.js";
+import { createServer } from "../index.js";
+/** Reads the configuration from the environment and serves until the client disconnects. */
+export function main() {
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (err) {
+        if (err instanceof ConfigError) {
+            process.stderr.write(`heliyos-mcp: ${err.message}\n`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    const client = createClient({ baseUrl: config.baseUrl, apiKey: config.apiKey });
+    const options = { experimental: config.experimental };
+    // serveStdio picks the protocol era from the client's opening message and
+    // pins one server instance from the factory for the connection.
+    serveStdio(() => createServer(client, options), {
+        transport: new StdioServerTransport(),
+        onerror: (error) => process.stderr.write(`heliyos-mcp: ${error.message}\n`),
+    });
+}

package/dist/src/bin/stdio.js

@@ -2,30 +2,63 @@
 /**
  * stdio entry point: `npx -y @heliyos/heliyos-mcp`. stdout carries MCP protocol
  * messages only; diagnostics go to stderr and never include the API key.
+ *
+ * The server needs Node 20 or newer, but `npx` runs whatever `node` is first
+ * on the client's PATH, which with version managers is often an old default.
+ * So this file does nothing version-specific itself: it checks the running
+ * Node first and, when it is too old, re-executes the server on the newest
+ * suitable Node it can find on the machine (nvm, fnm, n, Volta, Homebrew,
+ * PATH), passing stdio straight through. Only then does it load the server.
  */
-import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
-import { createClient } from "../client/http.js";
-import { ConfigError, loadConfig } from "../config.js";
-import { createServer } from "../index.js";
-function main() {
-    let config;
-    try {
-        config = loadConfig();
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { PACKAGE_NAME, PACKAGE_VERSION } from "../version.js";
+import { candidateNodes, findNewerNode, majorOf, MIN_NODE_MAJOR } from "./nodeRuntime.js";
+/** Set on the re-executed child so a still-too-old Node can never loop. */
+const REEXEC_FLAG = "HELIYOS_MCP_REEXEC";
+function log(message) {
+    process.stderr.write(`heliyos-mcp: ${message}\n`);
+}
+/**
+ * Runs the server on another Node executable with this process's stdio and
+ * environment, and exits with the child's exit code.
+ */
+function reexec(nodePath, version) {
+    log(`Node ${process.versions.node} is too old (needs ${MIN_NODE_MAJOR}+); restarting on Node ${version} at ${nodePath}`);
+    const child = spawn(nodePath, [fileURLToPath(import.meta.url)], {
+        stdio: "inherit",
+        env: { ...process.env, [REEXEC_FLAG]: "1" },
+    });
+    child.on("error", (err) => {
+        log(`could not start ${nodePath}: ${err.message}`);
+        process.exit(1);
+    });
+    child.on("exit", (code, signal) => {
+        if (signal)
+            process.kill(process.pid, signal);
+        process.exit(code ?? 1);
+    });
+}
+async function start() {
+    // `--version` answers without starting a server, so a client setup can warm
+    // the npx cache (`npx -y @heliyos/heliyos-mcp --version`) ahead of the first run.
+    if (process.argv.includes("--version") || process.argv.includes("-v")) {
+        process.stdout.write(`${PACKAGE_NAME} ${PACKAGE_VERSION} (node ${process.versions.node})\n`);
+        return;
     }
-    catch (err) {
-        if (err instanceof ConfigError) {
-            process.stderr.write(`heliyos-mcp: ${err.message}\n`);
-            process.exit(1);
+    if (majorOf(process.versions.node) < MIN_NODE_MAJOR) {
+        const newer = process.env[REEXEC_FLAG] ? undefined : findNewerNode(candidateNodes());
+        if (newer) {
+            reexec(newer.path, newer.version);
+            return;
         }
-        throw err;
+        log(`Node ${process.versions.node} is too old: this server needs Node ${MIN_NODE_MAJOR} or newer and found no newer Node on this machine. ` +
+            "Install Node 20+ (https://nodejs.org) or, with nvm, run `nvm install 20 && nvm alias default 20`, then restart your client.");
+        process.exit(1);
     }
-    const client = createClient({ baseUrl: config.baseUrl, apiKey: config.apiKey });
-    const options = { experimental: config.experimental };
-    //  serveStdio picks the protocol era from the client's opening message and
-    //  pins one server instance from the factory for the connection.
-    serveStdio(() => createServer(client, options), {
-        transport: new StdioServerTransport(),
-        onerror: (error) => process.stderr.write(`heliyos-mcp: ${error.message}\n`),
-    });
+    // Loaded only once the runtime is known to be new enough: these modules use
+    // global fetch and other APIs an old Node would fail on at import time.
+    const { main } = await import("./serve.js");
+    main();
 }
-main();
+void start();

package/dist/src/version.d.ts

@@ -1,4 +1,4 @@
 /** The npm package name, for the User-Agent header. */
 export declare const PACKAGE_NAME = "@heliyos/heliyos-mcp";
 /** The package version, for the User-Agent header and the MCP server info. */
-export declare const PACKAGE_VERSION = "1.0.3";
+export declare const PACKAGE_VERSION = "1.0.4";

package/dist/src/version.js

@@ -4,4 +4,4 @@
 /** The npm package name, for the User-Agent header. */
 export const PACKAGE_NAME = "@heliyos/heliyos-mcp";
 /** The package version, for the User-Agent header and the MCP server info. */
-export const PACKAGE_VERSION = "1.0.3";
+export const PACKAGE_VERSION = "1.0.4";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heliyos/heliyos-mcp",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Model Context Protocol server for Heliyos, the AI operating system for revenue. Gives AI agents tools for customer records, notes, tasks, email and meeting history, Scouts and signals, reviews, workers and the knowledge base, over stdio with a workspace API key.",
   "type": "module",
   "mcpName": "ai.heliyos/heliyos-mcp",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "heliyos",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Heliyos, the AI operating system for revenue, for your agent: customer records, notes, tasks, Scouts, reviews, knowledge and AI workers. Set HELIYOS_API_KEY in the environment the client starts servers with.",
   "author": {
     "name": "Heliyos",

package/server.json

@@ -3,7 +3,7 @@
   "name": "ai.heliyos/heliyos-mcp",
   "title": "Heliyos",
   "description": "Heliyos, the AI operating system for revenue: records, notes, tasks, Scouts and AI workers.",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "websiteUrl": "https://docs.heliyos.ai/mcp/overview",
   "repository": {
     "url": "https://github.com/heliyos-ai/heliyos-mcp",
@@ -14,7 +14,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@heliyos/heliyos-mcp",
-      "version": "1.0.3",
+      "version": "1.0.4",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"