diff --git a/CHANGELOG.md b/CHANGELOG.md index 6ccabeb..bd4b004 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ ## Unreleased +- README troubleshooting: a new row explains that `npx` (and an MCP client's npx entry) hides install-script output, so a failed setup, such as a missing platform package, exits without printing anything (exit code 127 on Linux), and shows how to reveal the message with `--foreground-scripts`. The missing-platform row now also names Windows on Arm among the platforms without a platform package. The main package's `postinstall` stays a bare command; CONTRIBUTING explains why a shell fallback message is not used. + ## 0.5.0 Upgrade notes: a locked configuration whose login can execute server-file functions is now refused at startup, and npm installs that omit optional dependencies now fail (both below). Existing tool names, parameters, environment variables, CLI flags and the targets-file format remain compatible; additions such as the `parameters` input of `execute_sql`/`explain_query` are optional. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2eff8d8..a0f22a3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -96,7 +96,7 @@ Windows/macOS CI uses `packages --artifacts artifacts/packages --installation-on Package CLI checks and fresh-cache npx initialization allow up to 600 seconds: npx downloads and installs the platform package before the server starts, and Windows installation can exceed 45 seconds. Subsequent MCP calls retain their 20-second deadline. The smoke verifies stdin-EOF shutdown through the real npx wrapper and SIGTERM against that npx installation's native server: npm does not forward a signal sent only to its root process. It runs npm at `warn` log level to separate npm's command-echo notices from server diagnostics while retaining warnings/errors; production commands and logging are unchanged. -The npm distribution is one main package, `@codegiveness/postgresql-sharp-mcp`, plus five platform packages named `@codegiveness/postgresql-sharp-mcp--` (`win32-x64`, `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`). The main package lists them as exact-version `optionalDependencies`, and npm installs only the one whose `os`/`cpu`/`libc` fields match. Each platform package holds that platform's self-contained server and C# installer under `runtime/` and exposes the installer as the `postgresql-sharp-mcp-npm-install` bin. The main package's only script, `postinstall`, runs that bin, which copies the server into the main package's `bin/` over the seed executable. To inspect the npm packages manually, replace `` with the version in `npm/package.json` and `-` with this machine's platform: +The npm distribution is one main package, `@codegiveness/postgresql-sharp-mcp`, plus five platform packages named `@codegiveness/postgresql-sharp-mcp--` (`win32-x64`, `linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`). The main package lists them as exact-version `optionalDependencies`, and npm installs only the one whose `os`/`cpu`/`libc` fields match. Each platform package holds that platform's self-contained server and C# installer under `runtime/` and exposes the installer as the `postgresql-sharp-mcp-npm-install` bin. The main package's only script, `postinstall`, runs that bin, which copies the server into the main package's `bin/` over the seed executable. Keep that script a bare command. Shell operators such as an `|| echo ...` fallback would add logic outside C# and tie every install to npm's `script-shell`: PowerShell, for example, rejects `1>&2` while parsing, so even installs with the platform package present would fail. Without the platform package the install fails with the shell's not-found message for the bin, which the README troubleshooting table explains. To inspect the npm packages manually, replace `` with the version in `npm/package.json` and `-` with this machine's platform: ```bash npm install --prefix ./artifacts/npm-client --ignore-scripts --offline --no-audit --no-fund \ diff --git a/README.md b/README.md index 6368ba9..b151c2d 100644 --- a/README.md +++ b/README.md @@ -329,7 +329,8 @@ Use your actual paths and keep validation stderr private. Reload the saved MCP c | Executable not found / spawn error | Use an absolute executable path including `.exe` on Windows, not an archive/folder; keep extracted files together. | | Wrong architecture / cannot execute binary | Match the archive to your OS and CPU. | | npm reports blocked install scripts / native command cannot execute | Use the full npx command above with package-specific `--allow-scripts`; if a previous install skipped scripts, use a fresh npm cache for the corrected command. | -| npm install fails with `postgresql-sharp-mcp-npm-install: not found` (or "is not recognized") | npm did not install the platform package for this machine. Remove `--omit=optional`/`--no-optional` and any `omit=optional` npm setting. If a project `package-lock.json` was created on another OS, npm can omit this platform's package ([npm/cli#4828](https://github.com/npm/cli/issues/4828)); delete `node_modules` and the lockfile, then reinstall. Supported platforms are Windows x64, glibc Linux x64/arm64 and macOS x64/arm64; on Alpine/musl or other platforms, use the [.NET tool](#1-install-or-run) or a container. | +| npm install fails with `postgresql-sharp-mcp-npm-install: not found` (or "is not recognized") | npm did not install the platform package for this machine. Remove `--omit=optional`/`--no-optional` and any `omit=optional` npm setting. If a project `package-lock.json` was created on another OS, npm can omit this platform's package ([npm/cli#4828](https://github.com/npm/cli/issues/4828)); delete `node_modules` and the lockfile, then reinstall. Supported platforms are Windows x64, glibc Linux x64/arm64 and macOS x64/arm64; on Alpine/musl, Windows on Arm or other platforms, use the [.NET tool](#1-install-or-run) or a container. | +| npx or an MCP client's npx entry fails and prints nothing (on Linux, exit code 127) | npx hides install-script output. Rerun the same command in a terminal with `--foreground-scripts` added after `npx -y` to see it, then follow the row above if it shows `postgresql-sharp-mcp-npm-install: not found` (or "is not recognized"), or the installer's own `postgresql-sharp-mcp: ...` message otherwise. | | .NET runtime not found | npm 0.3.2 and earlier require .NET; upgrade to 0.3.3 or newer after publication or use a local fixed artifact. The .NET tool still requires .NET 10 and `DOTNET_ROOT` for custom runtime locations. npm 0.3.3 and newer and standalone archives bundle the runtime. | | Invalid configuration / missing credentials | Repeat the hidden prompt, clear stale credential sources from the shell/client entry, and start a new client from that shell. Raw PostgreSQL URLs are not accepted. For files, check the path, JSON escaping and accidental `.txt` extension. | | Connection refused, timeout or authentication error | Run `--validate`; check host, port, database, login/password, network/VPN and PostgreSQL access rules. Installing this app does not grant access. |