gulliver-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# gulliver-mcp (npm launcher)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Test on tiny data before you run on giant data.**
+
+Gulliver gives AI agents a dress rehearsal for SQL: estimate the cost, rehearse on 1% → 3% → 10% of the data,
+predict what 100% will do, and only run the full query inside a budget. Local-first, open source, MCP + CLI.
+
+This npm package is a small launcher. Gulliver itself is written in Python and published on PyPI as
+[`gulliver-mcp`](https://pypi.org/project/gulliver-mcp/). The launcher starts the matching Python version for you.
+
+Full documentation: https://github.com/laaielichter/Gulliver
+
+## Requirements
+
+- Node 18 or newer
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) (recommended) or pipx
+
+No Python setup needed beyond that: uv downloads what it needs the first time.
+
+## Use it from your agent (MCP)
+
+Claude Code:
+
+```bash
+claude mcp add gulliver -- npx -y gulliver-mcp --dsn /abs/path/data.duckdb
+```
+
+Any MCP client with a JSON config:
+
+```json
+{
+  "mcpServers": {
+    "gulliver": {
+      "command": "npx",
+      "args": ["-y", "gulliver-mcp", "--config", "/abs/path/gulliver.toml"]
+    }
+  }
+}
+```
+
+## Use the CLI
+
+```bash
+npx -p gulliver-mcp gulliver demo
+npx -p gulliver-mcp gulliver preflight "select count(*) from events" --dsn gulliver_demo.duckdb
+```
+
+## Warehouse drivers
+
+DuckDB works out of the box. For other engines, set `GULLIVER_EXTRAS`:
+
+```bash
+GULLIVER_EXTRAS=postgres npx -y gulliver-mcp --dsn postgresql://...
+GULLIVER_EXTRAS=bigquery,snowflake npx -y gulliver-mcp --config gulliver.toml
+```
+
+Advanced: `GULLIVER_PY_SPEC` overrides the full Python package spec (for example a local path).
+
+## Without npm
+
+```bash
+uvx gulliver-mcp --dsn path/to/warehouse.duckdb
+# or
+pip install gulliver-mcp
+```
+
+## License
+
+MIT

package/bin/gulliver-mcp.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+"use strict";
+require("./launch.js")("gulliver-mcp");

package/bin/gulliver.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+"use strict";
+require("./launch.js")("gulliver");

package/bin/launch.js

@@ -0,0 +1,72 @@
+"use strict";
+
+// Thin launcher: runs the Python package gulliver-mcp (same version as this npm package)
+// through uv, with pipx as a fallback. stdio is passed straight through, so MCP over stdio works.
+
+const { spawnSync, spawn } = require("node:child_process");
+const { version } = require("../package.json");
+
+function pythonSpec() {
+  if (process.env.GULLIVER_PY_SPEC) return process.env.GULLIVER_PY_SPEC;
+  const extras = (process.env.GULLIVER_EXTRAS || "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  const name = extras.length ? `gulliver-mcp[${extras.join(",")}]` : "gulliver-mcp";
+  return `${name}==${version}`;
+}
+
+function available(cmd) {
+  const r = spawnSync(cmd, ["--version"], { stdio: "ignore" });
+  return !r.error && r.status === 0;
+}
+
+function runners(command, spec, args) {
+  return [
+    ["uvx", ["--from", spec, command, ...args]],
+    ["uv", ["tool", "run", "--from", spec, command, ...args]],
+    ["pipx", ["run", "--spec", spec, command, ...args]],
+  ];
+}
+
+module.exports = function launch(command) {
+  const args = process.argv.slice(2);
+  const spec = pythonSpec();
+  const found = runners(command, spec, args).find(([bin]) => available(bin));
+
+  if (!found) {
+    process.stderr.write(
+      [
+        "gulliver: this npm package starts the Python package " + spec + ",",
+        "but it needs uv (recommended) or pipx, and neither was found.",
+        "",
+        "Install uv:  https://docs.astral.sh/uv/getting-started/installation/",
+        "  macOS/Linux:  curl -LsSf https://astral.sh/uv/install.sh | sh",
+        "  Windows:      powershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"",
+        "",
+        "Or skip npm and install directly:  pip install gulliver-mcp",
+        "",
+      ].join("\n")
+    );
+    process.exit(1);
+  }
+
+  const [bin, binArgs] = found;
+  const child = spawn(bin, binArgs, { stdio: "inherit" });
+
+  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.on(sig, () => {
+      if (!child.killed) child.kill(sig);
+    });
+  }
+
+  child.on("error", (err) => {
+    process.stderr.write(`gulliver: could not start ${bin}: ${err.message}\n`);
+    process.exit(1);
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) process.kill(process.pid, signal);
+    else process.exit(code === null ? 1 : code);
+  });
+};

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "gulliver-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Test on tiny data before you run on giant data. npm launcher for the Gulliver MCP server and CLI (runs the Python package gulliver-mcp via uv).",
+  "license": "MIT",
+  "author": "laaielichter",
+  "homepage": "https://github.com/laaielichter/Gulliver#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/laaielichter/Gulliver.git",
+    "directory": "npm"
+  },
+  "bugs": {
+    "url": "https://github.com/laaielichter/Gulliver/issues"
+  },
+  "mcpName": "io.github.laaielichter/gulliver",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "ai-agents",
+    "data-engineering",
+    "sql",
+    "duckdb",
+    "bigquery",
+    "snowflake",
+    "postgres",
+    "cost-optimization",
+    "llm"
+  ],
+  "bin": {
+    "gulliver-mcp": "bin/gulliver-mcp.js",
+    "gulliver": "bin/gulliver.js"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}