mssql-mcp 2.1.1 → 2.3.0

package/dist/src/resources/metadata.js

@@ -0,0 +1,58 @@
+import { getPool } from "../db/connection.js";
+function notConnectedText() {
+    return JSON.stringify({ error: "Not connected. Use connect_database first." });
+}
+export function registerMetadataResources(server) {
+    server.registerResource("databases", "mssql://databases", {
+        title: "Databases",
+        description: "Snapshot list of all databases on the SQL Server instance.",
+        mimeType: "application/json",
+    }, async () => {
+        const pool = getPool();
+        if (!pool?.connected) {
+            return {
+                contents: [
+                    { uri: "mssql://databases", text: notConnectedText(), mimeType: "application/json" },
+                ],
+            };
+        }
+        const result = await pool
+            .request()
+            .query(`SELECT name, state_desc FROM sys.databases ORDER BY name`);
+        return {
+            contents: [
+                {
+                    uri: "mssql://databases",
+                    text: JSON.stringify(result.recordset, null, 2),
+                    mimeType: "application/json",
+                },
+            ],
+        };
+    });
+    server.registerResource("schemas", "mssql://schemas", {
+        title: "Schemas",
+        description: "Snapshot list of all schemas in the current database.",
+        mimeType: "application/json",
+    }, async () => {
+        const pool = getPool();
+        if (!pool?.connected) {
+            return {
+                contents: [
+                    { uri: "mssql://schemas", text: notConnectedText(), mimeType: "application/json" },
+                ],
+            };
+        }
+        const result = await pool
+            .request()
+            .query(`SELECT SCHEMA_NAME, SCHEMA_OWNER FROM INFORMATION_SCHEMA.SCHEMATA ORDER BY SCHEMA_NAME`);
+        return {
+            contents: [
+                {
+                    uri: "mssql://schemas",
+                    text: JSON.stringify(result.recordset, null, 2),
+                    mimeType: "application/json",
+                },
+            ],
+        };
+    });
+}

package/dist/src/schemas/outputs.d.ts

