{
  "markdown": "# nexql-mcp\n\nStandalone Postgres MCP server — schema-aware, read-only by default, installable everywhere.\n\nNexQL Pro ships an in-process MCP server locked to VS Code (`pro/src/mcp/`). This repo extracts that capability into an independent Rust binary any MCP client can spawn: Claude Desktop, Cursor, VS Code Copilot, Zed, etc.\n\n**Status:** Phases 0–6 + **Phase 7 extension cutover (stdio spawn)** + **Phase 8 HTTP (bearer, sessions, rate limit)** + **Phase 9 write/admin tools** landed. 54 tools across Schema, Query, Context, Perf, Write, and Admin. Full OAuth gateway stays pro-only; session-store LRU eviction cap not yet implemented. See [docs/CUTOVER.md](docs/CUTOVER.md).\n\n## Why this exists\n\nCompeting Postgres MCP servers expose `connect → run query → return rows`. Models hallucinate table names against schemas that do not exist. NexQL's moat is the offline schema index (TF-IDF, join graph with inferred FKs, value profiles, optional embeddings, RRF fusion) built in `pro/src/features/dbindex/`. This repo ports that index plus 54 query/schema/DBA/meta tools from Pro into a fast, trivially installable binary.\n\n## Architecture\n\n```\ncrates/\n├── nexql-mcp/      CLI, subcommands, wiring (binary)\n├── nexql-proto/    MCP JSON-RPC types, transports\n├── nexql-tools/    tool registry, schemas, executors\n├── nexql-index/    dbindex port (builder, store, lexical, joins, embed)\n├── nexql-conn/     connection resolution, pool, credentials\n└── nexql-policy/   access modes, allow/deny, PII, caps, audit\nnpm/                npx shim (per-platform optionalDependencies)\nmcpb/               one-click Claude Desktop bundle\ndocs/               per-client setup, tool reference\n```\n\nLayering is one-directional: `policy` + `conn` are leaves → `index` → `tools` → binary. `nexql-tools` never depends on `nexql-proto`.\n\n**Scope boundary:** nexql-mcp manages objects *within* a connected database (tables, indexes, columns, …), not the database catalog itself. `CREATE DATABASE` / `DROP DATABASE` are rejected in every access mode — permanent, intentional scope, not a gap. See [docs/tools/README.md](docs/tools/README.md#scope-boundary-no-database-catalog-operations) and [docs/REFERENCE.md](docs/REFERENCE.md).\n\n## Install\n\n### npx — recommended, zero install\n\n```bash\nnpx -y nexql-mcp@latest postgres://dev@localhost:5432/appdb doctor\n```\n\n`-y` skips the \"ok to proceed?\" confirmation prompt; `@latest` always resolves the newest published\nrelease instead of whatever npx happens to have cached — always use both together. This is the desired\nway to run nexql-mcp: no separate install step, nothing added to `PATH`, works identically whether a\nhuman is typing it or an AI agent is running it on your behalf. Requires [Node.js](https://nodejs.org/)\n(npx ships with it) — nothing else.\n\n```bash\n# Verify\nnpx -y nexql-mcp@latest --version\n\n# Setup\nnpx -y nexql-mcp@latest setup  # initialize connections and db profiles\n\n# Wire your MCP client (or run the guided wizard)\nnpx -y nexql-mcp@latest init cursor          # Cursor\nnpx -y nexql-mcp@latest init claude-desktop  # Claude Desktop\nnpx -y nexql-mcp@latest init vscode-copilot  # VS Code Copilot\nnpx -y nexql-mcp@latest tui                  # interactive profile + client wiring\n```\n\nClient config (`command`/`args`) uses the same pattern — no install step for the client to rely on either:\n\n```json\n{\n  \"mcpServers\": {\n    \"nexql-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"nexql-mcp@latest\", \"--profile\", \"mydb\"]\n    }\n  }\n}\n```\n\n> **If you are an AI coding agent setting this up on a user's behalf:** run `npx -y nexql-mcp@latest init <client> --apply` — non-interactive, no browser needed, writes the merged client config directly (`.mcp.json` for `claude-code`, `claude_desktop_config.json` for `claude-desktop`, etc. — see [docs/clients/README.md](docs/clients/README.md) for exact paths per client). Or drive `nexql-mcp setup`'s HTTP API directly: `POST /api/v1/clients/preview` → `POST /api/v1/clients/apply` (bearer token printed to stderr on startup). Prefer this over hand-writing `claude mcp add`-style shell commands or hand-parsing/merging the client's JSON config yourself.\n\nPer-client config paths and paste blocks: [docs/clients/README.md](docs/clients/README.md).\n\n`npm install -g nexql-mcp` also works if you'd rather have a permanent `nexql-mcp` on `PATH` than repeat\n`npx -y nexql-mcp@latest` — same shim, same [`@nexql/mcp-<os>-<arch>`](npm/bin/nexql-mcp.js) prebuilt\nbinaries, no Rust toolchain needed either way.\n\n**Linux system requirements:** prebuilt GNU/Linux binaries target **glibc 2.35+** (Ubuntu 22.04, Debian 12, RHEL 9, and newer). If npx/npm fails with `GLIBC_2.39 not found`, use one of the fallback methods below (`cargo install` builds from source; Docker sidesteps glibc entirely). Musl/static Linux builds are not published yet.\n\n### Other install methods (fallback)\n\nReach for one of these only if npx isn't an option — an offline/air-gapped environment, a CI image that\nwants a pinned binary baked in, no Node.js available, or you simply prefer a permanent install. All ship\nthe same binary as the npm package.\n\n<details>\n<summary><strong>Quick install script (Linux / macOS / Windows)</strong> — installs a permanent binary, no Node.js required</summary>\n\n**Linux & macOS** — downloads the latest release, installs to `/usr/local/bin` (or `~/.local/bin` if sudo is unavailable), then prints setup steps:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/NexQL-OSS/mcp/main/scripts/install.sh | bash\n```\n\nPin a version:\n\n```bash\nNEXQL_MCP_VERSION=v0.2.2 curl -fsSL https://raw.githubusercontent.com/NexQL-OSS/mcp/main/scripts/install.sh | bash\n```\n\n**Windows** (PowerShell) — installs to `%LOCALAPPDATA%\\Programs\\nexql-mcp` and adds it to your user `PATH`:\n\n```powershell\nirm https://raw.githubusercontent.com/NexQL-OSS/mcp/main/scripts/install.ps1 | iex\n```\n\nPin a version:\n\n```powershell\n$env:NEXQL_MCP_VERSION = \"v0.2.2\"; irm https://raw.githubusercontent.com/NexQL-OSS/mcp/main/scripts/install.ps1 | iex\n```\n\nOr download and run the scripts locally: [`scripts/install.sh`](scripts/install.sh) · [`scripts/install.ps1`](scripts/install.ps1). Once installed, drop the `npx -y nexql-mcp@latest` prefix and call `nexql-mcp` directly for every command above.\n\n</details>\n\n<details>\n<summary><strong>uv (PyPI)</strong></summary>\n\n[uv](https://docs.astral.sh/uv/) installs CLI tools from PyPI into isolated environments — same prebuilt binary, no Rust toolchain.\n\nInstall uv itself (if needed):\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux\n```\n\n```powershell\nirm https://astral.sh/uv/install.ps1 | iex        # Windows\n```\n\nInstall nexql-mcp:\n\n```bash\nuv tool install nexql-mcp\nuv tool update-shell    # once, if uv warns the tool bin dir is not on PATH\n```\n\nOne-off without installing (uv's equivalent of `npx -y`):\n\n```bash\nuvx nexql-mcp postgres://dev@localhost:5432/appdb doctor\n```\n\nPin a version:\n\n```bash\nuv tool install 'nexql-mcp==0.2.2'\n```\n\nUpgrade later:\n\n```bash\nuv tool upgrade nexql-mcp\n```\n\n> **PyPI status:** wheels are not published yet. Until the first PyPI release lands, use npx or the quick install script above. Maintainer steps: [docs/publish-pypi-uv.md](docs/publish-pypi-uv.md).\n\n</details>\n\n<details>\n<summary><strong>cargo (crates.io)</strong> — builds from source</summary>\n\n```bash\ncargo install nexql-mcp\n```\n\nNeeds clang/libclang first (`pg_query`'s bindgen requires it):\n\n```bash\nsudo apt install clang libclang-dev   # Debian/Ubuntu\nsudo pacman -S clang                  # Arch\n```\n\n</details>\n\n<details>\n<summary><strong>Manual download</strong> — grab a release archive by hand</summary>\n\nFrom the [Releases page](https://github.com/NexQL-OSS/mcp/releases/latest):\n\n| Platform | Archive |\n|----------|---------|\n| Linux x64 | `nexql-mcp-<tag>-x86_64-unknown-linux-gnu.tar.gz` |\n| Linux arm64 | `nexql-mcp-<tag>-aarch64-unknown-linux-gnu.tar.gz` |\n| macOS Intel | `nexql-mcp-<tag>-x86_64-apple-darwin.tar.gz` |\n| macOS Apple Silicon | `nexql-mcp-<tag>-aarch64-apple-darwin.tar.gz` |\n| Windows x64 | `nexql-mcp-<tag>-x86_64-pc-windows-msvc.tar.gz` |\n\nExtract and put `nexql-mcp` (or `nexql-mcp.exe`) on your `PATH`.\n\n</details>\n\n<details>\n<summary><strong>Docker</strong></summary>\n\nPrebuilt, published on every release to [GHCR](https://github.com/NexQL-OSS/mcp/pkgs/container/mcp):\n\n```bash\ndocker run --rm -i ghcr.io/nexql-oss/mcp:0.5.0 postgres://dev@host.docker.internal:5432/appdb\n# or: ghcr.io/nexql-oss/mcp:latest\n```\n\nOr build locally from the distroless `Dockerfile`:\n\n```bash\ndocker build -t nexql-mcp:0.5.0 .\ndocker run --rm -i nexql-mcp:0.5.0 postgres://dev@host.docker.internal:5432/appdb\n```\n\n</details>\n\n<details>\n<summary><strong>Claude Desktop (MCPB one-click bundle)</strong></summary>\n\nEach release attaches a platform `.mcpb` bundle (`nexql-mcp-<vendor>.mcpb`) — download the one matching\nyour OS/arch from the [Releases page](https://github.com/NexQL-OSS/mcp/releases/latest) and double-click\nto install into Claude Desktop. Built from [`mcpb/manifest.json`](mcpb/manifest.json) via\n[`scripts/package-mcpb.sh`](scripts/package-mcpb.sh).\n\n</details>\n\n<details>\n<summary><strong>Homebrew</strong></summary>\n\nNo published tap yet — each release renders a formula (`Formula/nexql-mcp.rb`, via\n[`scripts/render-homebrew-formula.sh`](scripts/render-homebrew-formula.sh)) and attaches it as a release\nasset for a future `homebrew-tap` repo to pick up. Until that tap exists, use npx or the quick install script above.\n\n</details>\n\n<details>\n<summary><strong>MCP Registry</strong></summary>\n\nListed in the [official MCP Registry](https://registry.modelcontextprotocol.io) as\n`io.github.NexQL-OSS/nexql-mcp` ([`server.json`](server.json)), published automatically after each\nrelease via GitHub OIDC (no stored credentials) — see\n[`.github/workflows/publish-mcp-registry.yml`](.github/workflows/publish-mcp-registry.yml).\n\n- mcp-name: io.github.NexQL-OSS/nexql-mcp\n\n</details>\n\n<details>\n<summary><strong>From source</strong></summary>\n\n```bash\nexport LIBCLANG_PATH=\"${LIBCLANG_PATH:-/usr/lib}\"   # or your llvm lib dir\ncargo build --release -p nexql-mcp\n./target/release/nexql-mcp postgres://dev@localhost:5432/appdb\n```\n\n</details>\n\n## Set up a connection\n\n> Commands below assume `nexql-mcp` resolves on `PATH`. If you're running via npx instead, prefix each one with `npx -y nexql-mcp@latest` in place of `nexql-mcp` — see [Install](#install).\n\n**One-off**, no config — pass a connection string directly:\n\n```bash\nnexql-mcp postgres://dev@localhost:5432/appdb\n```\n\n**Saved profiles** — put connections in `~/.config/nexql-mcp/config.toml` (override the path with `NEXQL_MCP_CONFIG`):\n\n```toml\ndefault_profile = \"local\"\n\n[profiles.local]\nurl = \"postgres://dev@localhost:5432/appdb\"\naccess_mode = \"read\"\n\n[profiles.prod]\nhost = \"prod.example.com\"\ndbname = \"app\"\nuser = \"readonly_agent\"\npassword_command = \"op read op://vault/pg/password\"   # never store plaintext secrets\nsslmode = \"verify-full\"\naccess_mode = \"read\"\nschemas = [\"public\", \"billing\"]\ndeny_tables = [\"auth.*\"]\npii_columns = [\"public.users.ssn\", \"public.users.email\"]\nmax_rows = 200\n```\n\nFull field reference: [docs/config.example.toml](docs/config.example.toml). Then run bare (`nexql-mcp`) to use `default_profile`, or `nexql-mcp --profile prod`.\n\n**Test a connection** before wiring it into a client:\n\n```bash\nnexql-mcp postgres://dev@localhost:5432/appdb doctor\n# or, for a saved profile (note: --profile goes before the subcommand):\nnexql-mcp --profile prod doctor\n```\n\n**Guided setup** — an interactive profile editor plus one-keystroke wiring into whichever clients you use:\n\n- `nexql-mcp tui` — terminal UI (see [Interactive TUI](#interactive-tui) below)\n- `nexql-mcp setup` — browser UI on loopback (profiles, client wiring, npx/path launch toggle); also `npx -y nexql-mcp@latest setup`\n\n### Wire a client\n\n```bash\nnexql-mcp postgres://dev@localhost:5432/appdb init cursor\n```\n\nSupported `init` clients: `claude` | `claude-desktop` | `claude-code` | `cursor` | `vscode` | `vscode-copilot` | `zed` | `windsurf` | `continue` | `jetbrains` | `openai-agents`.\n\nPer-client paste blocks: [docs/clients/README.md](docs/clients/README.md).\n\n### Tool surface / context budget\n\n`--tools query|dba|meta|full` (env: `NEXQL_MCP_TOOLS`) restricts which tools are *advertised* to the client — a context-window budgeting knob, not a security boundary. It's purely advisory: `nexql-policy`'s `access_mode` (`read`/`write`/`admin`, set via `--access-mode` or a profile's `access_mode`) is what actually gates what a call can do. Pick a narrower profile only to reduce how much tool-schema JSON gets loaded into your agent's context window:\n\n- `query` — core query/discovery tools (schema search, `run_select`, `explain_query`, …)\n- `dba` — monitoring/admin tools (health checks, index suggestions, locks, …)\n- `meta` — the smallest initial surface, plus `discover_tools` for lazy on-demand activation of the rest (see [docs/tools/README.md](docs/tools/README.md#start-here))\n- `full` (default) — every active tool\n\nExact membership per profile: `nexql-tools/src/registry.rs`'s `QUERY_PROFILE`/`DBA_PROFILE`/`META_PROFILE`/`ACTIVE` constants.\n\n## Use with the NexQL VS Code extension\n\nIf you already use [`ric-v.postgres-explorer`](https://marketplace.visualstudio.com/items?itemName=ric-v.postgres-explorer) (+ NexQL Pro), you don't need any of the above — the extension can spawn this binary itself and reuse your existing saved connections instead of a separate `config.toml`.\n\n1. Settings → search **NexQL: Mcp: Enabled** (`postgresExplorer.mcp.enabled`) → check it. Off by default.\n2. That's it — it takes effect immediately (no reload needed) and picks up every connection already saved in `postgresExplorer.connections`. It shows up as an MCP server named **NexQL** in Copilot Chat / agent-mode tool pickers.\n\nThe extension resolves the binary in this order: `postgresExplorer.mcp.binaryPath` setting → `NEXQL_MCP_BIN` env var → a copy bundled with the extension → whatever `nexql-mcp` is on your `PATH` (i.e. anything installed via npm/cargo/curl above). Set `postgresExplorer.mcp.binaryPath` explicitly if you want the extension to use a specific install.\n\n### Interactive TUI\n\n```bash\nnexql-mcp tui\n```\n\nGuided profile editor: add/edit/delete a connection profile, test-connect it live before saving, then pick any of 7 clients (Claude Desktop, Claude Code, Cursor, VS Code, Copilot Chat, Zed, Windsurf) to wire it into at once. Each selected client's real config file is read, merged (existing unrelated servers are preserved), shown as a diff, and only written after you confirm — a timestamped backup is kept alongside it. `continue` / `jetbrains` / `openai-agents` have no safe on-disk merge target, so those stay copy-paste snippets in the summary screen, same as `init`.\n\nKeys: `n` new · `e`/Enter edit · `d` delete · `t` test · `w` wire into clients · `q` quit. Bare `nexql-mcp` (no URL, no flags) launches the TUI automatically when nothing else resolves a connection.\n\n### Releases\n\nPushing a `v*` tag triggers [`.github/workflows/release.yml`](.github/workflows/release.yml): builds\ndarwin arm64/x64, linux gnu arm64/x64, and windows x64; attaches archives, per-platform `.mcpb` bundles,\na CycloneDX SBOM, and a rendered Homebrew formula to a GitHub release; publishes the npm packages and\nGHCR image; and publishes the workspace crates to crates.io in dependency order. A follow-up workflow\n([`publish-mcp-registry.yml`](.github/workflows/publish-mcp-registry.yml)) then lists the release on the\nMCP Registry via GitHub OIDC. Linux GNU binaries are built on Ubuntu 22.04 (glibc 2.35). Musl targets remain deferred until a clang-enabled musl builder is validated.\n\n## Development\n\n```bash\ncargo check          # workspace compile\ncargo run -p nexql-mcp -- doctor\ncargo test -p nexql-mcp -- init_clients\ncargo fmt --all\ncargo clippy --workspace --all-targets\n```\n\nRead [CLAUDE.md](CLAUDE.md) and [docs/REFERENCE.md](docs/REFERENCE.md) before implementing.\n\n## License\n\nGPL-3.0-only for all crates in this repo, from v0.2.0 onward. If you distribute this\nprogram or a derivative — including bundled inside another application — you must\nrelease your source under the GPL as well.\n\nReleases up to and including **v0.1.6** were published under Apache-2.0. That grant\nis irrevocable for those versions and is unaffected by this change.\n\nCopyright is held solely by the NexQL-OSS Team, so commercial licenses that lift the\nGPL obligation are available on request. Premium extensions (provider embeddings,\nteam sync, hosted gateway) live in a separate proprietary crate.\n\n## Roadmap\n\n| Phase | Deliverable |\n|-------|-------------|\n| 0 | Spike: tokio-postgres + candle MiniLM proof |\n| 1 | `nexql-conn` + `nexql-policy` + pg_query validator |\n| 2 | MCP stdio transport + ~8 catalog tools |\n| 3 | `nexql-index` (byte-compatible with TS format) |\n| 4 | Full tool surface, resources, prompts, completions |\n| 5 | Local embeddings + RRF fusion |\n| 6 | v1.0 ship: cargo-dist, npm, brew, Docker, MCPB |\n| 7 | Extension cutover — VS Code spawns binary via stdio MCP definition |\n| 8 | Streamable HTTP + bearer token (`--http` / `NEXQL_MCP_HTTP_TOKEN`) — OAuth gateway = pro |\n| 9 | Write/admin tools + `validate_write_sql` (opt-in `--access-mode write\\|admin`) |\n| 10 | Agent ergonomics — `orient` one-call bootstrap, `discover_tools` + `--tools` context-budget profiles, `init <client> --apply`, `save_profile` merge semantics, `apply_ddl` destructive-confirm gate, per-call `timeout_ms` ([docs/roadmap/claude-review-2026-08-23.md](docs/roadmap/claude-review-2026-08-23.md)) |\n\nFull plan: internal design doc (federated-greeting-badger). Cutover details: [docs/CUTOVER.md](docs/CUTOVER.md).\n\n## Reference implementation\n\nTypeScript sources in the sibling `nexql-pro` checkout (chat still uses these; MCP HTTP stack removed):\n\n- `pro/src/mcp/McpDefinitionProvider.ts` — stdio spawn of this binary\n- `pro/src/mcp/NexqlMcpStdioHost.ts` — ephemeral profile + binary resolve\n- `pro/src/providers/chat/tools/ToolSpec.ts`\n- `pro/src/providers/chat/tools/ToolExecutor.ts`\n- `pro/src/features/dbindex/*`\n",
  "bytes": 18138,
  "sha": "315313189181561f45a8c0b46bd5b4a477fed5870d35d989f840e337408e1e8f",
  "repo_slug": "nexql-oss/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_nexql_oss_nexql_mcp_56fd36ea/readme"
}