fix(cli): curate wheels MCP tool surface and fix stats crash (#2139)

* feat(cli): hide cli-only commands from lucli mcp tools/list

Uses the mcpHiddenTools() convention from LuCLI 0.3.4 to exclude mcp,
d, new, console, start, stop, and browser from MCP auto-discovery.
All seven remain callable as CLI subcommands.

Agents doing 'tools/list' on the wheels MCP server now see 16 curated
tools instead of 23, with stateful/interactive/meta commands filtered
out.

* fix(cli): guard Left(str,0) in sprintf helper for Lucee 7

The private sprintf() helper used by 'wheels stats' called
left(result, match.pos[1] - 1) without guarding against pos=1.
Lucee 7 throws 'parameter 2 of the function left can not be 0'
where Lucee 6 returned an empty string silently.

Added a ternary guard per the cross-engine compatibility pattern
documented in the Wheels CLAUDE.md. Exercised via the
sandbox-level MCP tools/call stats test.

* chore(cli): delete redundant services/MCP.cfc schema registry

The parallel schema registry at cli/lucli/services/MCP.cfc was never
wired into LuCLI's MCP discovery path — LuCLI auto-discovers tool
schemas from Module.cfc public function signatures, not from a
schema service. The file also drifted: used wrong tool names
(wheels_generate vs auto-discovered 'generate') and was missing
notes/stats/db/etc.

Rich parameter schemas for MCP tools will be reintroduced in a
follow-up PR by adding typed parameters directly to Module.cfc
public functions, where LuCLI's buildInputSchema() reads them.

* docs(docs): document mcp curation, stats fix, mcp service removal

Author: bpamiri

CHANGELOG.md

@@ -119,6 +119,7 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 - Architecture hardening: XSS helpers consolidated, error hooks added, interface verification (#2097)
 - CSRF cookie encryption key auto-generated when empty (apps should still set their own for stable cross-deploy cookies) (#2054)
 - CI engine testing restructured: 42 jobs reduced to 8 via engine-grouped testing (#1939)
+- `wheels mcp wheels` MCP surface curated — 7 CLI-only commands (`mcp`, `d`, `new`, `console`, `start`, `stop`, `browser`) hidden from MCP `tools/list` via the `mcpHiddenTools()` convention (requires LuCLI 0.3.4+). All remain reachable as CLI subcommands. Tool count drops from 23 to 16 for agent consumers.
 
 ### Deprecated
 
@@ -132,11 +133,13 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 - Railo compatibility workaround from `$initializeMixins` — Railo is no longer a target (#1987)
 - `server.cfc` file (#1902)
 - Stale monorepo artifacts after repository flatten (#1988)
+- `cli/lucli/services/MCP.cfc` parallel schema registry — never wired into LuCLI's MCP discovery, drifted out of sync with `Module.cfc`. Rich parameter schemas will return via typed parameters directly on Module.cfc functions in a follow-up PR.
 
 ### Fixed
 
 - View lookup after `renderText()` / `renderWith()` no longer breaks subsequent partial rendering (#1991)
 - Scaffolded apps from `wheels new` now boot correctly (#2096)
+- `wheels stats` crash on Lucee 7 — private `sprintf()` helper called `Left(result, 0)` when the format string started with a placeholder. Lucee 7 throws where Lucee 6 returned empty silently. Added a ternary guard per the project's cross-engine compatibility pattern.
 - CockroachDB primary key uses `unique_rowid()` instead of `SERIAL` (#1986)
 - CockroachDB SQL generation fixes and soft-fail removed from test matrix (#1999)
 - CockroachDB `RETURNING` clause identity select (#1993)

cli/lucli/Module.cfc

@@ -94,6 +94,31 @@ component extends="modules.BaseModule" {
 		return result;
 	}
 
+	// ─────────────────────────────────────────────────
+	//  MCP framework convention — hide CLI-only commands
+	// ─────────────────────────────────────────────────
+
+	/**
+	 * hint: Declare public functions to hide from MCP tools/list.
+	 *
+	 * These remain reachable as CLI subcommands. Hidden because they are
+	 * stateful (start/stop), destructive (new scaffolds a whole project),
+	 * interactive (console), meta (mcp), alias (d), or don't translate to
+	 * single-call MCP semantics (browser). Read by LuCLI >= 0.3.4 per the
+	 * mcpHiddenTools() convention.
+	 */
+	public array function mcpHiddenTools() {
+		return [
+			"mcp",      // meta command — prints MCP setup instructions
+			"d",        // alias for destroy
+			"new",      // scaffolds a whole new Wheels project
+			"console",  // interactive CFML REPL — not usable over stdio
+			"start",    // dev server lifecycle (stateful)
+			"stop",     // dev server lifecycle (stateful)
+			"browser"   // multi-step browser testing flow
+		];
+	}
+
 	// ─────────────────────────────────────────────────
 	//  generate — Code generation
 	// ─────────────────────────────────────────────────
@@ -3778,7 +3803,9 @@ component extends="modules.BaseModule" {
 			} else {
 				value = repeatString(" ", max(0, width - len(value))) & value;
 			}
-			result = left(result, match.pos[1] - 1) & value & mid(result, match.pos[1] + match.len[1], len(result));
+			// Guard: Left(str, 0) throws on Lucee 7 ("parameter 2 cannot be 0")
+			var prefix = match.pos[1] > 1 ? left(result, match.pos[1] - 1) : "";
+			result = prefix & value & mid(result, match.pos[1] + match.len[1], len(result));
 			argIndex++;
 		}
 		return result;

cli/lucli/services/MCP.cfc

@@ -42,6 +42,18 @@ component extends="testbox.system.BaseSpec" {
 			"validate"
 		];
 
+		// Public functions deliberately hidden from MCP tools/list via
+		// mcpHiddenTools(). They remain callable as CLI subcommands.
+		variables.expectedHiddenTools = [
+			"mcp",      // meta command
+			"d",        // alias for destroy
+			"new",      // scaffolds whole project
+			"console",  // interactive REPL
+			"start",    // dev server lifecycle
+			"stop",     // dev server lifecycle
+			"browser"   // multi-step browser flow
+		];
+
 		// Create a temp project directory for tool invocation tests
 		variables.testDir = getTempDirectory() & "wheels_e2e_mcp_" & createUUID();
 		directoryCreate(variables.testDir);
@@ -175,6 +187,21 @@ component extends="testbox.system.BaseSpec" {
 					);
 				}
 			});
+
+			it("declares mcpHiddenTools() to curate the MCP tool surface", function() {
+				// The function must exist as a public function returning an array
+				expect(variables.moduleSource contains "public array function mcpHiddenTools").toBeTrue(
+					"Module.cfc must declare mcpHiddenTools() to hide CLI-only commands from MCP tools/list"
+				);
+
+				// And it must name every tool we expect to hide
+				for (var hidden in variables.expectedHiddenTools) {
+					var pattern = '"' & hidden & '"';
+					expect(variables.moduleSource contains pattern).toBeTrue(
+						"mcpHiddenTools() must include '" & hidden & "' — check the returned array"
+					);
+				}
+			});
 		});
 
 		// ─── MCP Tool Invocation via Services ──────────