diff --git a/CLAUDE.md b/CLAUDE.md index da54ff0b2f..a9bc5e6de1 100755 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -713,7 +713,7 @@ User-facing `fix`/`feat` PRs add a **fragment file**, never a direct `CHANGELOG. There is no `wheels mcp setup` command — copy the JSON above into `.mcp.json` manually (see the MCP integration guide for OpenCode/Cursor variants). -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`, `wheels_deploy`, `wheels_packages`). CLI-only tools (`main`, `mcp`, `d`, `g`, `new`, `console`, `start`, `stop`, `browser`) are hidden via `mcpHiddenTools()`. +Tools are auto-discovered from `cli/lucli/Module.cfc` public functions. Names in `tools/list` are the bare function names — NOT `wheels_*`-prefixed (live-verified on the released 4.0.3 CLI): `analyze`, `create`, `db`, `deploy`, `destroy`, `doctor`, `generate`, `info`, `migrate`, `notes`, `packages`, `reload`, `routes`, `seed`, `stats`, `test`, `upgrade`, `validate` (18 tools; the `wheels` server entry in `.mcp.json` namespaces them per client). CLI-only tools (`main`, `mcp`, `d`, `g`, `new`, `console`, `start`, `stop`, `browser`) are hidden via `mcpHiddenTools()`. **Deprecated:** the in-dev-server HTTP endpoint at `/wheels/mcp`. Emits a deprecation notice on first request. Migrate to the stdio surface. @@ -725,13 +725,13 @@ Prefer MCP tools when the Wheels MCP server is available. Fall back to CLI other | Task | MCP | CLI | |------|-----|-----| -| Generate | `wheels_generate(type, name, attributes)` | `wheels g model/controller/scaffold Name attrs` | -| Migrate | `wheels_migrate(action="latest\|up\|down\|info\|doctor")` | `wheels migrate latest\|up\|down\|info\|doctor` | +| Generate | `generate(type, name, attributes)` | `wheels g model/controller/scaffold Name attrs` | +| Migrate | `migrate(action="latest\|up\|down\|info\|doctor")` | `wheels migrate latest\|up\|down\|info\|doctor` | | Migrator reconciliation | — | `wheels migrate forget\|pretend --yes` (shared dev DB orphan cleanup; see #2780) | -| Test | `wheels_test()` | `wheels test` | -| Reload | `wheels_reload()` | `?reload=true&password=...` | +| Test | `test()` | `wheels test` | +| Reload | `reload()` | `?reload=true&password=...` | | Server | — | `wheels start\|stop` | -| Analyze | `wheels_analyze(target="all")` | — | +| Analyze | `analyze(target="all")` | — | | Admin | — | `wheels g admin ModelName` | | Seed | — | `wheels seed` | diff --git a/cli/lucli/Module.cfc b/cli/lucli/Module.cfc index 5e3f72f95a..05dc97685e 100644 --- a/cli/lucli/Module.cfc +++ b/cli/lucli/Module.cfc @@ -1384,7 +1384,8 @@ component extends="modules.BaseModule" { out(" https://guides.wheels.dev/v4-0-0/command-line-tools/mcp-integration"); 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("Tool names match the command names: generate, migrate, etc. (unprefixed"); + out("in tools/list — the server entry in .mcp.json namespaces them per client)."); out("Stateful/interactive commands (start, stop, new, console, ...) are hidden"); out("from MCP tools/list via mcpHiddenTools() — they remain CLI-only."); return ""; diff --git a/web/sites/guides/src/content/docs/v4-0-0/command-line-tools/installation.mdx b/web/sites/guides/src/content/docs/v4-0-0/command-line-tools/installation.mdx index 6582904b18..a69efc5582 100644 --- a/web/sites/guides/src/content/docs/v4-0-0/command-line-tools/installation.mdx +++ b/web/sites/guides/src/content/docs/v4-0-0/command-line-tools/installation.mdx @@ -191,7 +191,7 @@ The package-manager installs do extra work on your behalf that this path skips. - **`LUCLI_HOME` isolation.** Package installs export `LUCLI_HOME=$HOME/.wheels` so installed modules live in `~/.wheels/modules/wheels/` and stay out of the way of any other LuCLI work. Standalone LuCLI uses `~/.lucli/modules/wheels/` — fine on its own, but a previously installed `wheels` module (e.g. v3.1.0 from the older registry entry) will shadow your new install unless you pass `--force`. - **JDK resolution.** Package installs probe for a Java 21 install and export `JAVA_HOME` inside their `wheels` wrapper. Standalone LuCLI uses whatever `java` is on your `PATH` — if that's a different major version, the runtime will refuse to start. Make sure `java -version` reports 21.x before installing. - **First-run SQLite shim.** The package wrappers auto-stage `sqlite-jdbc-*.jar` into Lucee Express's `lib/ext/` so `wheels start` against a SQLite datasource works out of the box. With a bare LuCLI install you'll need to drop the JAR there yourself the first time you create a SQLite-backed app. -- **Channel awareness.** `wheels --version` from a packaged install reports `(stable)` or `(bleeding-edge)`. From a bare LuCLI install, the module reports its own version but there's no channel marker — you have to remember which tarball URL you installed from. +- **Channel awareness.** `wheels version` from a packaged install reports `(stable)` or `(bleeding-edge)`. From a bare LuCLI install, the module reports its own version but there's no channel marker — you have to remember which tarball URL you installed from. - **No `scoop update` / `brew upgrade` story.** Upgrades are manual: re-run `lucli modules install wheels --force --url=…` with a newer release URL. This path exists for people who already run LuCLI for other modules and don't want a second binary on `PATH`. For everyone else, the Scoop / Homebrew / Linux package paths are the better default. @@ -208,12 +208,17 @@ wheels --version You should see something like: ``` title="illustrative — example version output" -Wheels 4.0.0-SNAPSHOT+1523 (snapshot) -LuCLI 0.3.7 -Java 21.0.8 +Wheels Version: 4.0.3 ``` -The three-line format tells you the Wheels Module version, the underlying LuCLI version, and the JVM the wrapper picked up. If any of those lines is missing or reports an unexpected value, jump to troubleshooting below. +followed by the Wheels ASCII-art banner. The richer check is `wheels version` (no dashes), which reports the release channel and the JVM the wrapper picked up: + +``` title="illustrative — example wheels version output" +Wheels 4.0.3 (stable) +Java 21.0.11 +``` + +If either line is missing or reports an unexpected value — say a Java major version other than 21 — jump to troubleshooting below. Running `wheels` with no arguments is also a quick sanity check — it prints the same Wheels help banner as `wheels --help`. (`wheels help` falls through to LuCLI's own generic help rather than the Wheels banner, so prefer `wheels --help`.) If you see a `Component [modules.wheels.Module] has no function with name [main]` error instead, you are running a build that predates this fix — upgrade to the latest 4.0.x release to restore the expected behavior. @@ -233,7 +238,7 @@ On Linux, the `.deb`/`.rpm` package installs `/usr/bin/wheels`, which should be ### Conflict with a standalone LuCLI install sharing `~/.lucli/` -The wheels formula deliberately isolates runtime state under `~/.wheels/` (via `LUCLI_HOME`) so a standalone `lucli` install — which uses `~/.lucli/` — stays out of the way. If you previously had LuCLI installed directly and see odd module-resolution errors, check that the wrapper set `LUCLI_HOME` correctly (`wheels system env` will dump the resolved environment) and that `~/.wheels/modules/wheels/` contains a current `Module.cfc` and `.module-version` file. +The wheels formula deliberately isolates runtime state under `~/.wheels/` (via `LUCLI_HOME`) so a standalone `lucli` install — which uses `~/.lucli/` — stays out of the way. If you previously had LuCLI installed directly and see odd module-resolution errors, check that the wrapper set `LUCLI_HOME` correctly (`wheels system paths` prints the resolved home directory and where it came from) and that `~/.wheels/modules/wheels/` contains a current `Module.cfc` and `.module-version` file. ### Windows: `there is no Resource provider available with the name [c]` diff --git a/web/sites/guides/src/content/docs/v4-0-0/command-line-tools/mcp-integration.mdx b/web/sites/guides/src/content/docs/v4-0-0/command-line-tools/mcp-integration.mdx index 2fadde848d..9cf8a4c25b 100644 --- a/web/sites/guides/src/content/docs/v4-0-0/command-line-tools/mcp-integration.mdx +++ b/web/sites/guides/src/content/docs/v4-0-0/command-line-tools/mcp-integration.mdx @@ -18,7 +18,7 @@ The `wheels` binary can run as a Model Context Protocol (MCP) server over stdio, ## How it works -LuCLI ships a generic `mcp` subcommand that wraps any installed module's public functions as MCP tools over stdio JSON-RPC. Running `wheels mcp wheels` starts that server bound to the Wheels Module — every public function in `cli/lucli/Module.cfc` becomes a tool named `wheels_` (for example, `wheels_generate`, `wheels_migrate`). The AI IDE spawns `wheels` as a subprocess, speaks newline-delimited JSON-RPC over stdin/stdout, and receives tool results the same way. No network listener is involved. +LuCLI ships a generic `mcp` subcommand that wraps any installed module's public functions as MCP tools over stdio JSON-RPC. Running `wheels mcp wheels` starts that server bound to the Wheels Module — every public function in `cli/lucli/Module.cfc` becomes a tool named after the function itself (for example, `generate`, `migrate`). Tool names appear unprefixed in `tools/list`; the `wheels` server entry in your MCP config is what namespaces them per client. The AI IDE spawns `wheels` as a subprocess, speaks newline-delimited JSON-RPC over stdin/stdout, and receives tool results the same way. No network listener is involved. ## Setup @@ -37,7 +37,7 @@ Add an `.mcp.json` file to your project root (or wherever your IDE expects it). That's the whole configuration. The first `wheels` is the binary name; the second is the module name to expose. The IDE launches the subprocess on demand — you don't need to keep `wheels mcp wheels` running yourself, and the server exits when the IDE disconnects. -Running `wheels mcp` on its own (no module name) prints the same snippet and a short pointer to configuration docs. It is a help command, not a setup wizard — there is no generated file today. +Don't try `wheels mcp` on its own to see this snippet: on the released launcher, LuCLI reserves the `mcp` verb and a bare invocation exits with `mcp: missing module name` instead of reaching the Wheels Module's help text. To check the server from a shell, use the `--once` smoke test below. There is no setup wizard and no generated file — add the `.mcp.json` snippet manually.