@adriancy/mcp-mssql 1.0.0 → 1.0.1

package/.env.example

@@ -1,21 +1,51 @@
 # Required
 MSSQL_SERVER=localhost
-MSSQL_USER=sa
-MSSQL_PASSWORD=
-MSSQL_DATABASE=master
+MSSQL_USER=your_user
+MSSQL_PASSWORD=your_password
+MSSQL_DATABASE=your_database
 
-# Optional (default 1433)
+# Optional (default 1433). Omit or ignore when using MSSQL_INSTANCE_NAME (named instance).
 # MSSQL_PORT=1433
 
-# TLS (defaults: encrypt true, trust cert false)
+# TLS (defaults: encrypt true, trust cert false). MSSQL_ENCRYPT may be true, false, or strict (TDS 8.0).
 # MSSQL_ENCRYPT=true
 # MSSQL_TRUST_SERVER_CERTIFICATE=false
+# MSSQL_TLS_SERVER_NAME=
+# Paths on the MCP host; PEM contents read at startup (fail fast if missing).
+# MSSQL_TLS_CA_FILE=
+# MSSQL_TLS_CERT_FILE=
+# MSSQL_TLS_KEY_FILE=
+# MSSQL_TLS_KEY_PASSPHRASE=
+
+# Connectivity / resilience
+# MSSQL_CONNECTION_TIMEOUT_MS=
+# MSSQL_DOMAIN=
+# MSSQL_INSTANCE_NAME=
+# MSSQL_MULTI_SUBNET_FAILOVER=false
+# MSSQL_READ_ONLY_INTENT=false
+# MSSQL_MAX_RETRIES_ON_TRANSIENT_ERRORS=
+# MSSQL_CONNECTION_RETRY_INTERVAL_MS=
+
+# Pool (defaults: max 10, min 0, idle 30000 ms)
+# MSSQL_POOL_MAX=10
+# MSSQL_POOL_MIN=0
+# MSSQL_POOL_IDLE_TIMEOUT_MS=30000
+
+# Session / protocol
+# MSSQL_APP_NAME=
+# MSSQL_USE_UTC=true
+# MSSQL_TDS_VERSION=
+
+# Authentication (unset = SQL login via MSSQL_USER / MSSQL_PASSWORD).
+# ntlm | azure-active-directory-password | azure-active-directory-access-token | azure-active-directory-service-principal-secret
+# MSSQL_AUTH_TYPE=
+# MSSQL_AZURE_CLIENT_ID=
+# MSSQL_AZURE_TENANT_ID=
+# MSSQL_AZURE_CLIENT_SECRET=
+# MSSQL_AZURE_ACCESS_TOKEN=
 
 # Safety: when false/ unset, blocks common write/DDL/exec patterns (heuristic only)
 # MSSQL_ALLOW_WRITES=false
 
-# Cap rows returned (SET ROWCOUNT); unset = no cap
-# MSSQL_MAX_ROWS=5000
-
 # Request timeout in ms (driver)
 # MSSQL_QUERY_TIMEOUT_MS=30000

package/README.md

@@ -1,49 +1,20 @@
-# mssql-mcp
+# `@adriancy/mcp-mssql`
 
