fix(mcp): restore spec-valid HTTP transport and CLI tools

[dajiaohuang]

Summary

• bridge the filtered Ruflo CLI tool registry into the HTTP/WebSocket MCP server
• return the string protocol version supplied by @claude-flow/mcp
• accept valid JSON Schemas whose unconstrained nodes omit type
• bind IPv4 and IPv6 loopback transports to one shared MCP server state
• support the legacy HTTP+SSE fallback on GET /mcp
• preserve CLAUDE_FLOW_MCP_TOOLS unless an explicit --tools flag overrides it
• keep the CLI and MCP package versions in publishable lockstep

Root cause

The CLI package was pinned to @claude-flow/mcp@3.0.0-alpha.8, whose initialize result used an object-valued protocolVersion. The HTTP startup path also created a standalone MCP server without registering Ruflo's CLI tools, leaving only four built-ins.

Bridging the tools exposed a second compatibility issue: the MCP registry rejected valid JSON Schema nodes without an explicit type, even though its execution validator already treats a missing type as an unconstrained JSON value.

The default hostname could resolve to one loopback family only. The dual-bind implementation now attaches both loopback transports to one MCP server, so sessions, tool state, and notifications are shared across IPv4 and IPv6.

Validation

• @claude-flow/mcp: 75 tests passed
• HTTP end-to-end regression: 3 tests passed, including IPv4 initialize → IPv6 call and legacy SSE request/response
• the end-to-end suite now fails instead of silently skipping when bin/cli.js has not been built
• MCP and CLI TypeScript builds passed
• git diff --check passed
• related CLI MCP suite: 58 passed; the existing mcp start -t http prints a full success table (Status: Running, health/RPC URLs) then exits 0 without ever binding the port #2984 SIGTERM assertion reports a Windows-only null exit code after successful shutdown rather than numeric 0

Release blocker

As of 2026-08-14, npm still publishes @claude-flow/mcp only through 3.0.0-alpha.9. This PR intentionally pins the CLI to exact 3.0.0-alpha.10, because that package contains the schema compatibility required to register all CLI tools. The PR remains Draft until a maintainer publishes @claude-flow/mcp@3.0.0-alpha.10; only then can the CLI dependency be installed outside the workspace.

Closes #2990

[ruvnet]

Reviewed. CI hasn't run on this branch (0 check-runs, pending status) — but there's a hard merge blocker independent of that.

v3/@claude-flow/cli/package.json pins an exact, unpublished dependency version. The diff bumps to @claude-flow/mcp@3.0.0-alpha.10 for the string-typed protocolVersion fix, but npm view @claude-flow/mcp versions only goes up to alpha.9 — the registry doesn't have alpha.10 yet. The in-repo link:../mcp in the lockfile masks this locally, but a published @claude-flow/cli built from this PR as-is would be uninstallable until @claude-flow/mcp@3.0.0-alpha.10 actually ships. This needs to be sequenced — publish the mcp package first, then land this.

Two more worth addressing in the same pass:

• The regression test for this fix is describe.skipIf(!CLI_BUILT) — it silently no-ops in any CI job that doesn't build bin/cli.js first, so a green run here wouldn't actually prove anything without confirming that precondition holds.
• The dual 127.0.0.1+::1 bind creates two independent createMCPServer instances sharing a port rather than one server listening on both — a client that initializes against one and calls against the other would hit a server with no session state for it. And mcp start -t http (3.38.2, post-#2984): initialize returns protocolVersion as object — spec-validating clients reject the handshake; http tools/list serves only 4 system tools #2990's SSE-fallback complaint (GET /mcp → 404) isn't addressed by this diff.

The protocolVersion-as-string and filtered-tool-registry parts of the fix look correct for what they cover — just needs the publish sequencing resolved and the skip-condition tightened before merge.

[dajiaohuang]

Addressed the actionable review points in ca8ae33:

• replaced the two independent MCP servers with one server owning both IPv4 and IPv6 transports; the regression now initializes over 127.0.0.1 and calls tools/list over ::1, proving shared session state
• added the legacy HTTP+SSE fallback on GET /mcp, including endpoint negotiation and SSE-delivered JSON-RPC responses
• removed describe.skipIf(!CLI_BUILT); the end-to-end suite now fails explicitly when the built CLI precondition is missing

Validation: MCP 75/75 tests, HTTP end-to-end 3/3 tests, MCP build, CLI build, and git diff --check all passed. I also rechecked npm today: @claude-flow/mcp@3.0.0-alpha.10 is still unpublished (latest is alpha.9). I marked the PR Draft and documented that as the only remaining release-sequencing blocker; I cannot safely remove the exact pin because alpha.10's schema compatibility is required for the full CLI registry.