feat(cli): canonicalize lucli stdio mcp, deprecate in-dev-server http mcp (#2140)

* feat(cli): canonicalize lucli stdio mcp in templates and cli setup

Updates all four .mcp.json / .opencode.json templates shipped with the
Wheels CLI to the stdio configuration:

    {"mcpServers":{"wheels":{"command":"wheels","args":["mcp","wheels"]}}}

Templates touched:
  - cli/src/templates/McpConfig.json  (wheels mcp setup output)
  - app/snippets/McpConfig.json       (new-app scaffold snippet)
  - tools/build/base/.mcp.json        (base build template)
  - tools/build/base/.opencode.json   (base build OpenCode template)

Also simplifies 'wheels mcp setup' — port detection, noAutoStart, and
{PORT} template interpolation are no longer needed for stdio transport.
Users can now run 'wheels mcp setup' or 'wheels mcp setup --force' and
get a working config with no runtime state inspection.

Module.cfc's mcp() subcommand now shows the 'wheels' binary name (not
'lucli') in the sample config, matching how end users actually invoke
the CLI.

* chore(config): deprecate in-dev-server mcp endpoint

The HTTP MCP endpoint at /wheels/mcp (mounted from
vendor/wheels/public/views/mcp.cfm backed by McpServer.cfc) is
superseded by the LuCLI stdio MCP (wheels mcp wheels). Keep it alive
for this release as a compatibility shim but signal deprecation:

  - mcp.cfm logs a one-time per-JVM deprecation warning to
    application wheels_mcp log on first request
  - McpServer.cfc serverInfo now advertises deprecated=true and a
    deprecationNotice string so MCP clients that inspect serverInfo
    can surface a migration banner to the user

Removal is scheduled for a future release once 'wheels mcp setup'
has landed in a released Wheels CLI and users have had time to
migrate.

* docs(docs): describe lucli stdio mcp as canonical in claude.md and guides

CLAUDE.md MCP Server section now documents the stdio config as the
canonical surface with the HTTP endpoint marked deprecated. Adds the
full auto-discovered tool inventory and links to the configuration
guide for deeper docs.

mcp-setup.md rewritten to reflect the new 'wheels mcp setup' behavior
(stdio transport, no port needed). Lists the 16 MCP-exposed tools and
notes the 7 CLI-only tools hidden via mcpHiddenTools(). Adds a
migration note pointing pre-4.0 HTTP users at 'wheels mcp setup
--force'.

mcp-configuration-guide.md: Overview + Quick Start rewritten around
the stdio transport. Legacy HTTP section retained (still works, with
deprecation warning) for users not yet ready to migrate.

* docs(docs): changelog entries for plan c mcp deprecation and canonicalization

Author: bpamiri

CHANGELOG.md

@@ -120,12 +120,14 @@ All historical references to "CFWheels" in this changelog have been preserved fo
 - 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.