-MCP server (stdio) that connects to Microsoft SQL Server using the `mssql` driver. Tool arguments are defined and validated with [Valibot](https://valibot.dev); JSON Schema for clients is generated with `@valibot/to-json-schema`.
+MCP server (stdio) for Microsoft SQL Server. Exposes tools so Cursor (or any MCP client) can list tables, describe columns, and run read-biased T-SQL.
 
-**Implementation note:** This project uses the low-level `@modelcontextprotocol/sdk` `Server` class rather than `McpServer`, because the current SDK’s `McpServer.registerTool` path is built around Zod for schema export and validation. Tools are registered with `ListTools` / `tools/call` handlers and Valibot parsing inside the handlers.
+## Use it in Cursor
 
-## Tools
-
-- **`mssql_query`** — Run a T-SQL batch; returns `recordsets` and `rowsAffected`. Honors `MSSQL_MAX_ROWS` via `SET ROWCOUNT` when set.
-- **`mssql_list_tables`** — Base tables from `INFORMATION_SCHEMA.TABLES`, optional schema filter.
-- **`mssql_describe_table`** — Column metadata from `INFORMATION_SCHEMA.COLUMNS`.
-
-## Environment variables
-
-See [`.env.example`](.env.example). Required: `MSSQL_SERVER`, `MSSQL_USER`, `MSSQL_PASSWORD`, `MSSQL_DATABASE`.
-
-- **`MSSQL_ALLOW_WRITES`** — Default off. When off, a heuristic blocks common write/DDL/exec keywords (not a substitute for DB permissions).
-- **`MSSQL_MAX_ROWS`** — When set, wraps batches in `SET ROWCOUNT` for `mssql_query`.
-- **`MSSQL_ENCRYPT`** / **`MSSQL_TRUST_SERVER_CERTIFICATE`** — Passed through to the driver (`encrypt` defaults to true).
-
-## Build and run
-
-```bash
-pnpm install
-pnpm run build
-pnpm start
-```
-
-Development (no separate build):
-
-```bash
-pnpm dev
-```
-
-Do not write logs to **stdout** when running under MCP; the protocol uses stdout. Errors on startup go to stderr via `console.error`.
+1. Open **Cursor Settings → MCP** (or edit your MCP JSON).
+2. Add a server block. Set `env` to your database (see [`.env.example`](.env.example)).
 
-## Cursor MCP configuration
-
-**Published package (`npx`):** from `@adriancy/mssql-mcp` **1.0.1+** you can run the CLI without a local path:
+**From npm** (after the package is published):
 
 ```json
 {
   "mcpServers": {
     "mssql": {
       "command": "npx",
-      "args": ["-y", "@adriancy/mssql-mcp"],
+      "args": ["-y", "@adriancy/mcp-mssql"],
       "env": {
         "MSSQL_SERVER": "localhost",
         "MSSQL_USER": "your_user",
@@ -56,14 +27,14 @@ Do not write logs to **stdout** when running under MCP; the protocol uses stdout
 }
 ```
 
-**Local checkout:** use the absolute path to `dist/index.js`:
+**From a local clone** (run `pnpm install && pnpm build` first):
 
 ```json
 {
   "mcpServers": {
     "mssql": {
       "command": "node",
-      "args": ["/home/adrian/code/mcp/mssql-mcp/dist/index.js"],
+      "args": ["/absolute/path/to/mssql-mcp/dist/index.js"],
       "env": {
         "MSSQL_SERVER": "localhost",
         "MSSQL_USER": "your_user",
@@ -76,23 +47,74 @@ Do not write logs to **stdout** when running under MCP; the protocol uses stdout
 }
 ```
 
-Use **`node`** for local paths. Do **not** use **`pnpm`** as `command` for MCP: if pnpm prints errors to stdout, Cursor can show JSON parse errors because the protocol uses stdout. **`npx`** is fine for the published package: it execs the `mssql-mcp` bin (Node) after install.
+Use **`node`** for local files. Avoid **`pnpm`** as the MCP `command` — extra output on stdout can break the protocol.
+
+Confirm the install name matches npm: `npm view @adriancy/mcp-mssql version`.
+
+## Environment
+
+All variables are read from the MCP process environment (e.g. Cursor `env`). Booleans treat `1`, `true`, `yes`, `on` (case-insensitive) as true and `0`, `false`, `no`, `off` as false. Invalid boolean and integer values fail startup validation.
+
+| Variable | Required | Default | Meaning |
+|----------|----------|---------|---------|
+| `MSSQL_SERVER` | yes | — | Hostname or IP of SQL Server |
+| `MSSQL_USER` | yes† | — | Login user (SQL auth, NTLM, Azure AD password); not used for `azure-active-directory-access-token` or service-principal-only flows |
+| `MSSQL_PASSWORD` | yes*† | — | Login password (*may be empty for some setups) |
+| `MSSQL_DATABASE` | yes | — | Initial database |
+| `MSSQL_PORT` | no | `1433` | TCP port; omit when using `MSSQL_INSTANCE_NAME` (driver uses instance + SQL Browser) |
+| `MSSQL_ENCRYPT` | no | `true` | TLS `encrypt`: `true`, `false`, or `strict` (TDS 8.0 / tedious) |
+| `MSSQL_TRUST_SERVER_CERTIFICATE` | no | `false` | Trust self-signed / skip cert validation (dev only) |
+| `MSSQL_TLS_SERVER_NAME` | no | — | Hostname for TLS validation when it differs from `MSSQL_SERVER` (e.g. connect by IP) |
+| `MSSQL_TLS_CA_FILE` | no | — | Path to CA PEM; passed via `cryptoCredentialsDetails.ca` |
+| `MSSQL_TLS_CERT_FILE` | no | — | Optional client cert PEM (mutual TLS) |
+| `MSSQL_TLS_KEY_FILE` | no | — | Optional client private key PEM |
+| `MSSQL_TLS_KEY_PASSPHRASE` | no | — | Passphrase for encrypted client key |
+| `MSSQL_CONNECTION_TIMEOUT_MS` | no | *(driver default)* | Pool `connectionTimeout` (ms). `0` → unset |
+| `MSSQL_DOMAIN` | no | — | Domain login (`config.domain` for SQL auth; required for `MSSQL_AUTH_TYPE=ntlm`) |
+| `MSSQL_INSTANCE_NAME` | no | — | Named instance (`options.instanceName`); do not rely on `MSSQL_PORT` with this set |
+| `MSSQL_MULTI_SUBNET_FAILOVER` | no | `false` | Availability-group style failover hint |
+| `MSSQL_READ_ONLY_INTENT` | no | `false` | Read-only routing for AG secondaries |
+| `MSSQL_MAX_RETRIES_ON_TRANSIENT_ERRORS` | no | — | Tedious `maxRetriesOnTransientErrors`; `0` → unset |
+| `MSSQL_CONNECTION_RETRY_INTERVAL_MS` | no | — | Tedious `connectionRetryInterval`; `0` → unset |
+| `MSSQL_POOL_MAX` | no | `10` | Pool max connections |
+| `MSSQL_POOL_MIN` | no | `0` | Pool min connections |
+| `MSSQL_POOL_IDLE_TIMEOUT_MS` | no | `30000` | `pool.idleTimeoutMillis` |
+| `MSSQL_APP_NAME` | no | — | `options.appName` (server tracing) |
+| `MSSQL_USE_UTC` | no | `true` | `options.useUTC` when set |
+| `MSSQL_TDS_VERSION` | no | — | `7_1`, `7_2`, `7_3_A`, `7_3_B`, or `7_4` |
+| `MSSQL_AUTH_TYPE` | no | — | `ntlm`, `azure-active-directory-password`, `azure-active-directory-access-token`, `azure-active-directory-service-principal-secret`, or unset/`default` for SQL login |
+| `MSSQL_AZURE_CLIENT_ID` | no‡ | — | Azure AD app (client) ID where required |
+| `MSSQL_AZURE_TENANT_ID` | no‡ | — | Tenant ID (optional for password auth, defaults `common`; required for service principal) |
+| `MSSQL_AZURE_CLIENT_SECRET` | no‡ | — | Service principal secret |
+| `MSSQL_AZURE_ACCESS_TOKEN` | no‡ | — | Pre-obtained token for access-token auth |
+| `MSSQL_ALLOW_WRITES` | no | `false` | If false/unset, blocks common write/DDL/exec patterns in `mssql_query` (heuristic only) |
+| `MSSQL_QUERY_TIMEOUT_MS` | no | *(driver default)* | Request timeout in ms for the driver. `0` → unset |
+
+† Required for SQL authentication and for auth types that use interactive user login.  
+‡ Required depending on `MSSQL_AUTH_TYPE`; see [`.env.example`](.env.example). NTLM on Node 17+ may need `--openssl-legacy-provider` (see [tedious FAQ](https://tediousjs.github.io/tedious/frequently-encountered-problems.html)).
+
+See also [`.env.example`](.env.example).
 
-### Dev mode without a build (still use `node`)
+## Tools
 
-Set **`cwd`** to this repo so `node` can resolve `tsx` from `node_modules`:
+| Tool | Purpose |
+|------|--------|
+| `mssql_query` | Run T-SQL; returns rows and `rowsAffected` |
+| `mssql_list_tables` | Tables in `INFORMATION_SCHEMA` |
+| `mssql_describe_table` | Column metadata |
 
-```json
-{
-  "mcpServers": {
-    "mssql": {
-      "command": "node",
-      "args": ["--import", "tsx", "/home/adrian/code/mcp/src/index.ts"],
-      "cwd": "/home/adrian/code/mcp",
-      "env": { }
-    }
-  }
-}
+When `MSSQL_ALLOW_WRITES` is unset/false, obvious write/DDL patterns are blocked (heuristic only; use DB permissions for real safety).
+
+## Develop
+
+```bash
+pnpm install
+pnpm check
+pnpm test
+pnpm build && pnpm start
+pnpm dev
 ```
 
-Fill `env` the same as in the example above. Run `pnpm install` locally first so `tsx` exists.
+Use `pnpm format` to apply Biome formatting fixes and `pnpm lint` to run lint rules without formatting.
+
+Use a read-only or least-privilege SQL login for day-to-day use.

package/dist/config.d.ts

@@ -1,14 +1,35 @@
+import type * as tls from 'node:tls';
+export type AuthTypeNormalized = undefined | 'ntlm' | 'azure-active-directory-password' | 'azure-active-directory-access-token' | 'azure-active-directory-service-principal-secret';
 export type AppConfig = {
     server: string;
     port: number;
     user: string;
     password: string;
     database: string;
-    encrypt: boolean;
+    encrypt: boolean | 'strict';
     trustServerCertificate: boolean;
     allowWrites: boolean;
-    maxRows: number | undefined;
     queryTimeoutMs: number | undefined;
+    authType: AuthTypeNormalized;
+    domain: string | undefined;
+    tlsServerName: string | undefined;
+    cryptoCredentialsDetails: tls.SecureContextOptions | undefined;
+    connectionTimeoutMs: number | undefined;
+    instanceName: string | undefined;
+    multiSubnetFailover: boolean | undefined;
+    readOnlyIntent: boolean | undefined;
+    maxRetriesOnTransientErrors: number | undefined;
+    connectionRetryIntervalMs: number | undefined;
+    poolMax: number;
+    poolMin: number;
+    poolIdleTimeoutMs: number;
+    appName: string | undefined;
+    useUtc: boolean | undefined;
+    tdsVersion: string | undefined;
+    azureClientId: string | undefined;
+    azureTenantId: string | undefined;
+    azureClientSecret: string | undefined;
+    azureAccessToken: string | undefined;
 };
 export declare function loadConfig(): AppConfig;
 export declare function mssqlDriverConfig(cfg: AppConfig): import('mssql').config;

package/dist/config.js

@@ -1,29 +1,386 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import * as v from 'valibot';
+const TRUE_VALUES = new Set(['1', 'true', 'yes', 'on']);
+const FALSE_VALUES = new Set(['0', 'false', 'no', 'off']);
+const INTEGER_PATTERN = /^-?\d+$/;
+function isUnset(raw) {
+    return raw === undefined || raw.trim() === '';
+}
 function parseBool(raw, defaultValue) {
-    if (raw === undefined || raw === '')
+    const trimmed = raw?.trim();
+    if (trimmed === undefined || trimmed === '')
         return defaultValue;
-    return /^(1|true|yes|on)$/i.test(raw);
+    const normalized = trimmed.toLowerCase();
+    if (TRUE_VALUES.has(normalized))
+        return true;
+    if (FALSE_VALUES.has(normalized))
+        return false;
+    throw new Error(`Invalid boolean value "${raw}".`);
 }
-function parseIntEnv(raw, defaultValue) {
-    if (raw === undefined || raw === '')
-        return defaultValue;
-    const n = Number.parseInt(raw, 10);
-    return Number.isFinite(n) ? n : defaultValue;
+function parseIntEnv(raw) {
+    const trimmed = raw?.trim();
+    if (trimmed === undefined || trimmed === '')
+        return undefined;
+    if (!INTEGER_PATTERN.test(trimmed)) {
+        throw new Error(`Invalid integer value "${raw}".`);
+    }
+    return Number.parseInt(trimmed, 10);
+}
+function parseEncrypt(raw) {
+    const trimmed = raw?.trim();
+    if (trimmed === undefined || trimmed === '')
+        return true;
+    const t = trimmed.toLowerCase();
+    if (t === 'strict')
+        return 'strict';
+    return parseBool(raw, true);
+}
+function normalizeAuthType(raw) {
+    const trimmed = raw?.trim();
+    if (trimmed === undefined || trimmed === '')
+        return undefined;
+    const t = trimmed.toLowerCase();
+    if (t === '' || t === 'default')
+        return undefined;
+    return t;
+}
+const TDS_VERSIONS = new Set(['7_1', '7_2', '7_3_A', '7_3_B', '7_4']);
+const ALLOWED_AUTH = new Set([
+    'ntlm',
+    'azure-active-directory-password',
+    'azure-active-directory-access-token',
+    'azure-active-directory-service-principal-secret',
+]);
+function readPemFileOptional(label, filePath) {
+    const trimmed = filePath?.trim();
+    if (trimmed === undefined || trimmed === '')
+        return undefined;
+    const resolved = path.resolve(trimmed);
+    try {
+        return fs.readFileSync(resolved);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to read ${label} file at ${resolved}: ${msg}`);
+    }
 }
 const envSchema = v.object({
     MSSQL_SERVER: v.pipe(v.string(), v.nonEmpty()),
-    MSSQL_USER: v.pipe(v.string(), v.nonEmpty()),
-    MSSQL_PASSWORD: v.string(),
+    MSSQL_USER: v.optional(v.string()),
+    MSSQL_PASSWORD: v.optional(v.string()),
     MSSQL_DATABASE: v.pipe(v.string(), v.nonEmpty()),
     MSSQL_PORT: v.optional(v.string()),
     MSSQL_ENCRYPT: v.optional(v.string()),
     MSSQL_TRUST_SERVER_CERTIFICATE: v.optional(v.string()),
     MSSQL_ALLOW_WRITES: v.optional(v.string()),
-    MSSQL_MAX_ROWS: v.optional(v.string()),
     MSSQL_QUERY_TIMEOUT_MS: v.optional(v.string()),
+    MSSQL_TLS_SERVER_NAME: v.optional(v.string()),
+    MSSQL_TLS_CA_FILE: v.optional(v.string()),
+    MSSQL_TLS_CERT_FILE: v.optional(v.string()),
+    MSSQL_TLS_KEY_FILE: v.optional(v.string()),
+    MSSQL_TLS_KEY_PASSPHRASE: v.optional(v.string()),
+    MSSQL_CONNECTION_TIMEOUT_MS: v.optional(v.string()),
+    MSSQL_DOMAIN: v.optional(v.string()),
+    MSSQL_INSTANCE_NAME: v.optional(v.string()),
+    MSSQL_MULTI_SUBNET_FAILOVER: v.optional(v.string()),
+    MSSQL_READ_ONLY_INTENT: v.optional(v.string()),
+    MSSQL_MAX_RETRIES_ON_TRANSIENT_ERRORS: v.optional(v.string()),
+    MSSQL_CONNECTION_RETRY_INTERVAL_MS: v.optional(v.string()),
+    MSSQL_POOL_MAX: v.optional(v.string()),
+    MSSQL_POOL_MIN: v.optional(v.string()),
+    MSSQL_POOL_IDLE_TIMEOUT_MS: v.optional(v.string()),
+    MSSQL_APP_NAME: v.optional(v.string()),
+    MSSQL_USE_UTC: v.optional(v.string()),
+    MSSQL_TDS_VERSION: v.optional(v.string()),
+    MSSQL_AUTH_TYPE: v.optional(v.string()),
+    MSSQL_AZURE_CLIENT_ID: v.optional(v.string()),
+    MSSQL_AZURE_TENANT_ID: v.optional(v.string()),
+    MSSQL_AZURE_CLIENT_SECRET: v.optional(v.string()),
+    MSSQL_AZURE_ACCESS_TOKEN: v.optional(v.string()),
 });
