Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

fix(mcp): resolve installed CLI before npx fallback

Rudy Celekli982936e2bf8c
diff --git a/plugins/ruflo-core/README.md b/plugins/ruflo-core/README.md
index 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 contract
diff --git a/plugins/ruflo-core/scripts/mcp-launch.cjs b/plugins/ruflo-core/scripts/mcp-launch.cjs
index 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.cjs
index 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 dist
const 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/,
+ );
+});