ssms-mcp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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

@@ -0,0 +1,177 @@
+# ssms-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets AI assistants execute T-SQL queries against Microsoft SQL Server (the engine behind SSMS).
+
+## Features
+
+Tools exposed over MCP (stdio):
+
+| Tool | Description |
+| --- | --- |
+| `execute_query` | Run any T-SQL with optional named parameters. |
+| `list_databases` | List user databases. |
+| `list_tables` | List tables/views in a database (optional schema filter). |
+| `describe_table` | Columns, types, nullability, defaults, and PK. |
+| `server_info` | Server version + current connection context. |
+
+Safety controls:
+
+- `MSSQL_READ_ONLY=true` blocks `INSERT/UPDATE/DELETE/DDL/EXEC/...`.
+- `MSSQL_MAX_ROWS` caps rows returned per recordset (default `1000`).
+
+Authentication modes (set `MSSQL_AUTH_TYPE`):
+
+| Value | Description |
+| --- | --- |
+| `sql` | SQL auth (`MSSQL_USER` / `MSSQL_PASSWORD`). |
+| `ntlm` | Windows / NTLM (`MSSQL_DOMAIN` / `MSSQL_NTLM_USER` / `MSSQL_NTLM_PASSWORD`). |
+| `entra-interactive` | **Microsoft Entra MFA via browser popup** — same flow SSMS uses. |
+| `entra-device-code` | Microsoft Entra MFA via device-code flow (great for headless / remote shells). |
+| `entra-default` | `DefaultAzureCredential` chain (Azure CLI, VS, env vars, MSI…). |
+| `entra-password` | Entra username + password. **Does NOT support MFA.** |
+| `entra-service-principal` | App registration client credentials. |
+| `entra-msi` | Managed Identity (Azure VMs, App Service, etc.). |
+| `entra-access-token` | Pre-supplied bearer token in `MSSQL_ACCESS_TOKEN`. |
+
+Default: `sql` if `MSSQL_USER` is set, otherwise `ntlm` if `MSSQL_DOMAIN` is set, otherwise `entra-default`.
+
+## Install
+
+```bash
+npm install -g ssms-mcp
+```
+
+Or run with `npx` (no install):
+
+```bash
+npx ssms-mcp
+```
+
+## Configure
+
+Set environment variables before launching:
+
+| Variable | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `MSSQL_SERVER` | yes | — | `localhost`, `host\SQLEXPRESS`, FQDN, etc. |
+| `MSSQL_DATABASE` | no | — | Default database. |
+| `MSSQL_USER` | no | — | SQL auth user. Omit for Windows auth. |
+| `MSSQL_PASSWORD` | no | — | SQL auth password. |
+| `MSSQL_PORT` | no | 1433 | |
+| `MSSQL_INSTANCE_NAME` | no | — | e.g. `SQLEXPRESS`. |
+| `MSSQL_ENCRYPT` | no | `true` | |
+| `MSSQL_TRUST_SERVER_CERTIFICATE` | no | `true` | Set `false` in production. |
+| `MSSQL_CONNECT_TIMEOUT_MS` | no | 15000 | |
+| `MSSQL_REQUEST_TIMEOUT_MS` | no | 30000 | |
+| `MSSQL_READ_ONLY` | no | `false` | Block writes/DDL. |
+| `MSSQL_MAX_ROWS` | no | 1000 | Per recordset cap. |
+| `MSSQL_AUTH_TYPE` | no | auto | See table above. |
+| `MSSQL_TENANT_ID` | optional* | — | Azure AD tenant id (or `common` / `organizations`). See note below. |
+| `MSSQL_CLIENT_ID` | optional | Azure CLI public client | App registration client id. |
+| `MSSQL_REDIRECT_URI` | entra-interactive | `http://localhost` | Must match app reg. |
+| `MSSQL_ENTRA_USERNAME` | optional | — | Login hint / username for entra-password. |
+| `MSSQL_ENTRA_PASSWORD` | entra-password | — | Password (no MFA). |
+| `MSSQL_CLIENT_SECRET` | entra-service-principal | — | App reg secret. |
+| `MSSQL_ACCESS_TOKEN` | entra-access-token | — | Bearer token for `https://database.windows.net`. |
+| `MSSQL_DOMAIN` / `MSSQL_NTLM_USER` / `MSSQL_NTLM_PASSWORD` | ntlm | — | NTLM auth. |
+
+\* `MSSQL_TENANT_ID` is **only required** for `entra-password` and `entra-service-principal`.
+For `entra-interactive`, `entra-device-code`, and `entra-default` it can be omitted —
+`@azure/identity` will default to the `organizations` tenant, which works for any
+work/school account in its home tenant. Set it explicitly when:
+
+- you are a **guest** in the target Azure SQL tenant, or
+- you want to skip the account picker / pin auth to a specific tenant.
+
+## Use with VS Code / Claude Desktop
+
+Add to your MCP client config (e.g. `claude_desktop_config.json` or VS Code MCP settings):
+
+```json
+{
+  "mcpServers": {
+    "ssms": {
+      "command": "npx",
+      "args": ["-y", "ssms-mcp"],
+      "env": {
+        "MSSQL_SERVER": "localhost",
+        "MSSQL_DATABASE": "AdventureWorks",
+        "MSSQL_USER": "sa",
+        "MSSQL_PASSWORD": "your-password",
+        "MSSQL_READ_ONLY": "true"
+      }
+    }
+  }
+}
+```
+
+### Azure SQL with Microsoft Entra MFA (browser popup)
+
+This matches SSMS → "Microsoft Entra MFA". On first use, a browser window opens and you complete MFA; the token is cached in-memory until it expires.
+
+```json
+{
+  "mcpServers": {
+    "ssms": {
+      "command": "npx",
+      "args": ["-y", "ssms-mcp"],
+      "env": {
+        "MSSQL_SERVER": "myserver.database.windows.net",
+        "MSSQL_DATABASE": "mydb",
+        "MSSQL_AUTH_TYPE": "entra-interactive",
+        "MSSQL_TENANT_ID": "<your-tenant-id-or-common>",
+        "MSSQL_ENTRA_USERNAME": "you@contoso.com",
+        "MSSQL_READ_ONLY": "true"
+      }
+    }
+  }
+}
+```
+
+Headless / remote machine? Use device code flow — the URL + code are printed to stderr:
+
+```json
+"env": {
+  "MSSQL_SERVER": "myserver.database.windows.net",
+  "MSSQL_DATABASE": "mydb",
+  "MSSQL_AUTH_TYPE": "entra-device-code",
+  "MSSQL_TENANT_ID": "<tenant>"
+}
+```
+
+Already signed in via `az login` / Visual Studio? Just use the default chain:
+
+```json
+"env": {
+  "MSSQL_SERVER": "myserver.database.windows.net",
+  "MSSQL_DATABASE": "mydb",
+  "MSSQL_AUTH_TYPE": "entra-default"
+}
+```
+
+## Example tool calls
+
+```jsonc
+// execute_query
+{
+  "query": "SELECT TOP (@n) name FROM sys.tables WHERE name LIKE @pattern",
+  "parameters": { "n": 5, "pattern": "Sales%" }
+}
+```
+
+```jsonc
+// describe_table
+{ "table": "dbo.Customer", "database": "Sales" }
+```
+
+## Develop
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * SSMS MCP Server
+ * -----------------
+ * A Model Context Protocol server that exposes tools for executing
+ * T-SQL queries and inspecting schemas on Microsoft SQL Server
+ * (the engine behind SSMS).
+ *
+ * Connection is configured via environment variables:
+ *   MSSQL_SERVER         (required) e.g. "localhost" or "myhost\\SQLEXPRESS" or "myserver.database.windows.net"
+ *   MSSQL_DATABASE       (optional) default database
+ *   MSSQL_AUTH_TYPE      (optional) one of:
+ *                          "sql"                       SQL auth (MSSQL_USER/PASSWORD)
+ *                          "ntlm"                      Windows / NTLM (MSSQL_DOMAIN/MSSQL_NTLM_USER/PASSWORD)
+ *                          "entra-interactive"         Microsoft Entra MFA via browser popup (SSMS-style)
+ *                          "entra-device-code"         Microsoft Entra MFA via device-code flow
+ *                          "entra-default"             DefaultAzureCredential chain (CLI/VS/MSI/env)
+ *                          "entra-password"            Entra username+password (NOT MFA)
+ *                          "entra-service-principal"   Entra client credentials
+ *                          "entra-msi"                 Managed Identity
+ *                          "entra-access-token"        Pre-supplied token (MSSQL_ACCESS_TOKEN)
+ *                        Default: "sql" if MSSQL_USER set, else "ntlm" if MSSQL_DOMAIN set, else "entra-default".
+ *   MSSQL_USER           (optional) SQL auth user
+ *   MSSQL_PASSWORD       (optional) SQL auth password
+ *   MSSQL_PORT           (optional) default 1433
+ *   MSSQL_ENCRYPT        (optional) "true"|"false", default "true"
+ *   MSSQL_TRUST_SERVER_CERTIFICATE (optional) "true"|"false", default "true"
+ *   MSSQL_INSTANCE_NAME  (optional) named instance, e.g. "SQLEXPRESS"
+ *   MSSQL_CONNECT_TIMEOUT_MS (optional) default 15000
+ *   MSSQL_REQUEST_TIMEOUT_MS (optional) default 30000
+ *   MSSQL_READ_ONLY      (optional) "true" to reject non-SELECT statements
+ *   MSSQL_MAX_ROWS       (optional) cap rows returned per query (default 1000)
+ *
+ * Entra-specific env vars:
+ *   MSSQL_TENANT_ID       Azure AD tenant id (or "common" / "organizations")
+ *   MSSQL_CLIENT_ID       App registration client id (defaults to Azure CLI public client)
+ *   MSSQL_REDIRECT_URI    For entra-interactive (default "http://localhost")
+ *   MSSQL_ENTRA_USERNAME  For entra-password / hint for entra-interactive
+ *   MSSQL_ENTRA_PASSWORD  For entra-password (no MFA)
+ *   MSSQL_CLIENT_SECRET   For entra-service-principal
+ *   MSSQL_ACCESS_TOKEN    For entra-access-token (raw bearer token for https://database.windows.net)
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,506 @@
+#!/usr/bin/env node
+/**
+ * SSMS MCP Server
+ * -----------------
+ * A Model Context Protocol server that exposes tools for executing
+ * T-SQL queries and inspecting schemas on Microsoft SQL Server
+ * (the engine behind SSMS).
+ *
+ * Connection is configured via environment variables:
+ *   MSSQL_SERVER         (required) e.g. "localhost" or "myhost\\SQLEXPRESS" or "myserver.database.windows.net"
+ *   MSSQL_DATABASE       (optional) default database
+ *   MSSQL_AUTH_TYPE      (optional) one of:
+ *                          "sql"                       SQL auth (MSSQL_USER/PASSWORD)
+ *                          "ntlm"                      Windows / NTLM (MSSQL_DOMAIN/MSSQL_NTLM_USER/PASSWORD)
+ *                          "entra-interactive"         Microsoft Entra MFA via browser popup (SSMS-style)
+ *                          "entra-device-code"         Microsoft Entra MFA via device-code flow
+ *                          "entra-default"             DefaultAzureCredential chain (CLI/VS/MSI/env)
+ *                          "entra-password"            Entra username+password (NOT MFA)
+ *                          "entra-service-principal"   Entra client credentials
+ *                          "entra-msi"                 Managed Identity
+ *                          "entra-access-token"        Pre-supplied token (MSSQL_ACCESS_TOKEN)
+ *                        Default: "sql" if MSSQL_USER set, else "ntlm" if MSSQL_DOMAIN set, else "entra-default".
+ *   MSSQL_USER           (optional) SQL auth user
+ *   MSSQL_PASSWORD       (optional) SQL auth password
+ *   MSSQL_PORT           (optional) default 1433
+ *   MSSQL_ENCRYPT        (optional) "true"|"false", default "true"
+ *   MSSQL_TRUST_SERVER_CERTIFICATE (optional) "true"|"false", default "true"
+ *   MSSQL_INSTANCE_NAME  (optional) named instance, e.g. "SQLEXPRESS"
+ *   MSSQL_CONNECT_TIMEOUT_MS (optional) default 15000
+ *   MSSQL_REQUEST_TIMEOUT_MS (optional) default 30000
+ *   MSSQL_READ_ONLY      (optional) "true" to reject non-SELECT statements
+ *   MSSQL_MAX_ROWS       (optional) cap rows returned per query (default 1000)
+ *
+ * Entra-specific env vars:
+ *   MSSQL_TENANT_ID       Azure AD tenant id (or "common" / "organizations")
+ *   MSSQL_CLIENT_ID       App registration client id (defaults to Azure CLI public client)
+ *   MSSQL_REDIRECT_URI    For entra-interactive (default "http://localhost")
+ *   MSSQL_ENTRA_USERNAME  For entra-password / hint for entra-interactive
+ *   MSSQL_ENTRA_PASSWORD  For entra-password (no MFA)
+ *   MSSQL_CLIENT_SECRET   For entra-service-principal
+ *   MSSQL_ACCESS_TOKEN    For entra-access-token (raw bearer token for https://database.windows.net)
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import sql from "mssql";
+import { ClientSecretCredential, DefaultAzureCredential, DeviceCodeCredential, InteractiveBrowserCredential, ManagedIdentityCredential, UsernamePasswordCredential, } from "@azure/identity";
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+function envBool(name, def) {
+    const v = process.env[name];
+    if (v === undefined)
+        return def;
+    return /^(1|true|yes|on)$/i.test(v);
+}
+function envInt(name, def) {
+    const v = process.env[name];
+    if (!v)
+        return def;
+    const n = Number.parseInt(v, 10);
+    return Number.isFinite(n) ? n : def;
+}
+const READ_ONLY = envBool("MSSQL_READ_ONLY", false);
+const MAX_ROWS = envInt("MSSQL_MAX_ROWS", 1000);
+// SQL Server resource scope for Entra access tokens.
+const SQL_SCOPE = "https://database.windows.net/.default";
+// Azure CLI's public client id. Works for interactive/device-code against any
+// tenant that allows it. Override with MSSQL_CLIENT_ID for your own app reg.
+const DEFAULT_PUBLIC_CLIENT_ID = "04b07795-8ddb-461a-bbee-02f9e1bf7b46";
+function resolveAuthType() {
+    const explicit = process.env.MSSQL_AUTH_TYPE?.toLowerCase().trim();
+    if (explicit)
+        return explicit;
+    if (process.env.MSSQL_USER)
+        return "sql";
+    if (process.env.MSSQL_DOMAIN)
+        return "ntlm";
+    return "entra-default";
+}
+function buildEntraCredential(authType) {
+    const tenantId = process.env.MSSQL_TENANT_ID;
+    const clientId = process.env.MSSQL_CLIENT_ID ?? DEFAULT_PUBLIC_CLIENT_ID;
+    switch (authType) {
+        case "entra-interactive":
+            return new InteractiveBrowserCredential({
+                tenantId,
+                clientId,
+                redirectUri: process.env.MSSQL_REDIRECT_URI ?? "http://localhost",
+                loginHint: process.env.MSSQL_ENTRA_USERNAME,
+            });
+        case "entra-device-code":
+            return new DeviceCodeCredential({
+                tenantId,
+                clientId,
+                userPromptCallback: (info) => {
+                    // stderr only — stdout is reserved for MCP framing.
+                    console.error(`[ssms-mcp] ${info.message}`);
+                },
+            });
+        case "entra-password": {
+            const username = process.env.MSSQL_ENTRA_USERNAME;
+            const password = process.env.MSSQL_ENTRA_PASSWORD;
+            if (!tenantId || !username || !password) {
+                throw new Error("entra-password requires MSSQL_TENANT_ID, MSSQL_ENTRA_USERNAME and MSSQL_ENTRA_PASSWORD. Note: this flow does NOT support MFA.");
+            }
+            return new UsernamePasswordCredential(tenantId, clientId, username, password);
+        }
+        case "entra-service-principal": {
+            const secret = process.env.MSSQL_CLIENT_SECRET;
+            if (!tenantId || !process.env.MSSQL_CLIENT_ID || !secret) {
+                throw new Error("entra-service-principal requires MSSQL_TENANT_ID, MSSQL_CLIENT_ID and MSSQL_CLIENT_SECRET.");
+            }
+            return new ClientSecretCredential(tenantId, process.env.MSSQL_CLIENT_ID, secret);
+        }
+        case "entra-msi":
+            return new ManagedIdentityCredential(process.env.MSSQL_CLIENT_ID ? { clientId: process.env.MSSQL_CLIENT_ID } : undefined);
+        case "entra-default":
+        default:
+            return new DefaultAzureCredential({ tenantId });
+    }
+}
+// Cache acquired tokens so we don't trigger a fresh browser prompt for every
+// pool. Refresh ~5 minutes before expiry.
+let cachedToken = null;
+let credential = null;
+let credentialAuthType = null;
+async function acquireEntraToken(authType) {
+    if (authType === "entra-access-token") {
+        const t = process.env.MSSQL_ACCESS_TOKEN;
+        if (!t) {
+            throw new Error("entra-access-token requires MSSQL_ACCESS_TOKEN (a bearer token for https://database.windows.net).");
+        }
+        return t;
+    }
+    const now = Date.now();
+    if (cachedToken &&
+        credentialAuthType === authType &&
+        cachedToken.expiresOnTimestamp - now > 5 * 60 * 1000) {
+        return cachedToken.token;
+    }
+    if (!credential || credentialAuthType !== authType) {
+        credential = buildEntraCredential(authType);
+        credentialAuthType = authType;
+        cachedToken = null;
+    }
+    const tok = await credential.getToken(SQL_SCOPE);
+    if (!tok) {
+        throw new Error(`Failed to acquire Entra access token via ${authType}.`);
+    }
+    cachedToken = tok;
+    return tok.token;
+}
+function buildPoolConfig(databaseOverride) {
+    const server = process.env.MSSQL_SERVER;
+    if (!server) {
+        throw new Error("MSSQL_SERVER environment variable is required (e.g. 'localhost' or 'host\\\\SQLEXPRESS').");
+    }
+    const config = {
+        server,
+        database: databaseOverride ?? process.env.MSSQL_DATABASE,
+        port: process.env.MSSQL_PORT ? Number(process.env.MSSQL_PORT) : undefined,
+        connectionTimeout: envInt("MSSQL_CONNECT_TIMEOUT_MS", 15000),
+        requestTimeout: envInt("MSSQL_REQUEST_TIMEOUT_MS", 30000),
+        options: {
+            encrypt: envBool("MSSQL_ENCRYPT", true),
+            trustServerCertificate: envBool("MSSQL_TRUST_SERVER_CERTIFICATE", true),
+            instanceName: process.env.MSSQL_INSTANCE_NAME,
+        },
+        pool: { max: 5, min: 0, idleTimeoutMillis: 30000 },
+    };
+    return config;
+}
+async function buildAuthenticatedConfig(databaseOverride) {
+    const config = buildPoolConfig(databaseOverride);
+    const authType = resolveAuthType();
+    if (authType === "sql") {
+        const user = process.env.MSSQL_USER;
+        if (!user) {
+            throw new Error("MSSQL_AUTH_TYPE=sql requires MSSQL_USER (and MSSQL_PASSWORD).");
+        }
+        config.user = user;
+        config.password = process.env.MSSQL_PASSWORD ?? "";
+        config.authentication = {
+            type: "default",
+            options: { userName: user, password: process.env.MSSQL_PASSWORD ?? "" },
+        };
+        return config;
+    }
+    if (authType === "ntlm") {
+        const domain = process.env.MSSQL_DOMAIN;
+        if (!domain) {
+            throw new Error("MSSQL_AUTH_TYPE=ntlm requires MSSQL_DOMAIN.");
+        }
+        config.authentication = {
+            type: "ntlm",
+            options: {
+                domain,
+                userName: process.env.MSSQL_NTLM_USER ?? "",
+                password: process.env.MSSQL_NTLM_PASSWORD ?? "",
+            },
+        };
+        return config;
+    }
+    // All entra-* variants resolve to a pre-acquired bearer token that tedious
+    // accepts via 'azure-active-directory-access-token'.
+    const token = await acquireEntraToken(authType);
+    config.authentication = {
+        type: "azure-active-directory-access-token",
+        options: { token },
+    };
+    // Encryption is required for Azure SQL / Entra auth.
+    config.options = { ...config.options, encrypt: true };
+    return config;
+}
+// ---------------------------------------------------------------------------
+// Connection pool cache (per database)
+// ---------------------------------------------------------------------------
+const pools = new Map();
+async function getPool(database) {
+    const key = database ?? process.env.MSSQL_DATABASE ?? "__default__";
+    const existing = pools.get(key);
+    if (existing)
+        return existing;
+    const created = (async () => {
+        const cfg = await buildAuthenticatedConfig(database);
+        return new sql.ConnectionPool(cfg).connect();
+    })();
+    pools.set(key, created);
+    created.catch(() => pools.delete(key));
+    return created;
+}
+async function closeAllPools() {
+    const all = Array.from(pools.values());
+    pools.clear();
+    await Promise.allSettled(all.map(async (p) => {
+        try {
+            const pool = await p;
+            await pool.close();
+        }
+        catch {
+            /* ignore */
+        }
+    }));
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+const WRITE_REGEX = /\b(INSERT|UPDATE|DELETE|MERGE|DROP|TRUNCATE|ALTER|CREATE|GRANT|REVOKE|EXEC(UTE)?|BACKUP|RESTORE)\b/i;
+function assertReadOnly(query) {
+    if (READ_ONLY && WRITE_REGEX.test(query)) {
+        throw new Error("Server is in READ_ONLY mode (MSSQL_READ_ONLY=true); write/DDL statements are blocked.");
+    }
+}
+function trimRows(rows) {
+    if (rows.length > MAX_ROWS) {
+        return { rows: rows.slice(0, MAX_ROWS), truncated: true };
+    }
+    return { rows, truncated: false };
+}
+function asTextResult(payload) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof payload === "string"
+                    ? payload
+                    : JSON.stringify(payload, null, 2),
+            },
+        ],
+    };
+}
+function asErrorResult(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+        isError: true,
+        content: [{ type: "text", text: `Error: ${msg}` }],
+    };
+}
+// ---------------------------------------------------------------------------
+// Tool definitions
+// ---------------------------------------------------------------------------
+const TOOLS = [
+    {
+        name: "execute_query",
+        description: "Execute an arbitrary T-SQL query (or batch) against SQL Server and return the result rows as JSON. Honors MSSQL_READ_ONLY and MSSQL_MAX_ROWS.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "The T-SQL to execute." },
+                database: {
+                    type: "string",
+                    description: "Optional database to execute against (overrides default).",
+                },
+                parameters: {
+                    type: "object",
+                    description: "Optional named parameters: { name: value }. Reference them in SQL as @name.",
+                    additionalProperties: true,
+                },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "list_databases",
+        description: "List user databases on the server (excludes system DBs).",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "list_tables",
+        description: "List tables (and views) in a database. Returns schema, name, and type.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                database: { type: "string" },
+                schema: {
+                    type: "string",
+                    description: "Optional schema filter (e.g. 'dbo').",
+                },
+            },
+        },
+    },
+    {
+        name: "describe_table",
+        description: "Describe a table: columns, types, nullability, defaults, and primary key.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                table: {
+                    type: "string",
+                    description: "Table name. May be 'schema.table' or just 'table'.",
+                },
+                database: { type: "string" },
+            },
+            required: ["table"],
+        },
+    },
+    {
+        name: "server_info",
+        description: "Return SQL Server version and current connection context.",
+        inputSchema: { type: "object", properties: {} },
+    },
+];
+// ---------------------------------------------------------------------------
+// Tool handlers
+// ---------------------------------------------------------------------------
+async function handleExecuteQuery(args) {
+    const { query, database, parameters } = args;
+    if (!query || typeof query !== "string") {
+        throw new Error("`query` must be a non-empty string.");
+    }
+    assertReadOnly(query);
+    const pool = await getPool(database);
+    const request = pool.request();
+    if (parameters && typeof parameters === "object") {
+        for (const [k, v] of Object.entries(parameters)) {
+            request.input(k, v);
+        }
+    }
+    const result = await request.query(query);
+    // Multiple recordsets are possible.
+    const recordsets = result.recordsets ?? [];
+    const trimmed = recordsets.map((rs) => trimRows(rs));
+    return asTextResult({
+        rowsAffected: result.rowsAffected,
+        recordsetCount: recordsets.length,
+        recordsets: trimmed.map((t) => t.rows),
+        truncated: trimmed.some((t) => t.truncated),
+        maxRows: MAX_ROWS,
+    });
+}
+async function handleListDatabases() {
+    const pool = await getPool();
+    const result = await pool.request().query(`
+    SELECT name, database_id, create_date, collation_name, state_desc
+    FROM sys.databases
+    WHERE database_id > 4
+    ORDER BY name;
+  `);
+    return asTextResult(result.recordset);
+}
+async function handleListTables(args) {
+    const pool = await getPool(args.database);
+    const req = pool.request();
+    let where = "";
+    if (args.schema) {
+        req.input("schema", sql.NVarChar, args.schema);
+        where = "WHERE TABLE_SCHEMA = @schema";
+    }
+    const result = await req.query(`
+    SELECT TABLE_SCHEMA AS [schema], TABLE_NAME AS [name], TABLE_TYPE AS [type]
+    FROM INFORMATION_SCHEMA.TABLES
+    ${where}
+    ORDER BY TABLE_SCHEMA, TABLE_NAME;
+  `);
+    return asTextResult(result.recordset);
+}
+async function handleDescribeTable(args) {
+    const [schemaPart, tablePart] = args.table.includes(".")
+        ? args.table.split(".", 2)
+        : ["dbo", args.table];
+    const pool = await getPool(args.database);
+    const cols = await pool
+        .request()
+        .input("schema", sql.NVarChar, schemaPart)
+        .input("table", sql.NVarChar, tablePart).query(`
+      SELECT
+        COLUMN_NAME            AS name,
+        DATA_TYPE              AS dataType,
+        CHARACTER_MAXIMUM_LENGTH AS maxLength,
+        NUMERIC_PRECISION      AS precision,
+        NUMERIC_SCALE          AS scale,
+        IS_NULLABLE            AS isNullable,
+        COLUMN_DEFAULT         AS defaultValue,
+        ORDINAL_POSITION       AS ordinal
+      FROM INFORMATION_SCHEMA.COLUMNS
+      WHERE TABLE_SCHEMA = @schema AND TABLE_NAME = @table
+      ORDER BY ORDINAL_POSITION;
+    `);
+    const pk = await pool
+        .request()
+        .input("schema", sql.NVarChar, schemaPart)
+        .input("table", sql.NVarChar, tablePart).query(`
+      SELECT kcu.COLUMN_NAME AS name, kcu.ORDINAL_POSITION AS ordinal
+      FROM INFORMATION_SCHEMA.TABLE_CONSTRAINTS tc
+      JOIN INFORMATION_SCHEMA.KEY_COLUMN_USAGE kcu
+        ON tc.CONSTRAINT_NAME = kcu.CONSTRAINT_NAME
+       AND tc.TABLE_SCHEMA   = kcu.TABLE_SCHEMA
+      WHERE tc.CONSTRAINT_TYPE = 'PRIMARY KEY'
+        AND tc.TABLE_SCHEMA = @schema
+        AND tc.TABLE_NAME   = @table
+      ORDER BY kcu.ORDINAL_POSITION;
+    `);
+    return asTextResult({
+        schema: schemaPart,
+        table: tablePart,
+        columns: cols.recordset,
+        primaryKey: pk.recordset.map((r) => r.name),
+    });
+}
+async function handleServerInfo() {
+    const pool = await getPool();
+    const result = await pool.request().query(`
+    SELECT
+      @@VERSION              AS version,
+      @@SERVERNAME           AS serverName,
+      DB_NAME()              AS currentDatabase,
+      SUSER_SNAME()          AS loginName,
+      SYSTEM_USER            AS systemUser;
+  `);
+    return asTextResult({
+        ...result.recordset[0],
+        authType: resolveAuthType(),
+        readOnly: READ_ONLY,
+        maxRows: MAX_ROWS,
+    });
+}
+// ---------------------------------------------------------------------------
+// Server
+// ---------------------------------------------------------------------------
+const server = new Server({ name: "ssms-mcp", version: "0.2.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS,
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args = {} } = req.params;
+    try {
+        switch (name) {
+            case "execute_query":
+                return await handleExecuteQuery(args);
+            case "list_databases":
+                return await handleListDatabases();
+            case "list_tables":
+                return await handleListTables(args);
+            case "describe_table":
+                return await handleDescribeTable(args);
+            case "server_info":
+                return await handleServerInfo();
+            default:
+                return asErrorResult(`Unknown tool: ${name}`);
+        }
+    }
+    catch (err) {
+        return asErrorResult(err);
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Stderr is safe — stdout is reserved for MCP framing.
+    console.error("[ssms-mcp] server ready (stdio)");
+}
+const shutdown = async () => {
+    try {
+        await closeAllPools();
+    }
+    finally {
+        process.exit(0);
+    }
+};
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+main().catch((err) => {
+    console.error("[ssms-mcp] fatal:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "ssms-mcp",
+  "version": "0.2.0",
+  "description": "Model Context Protocol (MCP) server that executes SQL queries against Microsoft SQL Server (SSMS-compatible).",
+  "license": "MIT",
+  "author": "",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "ssms-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ssms",
+    "sql-server",
+    "mssql",
+    "tsql",
+    "database",
+    "ai",
+    "llm"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@azure/identity": "^4.4.1",
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "mssql": "^11.0.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/mssql": "^9.1.5",
+    "@types/node": "^20.11.30",
+    "typescript": "^5.4.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}