@agilemonster/mcp-server 1.0.24 → 1.0.26

package/dist/service.js

@@ -0,0 +1,327 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { agileMonsterHome, exec, which } from './runtime.js';
+/**
+ * Runs the card runner as a background service that starts with the computer.
+ *
+ * Without this, cards queued from the board are only worked while an AI coding tool happens to be open in
+ * the project folder (its MCP server pulses as a side effect). People do not know that, so their first card
+ * sits in "queued" for ever. `bootstrap` installs the service; `service install|status|uninstall` manage it.
+ *
+ * The service runs its own copy of the package from ~/.agilemonster/runner, so it does not depend on an npx
+ * cache that can be cleared or on a project folder that can move, and it updates that copy itself.
+ *
+ * macOS: a launchd agent. Linux: a systemd user unit. Windows: not yet.
+ */
+export const SERVICE_LABEL = 'com.agilemonster.pulse';
+export const SYSTEMD_UNIT = 'agilemonster-runner.service';
+const PACKAGE = '@agilemonster/mcp-server';
+/**
+ * The node binary the service should start. `process.execPath` is often a versioned folder (Homebrew's
+ * Cellar/node@24/24.21.0_1/…) that disappears with the next upgrade and would leave the service unable to
+ * start; the `node` on PATH is a stable link to the same binary, so prefer it when it is the same one.
+ */
+export function stableNodePath() {
+    const onPath = which('node');
+    if (onPath) {
+        try {
+            if (fs.realpathSync(onPath) === fs.realpathSync(process.execPath))
+                return onPath;
+        }
+        catch { }
+    }
+    return process.execPath;
+}
+export function defaultServiceDeps() {
+    return {
+        platform: process.platform,
+        home: os.homedir(),
+        amHome: agileMonsterHome(),
+        uid: typeof process.getuid === 'function' ? process.getuid() : null,
+        node: stableNodePath(),
+        npm: which('npm'),
+        pathEnv: process.env.PATH || '',
+        exec,
+    };
+}
+export function runnerDir(amHome) {
+    return path.join(amHome, 'runner');
+}
+/** The service's own copy of this package's entry point. */
+export function runnerEntry(amHome) {
+    return path.join(runnerDir(amHome), 'node_modules', '@agilemonster', 'mcp-server', 'bin', 'mcp.js');
+}
+export function serviceKind(platform) {
+    if (platform === 'darwin')
+        return 'launchd';
+    if (platform === 'linux')
+        return 'systemd';
+    return null;
+}
+export function unitPath(kind, home) {
+    return kind === 'launchd'
+        ? path.join(home, 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`)
+        : path.join(home, '.config', 'systemd', 'user', SYSTEMD_UNIT);
+}
+function xml(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+export function launchdPlist(o) {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${xml(o.node)}</string>
+    <string>${xml(o.entry)}</string>
+    <string>pulse-daemon</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xml(o.home)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>HOME</key>
+    <string>${xml(o.home)}</string>
+    <key>PATH</key>
+    <string>${xml(o.pathEnv)}</string>
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>15</integer>
+  <key>StandardOutPath</key>
+  <string>${xml(path.join(o.logDir, 'pulse-daemon.log'))}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(path.join(o.logDir, 'pulse-daemon.err.log'))}</string>
+</dict>
+</plist>
+`;
+}
+/** systemd splits ExecStart on spaces; a path with one must be quoted, and a literal % doubled. */
+function systemdArg(value) {
+    const escaped = value.replace(/%/g, '%%').replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return /[\s"']/.test(value) ? `"${escaped}"` : escaped;
+}
+export function systemdUnit(o) {
+    return `[Unit]
+Description=Agile Monster card runner
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=${systemdArg(o.node)} ${systemdArg(o.entry)} pulse-daemon
+WorkingDirectory=${o.home}
+Environment=${systemdArg(`PATH=${o.pathEnv}`)}
+Restart=always
+RestartSec=15
+StandardOutput=append:${path.join(o.logDir, 'pulse-daemon.log')}
+StandardError=append:${path.join(o.logDir, 'pulse-daemon.err.log')}
+
+[Install]
+WantedBy=default.target
+`;
+}
+/** The program an existing unit file starts (the script after the node binary), or null when unreadable. */
+export function unitTarget(kind, content) {
+    if (kind === 'launchd') {
+        const block = content.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+        if (!block)
+            return null;
+        const args = Array.from(block[1].matchAll(/<string>([\s\S]*?)<\/string>/g)).map((m) => m[1].replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&'));
+        return args.find((a) => /mcp\.js$/.test(a)) || args[1] || args[0] || null;
+    }
+    const line = content.match(/^ExecStart=(.*)$/m);
+    if (!line)
+        return null;
+    const parts = line[1].match(/"(?:[^"\\]|\\.)*"|\S+/g) || [];
+    const clean = parts.map((p) => (p.startsWith('"') ? p.slice(1, -1).replace(/\\(["\\])/g, '$1') : p).replace(/%%/g, '%'));
+    return clean.find((a) => /mcp\.js$/.test(a)) || clean[1] || clean[0] || null;
+}
+export async function serviceStatus(deps = defaultServiceDeps()) {
+    const kind = serviceKind(deps.platform);
+    if (!kind)
+        return { supported: false, kind: null, unitPath: null, installed: false, managed: false, target: null, running: false };
+    const file = unitPath(kind, deps.home);
+    let content = '';
+    try {
+        content = fs.readFileSync(file, 'utf8');
+    }
+    catch { }
+    const installed = content !== '';
+    const target = installed ? unitTarget(kind, content) : null;
+    const managed = !!target && path.resolve(target) === path.resolve(runnerEntry(deps.amHome));
+    let running = false;
+    if (installed) {
+        if (kind === 'launchd') {
+            const res = deps.uid === null ? null : await deps.exec('launchctl', ['print', `gui/${deps.uid}/${SERVICE_LABEL}`], { timeoutMs: 15000 });
+            running = !!res && res.ok && /state = running/.test(res.stdout);
+        }
+        else {
+            const res = await deps.exec('systemctl', ['--user', 'is-active', SYSTEMD_UNIT], { timeoutMs: 15000 });
+            running = res.stdout.trim() === 'active';
+        }
+    }
+    return { supported: true, kind, unitPath: file, installed, managed, target, running };
+}
+const KEEP_OPEN_HINT = 'Until then, cards are worked while your AI coding tool is open in the project folder, or while this runs in a terminal: npx -y @agilemonster/mcp-server pulse-daemon';
+export async function installService(options, deps = defaultServiceDeps()) {
+    const kind = serviceKind(deps.platform);
+    if (!kind) {
+        return {
+            ok: false,
+            outcome: 'unsupported',
+            message: `The background runner cannot be installed as a service on this system yet (${deps.platform}). ${KEEP_OPEN_HINT}`,
+        };
+    }
+    if (!options.hasApiKey) {
+        return {
+            ok: false,
+            outcome: 'failed',
+            message: 'No API key is saved on this computer yet. Run `npx -y @agilemonster/mcp-server bootstrap` in your project folder first.',
+        };
+    }
+    const status = await serviceStatus(deps);
+    if (status.installed && !status.managed && !options.force) {
+        return {
+            ok: true,
+            outcome: 'kept',
+            message: `A background runner is already set up on this computer (${status.target || status.unitPath}), so it was left as it is.` +
+                ' To replace it with the standard one: npx -y @agilemonster/mcp-server service install --force',
+        };
+    }
+    if (!deps.npm) {
+        return { ok: false, outcome: 'failed', message: `npm was not found, so the runner could not be installed. ${KEEP_OPEN_HINT}` };
+    }
+    if (kind === 'systemd') {
+        const probe = await deps.exec('systemctl', ['--user', 'show-environment'], { timeoutMs: 15000 });
+        if (!probe.ok) {
+            return {
+                ok: false,
+                outcome: 'unsupported',
+                message: `This system has no systemd user session, so the background runner could not be installed as a service. ${KEEP_OPEN_HINT}`,
+            };
+        }
+    }
+    // 1. The service's own copy of the package
+    const dir = runnerDir(deps.amHome);
+    const entry = runnerEntry(deps.amHome);
+    const logDir = path.join(deps.amHome, 'logs');
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.mkdirSync(logDir, { recursive: true });
+        const manifest = path.join(dir, 'package.json');
+        if (!fs.existsSync(manifest)) {
+            fs.writeFileSync(manifest, JSON.stringify({ name: 'agilemonster-runner', private: true }, null, 2), 'utf8');
+        }
+    }
+    catch (err) {
+        return { ok: false, outcome: 'failed', message: `Could not create ${dir}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const install = await deps.exec(deps.npm, updateArgs(dir), { cwd: dir, timeoutMs: 5 * 60 * 1000 });
+    if (!install.ok || !fs.existsSync(entry)) {
+        return { ok: false, outcome: 'failed', message: `Installing the runner failed: ${install.tail || 'npm did not produce the package'}. ${KEEP_OPEN_HINT}` };
+    }
+    // 2. The unit that starts it
+    const file = unitPath(kind, deps.home);
+    const unitOptions = { node: deps.node, entry, home: deps.home, logDir, pathEnv: deps.pathEnv };
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, kind === 'launchd' ? launchdPlist(unitOptions) : systemdUnit(unitOptions), 'utf8');
+    }
+    catch (err) {
+        return { ok: false, outcome: 'failed', message: `Could not write ${file}: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    // 3. Start it now and at every login
+    if (kind === 'launchd') {
+        if (deps.uid === null)
+            return { ok: false, outcome: 'failed', message: 'Could not determine the current user to start the service for.' };
+        const domain = `gui/${deps.uid}`;
+        await deps.exec('launchctl', ['bootout', `${domain}/${SERVICE_LABEL}`], { timeoutMs: 20000 }); // an older copy; fine if absent
+        let start = await deps.exec('launchctl', ['bootstrap', domain, file], { timeoutMs: 20000 });
+        if (!start.ok)
+            start = await deps.exec('launchctl', ['load', '-w', file], { timeoutMs: 20000 });
+        if (!start.ok) {
+            return { ok: false, outcome: 'failed', message: `The runner was installed but macOS would not start it: ${start.tail}. Log out and in again, or run: launchctl load -w "${file}"` };
+        }
+    }
+    else {
+        await deps.exec('systemctl', ['--user', 'daemon-reload'], { timeoutMs: 20000 });
+        const start = await deps.exec('systemctl', ['--user', 'enable', '--now', SYSTEMD_UNIT], { timeoutMs: 30000 });
+        if (!start.ok) {
+            return { ok: false, outcome: 'failed', message: `The runner was installed but systemd would not start it: ${start.tail}` };
+        }
+        // Keep it running when nobody is logged in at the desktop (best effort: needs no password on most systems)
+        const user = os.userInfo().username;
+        if (which('loginctl'))
+            await deps.exec('loginctl', ['enable-linger', user], { timeoutMs: 15000 });
+    }
+    return {
+        ok: true,
+        outcome: 'installed',
+        message: 'The background runner is installed and running. It starts with this computer and works cards queued from the board, with no coding tool open.',
+    };
+}
+export async function uninstallService(options = {}, deps = defaultServiceDeps()) {
+    const status = await serviceStatus(deps);
+    if (!status.supported || !status.kind || !status.unitPath) {
+        return { ok: false, outcome: 'unsupported', message: 'There is no background runner service on this system.' };
+    }
+    if (!status.installed)
+        return { ok: true, outcome: 'absent', message: 'No background runner service is installed.' };
+    if (!status.managed && !options.force) {
+        return {
+            ok: true,
+            outcome: 'kept',
+            message: `The runner service on this computer was not installed by this command (${status.target || status.unitPath}), so it was left as it is. Add --force to remove it anyway.`,
+        };
+    }
+    if (status.kind === 'launchd') {
+        if (deps.uid !== null)
+            await deps.exec('launchctl', ['bootout', `gui/${deps.uid}/${SERVICE_LABEL}`], { timeoutMs: 20000 });
+    }
+    else {
+        await deps.exec('systemctl', ['--user', 'disable', '--now', SYSTEMD_UNIT], { timeoutMs: 30000 });
+    }
+    try {
+        fs.rmSync(status.unitPath, { force: true });
+        if (status.managed)
+            fs.rmSync(runnerDir(deps.amHome), { recursive: true, force: true });
+    }
+    catch (err) {
+        return { ok: false, outcome: 'failed', message: `Stopped the service but could not remove its files: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (status.kind === 'systemd')
+        await deps.exec('systemctl', ['--user', 'daemon-reload'], { timeoutMs: 20000 });
+    return { ok: true, outcome: 'removed', message: 'The background runner service was stopped and removed. Cards are no longer worked in the background on this computer.' };
+}
+/** npm arguments that install or update the service's own copy of the package. */
+export function updateArgs(dir, version = 'latest') {
+    return ['install', '--prefix', dir, '--no-audit', '--no-fund', '--loglevel=error', `${PACKAGE}@${version}`];
+}
+/**
+ * When this process is the service's own copy, the folder to update in place. Null for a copy started by
+ * npx, a global install or a source checkout: those update the way they were installed.
+ */
+export function managedRunnerDir(runningFile, amHome = agileMonsterHome()) {
+    const dir = runnerDir(amHome);
+    const resolved = path.resolve(runningFile);
+    return resolved.startsWith(path.resolve(dir) + path.sep) ? dir : null;
+}
+export async function describeService(deps = defaultServiceDeps()) {
+    const s = await serviceStatus(deps);
+    if (!s.supported)
+        return `Background runner: not available as a service on this system (${deps.platform}). ${KEEP_OPEN_HINT}`;
+    if (!s.installed)
+        return 'Background runner: not installed. Cards are worked only while your AI coding tool is open in the project folder.\nInstall it: npx -y @agilemonster/mcp-server service install';
+    const lines = [`Background runner: installed${s.running ? ' and running' : ', but not running right now'}.`];
+    lines.push(s.managed ? `  It starts with this computer and keeps itself up to date (${s.unitPath}).` : `  It was set up by hand and runs ${s.target || 'an unknown program'} (${s.unitPath}).`);
+    if (!s.running)
+        lines.push('  Start it again: npx -y @agilemonster/mcp-server service install' + (s.managed ? '' : ' --force'));
+    return lines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agilemonster/mcp-server",
-  "version": "1.0.24",
+  "version": "1.0.26",
   "type": "module",
   "description": "Official Model Context Protocol (MCP) server & Orchestrator for Agile Monster (Cursor, Claude Code, Antigravity, Codex, Hermes, Windsurf)",
   "main": "dist/server.js",
@@ -47,6 +47,9 @@
   ],
   "author": "Agile Monster",
   "license": "MIT",
+  "engines": {
+    "node": ">=18.14"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.6.1"
   },