grain-tools 0.0.1 → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mehul Fadnavis
+
+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,23 +1,377 @@
-# grain-tools
+# Grain
 
-Reserved for [Grain](https://grain.tools) — a local SQL execution layer that coding
-agents can drive over MCP, a CLI, or the VS Code extension.
+**A fast SQL workspace for VS Code and MCP-enabled AI agents.**
 
-**Nothing is published here yet.** This version reserves the name while the first
-release is prepared. When it ships, this package will provide the stdio MCP server:
+Run SQL in VS Code, manage database profiles securely, inspect results in a
+high-performance grid, and expose safe, visible database tools to Claude, Cursor,
+Copilot, and other Model Context Protocol clients.
+
+[![VS Code Marketplace](https://vsmarketplacebadges.dev/version/pattrnlabs.grain.svg)](https://marketplace.visualstudio.com/items?itemName=pattrnlabs.grain)
+[![Installs](https://vsmarketplacebadges.dev/installs/pattrnlabs.grain.svg)](https://marketplace.visualstudio.com/items?itemName=pattrnlabs.grain)
+[![OpenVSX](https://img.shields.io/open-vsx/v/pattrnlabs/grain?label=OpenVSX&color=a60ee5)](https://open-vsx.org/extension/pattrnlabs/grain)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+---
+
+## Why Grain?
+
+Grain is built for the workflow where humans and agents both need real
+database context:
+
+- **Query from the editor**: open a `.sql` file, press `Cmd+Enter` or
+  `Ctrl+Enter`, and inspect results without leaving VS Code.
+- **Manage real connection profiles**: create, test, select, and migrate
+  database connections from the Grain panel.
+- **Give agents safe, visible access**: expose read-only MCP tools for running
+  queries, listing schemas and tables, describing columns, and inspecting shared
+  result tabs. Agent queries are restricted to read-only SQL by default, and an
+  agent attached through the packaged bridge cannot change your saved connections
+  or ask for your stored credentials.
+- **Stay local-first**: there is no hosted Grain service and no bundled
+  AI model. Credentials are never kept in a configuration file; the service
+  picks an operating system credential helper, the OS keychain, VS Code's Secret
+  Storage, or — only when none is available — a local file protected by
+  filesystem permissions, in that order of preference.
+
+---
+
+## Highlights
+
+- **Connection manager** with dynamic connector forms, active profile selection,
+  legacy settings migration, and per-connection password actions.
+- **Tabbed result grid** powered by AG Grid with sorting, filtering, column type
+  display, adjustable density, TSV copy, and full export to CSV, TSV, or JSON
+  that re-runs the query to fetch every row.
+- **Daemon-backed execution** so heavy queries do not block the editor and
+  results can be shared across VS Code, browser, and MCP surfaces.
+- **MCP server** for Claude Desktop, Cursor, Copilot, and other MCP clients,
+  with safe mode enabled by default for read-only operation.
+- **Multi-surface sessions** so agent-triggered and editor-triggered work can be
+  inspected through the same local daemon without tab ID collisions.
+- **Transparent telemetry** that follows your VS Code telemetry setting and can
+  be turned off at any time. Crash reports carry redacted stack traces, with
+  file paths reduced to their extension and usernames removed. It never sends
+  SQL text, results, credentials, hostnames, database names,
+  schema/table/column names, workspace names, or raw driver error messages. The
+  separately controlled replay capability masks every rendered character and
+  input.
+
+---
+
+## Supported Databases
+
+Grain ships connector metadata and setup forms for:
+
+| Database       | Connector       |
+| -------------- | --------------- |
+| PostgreSQL     | `postgres`      |
+| MySQL          | `mysql`         |
+| SQLite         | `sqlite`        |
+| DuckDB         | `duckdb`        |
+| Trino / Presto | `trino`         |
+| Elasticsearch  | `elasticsearch` |
+| Snowflake      | `snowflake`     |
+| BigQuery       | `bigquery`      |
+| SQL Server     | `mssql`         |
+
+Trino/Presto and PostgreSQL are bundled into the extension build. Native and
+cloud-provider connectors are lazy-loaded and may require their driver runtime in
+the active environment; Grain reports guided missing-driver errors instead
+of failing silently.
+
+---
+
+## Quick Start: VS Code
+
+1. Install Grain from the
+   [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=pattrnlabs.grain)
+   or [OpenVSX](https://open-vsx.org/extension/pattrnlabs/grain).
+2. Run **Grain: Manage Connections** from the Command Palette.
+3. Add a connection profile, set its password, test it, and make it active.
+4. Open a `.sql` file and press **`Cmd+Enter`** on macOS or **`Ctrl+Enter`** on
+   Windows/Linux.
+
+Results open in the **Grain** panel at the bottom of the editor. To force a
+new tab, run **Grain: Run Query in New Tab**.
+
+### Migrating from Legacy Settings
+
+If you previously configured `sqlPreview.host`, `sqlPreview.port`,
+`sqlPreview.user`, `sqlPreview.catalog`, `sqlPreview.schema`, or
+`sqlPreview.databasePath`, open **Grain: Show Welcome Guide** or
+**Grain: Manage Connections**. Grain can import those settings into a
+named connection profile and keep passwords in VS Code Secret Storage.
+
+---
+
+## Quick Start: MCP Agents
+
+### One command
+
+```
+npx -y grain-tools --stdio
+```
+
+That is the command every MCP client is given, on every platform. There is no
+second setup path.
+
+1. Run **Grain: Manage Connections** and confirm your active connection.
+2. Open the Grain settings panel and **enable the MCP server** (`grain.mcpEnabled`).
+   This is required and ships **off** — the daemon serves no MCP surface until you turn it on.
+3. Keep safe mode enabled unless you explicitly want agents to run mutating SQL.
+4. Give your client the command:
+   - **Claude Code**: `claude mcp add grain -- npx -y grain-tools --stdio`
+   - **Cursor**: Settings → MCP Servers → Add new MCP server, type `command`,
+     command `npx -y grain-tools --stdio`
+   - **VS Code**: open the Extensions view, search `@mcp Grain`, and install it
+     into your user profile or the current workspace — the gallery entry carries
+     the command
+   - **Claude Desktop and other file-configured clients**: see
+     [the setup guide](docs/engineering/guides/mcp-client-setup.md), which
+     transcribes the same command into that client's config file
+
+This bridges to the daemon the VS Code extension is already running, so agent
+queries and sessions show up in the results grid alongside anything you run from
+the editor. It works with every MCP client — including ones that cannot send
+custom HTTP headers, such as Claude Desktop — and it needs no credential in your
+config, because the bridge reads the daemon's access token itself.
+
+`-y` is not decoration: an MCP client starts the server with no terminal
+attached, so npm's install prompt would have nobody to answer it.
+
+Enabling `grain.mcpEnabled` in the Grain settings panel is required
+for this stdio bridge too. Launching the bridge without it produces a clear
+refusal rather than a silent failure. If you want to refuse MCP everywhere, including
+this bridge, set `"mcp": { "enabled": false }` in `~/.grain/daemon.json`.
+
+### Advanced: HTTP
+
+The daemon requires an authorization token on every non-public route, so an HTTP
+client must send it. Use this when your client supports custom headers (Cursor
+and VS Code do):
 
 ```json
 {
   "mcpServers": {
     "grain": {
-      "command": "npx",
-      "args": ["-y", "grain-tools", "--stdio"]
+      "url": "http://127.0.0.1:PORT/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_TOKEN"
+      }
     }
   }
 }
 ```
 
-The primary install path will be a standalone binary from
-[grain.tools](https://grain.tools), which needs no Node.js and reduces the
-configuration above to `"command": "grain"`. This package is the fallback channel
-for anyone who would rather use npm.
+**`PORT` is not a fixed number.** The daemon asks the operating system for a free
+port and writes the address it got to `~/.grain/endpoint.json`, so that two
+accounts on one machine, two editors, or a container never compete for the same
+one. Read the current port from that file, or copy the whole snippet — port and
+token already filled in — from the Grain settings panel, which is the
+intended route.
+
+Because the port changes when the daemon restarts, a hand-written HTTP config
+goes stale. **The stdio setup above needs no port at all and is the recommended
+path for that reason.**
+
+To pin a port deliberately — a deployed host, or a client that cannot be
+reconfigured — start the daemon with `--port <number>`, or set
+`GRAIN_PORT`. A pinned port is used exactly as given and never reassigned.
+
+The token also lives at `~/.grain/auth-token`; treat it like a password,
+since it authorizes access to your connections and query results.
+
+> **Upgrading from 0.6.x?** Three things changed. A bare
+> `{"url": "http://localhost:8414/mcp"}` config no longer connects — switch to the
+> stdio config above (recommended) or add the `Authorization` header. **`8414` is
+> also no longer the port**: the daemon takes a free one and publishes it, so an
+> HTTP config that names any fixed port needs either the current port from
+> `~/.grain/endpoint.json` or an explicit `--port` to pin one. The stdio
+> config avoids the question entirely. And
+> `grain.mcpEnabled` now genuinely gates the surface: with it off, `/mcp`
+> returns **404**, because the route is not registered rather than being
+> registered and refused. Previously the setting only decided whether the daemon
+> started eagerly, so HTTP MCP answered whether or not you had enabled it.
+
+### Standalone / stdio Server with its own connections
+
+For CI jobs or any client that should not share the editor's daemon, the same
+command carries its own connection profiles through the environment:
+
+```bash
+GRAIN_CONNECTIONS='[{"id":"analytics","name":"Analytics","type":"postgres","host":"localhost","port":5432,"user":"analyst","database":"warehouse","password":"YOUR_PASSWORD"}]' \
+  npx -y grain-tools --stdio
+```
+
+The same variable goes in an `env` block for a file-configured client; see
+[the setup guide](docs/engineering/guides/mcp-client-setup.md).
+
+`--stdio` first looks for a shared daemon — for example, one started by the VS
+Code extension — and, if it finds one, bridges to it, so the agent's queries and
+sessions still appear in the VS Code grid exactly like the HTTP form above. It
+resolves the address in one order: an explicit `--port`/`--host`, then
+`GRAIN_MCP_PORT`, `GRAIN_PORT` or `MCP_PORT`, and otherwise the
+address the daemon published in `~/.grain/endpoint.json`. There is no
+fallback port to guess at: if nothing is pinned and nothing is published, there is
+no daemon to attach to. If no shared daemon is reachable, it falls back to
+starting its own embedded, isolated daemon exactly as before. Pass
+`--embedded` or set `GRAIN_EMBEDDED=1` to force the isolated daemon
+unconditionally, which is recommended for CI and other headless runs that
+shouldn't depend on (or interfere with) a locally running instance.
+The MCP `initialize` response explicitly reports `Grain isolation mode:
+shared` or `isolated` in its standard `instructions` field. Agents can use that
+protocol signal to tell whether their query sessions are visible in the user's
+editor; stderr is not required for detection.
+
+The extension and the daemon now agree on the address by publication rather than
+by both guessing the same default: the daemon writes where it actually bound, and
+the extension reads it. The endpoint-mismatch warning still fires when a pinned
+port disagrees with a running daemon's published one. It remains detection, not
+automatic correction: align the settings or remove the custom port.
+
+Two accounts on one machine, two editors, and a container each get their own
+daemon and their own address, because the address lives in each config directory
+rather than being one number for the whole machine. Setting `GRAIN_HOME`
+selects which config directory — and therefore which daemon — a client uses.
+
+The MCP server exposes tools for:
+
+| Tool               | What it does                                        |
+| ------------------ | --------------------------------------------------- |
+| `run_query`        | Execute SQL and return typed JSON rows              |
+| `list_connectors`  | Return supported connector types and setup schemas  |
+| `list_connections` | List configured connection profiles without secrets |
+| `save_connection`  | Add or update a connection profile                  |
+| `test_connection`  | Validate saved or unsaved connection settings       |
+| `list_schemas`     | List schemas for a connection                       |
+| `list_tables`      | List tables within a schema                         |
+| `describe_table`   | Return column names and types                       |
+| `get_tab_info`     | Inspect daemon result tab state                     |
+| `cancel_query`     | Cancel a running query                              |
+| `close_tab`        | Close a daemon result tab                           |
+
+Safe mode is on by default and restricts agents to read-only statements such as
+`SELECT`, `SHOW`, `DESCRIBE`, `EXPLAIN`, `WITH`, and connector-specific metadata
+queries.
+
+See the full [MCP client setup guide](docs/engineering/guides/mcp-client-setup.md)
+and [daemon URL reference](docs/engineering/guides/daemon-url-reference.md) for
+advanced configuration.
+
+---
+
+## Configuration
+
+Most users should use **Grain: Manage Connections** instead of editing
+settings JSON by hand.
+
+| Setting                    | Default                    | Description                                                                            |
+| -------------------------- | -------------------------- | -------------------------------------------------------------------------------------- |
+| `grain.activeConnectionId` | empty                      | Connection profile used for VS Code query execution                                    |
+| `grain.maxRowsToDisplay`   | `500`                      | Max rows shown in the grid; full export is still available                             |
+| `grain.fontSize`           | `0`                        | Results grid font size in px; `0` inherits from the editor                             |
+| `grain.rowHeight`          | `normal`                   | Grid density: `compact`, `normal`, or `comfortable`                                    |
+| `grain.tabNaming`          | `file-sequential`          | Result tab naming strategy                                                             |
+| `grain.alwaysRunInNewTab`  | `false`                    | Always open query results in a new tab                                                 |
+| `grain.mcpEnabled`         | `false`                    | Serve the local MCP surface for agent access. Off means `/mcp` is not registered (404) |
+| `grain.mcpSafeMode`        | `true`                     | Restrict MCP query execution to read-only statements                                   |
+| `grain.telemetry.enabled`  | `false`                    | Opt in to anonymous product telemetry                                                  |
+| `grain.telemetryHost`      | `https://us.i.posthog.com` | Advanced PostHog-compatible telemetry endpoint                                         |
+
+Legacy connection settings such as `sqlPreview.host`, `sqlPreview.port`,
+`sqlPreview.user`, `sqlPreview.catalog`, `sqlPreview.schema`, and
+`sqlPreview.databasePath` remain available for migration and backward
+compatibility.
+
+### Passwords and Secrets
+
+Passwords entered through the VS Code connection manager are stored per
+connection in VS Code Secret Storage, backed by the operating system keychain.
+They are not written to `settings.json` or sent to the webview.
+
+Use these commands when needed:
+
+- **Grain: Set Connection Password**
+- **Grain: Clear Connection Password**
+- **Grain: Manage Connections**
+
+### Managed Machines
+
+On most machines Grain runs as one background service the system keeps
+alive. On a machine whose policy forbids that, Grain starts on demand
+instead. The practical difference is that the first request after a pause
+takes a moment longer; nothing else changes.
+
+### Telemetry
+
+Grain telemetry is enabled by default when VS Code telemetry is enabled,
+and you can turn it off at any time with `grain.telemetry.enabled`. Events
+are anonymous and allowlisted, and are used to improve setup, connector
+reliability, query workflows, MCP adoption, and product quality.
+
+When something crashes, Grain sends a **redacted stack trace** so the
+failure can be diagnosed without asking you for logs. Before anything leaves
+your machine, file paths are reduced to their extension (`<path>/*.sql`) and
+usernames are removed; paths that point at code keep only the part from
+`node_modules/` or the build directory onward. If redaction fails for any
+reason, the report is dropped rather than sent.
+
+Grain never sends SQL text, query results, credentials, hostnames,
+database/schema/table/column names, workspace names, environment variables,
+process arguments, or raw driver error messages. A driver's error message can
+embed table names, column names, and literal data values, so crash reports
+carry the error's type and its stack — not the message text.
+
+Session replay is separately feature-flagged and disabled by default. When it is
+enabled, it covers only the VS Code results webview and masks every rendered
+character and input; it does not record SQL, results, or other displayed content.
+
+Use **Grain: Show Telemetry Status** to inspect the effective telemetry
+state.
+
+---
+
+## Architecture
+
+Grain uses a local daemon model:
+
+```text
+VS Code extension / MCP client / browser surface
+        |
+        v
+Grain daemon on localhost
+        |
+        v
+Database connector
+        |
+        v
+Your database
+```
+
+The daemon owns connection profiles, query execution, result tabs, MCP
+transports, and browser/VS Code projections. That lets editor sessions and agent
+sessions share the same local state while keeping credentials and execution on
+your machine.
+
+---
+
+## Release Notes
+
+See [Changelog.md](Changelog.md) for the full release history.
+
+---
+
+## Contributing
+
+Contributions are welcome, especially new connector support, reliability
+improvements, and documentation fixes. See [CONTRIBUTING.md](CONTRIBUTING.md)
+for setup instructions and development workflow.
+
+Found a bug? Open an issue on
+[GitHub](https://github.com/pattrnlabs/grain/issues).
+
+---
+
+## License
+
+MIT (c) 2026 [Mehul Fadnavis](https://github.com/fadnavismehul)