@@ -0,0 +1,153 @@
+import { z } from "zod";
+export declare const PaginationSchema: z.ZodObject<{
+    count: z.ZodNumber;
+    limit: z.ZodNumber;
+    offset: z.ZodNumber;
+    has_more: z.ZodBoolean;
+    next_offset: z.ZodNullable<z.ZodNumber>;
+    total_count: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    count: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+    next_offset: number | null;
+    total_count?: number | undefined;
+}, {
+    count: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+    next_offset: number | null;
+    total_count?: number | undefined;
+}>;
+export declare const ConnectionStateSchema: z.ZodObject<{
+    connected: z.ZodBoolean;
+    config: z.ZodNullable<z.ZodObject<{
+        server: z.ZodString;
+        database: z.ZodOptional<z.ZodString>;
+        port: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        server: string;
+        port: number;
+        database?: string | undefined;
+    }, {
+        server: string;
+        port: number;
+        database?: string | undefined;
+    }>>;
+    pool_info: z.ZodNullable<z.ZodObject<{
+        size: z.ZodNumber;
+        available: z.ZodNumber;
+        pending: z.ZodNumber;
+        borrowed: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        size: number;
+        available: number;
+        pending: number;
+        borrowed: number;
+    }, {
+        size: number;
+        available: number;
+        pending: number;
+        borrowed: number;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    connected: boolean;
+    config: {
+        server: string;
+        port: number;
+        database?: string | undefined;
+    } | null;
+    pool_info: {
+        size: number;
+        available: number;
+        pending: number;
+        borrowed: number;
+    } | null;
+}, {
+    connected: boolean;
+    config: {
+        server: string;
+        port: number;
+        database?: string | undefined;
+    } | null;
+    pool_info: {
+        size: number;
+        available: number;
+        pending: number;
+        borrowed: number;
+    } | null;
+}>;
+export declare const ColumnInfoSchema: z.ZodObject<{
+    COLUMN_NAME: z.ZodString;
+    DATA_TYPE: z.ZodString;
+    CHARACTER_MAXIMUM_LENGTH: z.ZodNullable<z.ZodNumber>;
+    NUMERIC_PRECISION: z.ZodNullable<z.ZodNumber>;
+    NUMERIC_SCALE: z.ZodNullable<z.ZodNumber>;
+    IS_NULLABLE: z.ZodString;
+    COLUMN_DEFAULT: z.ZodNullable<z.ZodString>;
+    ORDINAL_POSITION: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    COLUMN_NAME: string;
+    DATA_TYPE: string;
+    CHARACTER_MAXIMUM_LENGTH: number | null;
+    NUMERIC_PRECISION: number | null;
+    NUMERIC_SCALE: number | null;
+    IS_NULLABLE: string;
+    COLUMN_DEFAULT: string | null;
+    ORDINAL_POSITION: number;
+}, {
+    COLUMN_NAME: string;
+    DATA_TYPE: string;
+    CHARACTER_MAXIMUM_LENGTH: number | null;
+    NUMERIC_PRECISION: number | null;
+    NUMERIC_SCALE: number | null;
+    IS_NULLABLE: string;
+    COLUMN_DEFAULT: string | null;
+    ORDINAL_POSITION: number;
+}>;
+export declare const SchemaObjectSchema: z.ZodObject<{
+    TABLE_SCHEMA: z.ZodString;
+    TABLE_NAME: z.ZodString;
+    TABLE_TYPE: z.ZodString;
+    OBJECT_TYPE: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    TABLE_SCHEMA: string;
+    TABLE_NAME: string;
+    TABLE_TYPE: string;
+    OBJECT_TYPE: string;
+}, {
+    TABLE_SCHEMA: string;
+    TABLE_NAME: string;
+    TABLE_TYPE: string;
+    OBJECT_TYPE: string;
+}>;
+export declare const DatabaseInfoSchema: z.ZodObject<{
+    name: z.ZodString;
+    database_id: z.ZodNumber;
+    create_date: z.ZodUnknown;
+    collation_name: z.ZodNullable<z.ZodString>;
+    state_desc: z.ZodString;
+    user_access_desc: z.ZodString;
+    is_read_only: z.ZodBoolean;
+    recovery_model_desc: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    database_id: number;
+    collation_name: string | null;
+    state_desc: string;
+    user_access_desc: string;
+    is_read_only: boolean;
+    recovery_model_desc: string;
+    create_date?: unknown;
+}, {
+    name: string;
+    database_id: number;
+    collation_name: string | null;
+    state_desc: string;
+    user_access_desc: string;
+    is_read_only: boolean;
+    recovery_model_desc: string;
+    create_date?: unknown;
+}>;

package/dist/src/schemas/outputs.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+export const PaginationSchema = z.object({
+    count: z.number(),
+    limit: z.number(),
+    offset: z.number(),
+    has_more: z.boolean(),
+    next_offset: z.number().nullable(),
+    total_count: z.number().optional(),
+});
+export const ConnectionStateSchema = z.object({
+    connected: z.boolean(),
+    config: z
+        .object({
+        server: z.string(),
+        database: z.string().optional(),
+        port: z.number(),
+    })
+        .nullable(),
+    pool_info: z
+        .object({
+        size: z.number(),
+        available: z.number(),
+        pending: z.number(),
+        borrowed: z.number(),
+    })
+        .nullable(),
+});
+export const ColumnInfoSchema = z.object({
+    COLUMN_NAME: z.string(),
+    DATA_TYPE: z.string(),
+    CHARACTER_MAXIMUM_LENGTH: z.number().nullable(),
+    NUMERIC_PRECISION: z.number().nullable(),
+    NUMERIC_SCALE: z.number().nullable(),
+    IS_NULLABLE: z.string(),
+    COLUMN_DEFAULT: z.string().nullable(),
+    ORDINAL_POSITION: z.number(),
+});
+export const SchemaObjectSchema = z.object({
+    TABLE_SCHEMA: z.string(),
+    TABLE_NAME: z.string(),
+    TABLE_TYPE: z.string(),
+    OBJECT_TYPE: z.string(),
+});
+// create_date is a JS Date from mssql; z.unknown() avoids type mismatch after JSON serialization.
+export const DatabaseInfoSchema = z.object({
+    name: z.string(),
+    database_id: z.number(),
+    create_date: z.unknown(),
+    collation_name: z.string().nullable(),
+    state_desc: z.string(),
+    user_access_desc: z.string(),
+    is_read_only: z.boolean(),
+    recovery_model_desc: z.string(),
+});

package/dist/src/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/src/server.js

@@ -0,0 +1,27 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SERVER_NAME, SERVER_VERSION } from "./constants.js";
+import { registerConnectTools } from "./tools/connect.js";
+import { registerStatusTool } from "./tools/status.js";
+import { registerQueryTools } from "./tools/query.js";
+import { registerSchemaTools } from "./tools/schema.js";
+import { registerTableTools } from "./tools/table.js";
+import { registerProcedureTools } from "./tools/procedure.js";
+import { registerDatabasesTools } from "./tools/databases.js";
+import { registerConnectionResource } from "./resources/connection.js";
+import { registerMetadataResources } from "./resources/metadata.js";
+export function createServer() {
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    });
+    registerConnectTools(server);
+    registerStatusTool(server);
+    registerQueryTools(server);
+    registerSchemaTools(server);
+    registerTableTools(server);
+    registerProcedureTools(server);
+    registerDatabasesTools(server);
+    registerConnectionResource(server);
+    registerMetadataResources(server);
+    return server;
+}

