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): mcp start -t http exits after false-success table + doc drift from #2985 (#2987)

rUv87f4f8ab6736
diff --git a/README.md b/README.md
index bddc8522a5..92c8620461 100644
--- a/README.md
+++ b/README.md
@@ -56,7 +56,7 @@ There are **two different install paths** with very different surface areas. Pic
|---|---|---|
| What it gives you | Slash commands + a few skills + agent definitions per-plugin | Full Ruflo loop β€” 98 agents, 60+ commands, 30 skills, MCP server, hooks, daemon |
| Files in your workspace | **Zero** | `.claude/`, `.claude-flow/`, `CLAUDE.md`, helpers, settings |
-| MCP server registered | **No** (`memory_store`, `swarm_init`, etc. unavailable to Claude) | Yes |
+| MCP server registered | Only if `ruflo-core` is installed (it ships its own `.mcp.json`) β€” most other plugins don't | Yes |
| Hooks installed | No | Yes |
| Best for | Try a single plugin's commands without committing to the full install | Production use β€” everything works as documented |
@@ -73,7 +73,7 @@ There are **two different install paths** with very different surface areas. Pic
/plugin install ruflo-neural-trader@ruflo
```
-This adds slash commands and agent definitions only. The Ruflo MCP server is NOT registered, so `memory_store`, `swarm_init`, `agent_spawn`, etc. won't be callable from Claude. For the full loop, use Path B below.
+This adds slash commands and agent definitions. `ruflo-core` (installed above) does register its own MCP server on install β€” its tools are callable as `mcp__plugin_ruflo-core_ruflo__*` (e.g. `mcp__plugin_ruflo-core_ruflo__memory_store`), not the bare `memory_store`/`swarm_init`/`agent_spawn` names the CLI-track scaffold uses. Other plugins generally don't ship their own MCP server. For the full loop with the CLI-track tool names, use Path B below.
<details>
<summary><strong>πŸ”Œ All 35 plugins</strong></summary>
@@ -187,8 +187,8 @@ npm install -g ruflo@latest
### MCP Server
```bash
-# Add Ruflo as an MCP server in Claude Code (canonical form, matches USERGUIDE.md)
-claude mcp add ruflo -- npx ruflo@latest mcp start
+# Add Ruflo as an MCP server in Claude Code
+claude mcp add claude-flow -- npx ruflo@latest mcp start
```
---
diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md
index 0e97ec256b..88abaeab12 100644
--- a/docs/USERGUIDE.md
+++ b/docs/USERGUIDE.md
@@ -768,8 +768,8 @@ The `--add-missing` flag automatically detects and installs new skills, agents,
Add ruflo as an MCP server for seamless integration:
```bash
-# Add ruflo MCP server to Claude Code
-claude mcp add ruflo -- npx -y ruflo@latest mcp start
+# Add ruflo MCP server to Claude Code (canonical key is claude-flow β€” #2206)
+claude mcp add claude-flow -- npx -y ruflo@latest mcp start
# Verify installation
claude mcp list
@@ -1295,11 +1295,11 @@ Restart Claude Desktop after saving. Look for the MCP indicator (hammer icon) in
<summary>⌨️ <strong>Claude Code (CLI)</strong></summary>
```bash
-# Add via CLI (recommended)
-claude mcp add ruflo -- npx ruflo@latest mcp start
+# Add via CLI (recommended; canonical key is claude-flow β€” #2206)
+claude mcp add claude-flow -- npx ruflo@latest mcp start
# Or add with environment variables
-claude mcp add ruflo \
+claude mcp add claude-flow \
--env ANTHROPIC_API_KEY=sk-ant-... \
-- npx ruflo@latest mcp start
diff --git a/v3/@claude-flow/cli/__tests__/mcp-http-foreground-2984.test.ts b/v3/@claude-flow/cli/__tests__/mcp-http-foreground-2984.test.ts
new file mode 100644
index 0000000000..785717a28a
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/mcp-http-foreground-2984.test.ts
@@ -0,0 +1,103 @@
+// #2984: `ruflo mcp start -t http` printed a full "Status: Running" success
+// table β€” PID, health/RPC URLs β€” then exited with code 0 within seconds,
+// without ever binding the port. Root cause: bin/cli.js's "normal CLI mode"
+// branch (which `-t http` always takes, since it disqualifies the implicit
+// piped-stdin MCP auto-detect) unconditionally exits the process once the
+// dispatched command's action() promise resolves (#1552). mcp.ts's `start`
+// action returned normally right after printing the table, so the freshly
+// bound http.Server was torn down within milliseconds of the printed
+// success claim β€” `lsof`/`curl` against the advertised port both showed
+// nothing was ever actually listening.
+//
+// This is an end-to-end guard: it spawns the built CLI exactly like the bug
+// report, confirms the port is actually accepting connections *after* the
+// success table prints (not just that the table printed), and confirms
+// SIGTERM still produces a clean shutdown (proving the fix blocks forever
+// rather than hanging unkillably).
+//
+// Skipped when the CLI has not been built (`bin/cli.js` absent) β€” same
+// convention as memory-search-recall-2558.test.ts.
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { createConnection } from 'node:net';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const CLI = path.resolve(HERE, '..', 'bin', 'cli.js');
+const CLI_BUILT = fs.existsSync(CLI);
+
+let child: ChildProcessWithoutNullStreams | undefined;
+
+afterEach(async () => {
+ if (child && child.exitCode === null && child.signalCode === null) {
+ child.kill('SIGKILL');
+ }
+ child = undefined;
+});
+
+function waitForOutput(proc: ChildProcessWithoutNullStreams, match: string, timeoutMs: number): Promise<void> {
+ return new Promise((resolve, reject) => {
+ let buf = '';
+ const timer = setTimeout(() => reject(new Error(`timed out waiting for "${match}" in: ${buf}`)), timeoutMs);
+ const onData = (chunk: Buffer) => {
+ buf += chunk.toString();
+ if (buf.includes(match)) {
+ clearTimeout(timer);
+ proc.stdout.off('data', onData);
+ resolve();
+ }
+ };
+ proc.stdout.on('data', onData);
+ });
+}
+
+function tcpConnects(port: number, host: string, timeoutMs: number): Promise<boolean> {
+ return new Promise((resolve) => {
+ const socket = createConnection({ host, port }, () => {
+ socket.destroy();
+ resolve(true);
+ });
+ socket.on('error', () => resolve(false));
+ socket.setTimeout(timeoutMs, () => {
+ socket.destroy();
+ resolve(false);
+ });
+ });
+}
+
+describe.skipIf(!CLI_BUILT)('mcp start -t http stays running (#2984, end-to-end)', () => {
+ it('keeps the process alive and the port actually bound after printing success, then exits cleanly on SIGTERM', async () => {
+ const port = 39000 + Math.floor(Math.random() * 5000);
+ const host = '127.0.0.1';
+
+ child = spawn('node', [CLI, 'mcp', 'start', '-t', 'http', '--port', String(port), '--host', host], {
+ stdio: ['ignore', 'pipe', 'pipe'],
+ });
+
+ await waitForOutput(child, 'MCP Server started', 20_000);
+
+ // Give the event loop a moment past the point where the pre-fix code
+ // would have already called process.exit(0).
+ await new Promise((r) => setTimeout(r, 1500));
+
+ expect(child.exitCode, 'process exited early instead of staying in the foreground').toBeNull();
+
+ const connected = await tcpConnects(port, host, 3000);
+ expect(connected, `nothing was listening on ${host}:${port} β€” the server was torn down`).toBe(true);
+
+ // Graceful shutdown must still work β€” this isn't supposed to hang forever uncontrollably.
+ const exited = new Promise<number | null>((resolve) => {
+ child!.once('exit', (code) => resolve(code));
+ });
+ child.kill('SIGTERM');
+ const code = await Promise.race([
+ exited,
+ new Promise<'timeout'>((resolve) => setTimeout(() => resolve('timeout'), 5000)),
+ ]);
+ expect(code, 'process did not exit within 5s of SIGTERM').not.toBe('timeout');
+ expect(code).toBe(0);
+ }, 30_000);
+});
diff --git a/v3/@claude-flow/cli/src/commands/mcp.ts b/v3/@claude-flow/cli/src/commands/mcp.ts
index 6333f0f475..6cf0877d29 100644
--- a/v3/@claude-flow/cli/src/commands/mcp.ts
+++ b/v3/@claude-flow/cli/src/commands/mcp.ts
@@ -227,7 +227,42 @@ const startCommand: Command = {
output.writeln(output.dim(' Running in background mode'));
}
- return { success: true, data: status };
+ // #2984: this command is only reached via the "normal CLI mode" branch
+ // of bin/cli.js β€” i.e. every invocation NOT auto-detected as Claude
+ // Code's implicit piped-stdin MCP handshake (that path bypasses this
+ // action entirely and blocks on stdin forever, which is why it was
+ // unaffected). bin/cli.js unconditionally exits the process once this
+ // action's promise resolves (`cli.run().then(() => process.exit(0))`,
+ // #1552) β€” a design that assumed "mcp start never resolves" but this
+ // action DID resolve immediately after printing the table above, so
+ // the freshly-bound http/websocket listener (or the interactive-TTY
+ // stdio server) was torn down within milliseconds of the printed
+ // "Status: Running" claim. `daemonize` is not currently wired to
+ // actually fork/detach a background process (no branch reads it in
+ // MCPServerManager), so there is no real backgrounding path yet β€”
+ // every successful start here is a foreground server and must block
+ // until told to stop, matching `daemon start --foreground`'s
+ // established pattern in daemon.ts.
+ output.writeln();
+ output.writeln(output.dim('Press Ctrl+C to stop the server'));
+
+ let stopping = false;
+ const shutdown = async () => {
+ if (stopping) return;
+ stopping = true;
+ try { await manager.stop(); } catch { /* best-effort */ }
+ process.exit(0);
+ };
+ process.on('SIGINT', () => { void shutdown(); });
+ process.on('SIGTERM', () => { void shutdown(); });
+
+ // Ref'd handle so Node's event loop can't drain to empty even if some
+ // transport internals unref their own timers β€” same belt-and-suspenders
+ // as daemon.ts's foreground path (#1478).
+ setInterval(() => {}, 60_000);
+ await new Promise(() => {}); // Never resolves β€” server runs until killed.
+
+ return { success: true, data: status }; // unreachable, keeps the return type honest
} catch (error) {
output.printError(`Failed to start MCP server: ${(error as Error).message}`);
return { success: false, exitCode: 1 };
diff --git a/v3/@claude-flow/cli/src/init/executor.ts b/v3/@claude-flow/cli/src/init/executor.ts
index 4123c91961..dbe2163f3d 100644
--- a/v3/@claude-flow/cli/src/init/executor.ts
+++ b/v3/@claude-flow/cli/src/init/executor.ts
@@ -1061,7 +1061,9 @@ async function writeMCPConfig(
// #1779/#2612 β€” Skip writing if the user already has this MCP server
// registered elsewhere (parent .mcp.json, ~/.claude.json, etc). The
// canonical key is `claude-flow` (per #2206 β€” matches mcp__claude-flow__*
- // plugin tool refs); a stray `ruflo`-keyed entry pointing at the same
+ // tool refs used throughout the CLI-track scaffold; NOT the marketplace
+ // plugin binding, which is mcp__plugin_<plugin>_<server>__* per plugin β€”
+ // see #2985); a stray `ruflo`-keyed entry pointing at the same
// binary is the legacy-duplicate form that #2612 healed. Writing our
// fresh `claude-flow` entry on top of either variant starts the same
// binary twice under two tool namespaces. Force-mode (`--force`)