π 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): mcp start -t http exits after false-success table + doc drift from #2985 (#2987)
rUv87f4f8ab6736
diff --git a/README.md b/README.mdindex 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.mdindex 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 installationclaude 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 startdiff --git a/v3/@claude-flow/cli/__tests__/mcp-http-foreground-2984.test.ts b/v3/@claude-flow/cli/__tests__/mcp-http-foreground-2984.test.tsnew file mode 100644index 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.tsindex 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.tsindex 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`)