package/dist/src/tools/connect.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerConnectTools(server: McpServer): void;

package/dist/src/tools/connect.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { loadConfigFromEnv } from "../config.js";
+import { connectPool, disconnectPool, getConnectionState } from "../db/connection.js";
+import { toActionableError, toolError, toolSuccess } from "../utils/errors.js";
+import { ConnectionStateSchema } from "../schemas/outputs.js";
+export function registerConnectTools(server) {
+    server.registerTool("mssql_connect_database", {
+        title: "Connect Database",
+        description: "Connects to MS SQL Server using environment variables (DB_SERVER, DB_DATABASE, DB_USER, DB_PASSWORD, " +
+            "DB_PORT, DB_ENCRYPT, DB_TRUST_SERVER_CERTIFICATE). No credentials accepted as parameters — all " +
+            "connection settings come from the server environment only. Idempotent: calling again reconnects.",
+        inputSchema: {},
+        outputSchema: ConnectionStateSchema,
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false },
+    }, async () => {
+        try {
+            const config = loadConfigFromEnv();
+            await connectPool(config);
+            const state = getConnectionState();
+            return toolSuccess(`✅ Connected to ${config.server}${config.database ? ` (database: ${config.database})` : ""}`, state);
+        }
+        catch (err) {
+            const msg = toActionableError(err);
+            console.error("mssql_connect_database failed:", msg);
+            return toolError(`Connection failed: ${msg}`);
+        }
+    });
+    server.registerTool("mssql_disconnect_database", {
+        title: "Disconnect Database",
+        description: "Closes the current database connection and releases the connection pool. " +
+            "Safe to call even if not connected. Idempotent.",
+        inputSchema: {},
+        outputSchema: { message: z.string() },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false },
+    }, async () => {
+        try {
+            await disconnectPool();
+            const msg = "✅ Disconnected from database.";
+            return toolSuccess(msg, { message: msg });
+        }
+        catch (err) {
+            return toolError(`Disconnect failed: ${toActionableError(err)}`);
+        }
+    });
+}

package/dist/src/tools/databases.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDatabasesTools(server: McpServer): void;

