🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
fix(mcp): resolve installed CLI before npx fallback
Rudy Celekli982936e2bf8c
diff --git a/plugins/ruflo-core/README.md b/plugins/ruflo-core/README.mdindex 7f6498a706..0d4ef26459 100644--- a/plugins/ruflo-core/README.md+++ b/plugins/ruflo-core/README.md@@ -19,11 +19,11 @@ Foundation plugin. Registers the `ruflo` MCP server (314 tools), provides three## Configuration-The MCP server starts automatically when this plugin is active. Override environment variables in `.mcp.json` as needed.+The MCP server starts automatically when this plugin is active. Its launcher uses a built `@claude-flow/cli` from the project, an ancestor `node_modules`, or a global npm install reachable from `PATH` before falling back to `npx @latest`. Set `RUFLO_MCP_CLI_OVERRIDE` to a built `@claude-flow/cli/bin/cli.js` for a nonstandard install; an invalid override fails instead of running another version. Set `RUFLO_MCP_SKIP_NPX=1` to refuse the unpinned fallback. Override environment variables in `.mcp.json` as needed.## Compatibility-- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor. The `.mcp.json` invocation uses `@latest` for dynamic resolution; the smoke contract verifies the resolved CLI matches the v3.6 line.+- **CLI:** `.mcp.json` invokes the launcher above. Its resolved local or global CLI determines the version; `@latest` is the fallback only when no built install resolves.- **Verification:** `bash plugins/ruflo-core/scripts/smoke.sh` is the contract.## MCP server contractdiff --git a/plugins/ruflo-core/scripts/mcp-launch.cjs b/plugins/ruflo-core/scripts/mcp-launch.cjsindex 50e184e970..bea4112e4b 100644--- a/plugins/ruflo-core/scripts/mcp-launch.cjs+++ b/plugins/ruflo-core/scripts/mcp-launch.cjs@@ -15,47 +15,84 @@* version a user separately pinned via `npm install @claude-flow/cli`* (ADR-382 Gap 3 / issue #2971).*- * Candidate list and the dist/src/index.js existence guard mirror+ * The dist/src/index.js existence guard mirrors* .claude/helpers/hook-handler.cjs's resolveCliBinForHook(): a* marketplace-plugin checkout is installed by `git clone`/`git pull`* with no build step, so bin/cli.js can be present on disk while* importing dist/src/index.js throws ERR_MODULE_NOT_FOUND on every real* command. Checking for dist/ alongside bin/ prevents that doomed* candidate from winning ahead of a real local install or the npx- * fallback.+ * fallback. RUFLO_MCP_CLI_OVERRIDE can pin a built bin/cli.js when+ * an install lives outside the standard project or global npm layouts;+ * RUFLO_MCP_SKIP_NPX=1 rejects an unpinned fallback.*/const { existsSync } = require('fs');-const { join, dirname } = require('path');+const { join, dirname, resolve, isAbsolute, delimiter } = require('path');const { spawn } = require('child_process');const os = require('os');const MCP_ARGS = ['mcp', 'start'];-function resolveLocalCliBin(cwd, home) {- const candidates = [- join(home, '.claude', 'plugins', 'marketplaces', 'ruflo', 'bin', 'cli.js'),- join(cwd, 'node_modules', '@claude-flow', 'cli', 'bin', 'cli.js'),- join(cwd, 'node_modules', 'ruflo', 'bin', 'cli.js'),- join(cwd, 'v3', '@claude-flow', 'cli', 'bin', 'cli.js'),- ];- for (const candidate of candidates) {- try {- const distEntry = join(dirname(candidate), '..', 'dist', 'src', 'index.js');- if (existsSync(candidate) && existsSync(distEntry)) {- return candidate;- }- } catch {- // try next candidate+function isRunnableCli(candidate) {+ try {+ const distEntry = join(dirname(candidate), '..', 'dist', 'src', 'index.js');+ return existsSync(candidate) && existsSync(distEntry);+ } catch {+ return false;+ }+}++function resolveLocalCliBin(cwd, home, env = process.env) {+ // An explicit pin must fail closed if it disappears; silently running+ // @latest instead would defeat the override's purpose.+ if (env.RUFLO_MCP_CLI_OVERRIDE) {+ const override = resolve(cwd, env.RUFLO_MCP_CLI_OVERRIDE);+ if (!isRunnableCli(override)) {+ throw new Error(`RUFLO_MCP_CLI_OVERRIDE is not a built @claude-flow/cli bin: ${override}`);}+ return override;+ }++ const candidates = [join(home, '.claude', 'plugins', 'marketplaces', 'ruflo', 'bin', 'cli.js')];+ // Node resolves node_modules from the current directory and its ancestors.+ // A literal cwd-only probe misses installs from every nested project dir.+ for (let dir = resolve(cwd); ; dir = dirname(dir)) {+ candidates.push(+ join(dir, 'node_modules', '@claude-flow', 'cli', 'bin', 'cli.js'),+ join(dir, 'node_modules', 'ruflo', 'node_modules', '@claude-flow', 'cli', 'bin', 'cli.js'),+ join(dir, 'node_modules', 'ruflo', 'bin', 'cli.js'),+ join(dir, 'v3', '@claude-flow', 'cli', 'bin', 'cli.js'),+ );+ if (dirname(dir) === dir) break;+ }++ // npm global installs live next to bin/ on POSIX and under the shim+ // directory on Windows. Probe PATH roots without spawning npm or npx.+ for (const binDir of String(env.PATH || env.Path || '').split(delimiter)) {+ if (!isAbsolute(binDir)) continue;+ const modulesDir = process.platform === 'win32'+ ? join(binDir, 'node_modules')+ : join(binDir, '..', 'lib', 'node_modules');+ candidates.push(+ join(modulesDir, '@claude-flow', 'cli', 'bin', 'cli.js'),+ join(modulesDir, 'ruflo', 'node_modules', '@claude-flow', 'cli', 'bin', 'cli.js'),+ join(modulesDir, 'claude-flow', 'node_modules', '@claude-flow', 'cli', 'bin', 'cli.js'),+ );+ }+ for (const candidate of candidates) {+ if (isRunnableCli(candidate)) return candidate;}return null;}-function buildLaunchSpec(localBin) {+function buildLaunchSpec(localBin, env = process.env) {if (localBin) {return { command: process.execPath, args: [localBin, ...MCP_ARGS], shell: false };}+ if (env.RUFLO_MCP_SKIP_NPX === '1') {+ throw new Error('No built local CLI found and RUFLO_MCP_SKIP_NPX=1 forbids the @latest fallback');+ }const npxCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';// Windows .cmd shims aren't directly executable via CreateProcess — they// need shell:true (or an explicit cmd.exe /c wrapper) or spawn throws@@ -92,8 +129,13 @@ function launch({ command, args, shell }) {}if (require.main === module) {- const localBin = resolveLocalCliBin(process.cwd(), os.homedir());- launch(buildLaunchSpec(localBin));+ try {+ const localBin = resolveLocalCliBin(process.cwd(), os.homedir());+ launch(buildLaunchSpec(localBin));+ } catch (error) {+ process.stderr.write(`[mcp-launch] ${error.message}\n`);+ process.exitCode = 1;+ }}module.exports = { resolveLocalCliBin, buildLaunchSpec, MCP_ARGS };diff --git a/plugins/ruflo-core/scripts/mcp-launch.test.cjs b/plugins/ruflo-core/scripts/mcp-launch.test.cjsindex 2bd2651c53..40d6b4426d 100644--- a/plugins/ruflo-core/scripts/mcp-launch.test.cjs+++ b/plugins/ruflo-core/scripts/mcp-launch.test.cjs@@ -17,6 +17,7 @@ const path = require('path');const { resolveLocalCliBin, buildLaunchSpec, MCP_ARGS } = require(path.join(__dirname, 'mcp-launch.cjs'));+const NO_GLOBAL_PATH = { PATH: '' };function makeCliInstall(root, { withDist } = { withDist: true }) {const binDir = path.join(root, 'bin');@@ -35,7 +36,7 @@ test('picks the node_modules/@claude-flow/cli candidate when it has a built distconst home = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-launch-home-'));try {const expected = makeCliInstall(path.join(cwd, 'node_modules', '@claude-flow', 'cli'));- const resolved = resolveLocalCliBin(cwd, home);+ const resolved = resolveLocalCliBin(cwd, home, NO_GLOBAL_PATH);assert.equal(resolved, expected);} finally {fs.rmSync(cwd, { recursive: true, force: true });@@ -53,7 +54,7 @@ test('skips a source-only checkout (bin/cli.js with no dist/) and falls through'{ withDist: false });const expected = makeCliInstall(path.join(cwd, 'node_modules', 'ruflo'));- const resolved = resolveLocalCliBin(cwd, home);+ const resolved = resolveLocalCliBin(cwd, home, NO_GLOBAL_PATH);assert.equal(resolved, expected);} finally {fs.rmSync(cwd, { recursive: true, force: true });@@ -66,7 +67,7 @@ test('resolves the v3/@claude-flow/cli in-repo candidate last', () => {const home = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-launch-home-'));try {const expected = makeCliInstall(path.join(cwd, 'v3', '@claude-flow', 'cli'));- const resolved = resolveLocalCliBin(cwd, home);+ const resolved = resolveLocalCliBin(cwd, home, NO_GLOBAL_PATH);assert.equal(resolved, expected);} finally {fs.rmSync(cwd, { recursive: true, force: true });@@ -78,7 +79,59 @@ test('returns null when no candidate resolves', () => {const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-launch-'));const home = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-launch-home-'));try {- assert.equal(resolveLocalCliBin(cwd, home), null);+ assert.equal(resolveLocalCliBin(cwd, home, NO_GLOBAL_PATH), null);+ } finally {+ fs.rmSync(cwd, { recursive: true, force: true });+ fs.rmSync(home, { recursive: true, force: true });+ }+});++test('finds an installed CLI in an ancestor node_modules from a nested cwd', () => {+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-launch-root-'));+ const home = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-launch-home-'));+ try {+ const cwd = path.join(root, 'packages', 'app', 'src');+ fs.mkdirSync(cwd, { recursive: true });+ const expected = makeCliInstall(path.join(root, 'node_modules', '@claude-flow', 'cli'));+ assert.equal(resolveLocalCliBin(cwd, home, NO_GLOBAL_PATH), expected);+ } finally {+ fs.rmSync(root, { recursive: true, force: true });+ fs.rmSync(home, { recursive: true, force: true });+ }+});++test('finds a built globally installed ruflo dependency from PATH', () => {+ const prefix = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-launch-prefix-'));+ const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-launch-cwd-'));+ const home = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-launch-home-'));+ try {+ const binDir = process.platform === 'win32' ? prefix : path.join(prefix, 'bin');+ const modulesDir = process.platform === 'win32'+ ? path.join(prefix, 'node_modules')+ : path.join(prefix, 'lib', 'node_modules');+ fs.mkdirSync(binDir, { recursive: true });+ const expected = makeCliInstall(path.join(modulesDir, 'ruflo', 'node_modules', '@claude-flow', 'cli'));+ assert.equal(resolveLocalCliBin(cwd, home, { PATH: binDir }), expected);+ } finally {+ fs.rmSync(prefix, { recursive: true, force: true });+ fs.rmSync(cwd, { recursive: true, force: true });+ fs.rmSync(home, { recursive: true, force: true });+ }+});++test('an explicit CLI override is preferred and an invalid override cannot fall back to @latest', () => {+ const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-launch-cwd-'));+ const home = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-launch-home-'));+ try {+ const override = makeCliInstall(path.join(cwd, 'pinned-cli'));+ const other = makeCliInstall(path.join(cwd, 'node_modules', '@claude-flow', 'cli'));+ assert.notEqual(override, other);+ assert.equal(resolveLocalCliBin(cwd, home, {+ PATH: '', RUFLO_MCP_CLI_OVERRIDE: override,+ }), override);+ assert.throws(() => resolveLocalCliBin(cwd, home, {+ PATH: '', RUFLO_MCP_CLI_OVERRIDE: path.join(cwd, 'missing-cli.js'),+ }), /RUFLO_MCP_CLI_OVERRIDE/);} finally {fs.rmSync(cwd, { recursive: true, force: true });fs.rmSync(home, { recursive: true, force: true });@@ -93,7 +146,7 @@ test('buildLaunchSpec uses process.execPath + the resolved bin plus "mcp start"});test('buildLaunchSpec falls back to npx -y @claude-flow/cli@latest mcp start when nothing resolves', () => {- const spec = buildLaunchSpec(null);+ const spec = buildLaunchSpec(null, {});const expectedCmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';assert.equal(spec.command, expectedCmd);assert.deepEqual(spec.args, ['-y', '@claude-flow/cli@latest', ...MCP_ARGS]);@@ -101,3 +154,10 @@ test('buildLaunchSpec falls back to npx -y @claude-flow/cli@latest mcp start whe// spawn npx directly with no shell involved.assert.equal(spec.shell, process.platform === 'win32');});++test('RUFLO_MCP_SKIP_NPX=1 refuses an unpinned fallback', () => {+ assert.throws(+ () => buildLaunchSpec(null, { RUFLO_MCP_SKIP_NPX: '1' }),+ /RUFLO_MCP_SKIP_NPX=1 forbids/,+ );+});