-export function loadConfig() {
-    const e = v.parse(envSchema, {
+function inferAuthType(e) {
+    const t = normalizeAuthType(e.MSSQL_AUTH_TYPE);
+    if (t === undefined)
+        return undefined;
+    return t;
+}
+const BOOLEAN_ENV_KEYS = [
+    'MSSQL_TRUST_SERVER_CERTIFICATE',
+    'MSSQL_ALLOW_WRITES',
+    'MSSQL_MULTI_SUBNET_FAILOVER',
+    'MSSQL_READ_ONLY_INTENT',
+    'MSSQL_USE_UTC',
+];
+const INTEGER_ENV_RULES = [
+    { key: 'MSSQL_PORT', min: 1, max: 65_535 },
+    { key: 'MSSQL_QUERY_TIMEOUT_MS', min: 0 },
+    { key: 'MSSQL_CONNECTION_TIMEOUT_MS', min: 0 },
+    { key: 'MSSQL_MAX_RETRIES_ON_TRANSIENT_ERRORS', min: 0 },
+    { key: 'MSSQL_CONNECTION_RETRY_INTERVAL_MS', min: 0 },
+    { key: 'MSSQL_POOL_MAX', min: 1 },
+    { key: 'MSSQL_POOL_MIN', min: 0 },
+    { key: 'MSSQL_POOL_IDLE_TIMEOUT_MS', min: 0 },
+];
+function rawScalarChecks(e, addIssue) {
+    if (e.MSSQL_SERVER.trim() === '') {
+        addIssue({ message: 'MSSQL_SERVER is required and cannot be blank.' });
+    }
+    if (e.MSSQL_DATABASE.trim() === '') {
+        addIssue({ message: 'MSSQL_DATABASE is required and cannot be blank.' });
+    }
+    for (const key of BOOLEAN_ENV_KEYS) {
+        const raw = e[key];
+        if (isUnset(raw))
+            continue;
+        const normalized = raw.trim().toLowerCase();
+        if (!TRUE_VALUES.has(normalized) && !FALSE_VALUES.has(normalized)) {
+            addIssue({
+                message: `${key} must be one of: 1, true, yes, on, 0, false, no, off.`,
+            });
+        }
+    }
+    const encryptRaw = e.MSSQL_ENCRYPT;
+    if (!isUnset(encryptRaw)) {
+        const normalized = encryptRaw.trim().toLowerCase();
+        if (normalized !== 'strict' &&
+            !TRUE_VALUES.has(normalized) &&
+            !FALSE_VALUES.has(normalized)) {
+            addIssue({
+                message: 'MSSQL_ENCRYPT must be one of: 1, true, yes, on, 0, false, no, off, strict.',
+            });
+        }
+    }
+    for (const rule of INTEGER_ENV_RULES) {
+        const raw = e[rule.key];
+        if (typeof raw !== 'string' || isUnset(raw))
+            continue;
+        const trimmed = raw.trim();
+        if (!INTEGER_PATTERN.test(trimmed)) {
+            addIssue({ message: `${rule.key} must be an integer.` });
+            continue;
+        }
+        const value = Number.parseInt(trimmed, 10);
+        if (value < rule.min || (rule.max !== undefined && value > rule.max)) {
+            const range = rule.max === undefined
+                ? `greater than or equal to ${rule.min}`
+                : `between ${rule.min} and ${rule.max}`;
+            addIssue({ message: `${rule.key} must be ${range}.` });
+        }
+    }
+}
+function rawEnvChecks(e, addIssue) {
+    const rawAuth = normalizeAuthType(e.MSSQL_AUTH_TYPE);
+    if (rawAuth !== undefined && !ALLOWED_AUTH.has(rawAuth)) {
+        addIssue({
+            message: `Unsupported MSSQL_AUTH_TYPE "${e.MSSQL_AUTH_TYPE?.trim()}". Use default (unset), ntlm, azure-active-directory-password, azure-active-directory-access-token, or azure-active-directory-service-principal-secret.`,
+        });
+        return;
+    }
+    const authType = inferAuthType(e);
+    const user = (e.MSSQL_USER ?? '').trim();
+    if (authType === undefined) {
+        if (user === '') {
+            addIssue({
+                message: 'MSSQL_USER is required for SQL authentication (or set MSSQL_AUTH_TYPE).',
+            });
+        }
+        if (e.MSSQL_PASSWORD === undefined) {
+            addIssue({
+                message: 'MSSQL_PASSWORD is required for SQL authentication.',
+            });
+        }
+        return;
+    }
+    if (authType === 'ntlm') {
+        if (user === '')
+            addIssue({
+                message: 'MSSQL_USER is required when MSSQL_AUTH_TYPE=ntlm.',
+            });
+        if (e.MSSQL_PASSWORD === undefined) {
+            addIssue({
+                message: 'MSSQL_PASSWORD is required when MSSQL_AUTH_TYPE=ntlm.',
+            });
+        }
+        if (!e.MSSQL_DOMAIN?.trim())
+            addIssue({
+                message: 'MSSQL_DOMAIN is required when MSSQL_AUTH_TYPE=ntlm.',
+            });
+        return;
+    }
+    if (authType === 'azure-active-directory-password') {
+        if (user === '') {
+            addIssue({
+                message: 'MSSQL_USER is required when MSSQL_AUTH_TYPE=azure-active-directory-password.',
+            });
+        }
+        if (e.MSSQL_PASSWORD === undefined) {
+            addIssue({
+                message: 'MSSQL_PASSWORD is required when MSSQL_AUTH_TYPE=azure-active-directory-password.',
+            });
+        }
+        if (!e.MSSQL_AZURE_CLIENT_ID?.trim()) {
+            addIssue({
+                message: 'MSSQL_AZURE_CLIENT_ID is required when MSSQL_AUTH_TYPE=azure-active-directory-password.',
+            });
+        }
+        return;
+    }
+    if (authType === 'azure-active-directory-access-token') {
+        if (!e.MSSQL_AZURE_ACCESS_TOKEN?.trim()) {
+            addIssue({
+                message: 'MSSQL_AZURE_ACCESS_TOKEN is required when MSSQL_AUTH_TYPE=azure-active-directory-access-token.',
+            });
+        }
+        return;
+    }
+    if (authType === 'azure-active-directory-service-principal-secret') {
+        if (!e.MSSQL_AZURE_CLIENT_ID?.trim()) {
+            addIssue({
+                message: 'MSSQL_AZURE_CLIENT_ID is required when MSSQL_AUTH_TYPE=azure-active-directory-service-principal-secret.',
+            });
+        }
+        if (!e.MSSQL_AZURE_CLIENT_SECRET?.trim()) {
+            addIssue({
+                message: 'MSSQL_AZURE_CLIENT_SECRET is required when MSSQL_AUTH_TYPE=azure-active-directory-service-principal-secret.',
+            });
+        }
+        if (!e.MSSQL_AZURE_TENANT_ID?.trim()) {
+            addIssue({
+                message: 'MSSQL_AZURE_TENANT_ID is required when MSSQL_AUTH_TYPE=azure-active-directory-service-principal-secret.',
+            });
+        }
+    }
+}
+function rawPoolChecks(e, addIssue) {
+    const poolMaxRaw = e.MSSQL_POOL_MAX?.trim();
+    const poolMinRaw = e.MSSQL_POOL_MIN?.trim();
+    if ((poolMaxRaw !== undefined &&
+        poolMaxRaw !== '' &&
+        !INTEGER_PATTERN.test(poolMaxRaw)) ||
+        (poolMinRaw !== undefined &&
+            poolMinRaw !== '' &&
+            !INTEGER_PATTERN.test(poolMinRaw))) {
+        return;
+    }
+    const poolMax = parseIntEnv(e.MSSQL_POOL_MAX) ?? 10;
+    const poolMin = parseIntEnv(e.MSSQL_POOL_MIN) ?? 0;
+    if (poolMin > poolMax) {
+        addIssue({
+            message: `MSSQL_POOL_MIN (${poolMin}) cannot be greater than MSSQL_POOL_MAX (${poolMax}).`,
+        });
+    }
+}
+function rawTdsChecks(e, addIssue) {
+    const tdsRaw = e.MSSQL_TDS_VERSION?.trim();
+    if (tdsRaw === undefined || tdsRaw === '')
+        return;
+    if (!TDS_VERSIONS.has(tdsRaw)) {
+        addIssue({
+            message: `Invalid MSSQL_TDS_VERSION "${tdsRaw}". Use one of: ${[...TDS_VERSIONS].join(', ')}.`,
+        });
+    }
+}
+const appConfigSchema = v.pipe(envSchema, v.rawCheck(({ dataset, addIssue }) => {
+    rawScalarChecks(dataset.value, addIssue);
+}), v.rawCheck(({ dataset, addIssue }) => {
+    rawEnvChecks(dataset.value, addIssue);
+}), v.rawCheck(({ dataset, addIssue }) => {
+    rawPoolChecks(dataset.value, addIssue);
+}), v.rawCheck(({ dataset, addIssue }) => {
+    rawTdsChecks(dataset.value, addIssue);
+}), v.transform((e) => {
+    const authType = inferAuthType(e);
+    const port = parseIntEnv(e.MSSQL_PORT) ?? 1433;
+    const queryTimeoutValue = parseIntEnv(e.MSSQL_QUERY_TIMEOUT_MS);
+    const queryTimeoutMs = queryTimeoutValue === undefined || queryTimeoutValue === 0
+        ? undefined
+        : queryTimeoutValue;
+    const connectionTimeoutValue = parseIntEnv(e.MSSQL_CONNECTION_TIMEOUT_MS);
+    const connectionTimeoutMs = connectionTimeoutValue === undefined || connectionTimeoutValue === 0
+        ? undefined
+        : connectionTimeoutValue;
+    const ca = readPemFileOptional('MSSQL_TLS_CA_FILE', e.MSSQL_TLS_CA_FILE);
+    const cert = readPemFileOptional('MSSQL_TLS_CERT_FILE', e.MSSQL_TLS_CERT_FILE);
+    const key = readPemFileOptional('MSSQL_TLS_KEY_FILE', e.MSSQL_TLS_KEY_FILE);
+    const passphrase = e.MSSQL_TLS_KEY_PASSPHRASE?.trim() || undefined;
+    let cryptoCredentialsDetails;
+    if (ca !== undefined ||
+        cert !== undefined ||
+        key !== undefined ||
+        passphrase !== undefined) {
+        cryptoCredentialsDetails = {};
+        if (ca !== undefined)
+            cryptoCredentialsDetails.ca = ca;
+        if (cert !== undefined)
+            cryptoCredentialsDetails.cert = cert;
+        if (key !== undefined)
+            cryptoCredentialsDetails.key = key;
+        if (passphrase !== undefined)
+            cryptoCredentialsDetails.passphrase = passphrase;
+    }
+    const retriesValue = parseIntEnv(e.MSSQL_MAX_RETRIES_ON_TRANSIENT_ERRORS);
+    const maxRetriesOnTransientErrors = retriesValue === undefined || retriesValue === 0
+        ? undefined
+        : retriesValue;
+    const retryIntervalValue = parseIntEnv(e.MSSQL_CONNECTION_RETRY_INTERVAL_MS);
+    const connectionRetryIntervalMs = retryIntervalValue === undefined || retryIntervalValue === 0
+        ? undefined
+        : retryIntervalValue;
+    const tdsRaw = e.MSSQL_TDS_VERSION?.trim();
+    const tdsVersion = tdsRaw === '' || tdsRaw === undefined ? undefined : tdsRaw;
+    const instanceTrim = e.MSSQL_INSTANCE_NAME?.trim();
+    const instanceName = instanceTrim === '' ? undefined : instanceTrim;
+    const multiRaw = e.MSSQL_MULTI_SUBNET_FAILOVER;
+    const multiSubnetFailover = isUnset(multiRaw)
+        ? undefined
+        : parseBool(multiRaw, false);
+    const readOnlyRaw = e.MSSQL_READ_ONLY_INTENT;
+    const readOnlyIntent = isUnset(readOnlyRaw)
+        ? undefined
+        : parseBool(readOnlyRaw, false);
+    const useUtcRaw = e.MSSQL_USE_UTC;
+    const useUtc = isUnset(useUtcRaw) ? undefined : parseBool(useUtcRaw, true);
+    const poolMax = parseIntEnv(e.MSSQL_POOL_MAX) ?? 10;
+    const poolMin = parseIntEnv(e.MSSQL_POOL_MIN) ?? 0;
+    const poolIdleTimeoutMs = parseIntEnv(e.MSSQL_POOL_IDLE_TIMEOUT_MS) ?? 30_000;
+    const appTrim = e.MSSQL_APP_NAME?.trim();
+    const appName = appTrim === '' ? undefined : appTrim;
+    const tlsServerTrim = e.MSSQL_TLS_SERVER_NAME?.trim();
+    return {
+        server: e.MSSQL_SERVER.trim(),
+        port,
+        user: (e.MSSQL_USER ?? '').trim(),
+        password: e.MSSQL_PASSWORD ?? '',
+        database: e.MSSQL_DATABASE.trim(),
+        encrypt: parseEncrypt(e.MSSQL_ENCRYPT),
+        trustServerCertificate: parseBool(e.MSSQL_TRUST_SERVER_CERTIFICATE, false),
+        allowWrites: parseBool(e.MSSQL_ALLOW_WRITES, false),
+        queryTimeoutMs,
+        authType,
+        domain: e.MSSQL_DOMAIN?.trim() || undefined,
+        tlsServerName: tlsServerTrim === '' ? undefined : tlsServerTrim,
+        cryptoCredentialsDetails,
+        connectionTimeoutMs,
+        instanceName,
+        multiSubnetFailover,
+        readOnlyIntent,
+        maxRetriesOnTransientErrors,
+        connectionRetryIntervalMs,
+        poolMax,
+        poolMin,
+        poolIdleTimeoutMs,
+        appName,
+        useUtc,
+        tdsVersion,
+        azureClientId: e.MSSQL_AZURE_CLIENT_ID?.trim() || undefined,
+        azureTenantId: e.MSSQL_AZURE_TENANT_ID?.trim() || undefined,
+        azureClientSecret: e.MSSQL_AZURE_CLIENT_SECRET ?? undefined,
+        azureAccessToken: e.MSSQL_AZURE_ACCESS_TOKEN?.trim() || undefined,
+    };
+}));
+function readProcessEnv() {
+    return {
         MSSQL_SERVER: process.env.MSSQL_SERVER,
         MSSQL_USER: process.env.MSSQL_USER,
         MSSQL_PASSWORD: process.env.MSSQL_PASSWORD,
@@ -32,43 +389,128 @@ export function loadConfig() {
         MSSQL_ENCRYPT: process.env.MSSQL_ENCRYPT,
         MSSQL_TRUST_SERVER_CERTIFICATE: process.env.MSSQL_TRUST_SERVER_CERTIFICATE,
         MSSQL_ALLOW_WRITES: process.env.MSSQL_ALLOW_WRITES,
-        MSSQL_MAX_ROWS: process.env.MSSQL_MAX_ROWS,
         MSSQL_QUERY_TIMEOUT_MS: process.env.MSSQL_QUERY_TIMEOUT_MS,
-    });
-    const port = parseIntEnv(e.MSSQL_PORT, 1433);
-    const maxRowsRaw = e.MSSQL_MAX_ROWS;
-    const maxRows = maxRowsRaw === undefined || maxRowsRaw === ''
-        ? undefined
-        : Math.max(0, parseIntEnv(maxRowsRaw, 0));
-    const timeoutRaw = e.MSSQL_QUERY_TIMEOUT_MS;
-    const queryTimeoutMs = timeoutRaw === undefined || timeoutRaw === ''
-        ? undefined
-        : Math.max(0, parseIntEnv(timeoutRaw, 0));
-    return {
-        server: e.MSSQL_SERVER,
-        port,
-        user: e.MSSQL_USER,
-        password: e.MSSQL_PASSWORD,
-        database: e.MSSQL_DATABASE,
-        encrypt: parseBool(e.MSSQL_ENCRYPT, true),
-        trustServerCertificate: parseBool(e.MSSQL_TRUST_SERVER_CERTIFICATE, false),
-        allowWrites: parseBool(e.MSSQL_ALLOW_WRITES, false),
-        maxRows: maxRows === 0 ? undefined : maxRows,
-        queryTimeoutMs: queryTimeoutMs === 0 ? undefined : queryTimeoutMs,
+        MSSQL_TLS_SERVER_NAME: process.env.MSSQL_TLS_SERVER_NAME,
+        MSSQL_TLS_CA_FILE: process.env.MSSQL_TLS_CA_FILE,
+        MSSQL_TLS_CERT_FILE: process.env.MSSQL_TLS_CERT_FILE,
+        MSSQL_TLS_KEY_FILE: process.env.MSSQL_TLS_KEY_FILE,
+        MSSQL_TLS_KEY_PASSPHRASE: process.env.MSSQL_TLS_KEY_PASSPHRASE,
+        MSSQL_CONNECTION_TIMEOUT_MS: process.env.MSSQL_CONNECTION_TIMEOUT_MS,
+        MSSQL_DOMAIN: process.env.MSSQL_DOMAIN,
+        MSSQL_INSTANCE_NAME: process.env.MSSQL_INSTANCE_NAME,
+        MSSQL_MULTI_SUBNET_FAILOVER: process.env.MSSQL_MULTI_SUBNET_FAILOVER,
+        MSSQL_READ_ONLY_INTENT: process.env.MSSQL_READ_ONLY_INTENT,
+        MSSQL_MAX_RETRIES_ON_TRANSIENT_ERRORS: process.env.MSSQL_MAX_RETRIES_ON_TRANSIENT_ERRORS,
+        MSSQL_CONNECTION_RETRY_INTERVAL_MS: process.env.MSSQL_CONNECTION_RETRY_INTERVAL_MS,
+        MSSQL_POOL_MAX: process.env.MSSQL_POOL_MAX,
+        MSSQL_POOL_MIN: process.env.MSSQL_POOL_MIN,
+        MSSQL_POOL_IDLE_TIMEOUT_MS: process.env.MSSQL_POOL_IDLE_TIMEOUT_MS,
+        MSSQL_APP_NAME: process.env.MSSQL_APP_NAME,
+        MSSQL_USE_UTC: process.env.MSSQL_USE_UTC,
+        MSSQL_TDS_VERSION: process.env.MSSQL_TDS_VERSION,
+        MSSQL_AUTH_TYPE: process.env.MSSQL_AUTH_TYPE,
+        MSSQL_AZURE_CLIENT_ID: process.env.MSSQL_AZURE_CLIENT_ID,
+        MSSQL_AZURE_TENANT_ID: process.env.MSSQL_AZURE_TENANT_ID,
+        MSSQL_AZURE_CLIENT_SECRET: process.env.MSSQL_AZURE_CLIENT_SECRET,
+        MSSQL_AZURE_ACCESS_TOKEN: process.env.MSSQL_AZURE_ACCESS_TOKEN,
     };
 }
+export function loadConfig() {
+    return v.parse(appConfigSchema, readProcessEnv());
+}
 export function mssqlDriverConfig(cfg) {
-    return {
-        user: cfg.user,
-        password: cfg.password,
+    const options = {
+        encrypt: cfg.encrypt,
+        trustServerCertificate: cfg.trustServerCertificate,
+    };
+    if (cfg.tlsServerName !== undefined)
+        options.serverName = cfg.tlsServerName;
+    if (cfg.instanceName !== undefined)
+        options.instanceName = cfg.instanceName;
+    if (cfg.multiSubnetFailover !== undefined)
+        options.multiSubnetFailover = cfg.multiSubnetFailover;
+    if (cfg.readOnlyIntent !== undefined)
+        options.readOnlyIntent = cfg.readOnlyIntent;
+    if (cfg.maxRetriesOnTransientErrors !== undefined) {
+        options.maxRetriesOnTransientErrors = cfg.maxRetriesOnTransientErrors;
+    }
+    if (cfg.connectionRetryIntervalMs !== undefined) {
+        options.connectionRetryInterval = cfg.connectionRetryIntervalMs;
+    }
+    if (cfg.cryptoCredentialsDetails !== undefined) {
+        options.cryptoCredentialsDetails = cfg.cryptoCredentialsDetails;
+    }
+    if (cfg.appName !== undefined)
+        options.appName = cfg.appName;
+    if (cfg.useUtc !== undefined)
+        options.useUTC = cfg.useUtc;
+    if (cfg.tdsVersion !== undefined) {
+        options.tdsVersion = cfg.tdsVersion;
+    }
+    let authentication;
+    if (cfg.authType === 'ntlm') {
+        authentication = {
+            type: 'ntlm',
+            options: {
+                userName: cfg.user,
+                password: cfg.password,
+                domain: cfg.domain,
+            },
+        };
+    }
+    else if (cfg.authType === 'azure-active-directory-password') {
+        authentication = {
+            type: 'azure-active-directory-password',
+            options: {
+                userName: cfg.user,
+                password: cfg.password,
+                clientId: cfg.azureClientId,
+                tenantId: cfg.azureTenantId ?? 'common',
+            },
+        };
+    }
+    else if (cfg.authType === 'azure-active-directory-access-token') {
+        authentication = {
+            type: 'azure-active-directory-access-token',
+            options: { token: cfg.azureAccessToken },
+        };
+    }
+    else if (cfg.authType === 'azure-active-directory-service-principal-secret') {
+        authentication = {
+            type: 'azure-active-directory-service-principal-secret',
+            options: {
+                clientId: cfg.azureClientId,
+                clientSecret: cfg.azureClientSecret,
+                tenantId: cfg.azureTenantId,
+            },
+        };
+    }
+    const base = {
         server: cfg.server,
-        port: cfg.port,
         database: cfg.database,
-        pool: { max: 10, min: 0, idleTimeoutMillis: 30_000 },
-        options: {
-            encrypt: cfg.encrypt,
-            trustServerCertificate: cfg.trustServerCertificate,
+        pool: {
+            max: cfg.poolMax,
+            min: cfg.poolMin,
+            idleTimeoutMillis: cfg.poolIdleTimeoutMs,
         },
+        options,
         requestTimeout: cfg.queryTimeoutMs,
     };
+    if (cfg.connectionTimeoutMs !== undefined) {
+        base.connectionTimeout = cfg.connectionTimeoutMs;
+    }
+    if (cfg.instanceName === undefined) {
+        base.port = cfg.port;
+    }
+    if (authentication !== undefined) {
+        base.authentication = authentication;
+    }
+    else {
+        base.user = cfg.user;
+        base.password = cfg.password;
+        if (cfg.domain !== undefined) {
+            base.domain = cfg.domain;
+        }
+    }
+    return base;
 }

package/dist/index.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import sql from 'mssql';
-import * as v from 'valibot';
 import { Server } from '@modelcontextprotocol/sdk/server';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import sql from 'mssql';
+import * as v from 'valibot';
 import { loadConfig, mssqlDriverConfig } from './config.js';
-import { assertReadOnlySql, wrapWithRowCount } from './readonly-sql.js';
+import { assertReadOnlySql, ReadOnlySqlError } from './readonly-sql.js';
 import { mssqlDescribeTableSchema, mssqlListTablesSchema, mssqlQuerySchema, valibotToJsonSchema, } from './schemas.js';
 const SHARED_TOOL_PREAMBLE = 'Connection uses MSSQL_* environment variables on the MCP server process. Arbitrary SQL is dangerous; prefer a read-only or narrowly scoped database user.';
 function toolError(message) {
@@ -19,17 +19,32 @@ function jsonResult(data) {
         content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
     };
 }
+function logToolFailure(toolName, err) {
+    console.error(`[${toolName}]`, err);
+}
+function toolExecutionError(toolName, err) {
+    if (err instanceof ReadOnlySqlError) {
+        return toolError(err.message);
+    }
+    logToolFailure(toolName, err);
+    switch (toolName) {
+        case 'mssql_query':
+            return toolError('Query failed. Check SQL syntax, permissions, timeout settings, and database connectivity.');
+        case 'mssql_list_tables':
+            return toolError('Failed to list tables. Check permissions and database connectivity.');
+        case 'mssql_describe_table':
+            return toolError('Failed to describe the table. Check the schema/table name, permissions, and connectivity.');
+        default:
+            return toolError('The request failed. Check the server logs for details.');
+    }
+}
 async function runQuery(pool, cfg, batch) {
     assertReadOnlySql(batch, cfg.allowWrites);
-    const wrapped = wrapWithRowCount(batch, cfg.maxRows);
-    const result = await pool.request().query(wrapped);
+    const result = await pool.request().query(batch);
     const recordsets = result.recordsets;
     return jsonResult({
         rowsAffected: result.rowsAffected,
         recordsets,
-        rowCountNote: cfg.maxRows !== undefined
-            ? `ROWCOUNT capped at ${cfg.maxRows} per batch (SET ROWCOUNT).`
-            : undefined,
     });
 }
 async function runListTables(pool, schemaFilter) {
@@ -114,14 +129,13 @@ async function main() {
             if (v.isValiError(err)) {
                 return toolError(`Invalid arguments: ${err.message}`);
             }
-            const msg = err instanceof Error ? err.message : String(err);
-            return toolError(msg);
+            return toolExecutionError(name, err);
         }
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
 main().catch((err) => {
-    console.error(err);
+    console.error('Fatal error in main():', err);
     process.exit(1);
 });

package/dist/readonly-sql.d.ts

@@ -1,8 +1,10 @@
 /**
  * Best-effort read-only gate. Not a substitute for database permissions.
  */
+export declare class ReadOnlySqlError extends Error {
+    constructor(message: string);
+}
 export declare function stripSqlComments(text: string): string;
 /** Masks single-quoted and N'...' string literals so keywords inside literals are ignored. */
 export declare function maskSqlStringLiterals(text: string): string;
 export declare function assertReadOnlySql(sql: string, allowWrites: boolean): void;
-export declare function wrapWithRowCount(sql: string, maxRows: number | undefined): string;

package/dist/readonly-sql.js

@@ -2,6 +2,12 @@
  * Best-effort read-only gate. Not a substitute for database permissions.
  */
 const FORBIDDEN = /\b(INSERT|UPDATE|DELETE|MERGE|DROP|ALTER|CREATE|TRUNCATE|EXEC|EXECUTE|GRANT|REVOKE|DENY|BULK)\b/i;
+export class ReadOnlySqlError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ReadOnlySqlError';
+    }
+}
 export function stripSqlComments(text) {
     let s = text.replace(/\/\*[\s\S]*?\*\//g, ' ');
     s = s.replace(/--[^\n\r]*/g, ' ');
@@ -55,12 +61,6 @@ export function assertReadOnlySql(sql, allowWrites) {
         return;
     const probe = maskSqlStringLiterals(stripSqlComments(sql));
     if (FORBIDDEN.test(probe)) {
-        throw new Error('Read-only mode: this batch contains a blocked keyword (INSERT, UPDATE, DELETE, MERGE, DDL, EXEC, etc.). Set MSSQL_ALLOW_WRITES=true to allow writes (still use a least-privilege login).');
+        throw new ReadOnlySqlError('Read-only mode: this batch contains a blocked keyword (INSERT, UPDATE, DELETE, MERGE, DDL, EXEC, etc.). Set MSSQL_ALLOW_WRITES=true to allow writes (still use a least-privilege login).');
     }
 }
-export function wrapWithRowCount(sql, maxRows) {
-    if (maxRows === undefined || maxRows <= 0)
-        return sql;
-    const n = Math.floor(maxRows);
-    return `SET ROWCOUNT ${n}; ${sql}; SET ROWCOUNT 0;`;
-}

package/dist/schemas.js

@@ -1,5 +1,5 @@
-import * as v from 'valibot';
 import { toJsonSchema } from '@valibot/to-json-schema';
+import * as v from 'valibot';
 /** MCP tool inputSchema: JSON Schema derived from Valibot (descriptions flow to clients). */
 export function valibotToJsonSchema(schema) {
     const js = toJsonSchema(schema);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adriancy/mcp-mssql",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "private": false,
   "type": "module",
   "main": "dist/index.js",
@@ -19,6 +19,7 @@
     "valibot": "^1.1.0"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.4.10",
     "@types/mssql": "^9.1.8",
     "@types/node": "^22.10.0",
     "tsx": "^4.19.2",
@@ -26,6 +27,10 @@
   },
   "scripts": {
     "build": "tsc",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "check": "biome check . --write",
+    "test": "node --import tsx --test",
     "start": "node dist/index.js",
     "dev": "node --import tsx src/index.ts"
   }