+- LuCLI stdio MCP (`wheels mcp wheels`) is now the canonical AI-agent surface for Wheels. `wheels mcp setup` generates `.mcp.json` and `.opencode.json` pointing at the stdio transport. No port or running dev server required. Updated templates: `cli/src/templates/McpConfig.json`, `app/snippets/McpConfig.json`, `tools/build/base/.mcp.json`, `tools/build/base/.opencode.json`.
 
 ### Deprecated
 
 - Legacy `plugins/` folder — superseded by the new `packages/` → `vendor/` activation model. Plugins still load, with a deprecation warning. (#1995)
 - RocketUnit test style for new tests — BDD syntax (via WheelsTest) is required going forward. Existing RocketUnit specs continue to run. (#1925)
 - `wheels.Test` test base class — extend `wheels.WheelsTest` instead (#1889)
+- In-dev-server HTTP MCP endpoint at `/wheels/mcp` — superseded by the LuCLI stdio MCP server (`wheels mcp wheels`). Emits a deprecation warning to the `wheels_mcp` log on first request and advertises `deprecated: true` in the `serverInfo` handshake. Scheduled for removal in a future release. Migrate existing projects with `wheels mcp setup --force`.
 
 ### Removed
 

CLAUDE.md

@@ -857,6 +857,16 @@ The project name is **Wheels** (not "CFWheels"). The rebrand happened at v3.0. A
 
 ## MCP Server
 
-Endpoint: `/wheels/mcp` (routes must come before `.wildcard()` in routes.cfm).
+**Canonical surface (Wheels 4.0+):** LuCLI stdio MCP at `wheels mcp wheels`. Configure your AI IDE with:
 
-Tools: `wheels_generate`, `wheels_migrate`, `wheels_test`, `wheels_server`, `wheels_reload`, `wheels_analyze`, `wheels_validate`.
+```json
+{"mcpServers":{"wheels":{"command":"wheels","args":["mcp","wheels"]}}}
+```
+
+Or run `wheels mcp setup` to generate `.mcp.json` + `.opencode.json` automatically.
+
+Tools are auto-discovered from `cli/lucli/Module.cfc` public functions, prefixed with the module name (`wheels_generate`, `wheels_migrate`, `wheels_test`, `wheels_reload`, `wheels_seed`, `wheels_analyze`, `wheels_validate`, `wheels_routes`, `wheels_info`, `wheels_destroy`, `wheels_doctor`, `wheels_stats`, `wheels_notes`, `wheels_db`, `wheels_upgrade`, `wheels_create`). CLI-only tools (`mcp`, `d`, `new`, `console`, `start`, `stop`, `browser`) are hidden from MCP `tools/list` via `mcpHiddenTools()`.
+
+Workflow orchestration (multi-step planning, feature development) is not a framework concern — use your preferred Claude Code plugin (Superpowers, feature-dev, etc.). The framework ships deterministic Wheels operations via MCP; the model orchestrates.
+
+**Deprecated:** The in-dev-server HTTP endpoint at `/wheels/mcp` (routed from `vendor/wheels/public/views/mcp.cfm`). Emits a deprecation notice and warning log on first request. Scheduled for removal in a future release — migrate to the stdio surface. See `docs/command-line-tools/commands/mcp/mcp-configuration-guide.md`.

app/snippets/McpConfig.json

@@ -1,8 +1,8 @@
 {
   "mcpServers": {
     "wheels": {
-      "url": "http://localhost:{PORT}/wheels/mcp",
-      "type": "http"
+      "command": "wheels",
+      "args": ["mcp", "wheels"]
     },
     "browsermcp": {
       "command": "npx",
@@ -11,4 +11,4 @@
       ]
     }
   }
-}
+}

cli/lucli/Module.cfc

@@ -615,14 +615,19 @@ component extends="modules.BaseModule" {
 	 * hint: Show MCP server configuration instructions
 	 */
 	public string function mcp() {
-		out("MCP is built into LuCLI. Run:", "bold");
-		out("  lucli mcp wheels");
+		out("MCP is built into the Wheels CLI. Run:", "bold");
+		out("  wheels mcp wheels");
 		out("");
-		out("Configure in Claude Code (.claude/claude_project_config.json):", "bold");
-		out('  {"mcpServers":{"wheels":{"command":"lucli","args":["mcp","wheels"]}}}');
+		out("Configure in Claude Code (.mcp.json):", "bold");
+		out('  {"mcpServers":{"wheels":{"command":"wheels","args":["mcp","wheels"]}}}');
+		out("");
+		out("For OpenCode, Cursor, and other AI IDEs, see:");
+		out("  docs/command-line-tools/commands/mcp/mcp-configuration-guide.md");
 		out("");
 		out("All public commands in this module are auto-discovered as MCP tools.");
 		out("Tools are prefixed with the module name: wheels_generate, wheels_migrate, etc.");
+		out("Stateful/interactive commands (start, stop, new, console, ...) are hidden");
+		out("from MCP tools/list via mcpHiddenTools() — they remain CLI-only.");
 		return "";
 	}
 

cli/src/commands/wheels/mcp/setup.cfc

@@ -1,72 +1,57 @@
 /**
- * Set up MCP (Model Context Protocol) integration for AI IDE support
- * Creates .mcp.json and .opencode.json configuration files in your project root
- * Uses the native CFML MCP server built into Wheels (no Node.js required)
+ * Set up MCP (Model Context Protocol) integration for AI IDE support.
+ *
+ * Writes .mcp.json and .opencode.json configuration files in the project
+ * root. Both point your AI IDE at the LuCLI stdio MCP server (`wheels mcp
+ * wheels`) — the canonical Wheels MCP surface as of 4.0. No port or running
+ * dev server required; the IDE launches the stdio subprocess on demand.
  *
  * Examples:
  * {code:bash}
  * wheels mcp setup
- * wheels mcp setup --port=8080
  * wheels mcp setup --force
  * {code}
  **/
 component extends="../base" {
 
 	/**
-	 * @port Port number for Wheels server (auto-detected if not provided)
 	 * @force Overwrite existing configuration files
-	 * @noAutoStart Don't automatically start server if not running
 	 **/
-	function run(
-		numeric port = 0,
-		boolean force = false,
-		boolean noAutoStart = false
-	) {
+	function run(boolean force = false) {
 		print.line();
 		print.boldYellowLine("🤖 Setting up MCP Integration for Wheels");
 		print.line("=" .repeatString(50));
 		print.line();
 
-		// Check if we're in a Wheels application
 		if (!isWheelsApp()) {
 			print.redLine("❌ This doesn't appear to be a Wheels application directory.");
 			print.line("   Looking for /vendor/wheels, /config, and /app folders");
 			print.line();
 			print.yellowLine("   Run this command from your Wheels project root directory.");
 			return;
-		} else {
-			print.greenLine("✅ Wheels application detected");
 		}
+		print.greenLine("✅ Wheels application detected");
+		print.greenLine("✅ Using LuCLI stdio MCP (transport: stdio, no port needed)");
 
-		print.greenLine("✅ Using native CFML MCP server (no Node.js required)");
-
-		// Detect or use provided port
-		var serverPort = detectServerPort(arguments.port, arguments.noAutoStart);
 		print.line();
-
-		// Create configuration files
 		print.boldLine("Creating MCP configuration files...");
 
 		try {
 			var projectRoot = getCWD();
 
-			// Create .mcp.json
 			var mcpConfigPath = projectRoot & "/.mcp.json";
 			if (!fileExists(mcpConfigPath) || arguments.force) {
 				var mcpTemplate = fileRead(expandPath("/wheels-cli/templates/McpConfig.json"));
-				var mcpContent = replace(mcpTemplate, "{PORT}", serverPort, "ALL");
-				fileWrite(mcpConfigPath, mcpContent);
+				fileWrite(mcpConfigPath, mcpTemplate);
 				print.greenLine("✅ Created .mcp.json");
 			} else {
 				print.yellowLine("⚠️  .mcp.json already exists (use --force to overwrite)");
 			}
 
-			// Create .opencode.json
 			var opencodeConfigPath = projectRoot & "/.opencode.json";
 			if (!fileExists(opencodeConfigPath) || arguments.force) {
 				var opencodeTemplate = fileRead(expandPath("/wheels-cli/templates/OpenCodeConfig.json"));
-				var opencodeContent = replace(opencodeTemplate, "{PORT}", serverPort, "ALL");
-				fileWrite(opencodeConfigPath, opencodeContent);
+				fileWrite(opencodeConfigPath, opencodeTemplate);
 				print.greenLine("✅ Created .opencode.json");
 			} else {
 				print.yellowLine("⚠️  .opencode.json already exists (use --force to overwrite)");
@@ -77,21 +62,20 @@ component extends="../base" {
 			print.redLine("❌ Configuration failed: " & e.message);
 			return;
 		}
-		print.line();
 
-		// Summary
+		print.line();
 		print.boldGreenLine("✨ MCP Integration Setup Complete!");
 		print.line();
 		print.boldLine("Configuration Summary:");
-		print.indentedLine("Wheels MCP Endpoint: http://localhost:" & serverPort & "/wheels/mcp");
-		print.indentedLine("Server Type: Native CFML (no Node.js required)");
-		print.indentedLine("Files Created: .mcp.json, .opencode.json");
+		print.indentedLine("MCP transport: stdio (launched on demand by your AI IDE)");
+		print.indentedLine('Command: wheels mcp wheels');
+		print.indentedLine("Files created: .mcp.json, .opencode.json");
 		print.line();
 
 		print.boldLine("Next Steps:");
-		print.indentedLine("1. Ensure your Wheels server is running on port " & serverPort);
-		print.indentedLine("2. Configure your AI IDE to use the generated configuration files");
-		print.indentedLine("3. Test the connection: wheels mcp test");
+		print.indentedLine("1. Ensure the 'wheels' CLI binary is on PATH (brew install wheels)");
+		print.indentedLine("2. Restart your AI IDE so it re-reads .mcp.json / .opencode.json");
+		print.indentedLine("3. Verify tool discovery in the IDE's MCP panel — 16 tools should appear");
 		print.line();
 
 		print.boldLine("Available MCP Commands:");
@@ -100,116 +84,15 @@ component extends="../base" {
 		print.indentedLine("wheels mcp remove  - Remove MCP integration");
 		print.line();
 
-		print.yellowLine("💡 The generated files provide AI assistants with:");
-		print.indentedLine("• Real-time access to your Wheels project structure");
-		print.indentedLine("• Complete API documentation and guides");
-		print.indentedLine("• Ability to generate models, controllers, and migrations");
-		print.indentedLine("• Direct execution of tests and server commands");
-		print.indentedLine("• Browser automation capabilities (via Browser MCP)");
+		print.yellowLine("💡 The generated files give AI assistants:");
+		print.indentedLine("• Code generation (generate, destroy, seed, ...)");
+		print.indentedLine("• Migration + database operations (migrate, db, ...)");
+		print.indentedLine("• Project introspection (routes, info, analyze, doctor, stats, notes)");
+		print.indentedLine("• Test runner (test)");
+		print.indentedLine("• Browser automation (via Browser MCP)");
+		print.line();
+		print.indentedLine("Full guide: docs/command-line-tools/commands/mcp/mcp-configuration-guide.md");
 		print.line();
 	}
 
-	private function detectServerPort(port, noAutoStart) {
-		var serverPort = 0;
-
-		if (!isNull(port) && port > 0) {
-			serverPort = port;
-			print.line("Using specified port: " & serverPort);
-		} else {
-			print.line("Detecting Wheels server port...");
-
-			// Use CommandBox serverService to get server info
-			try {
-				var cwd = getCWD();
-				var serverInfo = {};
-
-				// Try current directory first
-				serverInfo = serverService.getServerInfoByWebroot(cwd);
-
-				// If not found, try with /public subdirectory (common Wheels setup)
-				if (serverInfo.isEmpty() && directoryExists(cwd & "/public")) {
-					serverInfo = serverService.getServerInfoByWebroot(cwd & "/public");
-				}
-
-				// If still not found, try parent directory (in case we're in /public)
-				if (serverInfo.isEmpty() && getFileFromPath(cwd) == "public") {
-					var parentDir = getDirectoryFromPath(cwd.substring(1, cwd.length() - 1));
-					serverInfo = serverService.getServerInfoByWebroot(parentDir);
-				}
-
-				if (!serverInfo.isEmpty()) {
-					// Check if server is running
-					if (serverInfo.status == "running") {
-						// Get the port from the running server
-						if (structKeyExists(serverInfo, "port")) {
-							serverPort = serverInfo.port;
-							print.greenLine("✅ Detected running server on port " & serverPort);
-						} else if (structKeyExists(serverInfo, "web") &&
-								   structKeyExists(serverInfo.web, "http") &&
-								   structKeyExists(serverInfo.web.http, "port")) {
-							serverPort = serverInfo.web.http.port;
-							print.greenLine("✅ Detected running server on port " & serverPort);
-						}
-					} else if (serverInfo.status == "stopped") {
-						// Server exists but is stopped
-						print.yellowLine("⚠️  Server is configured but not running");
-
-						// Try to get configured port even if stopped
-						if (structKeyExists(serverInfo, "port")) {
-							serverPort = serverInfo.port;
-							print.line("   Using configured port: " & serverPort);
-						}
-					}
-				}
-			} catch (any e) {
-				// Fallback if serverService fails
-				print.yellowLine("⚠️  Could not detect server via CommandBox service");
-			}
-		}
-
-		// If no server detected and auto-start enabled, try to start server
-		if (serverPort == 0 && !noAutoStart) {
-			print.line("No running server detected. Attempting to start server...");
-
-			try {
-				// Start the server using serverService
-				var serverInfo = serverService.start(
-					name = "",  // Use default name for current directory
-					directory = getCWD(),
-					saveSettings = true
-				);
-
-				sleep(3000); // Wait for server to fully start
-
-				// Get the server info again after starting
-				serverInfo = serverService.getServerInfoByWebroot(getCWD());
-
-				if (!serverInfo.isEmpty() && serverInfo.status == "running") {
-					if (structKeyExists(serverInfo, "port")) {
-						serverPort = serverInfo.port;
-						print.greenLine("✅ Started server on port " & serverPort);
-					}
-				}
-			} catch (any e) {
-				print.yellowLine("⚠️  Could not start server automatically: " & e.message);
-			}
-		}
-
-		if (serverPort == 0) {
-			print.yellowLine("⚠️  Could not detect server port.");
-			print.line();
-			print.line("Options:");
-			print.indentedLine("1. Start your server: wheels server start");
-			print.indentedLine("2. Specify port manually: wheels mcp setup --port=60000");
-			print.indentedLine("3. Run with --noAutoStart to disable server auto-start");
-			print.line();
-
-			// Ask for port
-			var userPort = ask("Enter your Wheels server port (or press Enter to use 60000): ");
-			serverPort = len(trim(userPort)) ? userPort : 60000;
-		}
-
-		return serverPort;
-	}
-
-}
+}

cli/src/templates/McpConfig.json

@@ -1,8 +1,8 @@
 {
   "mcpServers": {
     "wheels": {
-      "url": "http://localhost:{PORT}/wheels/mcp",
-      "type": "http"
+      "command": "wheels",
+      "args": ["mcp", "wheels"]
     },
     "browsermcp": {
       "command": "npx",
@@ -11,4 +11,4 @@
       ]
     }
   }
-}
+}