mssql-mcp 2.1.1 → 2.3.1

package/dist/src/tools/schema.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import sql from "mssql";
+import { requirePool } from "../db/connection.js";
+import { buildSchemaObjectsQuery } from "../db/query-builders.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, SchemaObjectSchema } from "../schemas/outputs.js";
+export function registerSchemaTools(server) {
+    server.registerTool("mssql_list_schema_objects", {
+        title: "List Schema Objects",
+        description: "Lists tables, views, stored procedures, or functions in the connected database. " +
+            "Read-only. Supports filtering by schema name and pagination. " +
+            "Example: objectType='tables', schemaName='dbo', limit=20",
+        inputSchema: {
+            objectType: z
+                .enum(["tables", "views", "procedures", "functions", "all"])
+                .optional()
+                .default("tables")
+                .describe("Type of objects to list (default: tables)"),
+            schemaName: z
+                .string()
+                .optional()
+                .describe("Filter to a specific schema (e.g. 'dbo')"),
+            limit: z.number().int().min(1).max(200).optional().default(20).describe("Max objects (default 20)"),
+            offset: z.number().int().min(0).optional().default(0).describe("Skip N objects"),
+            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: { objects: z.array(SchemaObjectSchema), pagination: PaginationSchema },
+    }, async ({ objectType, schemaName, limit: rawLimit, offset, response_format }) => {
+        try {
+            const pool = requirePool();
+            const limit = clampLimit(rawLimit);
+            const query = buildSchemaObjectsQuery(objectType, schemaName);
+            const request = pool.request();
+            if (schemaName) {
+                request.input("schemaName", sql.VarChar, schemaName);
+            }
+            const result = await request.query(query);
+            const allRows = result.recordset ?? [];
+            const page = allRows.slice(offset, offset + limit);
+            const pagination = buildPaginationMeta(page.length, limit, offset, allRows.length);
+            const structured = { objects: page, pagination };
+            if (response_format === "markdown") {
+                const rows = page;
+                let text = formatMarkdownTable(rows, `Schema Objects (${objectType})`);
+                text += `\n\n*Showing ${page.length} of ${allRows.length} · offset ${offset}*`;
+                return toolSuccess(text, structured);
+            }
+            return toolSuccess(formatJson(structured), structured);
+        }
+        catch (err) {
+            const msg = toActionableError(err);
+            console.error("mssql_list_schema_objects failed:", msg);
+            return toolError(`Schema query failed: ${msg}`);
+        }
+    });
+    // Backward-compatible alias
+    server.registerTool("mssql_get_schema", {
+        title: "Get Schema (deprecated — use mssql_list_schema_objects)",
+        description: "Deprecated alias for mssql_list_schema_objects. Use mssql_list_schema_objects instead.",
+        inputSchema: {
+            objectType: z
+                .enum(["tables", "views", "procedures", "functions", "all"])
+                .optional()
+                .default("tables"),
+            schemaName: z.string().optional(),
+            response_format: z.enum(["json", "markdown"]).optional().default("json"),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    }, async ({ objectType, schemaName, response_format }) => {
+        try {
+            const pool = requirePool();
+            const query = buildSchemaObjectsQuery(objectType, schemaName);
+            const request = pool.request();
+            if (schemaName) {
+                request.input("schemaName", sql.VarChar, schemaName);
+            }
+            const result = await request.query(query);
+            const rows = result.recordset ?? [];
+            if (response_format === "markdown") {
+                return toolSuccess(formatMarkdownTable(rows));
+            }
+            return toolSuccess(formatJson(rows));
+        }
+        catch (err) {
+            return toolError(`Schema query failed: ${toActionableError(err)}`);
+        }
+    });
+}

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

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

package/dist/src/tools/status.js

@@ -0,0 +1,17 @@
+import { getConnectionState } from "../db/connection.js";
+import { toolSuccess } from "../utils/errors.js";
+import { formatJson } from "../utils/format.js";
+import { ConnectionStateSchema } from "../schemas/outputs.js";
+export function registerStatusTool(server) {
+    server.registerTool("mssql_connection_status", {
+        title: "Connection Status",
+        description: "Returns the current connection status, server address, database name, and connection pool metrics. " +
+            "Read-only. Safe to call at any time.",
+        inputSchema: {},
+        outputSchema: ConnectionStateSchema,
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    }, async () => {
+        const state = getConnectionState();
+        return toolSuccess(formatJson(state), state);
+    });
+}

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

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

package/dist/src/tools/table.js

@@ -0,0 +1,261 @@
+import { z } from "zod";
+import sql from "mssql";
+import { requirePool } from "../db/connection.js";
+import { validateIdentifier, validateOrderBy, SAFE_IDENTIFIER_RE } from "../db/validators.js";
+import { buildSelectQuery, buildSelectWithWhereQuery } from "../db/query-builders.js";
+import { toActionableError, toolError, toolSuccess } from "../utils/errors.js";
+import { formatJson, truncatePayload } from "../utils/format.js";
+import { formatMarkdownTable } from "../utils/markdown.js";
+import { buildPaginationMeta, clampLimit } from "../utils/pagination.js";
+import { PaginationSchema, ColumnInfoSchema } from "../schemas/outputs.js";
+export function registerTableTools(server) {
+    server.registerTool("mssql_describe_table_columns", {
+        title: "Describe Table Columns",
+        description: "Returns column definitions for a table: name, data type, length, nullability, default, and ordinal position. " +
+            "Read-only. Uses parameterized queries to prevent injection.",
+        inputSchema: {
+            tableName: z.string().min(1).describe("Table name"),
+            schemaName: z.string().optional().default("dbo").describe("Schema name (default: dbo)"),
+            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: { columns: z.array(ColumnInfoSchema), table: z.string() },
+    }, async ({ tableName, schemaName, response_format }) => {
+        try {
+            const pool = requirePool();
+            validateIdentifier(tableName, "table name");
+            validateIdentifier(schemaName, "schema name");
+            const result = await pool
+                .request()
+                .input("tableName", sql.VarChar, tableName)
+                .input("schemaName", sql.VarChar, schemaName)
+                .query(`
+            SELECT COLUMN_NAME, DATA_TYPE, CHARACTER_MAXIMUM_LENGTH,
+              NUMERIC_PRECISION, NUMERIC_SCALE, IS_NULLABLE,
+              COLUMN_DEFAULT, ORDINAL_POSITION
+            FROM INFORMATION_SCHEMA.COLUMNS
+            WHERE TABLE_NAME = @tableName AND TABLE_SCHEMA = @schemaName
+            ORDER BY ORDINAL_POSITION
+          `);
+            const structured = {
+                columns: result.recordset,
+                table: `${schemaName}.${tableName}`,
+            };
+            if (response_format === "markdown") {
+                const rows = result.recordset;
+                return toolSuccess(formatMarkdownTable(rows, `Columns: ${schemaName}.${tableName}`), structured);
+            }
+            return toolSuccess(formatJson(structured), structured);
+        }
+        catch (err) {
+            const msg = toActionableError(err);
+            console.error("mssql_describe_table_columns failed:", msg);
+            return toolError(`Table description failed: ${msg}`);
+        }
+    });
+    // Backward-compatible alias
+    server.registerTool("mssql_describe_table", {
+        title: "Describe Table (deprecated — use mssql_describe_table_columns)",
+        description: "Deprecated alias for mssql_describe_table_columns.",
+        inputSchema: {
+            tableName: z.string().min(1),
+            schemaName: z.string().optional().default("dbo"),
+            response_format: z.enum(["json", "markdown"]).optional().default("json"),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    }, async ({ tableName, schemaName, response_format }) => {
+        try {
+            const pool = requirePool();
+            validateIdentifier(tableName, "table name");
+            validateIdentifier(schemaName, "schema name");
+            const result = await pool
+                .request()
+                .input("tableName", sql.VarChar, tableName)
+                .input("schemaName", sql.VarChar, schemaName)
+                .query(`
+            SELECT COLUMN_NAME, DATA_TYPE, CHARACTER_MAXIMUM_LENGTH,
+              NUMERIC_PRECISION, NUMERIC_SCALE, IS_NULLABLE,
+              COLUMN_DEFAULT, ORDINAL_POSITION
+            FROM INFORMATION_SCHEMA.COLUMNS
+            WHERE TABLE_NAME = @tableName AND TABLE_SCHEMA = @schemaName
+            ORDER BY ORDINAL_POSITION
+          `);
+            const rows = result.recordset ?? [];
+            if (response_format === "markdown") {
+                return toolSuccess(formatMarkdownTable(rows));
+            }
+            return toolSuccess(formatJson(rows));
+        }
+        catch (err) {
+            return toolError(`Table description failed: ${toActionableError(err)}`);
+        }
+    });
+    const safeIdentifierPattern = SAFE_IDENTIFIER_RE;
+    server.registerTool("mssql_read_table_rows", {
+        title: "Read Table Rows",
+        description: "Returns rows from a table with optional column projection, WHERE filtering, ORDER BY, and pagination. " +
+            "Read-only. Table and schema names are validated as safe identifiers. " +
+            "WHERE clause values MUST be passed via 'parameters' using @paramName placeholders. " +
+            "Pagination: limit (1-200, default 20) and offset. " +
+            "Example: tableName='Orders', schemaName='dbo', columns=['OrderId','Total'], limit=50",
+        inputSchema: {
+            tableName: z
+                .string()
+                .min(1)
+                .regex(safeIdentifierPattern, "Must be a valid SQL identifier")
+                .describe("Table name"),
+            schemaName: z
+                .string()
+                .regex(safeIdentifierPattern, "Must be a valid SQL identifier")
+                .optional()
+                .default("dbo")
+                .describe("Schema name (default: dbo)"),
+            columns: z
+                .array(z.string().regex(safeIdentifierPattern))
+                .optional()
+                .describe("Columns to return (default: all)"),
+            limit: z.number().int().min(1).max(200).optional().default(20).describe("Max rows (1-200)"),
+            offset: z.number().int().min(0).optional().default(0).describe("Rows to skip"),
+            whereClause: z
+                .string()
+                .optional()
+                .describe("WHERE predicate without WHERE keyword. Use @paramName for all values. " +
+                "Example: 'Status = @status AND Amount > @minAmount'"),
+            orderBy: z
+                .string()
+                .optional()
+                .describe("ORDER BY expression. Example: 'CreatedAt DESC, Id ASC'"),
+            parameters: z
+                .record(z.union([z.string(), z.number(), z.boolean(), z.null()]))
+                .optional()
+                .describe("Values for WHERE clause @paramName placeholders"),
+            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: {
+            data: z.array(z.record(z.unknown())),
+            pagination: PaginationSchema,
+            table: z.string(),
+            execution_time_ms: z.number(),
+            truncated: z.boolean().optional(),
+            truncation_message: z.string().optional(),
+        },
+    }, async ({ tableName, schemaName, columns, limit: rawLimit, offset, whereClause, orderBy, parameters, response_format }) => {
+        try {
+            const pool = requirePool();
+            validateIdentifier(tableName, "table name");
+            validateIdentifier(schemaName, "schema name");
+            const limit = clampLimit(rawLimit);
+            const safeOrderBy = orderBy ? validateOrderBy(orderBy) : null;
+            const query = whereClause
+                ? buildSelectWithWhereQuery(schemaName, tableName, columns ?? null, whereClause, safeOrderBy, offset, limit)
+                : buildSelectQuery(schemaName, tableName, columns ?? null, safeOrderBy, offset, limit);
+            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 pagination = buildPaginationMeta(data.length, limit, offset);
+            const structured = {
+                data,
+                pagination,
+                table: `${schemaName}.${tableName}`,
+                execution_time_ms: elapsed,
+            };
+            if (truncated) {
+                structured.truncated = truncated;
+                structured.truncation_message = truncation_message;
+            }
+            if (response_format === "markdown") {
+                const rows = data;
+                let text = formatMarkdownTable(rows, `${schemaName}.${tableName}`);
+                if (truncated)
+                    text += `\n\n> ⚠️ ${truncation_message}`;
+                text += `\n\n*${rows.length} rows · offset ${offset} · ${elapsed}ms*`;
+                return toolSuccess(text, structured);
+            }
+            return toolSuccess(formatJson(structured), structured);
+        }
+        catch (err) {
+            const msg = toActionableError(err);
+            console.error("mssql_read_table_rows failed:", msg);
+            return toolError(`Read table rows failed: ${msg}`);
+        }
+    });
+    // Backward-compatible alias
+    server.registerTool("mssql_get_table_data", {
+        title: "Get Table Data (deprecated — use mssql_read_table_rows)",
+        description: "Deprecated alias for mssql_read_table_rows. Use mssql_read_table_rows instead. " +
+            "⚠️ whereClause must use @paramName placeholders for all values.",
+        inputSchema: {
+            tableName: z
+                .string()
+                .min(1)
+                .regex(SAFE_IDENTIFIER_RE, "Must be a valid SQL identifier"),
+            schemaName: z
+                .string()
+                .regex(SAFE_IDENTIFIER_RE, "Must be a valid SQL identifier")
+                .optional()
+                .default("dbo"),
+            limit: z.number().int().min(1).max(200).optional().default(20),
+            offset: z.number().int().min(0).optional().default(0),
+            whereClause: z.string().optional(),
+            orderBy: z.string().optional(),
+            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: true, idempotentHint: true, openWorldHint: false },
+    }, async ({ tableName, schemaName, limit: rawLimit, offset, whereClause, orderBy, parameters, response_format }) => {
+        try {
+            const pool = requirePool();
+            validateIdentifier(tableName, "table name");
+            validateIdentifier(schemaName, "schema name");
+            const limit = clampLimit(rawLimit);
+            const safeOrderBy = orderBy ? validateOrderBy(orderBy) : null;
+            const query = whereClause
+                ? buildSelectWithWhereQuery(schemaName, tableName, null, whereClause, safeOrderBy, offset, limit)
+                : buildSelectQuery(schemaName, tableName, null, safeOrderBy, offset, limit);
+            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 pagination = buildPaginationMeta(data.length, limit, offset);
+            const structured = {
+                data,
+                metadata: { ...pagination, execution_time_ms: elapsed, table: `${schemaName}.${tableName}` },
+            };
+            if (truncated) {
+                structured.truncated = truncated;
+                structured.truncation_message = truncation_message;
+            }
+            if (response_format === "markdown") {
+                return toolSuccess(formatMarkdownTable(data));
+            }
+            return toolSuccess(formatJson(structured), structured);
+        }
+        catch (err) {
+            return toolError(`Get table data failed: ${toActionableError(err)}`);
+        }
+    });
+}

package/dist/src/transports/http.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { HttpConfig } from "../config.js";
+export declare function runHttpTransport(server: McpServer, config: HttpConfig): Promise<void>;

package/dist/src/transports/http.js

@@ -0,0 +1,54 @@
+import { createServer } from "node:http";
+import { randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { closePoolOnShutdown } from "../db/connection.js";
+export async function runHttpTransport(server, config) {
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+    });
+    const httpServer = createServer((req, res) => {
+        // Origin validation: only allow localhost by default
+        const origin = req.headers["origin"];
+        if (origin) {
+            const allowed = [
+                "http://localhost",
+                "http://127.0.0.1",
+                `http://${config.host}`,
+                `http://${config.host}:${config.port}`,
+            ];
+            const isAllowed = allowed.some((o) => origin.startsWith(o));
+            if (!isAllowed) {
+                res.writeHead(403, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Forbidden: origin not allowed" }));
+                return;
+            }
+        }
+        transport.handleRequest(req, res);
+    });
+    const shutdown = async (signal) => {
+        console.error(`\nShutting down HTTP server (${signal})...`);
+        httpServer.close();
+        await transport.close();
+        await closePoolOnShutdown();
+        process.exit(0);
+    };
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    process.on("SIGUSR2", () => shutdown("SIGUSR2"));
+    process.on("uncaughtException", (err) => {
+        console.error("Uncaught exception:", err);
+        shutdown("uncaughtException");
+    });
+    process.on("unhandledRejection", (reason) => {
+        console.error("Unhandled rejection:", reason);
+        shutdown("unhandledRejection");
+    });
+    await server.connect(transport);
+    await new Promise((resolve, reject) => {
+        httpServer.listen(config.port, config.host, () => {
+            console.error(`MCP HTTP server listening on http://${config.host}:${config.port}`);
+            resolve();
+        });
+        httpServer.on("error", reject);
+    });
+}

package/dist/src/transports/stdio.d.ts

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

package/dist/src/transports/stdio.js

@@ -0,0 +1,23 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { closePoolOnShutdown } from "../db/connection.js";
+export async function runStdioTransport(server) {
+    const transport = new StdioServerTransport();
+    const shutdown = async (signal) => {
+        console.error(`\nShutting down (${signal})...`);
+        await closePoolOnShutdown();
+        console.error("Server stopped.");
+        process.exit(0);
+    };
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    process.on("SIGUSR2", () => shutdown("SIGUSR2"));
+    process.on("uncaughtException", (err) => {
+        console.error("Uncaught exception:", err);
+        shutdown("uncaughtException");
+    });
+    process.on("unhandledRejection", (reason) => {
+        console.error("Unhandled rejection:", reason);
+        shutdown("unhandledRejection");
+    });
+    await server.connect(transport);
+}

package/dist/src/types.d.ts

@@ -0,0 +1,37 @@
+export interface PaginationMeta {
+    count: number;
+    limit: number;
+    offset: number;
+    has_more: boolean;
+    next_offset: number | null;
+    total_count?: number;
+}
+export interface ToolResult<T = unknown> {
+    data: T;
+    meta?: Record<string, unknown>;
+    pagination?: PaginationMeta;
+    execution_time_ms?: number;
+    truncated?: boolean;
+    truncation_message?: string;
+}
+export interface DatabaseConfig {
+    server: string;
+    database?: string;
+    user?: string;
+    password?: string;
+    port: number;
+    encrypt: boolean;
+    trustServerCertificate: boolean;
+    connectionTimeout: number;
+    requestTimeout: number;
+}
+export interface ConnectionState {
+    connected: boolean;
+    config: Pick<DatabaseConfig, "server" | "database" | "port"> | null;
+    pool_info: {
+        size: number;
+        available: number;
+        pending: number;
+        borrowed: number;
+    } | null;
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/errors.d.ts

@@ -0,0 +1,19 @@
+export declare class McpToolError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare function toActionableError(error: unknown): string;
+export declare function toolError(message: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};
+export declare function toolSuccess(text: string, structuredContent?: Record<string, unknown>): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+};

package/dist/src/utils/errors.js

@@ -0,0 +1,29 @@
+export class McpToolError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "McpToolError";
+    }
+}
+export function toActionableError(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+export function toolError(message) {
+    return {
+        content: [{ type: "text", text: `❌ ${message}` }],
+        isError: true,
+    };
+}
+export function toolSuccess(text, structuredContent) {
+    const result = {
+        content: [{ type: "text", text }],
+    };
+    if (structuredContent !== undefined) {
+        result.structuredContent = structuredContent;
+    }
+    return result;
+}

package/dist/src/utils/format.d.ts

@@ -0,0 +1,6 @@
+export declare function formatJson(data: unknown): string;
+export declare function truncatePayload(data: unknown[], maxBytes?: number): {
+    data: unknown[];
+    truncated: boolean;
+    truncation_message?: string;
+};

package/dist/src/utils/format.js

@@ -0,0 +1,27 @@
+import { MAX_TEXT_PAYLOAD_BYTES } from "../constants.js";
+export function formatJson(data) {
+    return JSON.stringify(data, null, 2);
+}
+export function truncatePayload(data, maxBytes = MAX_TEXT_PAYLOAD_BYTES) {
+    const full = JSON.stringify(data);
+    if (Buffer.byteLength(full, "utf8") <= maxBytes) {
+        return { data, truncated: false };
+    }
+    // Binary search for safe row count
+    let lo = 0;
+    let hi = data.length;
+    while (lo < hi) {
+        const mid = Math.floor((lo + hi + 1) / 2);
+        if (Buffer.byteLength(JSON.stringify(data.slice(0, mid)), "utf8") <= maxBytes) {
+            lo = mid;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return {
+        data: data.slice(0, lo),
+        truncated: true,
+        truncation_message: `Result truncated to ${lo} of ${data.length} rows to stay within ${maxBytes} byte limit.`,
+    };
+}

package/dist/src/utils/markdown.d.ts

@@ -0,0 +1,3 @@
+export declare function formatMarkdownTable(rows: Record<string, unknown>[], title?: string): string;
+export declare function formatMarkdownList(obj: Record<string, unknown>, title?: string): string;
+export declare function formatMarkdownMultiRecordsets(recordsets: unknown[][], title?: string): string;

package/dist/src/utils/markdown.js

@@ -0,0 +1,33 @@
+function escapeCell(value) {
+    return String(value ?? "")
+        .replace(/\r?\n|\r/g, " ")
+        .replace(/\|/g, "\\|");
+}
+export function formatMarkdownTable(rows, title) {
+    if (rows.length === 0) {
+        return title ? `**${title}**\n\nNo results found.` : "No results found.";
+    }
+    const headers = Object.keys(rows[0]);
+    const header = `| ${headers.join(" | ")} |`;
+    const sep = `| ${headers.map(() => "---").join(" | ")} |`;
+    const body = rows
+        .map((row) => `| ${headers.map((h) => escapeCell(row[h])).join(" | ")} |`)
+        .join("\n");
+    const table = [header, sep, body].join("\n");
+    return title ? `**${title}**\n\n${table}` : table;
+}
+export function formatMarkdownList(obj, title) {
+    const lines = Object.entries(obj).map(([k, v]) => `- **${k}**: ${typeof v === "object" ? JSON.stringify(v) : String(v ?? "")}`);
+    const list = lines.join("\n");
+    return title ? `**${title}**\n\n${list}` : list;
+}
+export function formatMarkdownMultiRecordsets(recordsets, title) {
+    if (!recordsets || recordsets.length === 0)
+        return "No result sets returned.";
+    const parts = recordsets.map((rs, i) => {
+        const rows = rs;
+        return formatMarkdownTable(rows, `Result Set ${i + 1}`);
+    });
+    const body = parts.join("\n\n");
+    return title ? `**${title}**\n\n${body}` : body;
+}

package/dist/src/utils/pagination.d.ts

@@ -0,0 +1,3 @@
+import type { PaginationMeta } from "../types.js";
+export declare function clampLimit(limit: number | undefined): number;
+export declare function buildPaginationMeta(count: number, limit: number, offset: number, totalCount?: number): PaginationMeta;

package/dist/src/utils/pagination.js

@@ -0,0 +1,18 @@
+import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } from "../constants.js";
+export function clampLimit(limit) {
+    const n = limit ?? DEFAULT_PAGE_SIZE;
+    return Math.min(Math.max(1, n), MAX_PAGE_SIZE);
+}
+export function buildPaginationMeta(count, limit, offset, totalCount) {
+    // has_more is an approximation when totalCount is unknown:
+    // if count === limit, there *may* be more rows (could be a false positive on the last page).
+    const has_more = totalCount != null ? offset + count < totalCount : count === limit;
+    return {
+        count,
+        limit,
+        offset,
+        has_more,
+        next_offset: has_more ? offset + limit : null,
+        total_count: totalCount,
+    };
+}

package/dist/tests/unit/markdown.test.d.ts

@@ -0,0 +1 @@
+export {};