@eamonboyle/mssql-mcp 1.6.0 → 2.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm version](https://img.shields.io/npm/v/@eamonboyle/mssql-mcp.svg)](https://www.npmjs.com/package/@eamonboyle/mssql-mcp)
-[![Node.js 20+](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
+[![Node.js 22+](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org/)
 [![X: @eamonyo](https://img.shields.io/badge/X-%40eamonyo-000000?style=flat-square&logo=x&logoColor=white)](https://x.com/eamonyo)
 
 [![Add to Cursor](https://img.shields.io/badge/Add_to-Cursor-000000?style=for-the-badge&logo=cursor&logoColor=white)](https://cursor.com/en/install-mcp?name=mssql-local&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBlYW1vbmJveWxlL21zc3FsLW1jcCJdLCJlbnYiOnsiU0VSVkVSX05BTUUiOiJsb2NhbGhvc3QiLCJEQVRBQkFTRV9OQU1FIjoiQXBwREIiLCJEQVRBQkFTRVMiOiJBcHBEQixSZXBvcnRpbmdEQiIsIkRCX1VTRVIiOiJ5b3VyX3VzZXJuYW1lIiwiREJfUEFTU1dPUkQiOiJ5b3VyX3Bhc3N3b3JkIiwiVFJVU1RfU0VSVkVSX0NFUlRJRklDQVRFIjoidHJ1ZSIsIlJFQURPTkxZIjoiZmFsc2UiLCJFTkFCTEVfRERMIjoiZmFsc2UifX0=)
@@ -30,10 +30,12 @@ Supported clients include Cursor, VS Code, Claude Desktop, and other MCP-compati
 
 ### Prerequisites
 
-- Node.js 20 or newer
+- Node.js 22 or newer (check with `node --version`)
 - Microsoft SQL Server
 - An MCP-compatible client
 
+> **Still on Node.js 20?** Version 1.6.0 is the last release that runs on Node 20, which reached end-of-life in April 2026. Newer releases stop at startup with a message explaining this. Upgrade Node.js, or pin the older release in your MCP configuration with `npx -y @eamonboyle/mssql-mcp@1.6.0`.
+
 The recommended installation runs the published package directly:
 
 ```bash
@@ -112,11 +114,31 @@ The server validates these variables before starting. Missing or blank values pr
 
 | Variable                   | Accepted format        | Purpose                                                               |
 | -------------------------- | ---------------------- | --------------------------------------------------------------------- |
-| `DB_USER`                  | Nonblank string        | SQL authentication username                                           |
-| `DB_PASSWORD`              | Nonblank string        | SQL authentication password                                           |
+| `DB_USER`                  | Nonblank string        | SQL login (or NTLM) username; not used for Entra ID auth              |
+| `DB_PASSWORD`              | Nonblank string        | SQL login (or NTLM) password; not used for Entra ID auth              |
 
 At least one database variable is required: set `DATABASE_NAME`, `DATABASES`, or both. With only `DATABASE_NAME`, that database is both the default and the allowlist. With only `DATABASES`, the first entry is the default. When both are set, `DATABASE_NAME` is used if it appears in `DATABASES`; otherwise the first allowed database is the runtime default.
 
+### Authentication
+
+`SQL_AUTH_TYPE` selects how the server signs in to SQL Server. The default, `sql`, uses `DB_USER` and `DB_PASSWORD`.
+
+| `SQL_AUTH_TYPE`           | Also requires                                              | Notes                                                                                              |
+| ------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `sql` (default)           | `DB_USER`, `DB_PASSWORD`                                   | SQL Server login                                                                                   |
+| `ntlm`                    | `DB_USER`, `DB_PASSWORD`, `DB_DOMAIN`                      | Windows domain account over NTLM; integrated (SSPI) auth of the current user is not supported      |
+| `azure-default`           | Optional `AZURE_CLIENT_ID`                                 | Microsoft Entra ID via `DefaultAzureCredential`: `az login`, managed identity, workload identity, environment credentials |
+| `azure-service-principal` | `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID` | Entra ID app registration with a client secret                                                     |
+| `azure-access-token`      | `AZURE_ACCESS_TOKEN`                                       | A pre-acquired Entra ID token; it is not refreshed, so restart the server when it expires          |
+
+Entra ID types default `ENCRYPT` to `true` and `TRUST_SERVER_CERTIFICATE` to `false`, because Azure SQL requires TLS and presents publicly trusted certificates. For Azure SQL with `azure-default` after `az login`:
+
+```text
+SERVER_NAME=myserver.database.windows.net
+DATABASE_NAME=mydb
+SQL_AUTH_TYPE=azure-default
+```
+
 ### Hostname and port
 
 > Do not include the port in `SERVER_NAME`. Values such as `localhost,1434` are not supported by the Node.js `mssql` driver configuration used by this package. Set `SERVER_NAME` to the hostname and use `SERVER_PORT` separately.
@@ -152,8 +174,9 @@ Optional variables do not need empty placeholders. In-code defaults apply when t
 | ----------------------- | ----------------------------- | --------------------- | -------------------------------------------------------------- |
 | `SERVER_NAME`           | Hostname                      | `localhost`           | SQL Server hostname only                                      |
 | `SERVER_PORT`           | Integer from `1` to `65535`   | Driver default `1433` | SQL Server TCP port; omitted from the driver config when unset |
-| `ENCRYPT`               | `"true"` or `"false"`         | `"false"`             | Enable TLS encryption in the `mssql` driver                    |
-| `TRUST_SERVER_CERTIFICATE` | `"true"` or `"false"`      | `"true"`              | Trust the SQL Server certificate without validating its chain |
+| `SQL_AUTH_TYPE`         | See [Authentication](#authentication) | `sql`         | SQL Server authentication method                               |
+| `ENCRYPT`               | `"true"` or `"false"`         | `"false"` (`"true"` for Entra ID) | Enable TLS encryption in the `mssql` driver        |
+| `TRUST_SERVER_CERTIFICATE` | `"true"` or `"false"`      | `"true"` (`"false"` for Entra ID) | Trust the SQL Server certificate without validating its chain |
 | `READONLY`              | `"true"` or `"false"`         | `"false"`             | Remove write and DDL tools when enabled                        |
 | `ENABLE_DDL`            | `"true"` or `"false"`         | `"false"`             | Allow registered DDL tools to execute                          |
 | `CONNECTION_TIMEOUT`    | Positive integer seconds      | `30`                  | SQL Server connection timeout                                  |
@@ -165,6 +188,9 @@ Optional variables do not need empty placeholders. In-code defaults apply when t
 | `MCP_HTTP_HOST`         | Host or IP string             | `127.0.0.1`           | Bind address for HTTP mode                                     |
 | `MCP_HTTP_PORT`         | Integer from `1` to `65535`   | `3333`                | Bind port for HTTP mode                                        |
 | `MCP_BASE_URL`          | Absolute HTTP or HTTPS URL    | Unset                 | Public HTTP base advertised by the server; `/mcp` is appended  |
+| `MCP_HTTP_AUTH_TOKEN`   | Nonblank string               | Unset                 | Require `Authorization: Bearer <token>` on HTTP requests       |
+| `MCP_HTTP_ALLOWED_HOSTS`| Comma-separated hostnames     | Loopback + bind host + `MCP_BASE_URL` host | Hostnames accepted in `Host`/`Origin` headers |
+| `MCP_HTTP_ALLOW_UNAUTHENTICATED` | `"true"` or `"false"` | `"false"`           | Allow a non-loopback `MCP_HTTP_HOST` without a token           |
 
 Blank optional values use their documented defaults. Explicit nonblank invalid integers, booleans, ports, URLs, or transport names fail validation rather than falling back silently.
 
@@ -180,7 +206,7 @@ Blank optional values use their documented defaults. Explicit nonblank invalid i
 
 When writes are enabled:
 
-1. `insert_data`, `update_data`, `delete_data`, and DDL tools require `confirmed: true` unless the client completes MCP elicitation.
+1. `insert_data`, `update_data`, `delete_data`, and DDL tools ask the user to confirm through MCP elicitation when the client supports it (Cursor, VS Code, Claude). Clients without elicitation must pass `confirmed: true`. Over HTTP, prompts work for 2026-07-28 clients; 2025-era HTTP clients must pass `confirmed: true` because the stateless transport cannot carry their elicitation round trip.
 2. `update_data` and `delete_data` require nonempty structured `filters`, not raw SQL WHERE text.
 3. With the default `REQUIRE_WRITE_PREVIEW=true`, call `preview_update` or `preview_delete` first and pass its `previewToken` to the matching write.
 4. Preview tokens expire after 10 minutes, are single-use, and are bound to the same tool, table, filters, and update payload.
@@ -206,7 +232,14 @@ The default endpoint is:
 http://127.0.0.1:3333/mcp
 ```
 
-An HTTP client must accept `application/json, text/event-stream`. Each HTTP request creates a fresh MCP server instance. Preview tokens use a process-wide store so they remain valid across requests to the same process.
+The HTTP endpoint serves both the 2026-07-28 MCP protocol and 2025-era clients. A client must accept `application/json, text/event-stream`. Each HTTP request creates a fresh MCP server instance; preview tokens, stored query results, and query plans use process-wide stores, so they stay valid across requests to the same process.
+
+HTTP security:
+
+- Only `/mcp` is served. `Host` and `Origin` headers are checked against `MCP_HTTP_ALLOWED_HOSTS` (by default loopback names, the bind host, and the `MCP_BASE_URL` host) to block DNS-rebinding attacks from web pages.
+- Set `MCP_HTTP_AUTH_TOKEN` to require `Authorization: Bearer <token>`.
+- The server speaks plain HTTP. Off loopback, put a TLS-terminating reverse proxy in front so the bearer token and query results are encrypted, and set `MCP_BASE_URL` to its `https://` address. Startup logs a warning when a non-loopback bind has no `https://` `MCP_BASE_URL`.
+- Binding `MCP_HTTP_HOST` to anything other than loopback fails at startup unless `MCP_HTTP_AUTH_TOKEN` is set, or `MCP_HTTP_ALLOW_UNAUTHENTICATED=true` acknowledges that another layer (reverse proxy, network policy) protects the endpoint.
 
 For a reverse proxy or externally published path, set `MCP_BASE_URL` to the public base without the final `/mcp` segment:
 
@@ -222,12 +255,15 @@ Cursor HTTP configuration:
 {
   "mcpServers": {
     "mssql-http": {
-      "url": "http://127.0.0.1:3333/mcp"
+      "url": "http://127.0.0.1:3333/mcp",
+      "headers": { "Authorization": "Bearer ${env:MSSQL_MCP_TOKEN}" }
     }
   }
 }
 ```
 
+Omit `headers` when `MCP_HTTP_AUTH_TOKEN` is not set.
+
 ## Tools
 
 | Tool                     | Mode  | Purpose                                                          |
@@ -243,7 +279,7 @@ Cursor HTTP configuration:
 | `describe_relationships` | Read  | Describe foreign keys involving one table                        |
 | `describe_dependencies`  | Read  | List objects that depend on an object                            |
 | `analyze_table`          | Read  | Return row counts, storage, and index details                    |
-| `read_data`              | Read  | Execute a validated SELECT query                                 |
+| `read_data`              | Read  | Execute a validated SELECT (or CTE) query in a rolled-back transaction |
 | `search_data`            | Read  | Search columns with parameterized LIKE predicates                |
 | `explain_query`          | Read  | Generate an estimated SELECT execution plan                      |
 | `preview_update`         | Read  | Preview an update and issue a token when required                |
@@ -270,9 +306,20 @@ Clients with MCP resource support can discover:
 - `mssql://database/{databaseName}/object/{schemaName}/{objectName}/dependencies`
 - `mssql://query-plan/{planId}`
 - `mssql://query-result/{resultId}`
+- `ui://mssql/query-results.html` (MCP Apps view)
 
 Table and object listings are cached for 30 seconds. Query plan and large query result resources are temporary process-local artifacts.
 
+### Query results grid (MCP Apps)
+
+`read_data` and `search_data` declare an [MCP Apps](https://modelcontextprotocol.io/extensions/apps) view. Hosts that support MCP Apps (Claude, VS Code, Cursor 2.6+, and others) render results as a sortable, filterable grid inline in the conversation. Other clients ignore the view and use the normal text and structured result.
+
+### read_data rules
+
+`read_data` accepts one `SELECT` statement, optionally preceded by common table expressions (`WITH ...`). String literals, comments, and bracketed or quoted identifiers are ignored when checking for disallowed keywords, so `[Update]` columns or `'Update pending'` values are fine. Statements that modify data, execute code (`EXEC`, `sp_`/`xp_` procedures), declare variables, or read server identity (`@@` variables, `SUSER_SNAME()`) are rejected.
+
+Every query also runs inside a transaction that is always rolled back, and results stream until `MAX_ROWS` rows have been read, at which point the query is cancelled and the result is marked `truncated`. SQL Server error messages (for example `Invalid column name`) are returned so the model can correct the query. Cancelling a tool call in the client cancels the running SQL request.
+
 Available prompts:
 
 - `explore_schema`
@@ -296,7 +343,7 @@ The repository includes a seeded SQL Server 2022 Docker environment:
 ```bash
 cp .env.example .env
 npm run db:up
-npm run test:e2e
+npm run test:e2e   # every tool over HTTP, then protocol checks (2026-07-28 + 2025 stdio)
 ```
 
 See [`docs/dev-database.md`](docs/dev-database.md) for database and E2E details and [`CONTRIBUTING.md`](CONTRIBUTING.md) for build, lint, and test commands.
@@ -308,6 +355,8 @@ See [`docs/dev-database.md`](docs/dev-database.md) for database and E2E details
 - `DDL_DISABLED`: set `ENABLE_DDL` to `"true"` only when DDL access is intended.
 - `PREVIEW_TOKEN_INVALID`: create a new matching preview and use its token once within 10 minutes.
 - stdio JSON parse errors: ensure scripts and dependencies write logs to stderr, not stdout.
+- HTTP `403 Forbidden`: the request's `Host` or `Origin` is not in `MCP_HTTP_ALLOWED_HOSTS`; add the public hostname (or set `MCP_BASE_URL`).
+- HTTP `401 Unauthorized`: send `Authorization: Bearer <MCP_HTTP_AUTH_TOKEN>`.
 - database rejected: add it to `DATABASES` and use the exact allowed name in `databaseName`.
 
 ## Security
@@ -316,7 +365,8 @@ See [`docs/dev-database.md`](docs/dev-database.md) for database and E2E details
 - Set `READONLY=true` whenever writes are unnecessary.
 - Keep `ENABLE_DDL=false` unless schema changes are explicitly needed.
 - Keep credentials out of source control and use your client's secret-input support or a secrets manager.
-- Bind HTTP mode to a trusted interface and add network authentication or isolation outside this package.
+- Keep HTTP mode on loopback, or set `MCP_HTTP_AUTH_TOKEN` and `MCP_HTTP_ALLOWED_HOSTS` when exposing it. Prefer TLS termination at a reverse proxy.
+- `read_data` validation and its rolled-back transaction are defense in depth; a least-privilege login is still the primary control.
 - Set `ENCRYPT=true` for TLS deployments and keep `TRUST_SERVER_CERTIFICATE=false` when the server certificate is publicly or privately trusted.
 - Report vulnerabilities through the [security policy](.github/SECURITY.md).
 

package/dist/apps/queryResultsApp.d.ts

@@ -0,0 +1,18 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+/**
+ * MCP Apps (io.modelcontextprotocol/ui) view that renders read_data and
+ * search_data results as an interactive grid in hosts that support it
+ * (Claude, VS Code, Cursor, …). Hosts without MCP Apps ignore the tool
+ * metadata and keep using the text/structured result.
+ */
+export declare const QUERY_RESULTS_APP_URI = "ui://mssql/query-results.html";
+export declare function buildQueryResultsHtml(): string;
+export declare function registerQueryResultsApp(server: McpServer): void;
+/** Tool `_meta` linking a tool to the query-results view (both key styles). */
+export declare const queryResultsToolMeta: {
+    ui: {
+        resourceUri: string;
+    };
+    "ui/resourceUri": string;
+};
+//# sourceMappingURL=queryResultsApp.d.ts.map

package/dist/apps/queryResultsApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryResultsApp.d.ts","sourceRoot":"","sources":["../../src/apps/queryResultsApp.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,kCAAkC,CAAC;AAqOrE,wBAAgB,qBAAqB,IAAI,MAAM,CAmB9C;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAuB/D;AAED,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB;;;;;CAGhC,CAAC"}

package/dist/apps/queryResultsApp.js

@@ -0,0 +1,272 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { RESOURCE_MIME_TYPE, registerAppResource, } from "@modelcontextprotocol/ext-apps/server";
+/**
+ * MCP Apps (io.modelcontextprotocol/ui) view that renders read_data and
+ * search_data results as an interactive grid in hosts that support it
+ * (Claude, VS Code, Cursor, …). Hosts without MCP Apps ignore the tool
+ * metadata and keep using the text/structured result.
+ */
+export const QUERY_RESULTS_APP_URI = "ui://mssql/query-results.html";
+const require = createRequire(import.meta.url);
+/**
+ * Loads the self-contained ext-apps View runtime and rewrites its trailing
+ * `export{…}` into a local binding so it can be inlined into a single
+ * module script (hosts render the view from one HTML document).
+ */
+function loadAppRuntime() {
+    const bundle = readFileSync(require.resolve("@modelcontextprotocol/ext-apps/app-with-deps"), "utf8");
+    const exportStart = bundle.lastIndexOf("export{");
+    if (exportStart === -1) {
+        throw new Error("Unexpected ext-apps bundle format: missing export list.");
+    }
+    const exportEnd = bundle.indexOf("}", exportStart);
+    const entries = bundle
+        .slice(exportStart + "export{".length, exportEnd)
+        .split(",")
+        .map((entry) => {
+        const [local, exported = local] = entry.trim().split(/\s+as\s+/);
+        return `${JSON.stringify(exported)}:${local}`;
+    });
+    return `${bundle.slice(0, exportStart)}const ExtApps={${entries.join(",")}};${bundle.slice(exportEnd + 1)}`;
+}
+const VIEW_STYLES = `
+:root { color-scheme: light dark; }
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  font-family: var(--font-sans, system-ui, sans-serif);
+  font-size: var(--font-text-sm-size, 13px);
+  color: var(--color-text-primary, CanvasText);
+  background: var(--color-background-primary, Canvas);
+}
+header {
+  display: flex; gap: 8px; align-items: center; flex-wrap: wrap;
+  padding: 8px 10px;
+  border-bottom: 1px solid var(--color-border-primary, #8884);
+}
+header .summary { flex: 1; color: var(--color-text-secondary, GrayText); }
+.badge {
+  padding: 1px 6px; border-radius: 999px; font-size: 11px;
+  background: var(--color-background-warning, #f5a62333);
+  color: var(--color-text-warning, inherit);
+}
+input[type="search"] {
+  font: inherit; padding: 3px 8px; min-width: 160px;
+  color: inherit; background: transparent;
+  border: 1px solid var(--color-border-primary, #8886);
+  border-radius: var(--border-radius-sm, 4px);
+}
+.grid { overflow: auto; max-height: 480px; }
+table { border-collapse: collapse; width: 100%; font-variant-numeric: tabular-nums; }
+th, td {
+  padding: 4px 10px; text-align: left; white-space: nowrap;
+  border-bottom: 1px solid var(--color-border-secondary, #8882);
+  max-width: 360px; overflow: hidden; text-overflow: ellipsis;
+}
+th {
+  position: sticky; top: 0; cursor: pointer; user-select: none;
+  background: var(--color-background-secondary, Canvas);
+  font-weight: 600;
+}
+th[aria-sort="ascending"]::after { content: " ▲"; }
+th[aria-sort="descending"]::after { content: " ▼"; }
+td.null { color: var(--color-text-tertiary, GrayText); font-style: italic; }
+td.num { text-align: right; }
+.empty, .error { padding: 16px 10px; color: var(--color-text-secondary, GrayText); }
+.error { color: var(--color-text-danger, #d33); }
+`;
+const VIEW_SCRIPT = `
+const { App, applyDocumentTheme, applyHostStyleVariables, applyHostFonts } = ExtApps;
+const MAX_RENDERED_ROWS = 1000;
+const root = document.getElementById("root");
+let rows = [];
+let columns = [];
+let meta = {};
+let sort = { column: null, direction: 1 };
+let filter = "";
+
+function extractRows(payload) {
+  const data = payload && payload.data;
+  if (Array.isArray(data)) return data;
+  if (data && Array.isArray(data.rows)) return data.rows;
+  if (data && Array.isArray(data.data)) return data.data;
+  return [];
+}
+
+function formatCell(value) {
+  if (value === null || value === undefined) return { text: "NULL", cls: "null" };
+  if (typeof value === "number" || typeof value === "bigint") return { text: String(value), cls: "num" };
+  if (typeof value === "object") return { text: JSON.stringify(value), cls: "" };
+  return { text: String(value), cls: "" };
+}
+
+function el(tag, attrs, children) {
+  const node = document.createElement(tag);
+  for (const [key, value] of Object.entries(attrs || {})) {
+    if (key === "text") node.textContent = value;
+    else if (key.startsWith("on")) node.addEventListener(key.slice(2), value);
+    else node.setAttribute(key, value);
+  }
+  for (const child of children || []) node.append(child);
+  return node;
+}
+
+function visibleRows() {
+  let result = rows;
+  if (filter) {
+    const needle = filter.toLowerCase();
+    result = result.filter((row) =>
+      columns.some((column) => String(row[column] ?? "").toLowerCase().includes(needle))
+    );
+  }
+  if (sort.column !== null) {
+    const column = sort.column;
+    result = [...result].sort((a, b) => {
+      const left = a[column];
+      const right = b[column];
+      if (left === right) return 0;
+      if (left === null || left === undefined) return 1;
+      if (right === null || right === undefined) return -1;
+      return (left < right ? -1 : 1) * sort.direction;
+    });
+  }
+  return result;
+}
+
+function render() {
+  root.replaceChildren();
+  if (meta.error) {
+    root.append(el("div", { class: "error", text: meta.error }));
+    return;
+  }
+
+  const shown = visibleRows();
+  const rendered = shown.slice(0, MAX_RENDERED_ROWS);
+  const summaryParts = [rows.length + " row" + (rows.length === 1 ? "" : "s")];
+  if (filter) summaryParts.push(shown.length + " matching");
+  if (rendered.length < shown.length) summaryParts.push("showing first " + rendered.length);
+
+  const header = el("header", {}, [
+    el("span", { class: "summary", text: summaryParts.join(" · ") }),
+  ]);
+  if (meta.truncated) {
+    header.append(el("span", { class: "badge", text: "Truncated at MAX_ROWS", title: "More rows exist on the server" }));
+  }
+  header.append(
+    el("input", {
+      type: "search",
+      placeholder: "Filter rows",
+      value: filter,
+      "aria-label": "Filter rows",
+      oninput: (event) => {
+        filter = event.target.value;
+        render();
+        const input = root.querySelector("input[type=search]");
+        input.focus();
+        input.setSelectionRange(filter.length, filter.length);
+      },
+    })
+  );
+  root.append(header);
+
+  if (rows.length === 0) {
+    root.append(el("div", { class: "empty", text: meta.message || "No rows returned." }));
+    return;
+  }
+
+  const headRow = el("tr", {}, columns.map((column) => {
+    const ariaSort = sort.column === column ? (sort.direction === 1 ? "ascending" : "descending") : "none";
+    return el("th", {
+      text: column,
+      scope: "col",
+      "aria-sort": ariaSort,
+      onclick: () => {
+        sort = sort.column === column ? { column, direction: -sort.direction } : { column, direction: 1 };
+        render();
+      },
+    });
+  }));
+  const body = el("tbody", {}, rendered.map((row) =>
+    el("tr", {}, columns.map((column) => {
+      const cell = formatCell(row[column]);
+      return el("td", { class: cell.cls, text: cell.text, title: cell.text });
+    }))
+  ));
+  root.append(el("div", { class: "grid" }, [el("table", {}, [el("thead", {}, [headRow]), body])]));
+}
+
+function showResult(result) {
+  const payload = result && result.structuredContent;
+  if (!payload) {
+    meta = { error: "This result has no structured content to display." };
+  } else if (payload.success === false) {
+    meta = { error: payload.message || "The query failed." };
+  } else {
+    rows = extractRows(payload);
+    columns = rows.length > 0 ? Object.keys(rows[0]) : [];
+    meta = { truncated: payload.truncated === true, message: payload.message };
+  }
+  sort = { column: null, direction: 1 };
+  filter = "";
+  render();
+}
+
+function applyHostContext(context) {
+  if (!context) return;
+  if (context.theme) applyDocumentTheme(context.theme);
+  if (context.styles && context.styles.variables) applyHostStyleVariables(context.styles.variables);
+  if (context.styles && context.styles.css && context.styles.css.fonts) applyHostFonts(context.styles.css.fonts);
+}
+
+const app = new App({ name: "mssql-query-results", version: "1.0.0" }, {}, { autoResize: true });
+app.ontoolresult = showResult;
+app.onhostcontextchanged = applyHostContext;
+root.append(el("div", { class: "empty", text: "Waiting for query results…" }));
+await app.connect();
+applyHostContext(app.getHostContext());
+`;
+let cachedHtml;
+export function buildQueryResultsHtml() {
+    cachedHtml ??= `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Query results</title>
+<style>${VIEW_STYLES}</style>
+</head>
+<body>
+<div id="root"></div>
+<script type="module">
+${loadAppRuntime()}
+${VIEW_SCRIPT}
+</script>
+</body>
+</html>
+`;
+    return cachedHtml;
+}
+export function registerQueryResultsApp(server) {
+    registerAppResource(server, "query_results_app", QUERY_RESULTS_APP_URI, {
+        title: "Query Results Grid",
+        description: "Interactive, sortable and filterable grid for read_data and search_data results.",
+        mimeType: RESOURCE_MIME_TYPE,
+        _meta: { ui: { prefersBorder: true } },
+    }, async () => ({
+        contents: [
+            {
+                uri: QUERY_RESULTS_APP_URI,
+                mimeType: RESOURCE_MIME_TYPE,
+                text: buildQueryResultsHtml(),
+                _meta: { ui: { prefersBorder: true } },
+            },
+        ],
+    }));
+}
+/** Tool `_meta` linking a tool to the query-results view (both key styles). */
+export const queryResultsToolMeta = {
+    ui: { resourceUri: QUERY_RESULTS_APP_URI },
+    "ui/resourceUri": QUERY_RESULTS_APP_URI,
+};
+//# sourceMappingURL=queryResultsApp.js.map

package/dist/apps/queryResultsApp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryResultsApp.js","sourceRoot":"","sources":["../../src/apps/queryResultsApp.ts"],"names":[],"mappings":"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"}

package/dist/checkNodeVersion.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=checkNodeVersion.d.ts.map

package/dist/checkNodeVersion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkNodeVersion.d.ts","sourceRoot":"","sources":["../src/checkNodeVersion.ts"],"names":[],"mappings":""}

package/dist/checkNodeVersion.js

@@ -0,0 +1,9 @@
+// Imported first by index.ts so it runs before any dependency is evaluated.
+// Logs to stderr only: stdout belongs to the stdio JSON-RPC stream.
+import { nodeVersionError } from "./nodeVersion.js";
+const versionError = nodeVersionError();
+if (versionError) {
+    console.error(versionError);
+    process.exit(1);
+}
+//# sourceMappingURL=checkNodeVersion.js.map

package/dist/checkNodeVersion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkNodeVersion.js","sourceRoot":"","sources":["../src/checkNodeVersion.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,oEAAoE;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,YAAY,GAAG,gBAAgB,EAAE,CAAC;AACxC,IAAI,YAAY,EAAE,CAAC;IACjB,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAC5B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/config.d.ts

@@ -1,10 +1,32 @@
 type Environment = NodeJS.ProcessEnv;
 export type McpTransportMode = "stdio" | "http";
+export declare const SQL_AUTH_TYPES: readonly ["sql", "ntlm", "azure-default", "azure-service-principal", "azure-access-token"];
+export type SqlAuthType = (typeof SQL_AUTH_TYPES)[number];
+export type SqlAuthConfig = {
+    type: "sql";
+    user: string;
+    password: string;
+} | {
+    type: "ntlm";
+    user: string;
+    password: string;
+    domain: string;
+} | {
+    type: "azure-default";
+    clientId?: string;
+} | {
+    type: "azure-service-principal";
+    clientId: string;
+    clientSecret: string;
+    tenantId: string;
+} | {
+    type: "azure-access-token";
+    token: string;
+};
 export interface SqlConnectionConfig {
     serverName: string;
     serverPort?: number;
-    dbUser: string;
-    dbPassword: string;
+    auth: SqlAuthConfig;
     encrypt: boolean;
     trustServerCertificate: boolean;
     connectionTimeoutSeconds: number;
@@ -22,15 +44,21 @@ export interface EnvironmentConfig extends SqlConnectionConfig {
     mcpHttpHost: string;
     mcpHttpPort: number;
     mcpBaseUrl?: string;
+    mcpHttpAuthToken?: string;
+    mcpHttpAllowUnauthenticated: boolean;
+    mcpHttpAllowedHosts: string[];
 }
 export declare function configureRuntimeEnvironment(environment: EnvironmentConfig): void;
 export declare function parseDatabaseList(value: string | undefined): string[];
+export declare function parseSqlAuthConfig(env?: Environment): SqlAuthConfig;
 export declare function parseSqlConnectionConfig(env?: Environment): SqlConnectionConfig;
 export declare function parseEnvironmentConfig(env?: Environment): EnvironmentConfig;
 export declare function getMaxRows(): number;
 export declare function getDefaultSearchLimit(): number;
 export declare function clampRowLimit(limit: unknown, fallback?: number): number;
 export declare function getMcpEndpointUrl(environment: Pick<EnvironmentConfig, "mcpBaseUrl" | "mcpHttpHost" | "mcpHttpPort">): string;
+/** Brackets IPv6 literals (`::1` -> `[::1]`) for use in a URL authority. */
+export declare function formatUrlHost(host: string): string;
 export declare function getMaxWriteRows(): number;
 export {};
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAQA,KAAK,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC;AAErC,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEhD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,sBAAsB,EAAE,OAAO,CAAC;IAChC,wBAAwB,EAAE,MAAM,CAAC;IACjC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAkB,SAAQ,mBAAmB;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,YAAY,EAAE,gBAAgB,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,iBAAiB,GAC7B,IAAI,CAKN;AAmHD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CASrE;AAED,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,WAAyB,GAC7B,mBAAmB,CAuBrB;AAED,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,WAAyB,GAC7B,iBAAiB,CAgDnB;AAeD,wBAAgB,UAAU,IAAI,MAAM,CAKnC;AAED,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAe,GAAG,MAAM,CAa7E;AAED,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,IAAI,CACf,iBAAiB,EACjB,YAAY,GAAG,aAAa,GAAG,aAAa,CAC7C,GACA,MAAM,CAKR;AAED,wBAAgB,eAAe,IAAI,MAAM,CASxC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAQA,KAAK,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC;AAErC,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEhD,eAAO,MAAM,cAAc,4FAMjB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C;IACE,IAAI,EAAE,yBAAyB,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB,GACD;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,sBAAsB,EAAE,OAAO,CAAC;IAChC,wBAAwB,EAAE,MAAM,CAAC;IACjC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAkB,SAAQ,mBAAmB;IAC5D,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,YAAY,EAAE,gBAAgB,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2BAA2B,EAAE,OAAO,CAAC;IACrC,mBAAmB,EAAE,MAAM,EAAE,CAAC;CAC/B;AAID,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,iBAAiB,GAC7B,IAAI,CAKN;AAmHD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CASrE;AAeD,wBAAgB,kBAAkB,CAChC,GAAG,GAAE,WAAyB,GAC7B,aAAa,CAoCf;AAED,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,WAAyB,GAC7B,mBAAmB,CA0BrB;AAED,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,WAAyB,GAC7B,iBAAiB,CAyDnB;AAeD,wBAAgB,UAAU,IAAI,MAAM,CAKnC;AAED,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,SAAe,GAAG,MAAM,CAa7E;AAED,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,IAAI,CACf,iBAAiB,EACjB,YAAY,GAAG,aAAa,GAAG,aAAa,CAC7C,GACA,MAAM,CAKR;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAgB,eAAe,IAAI,MAAM,CASxC"}