package/dist/src/tools/databases.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { requirePool } from "../db/connection.js";
+import { toActionableError, toolError, toolSuccess } from "../utils/errors.js";
+import { formatJson } from "../utils/format.js";
+import { formatMarkdownTable } from "../utils/markdown.js";
+import { buildPaginationMeta, clampLimit } from "../utils/pagination.js";
+import { PaginationSchema, DatabaseInfoSchema } from "../schemas/outputs.js";
+export function registerDatabasesTools(server) {
+    server.registerTool("mssql_list_databases", {
+        title: "List Databases",
+        description: "Lists all databases visible on the connected SQL Server instance with state and recovery information. " +
+            "Read-only. Supports pagination.",
+        inputSchema: {
+            limit: z.number().int().min(1).max(200).optional().default(20).describe("Max databases (default 20)"),
+            offset: z.number().int().min(0).optional().default(0).describe("Skip N databases"),
+            response_format: z
+                .enum(["json", "markdown"])
+                .optional()
+                .default("json")
+                .describe("Output format: 'json' for structured data, 'markdown' for human-readable table"),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+        outputSchema: { databases: z.array(DatabaseInfoSchema), pagination: PaginationSchema },
+    }, async ({ limit: rawLimit, offset, response_format }) => {
+        try {
+            const pool = requirePool();
+            const limit = clampLimit(rawLimit);
+            const result = await pool.request().query(`
+          SELECT name, database_id, create_date, collation_name,
+                 state_desc, user_access_desc, is_read_only,
+                 recovery_model_desc
+          FROM sys.databases
+          ORDER BY name
+        `);
+            const allRows = result.recordset ?? [];
+            const page = allRows.slice(offset, offset + limit);
+            const pagination = buildPaginationMeta(page.length, limit, offset, allRows.length);
+            const structured = { databases: page, pagination };
+            if (response_format === "markdown") {
+                const rows = page;
+                let text = formatMarkdownTable(rows, "Databases");
+                text += `\n\n*Showing ${page.length} of ${allRows.length} databases*`;
+                return toolSuccess(text, structured);
+            }
+            return toolSuccess(formatJson(structured), structured);
+        }
+        catch (err) {
+            const msg = toActionableError(err);
+            console.error("mssql_list_databases failed:", msg);
+            return toolError(`List databases failed: ${msg}`);
+        }
+    });
+}

package/dist/src/tools/procedure.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerProcedureTools(server: McpServer): void;

package/dist/src/tools/procedure.js

@@ -0,0 +1,106 @@
+import { z } from "zod";
+import { requirePool } from "../db/connection.js";
+import { validateIdentifier, bracketIdentifier } from "../db/validators.js";
+import { toActionableError, toolError, toolSuccess } from "../utils/errors.js";
+import { formatJson } from "../utils/format.js";
+import { formatMarkdownMultiRecordsets } from "../utils/markdown.js";
+const ProcedureOutputSchema = {
+    recordsets: z.array(z.array(z.record(z.unknown()))),
+    rows_affected: z.array(z.number()),
+    output: z.record(z.unknown()),
+    return_value: z.unknown(),
+};
+export function registerProcedureTools(server) {
+    server.registerTool("mssql_execute_stored_procedure", {
+        title: "Execute Stored Procedure",
+        description: "Executes a stored procedure by name. " +
+            "⚠️ May modify data — use only when an action is intended. " +
+            "Schema and procedure names are validated as safe identifiers. " +
+            "Pass all value parameters via 'parameters'.",
+        inputSchema: {
+            procedureName: z.string().min(1).describe("Stored procedure name"),
+            schemaName: z.string().optional().default("dbo").describe("Schema name (default: dbo)"),
+            parameters: z
+                .record(z.union([z.string(), z.number(), z.boolean(), z.null()]))
+                .optional()
+                .describe("Procedure input parameters (key-value pairs)"),
+            response_format: z
+                .enum(["json", "markdown"])
+                .optional()
+                .default("json")
+                .describe("Output format: 'json' for structured data, 'markdown' for human-readable tables"),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true },
+        outputSchema: ProcedureOutputSchema,
+    }, async ({ procedureName, schemaName, parameters, response_format }) => {
+        try {
+            const pool = requirePool();
+            validateIdentifier(procedureName, "procedure name");
+            validateIdentifier(schemaName, "schema name");
+            const qualifiedName = `${bracketIdentifier(schemaName)}.${bracketIdentifier(procedureName)}`;
+            const request = pool.request();
+            if (parameters) {
+                for (const [key, value] of Object.entries(parameters)) {
+                    request.input(key, value);
+                }
+            }
+            const result = await request.execute(qualifiedName);
+            const structured = {
+                recordsets: result.recordsets,
+                rows_affected: result.rowsAffected,
+                output: result.output,
+                return_value: result.returnValue,
+            };
+            if (response_format === "markdown") {
+                return toolSuccess(formatMarkdownMultiRecordsets(result.recordsets, qualifiedName), structured);
+            }
+            return toolSuccess(formatJson(structured), structured);
+        }
+        catch (err) {
+            const msg = toActionableError(err);
+            console.error("mssql_execute_stored_procedure failed:", msg);
+            return toolError(`Procedure execution failed: ${msg}`);
+        }
+    });
+    // Backward-compatible alias
+    server.registerTool("mssql_execute_procedure", {
+        title: "Execute Procedure (deprecated — use mssql_execute_stored_procedure)",
+        description: "Deprecated alias for mssql_execute_stored_procedure.",
+        inputSchema: {
+            procedureName: z.string().describe("Name of the stored procedure"),
+            schemaName: z.string().optional().default("dbo"),
+            parameters: z
+                .record(z.union([z.string(), z.number(), z.boolean(), z.null()]))
+                .optional(),
+            response_format: z.enum(["json", "markdown"]).optional().default("json"),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true },
+    }, async ({ procedureName, schemaName, parameters, response_format }) => {
+        try {
+            const pool = requirePool();
+            validateIdentifier(procedureName, "procedure name");
+            validateIdentifier(schemaName, "schema name");
+            const qualifiedName = `${bracketIdentifier(schemaName)}.${bracketIdentifier(procedureName)}`;
+            const request = pool.request();
+            if (parameters) {
+                for (const [key, value] of Object.entries(parameters)) {
+                    request.input(key, value);
+                }
+            }
+            const result = await request.execute(qualifiedName);
+            const structured = {
+                recordsets: result.recordsets,
+                rowsAffected: result.rowsAffected,
+                output: result.output,
+                returnValue: result.returnValue,
+            };
+            if (response_format === "markdown") {
+                return toolSuccess(formatMarkdownMultiRecordsets(result.recordsets));
+            }
+            return toolSuccess(formatJson(structured), structured);
+        }
+        catch (err) {
+            return toolError(`Procedure execution failed: ${toActionableError(err)}`);
+        }
+    });
+}

package/dist/src/tools/query.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerQueryTools(server: McpServer): void;

package/dist/src/tools/query.js

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { requirePool } from "../db/connection.js";
+import { toActionableError, toolError, toolSuccess } from "../utils/errors.js";
+import { formatJson, truncatePayload } from "../utils/format.js";
+import { formatMarkdownTable } from "../utils/markdown.js";
+const QueryOutputSchema = {
+    recordset: z.array(z.record(z.unknown())),
+    rows_affected: z.array(z.number()),
+    output: z.record(z.unknown()),
+    execution_time_ms: z.number(),
+    parameters_used: z.number(),
+    truncated: z.boolean(),
+    truncation_message: z.string().optional(),
+};
+async function runSqlQueryCore(query, parameters, response_format, logLabel) {
+    try {
+        const pool = requirePool();
+        const request = pool.request();
+        if (parameters) {
+            for (const [key, value] of Object.entries(parameters)) {
+                request.input(key, value);
+            }
+        }
+        const start = Date.now();
+        const result = await request.query(query);
+        const elapsed = Date.now() - start;
+        const { data, truncated, truncation_message } = truncatePayload(result.recordset ?? []);
+        const structured = {
+            recordset: data,
+            rows_affected: result.rowsAffected,
+            output: result.output,
+            execution_time_ms: elapsed,
+            parameters_used: parameters ? Object.keys(parameters).length : 0,
+            truncated,
+        };
+        if (truncation_message)
+            structured.truncation_message = truncation_message;
+        if (response_format === "markdown") {
+            const rows = data;
+            let text = formatMarkdownTable(rows);
+            if (truncated)
+                text += `\n\n> ⚠️ ${truncation_message}`;
+            text += `\n\n*Rows affected: ${(result.rowsAffected ?? []).join(", ")} · ${elapsed}ms*`;
+            return toolSuccess(text, structured);
+        }
+        return toolSuccess(formatJson(structured), structured);
+    }
+    catch (err) {
+        const msg = toActionableError(err);
+        console.error(`${logLabel} failed:`, msg);
+        return toolError(`Query failed: ${msg}`);
+    }
+}
+export function registerQueryTools(server) {
+    server.registerTool("mssql_run_sql_query", {
+        title: "Run SQL Query",
+        description: "Executes an arbitrary SQL statement against the connected database. " +
+            "⚠️ WARNING: This tool can read AND modify data (INSERT, UPDATE, DELETE, DDL). " +
+            "Always prefer parameterized inputs via the 'parameters' field — never embed user-supplied values " +
+            "directly in the query string. " +
+            "Example: query='SELECT * FROM dbo.Users WHERE Id = @id', parameters={id: 42}",
+        inputSchema: {
+            query: z.string().min(1).describe("SQL statement to execute"),
+            parameters: z
+                .record(z.union([z.string(), z.number(), z.boolean(), z.null()]))
+                .optional()
+                .describe("Named parameters referenced in the query via @paramName"),
+            response_format: z
+                .enum(["json", "markdown"])
+                .optional()
+                .default("json")
+                .describe("Output format: 'json' for structured data, 'markdown' for human-readable table"),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true },
+        outputSchema: QueryOutputSchema,
+    }, ({ query, parameters, response_format }) => runSqlQueryCore(query, parameters, response_format, "mssql_run_sql_query"));
+    // Backward-compatible alias
+    server.registerTool("mssql_execute_query", {
+        title: "Execute Query (deprecated — use mssql_run_sql_query)",
+        description: "Deprecated alias for mssql_run_sql_query. Use mssql_run_sql_query instead. " +
+            "⚠️ This tool can read AND modify data.",
+        inputSchema: {
+            query: z.string().min(1).describe("SQL query to execute"),
+            parameters: z
+                .record(z.union([z.string(), z.number(), z.boolean(), z.null()]))
+                .optional()
+                .describe("Query parameters"),
+            response_format: z.enum(["json", "markdown"]).optional().default("json"),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: false, openWorldHint: true },
+    }, ({ query, parameters, response_format }) => runSqlQueryCore(query, parameters, response_format, "mssql_execute_query"));
+}

package/dist/src/tools/schema.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSchemaTools(server: McpServer): void;