pg-lens-mcp 0.1.0-alpha

package/dist/db/queries.d.ts

@@ -0,0 +1,39 @@
+/**
+ * SQL query builders and filter-to-WHERE clause converters
+ */
+export interface Filter {
+    column: string;
+    operator: "=" | "!=" | "<" | ">" | "<=" | ">=" | "LIKE" | "ILIKE" | "IN" | "IS NULL" | "IS NOT NULL";
+    value?: string | number | boolean | null | (string | number)[];
+}
+/**
+ * Convert structured filters to parameterized WHERE clause
+ * Safe from SQL injection via parameterized queries
+ */
+export declare function buildWhereClause(filters: Filter[]): {
+    whereClause: string;
+    params: unknown[];
+};
+/**
+ * Build a paginated SELECT query with optional filters and ordering
+ */
+export declare function buildSelectQuery(options: {
+    schema: string;
+    table: string;
+    columns?: string[];
+    filters?: Filter[];
+    orderBy?: string;
+    orderDirection?: "ASC" | "DESC";
+    limit: number;
+    offset: number;
+}): {
+    query: string;
+    params: unknown[];
+};
+/**
+ * Build COUNT query with same filters
+ */
+export declare function buildCountQuery(schema: string, table: string, filters?: Filter[]): {
+    query: string;
+    params: unknown[];
+};

package/dist/db/queries.js

@@ -0,0 +1,76 @@
+/**
+ * SQL query builders and filter-to-WHERE clause converters
+ */
+/**
+ * Convert structured filters to parameterized WHERE clause
+ * Safe from SQL injection via parameterized queries
+ */
+export function buildWhereClause(filters) {
+    if (filters.length === 0) {
+        return { whereClause: "", params: [] };
+    }
+    const params = [];
+    const conditions = [];
+    filters.forEach((filter) => {
+        const columnName = `"${filter.column}"`;
+        if (filter.operator === "IS NULL" || filter.operator === "IS NOT NULL") {
+            conditions.push(`${columnName} ${filter.operator}`);
+        }
+        else if (filter.operator === "IN") {
+            if (!Array.isArray(filter.value)) {
+                throw new Error(`IN operator requires array value for column ${filter.column}`);
+            }
+            const placeholders = filter.value.map((val) => {
+                params.push(val);
+                return `$${params.length}`;
+            });
+            conditions.push(`${columnName} IN (${placeholders.join(", ")})`);
+        }
+        else {
+            if (filter.value === undefined) {
+                throw new Error(`Operator ${filter.operator} requires a value for column ${filter.column}`);
+            }
+            params.push(filter.value);
+            conditions.push(`${columnName} ${filter.operator} $${params.length}`);
+        }
+    });
+    return {
+        whereClause: conditions.join(" AND "),
+        params,
+    };
+}
+/**
+ * Build a paginated SELECT query with optional filters and ordering
+ */
+export function buildSelectQuery(options) {
+    const { schema, table, columns = ["*"], filters = [], orderBy, orderDirection = "ASC", limit, offset, } = options;
+    // Build column list
+    const columnList = columns[0] === "*" ? "*" : columns.map((c) => `"${c}"`).join(", ");
+    // Build WHERE clause
+    const { whereClause, params } = buildWhereClause(filters);
+    // Start building query
+    let query = `SELECT ${columnList} FROM "${schema}"."${table}"`;
+    // Add WHERE if filters exist
+    if (whereClause) {
+        query += ` WHERE ${whereClause}`;
+    }
+    // Add ORDER BY if specified
+    if (orderBy) {
+        query += ` ORDER BY "${orderBy}" ${orderDirection}`;
+    }
+    // Add pagination
+    params.push(limit, offset);
+    query += ` LIMIT $${params.length - 1} OFFSET $${params.length}`;
+    return { query, params };
+}
+/**
+ * Build COUNT query with same filters
+ */
+export function buildCountQuery(schema, table, filters = []) {
+    const { whereClause, params } = buildWhereClause(filters);
+    let query = `SELECT COUNT(*) as total FROM "${schema}"."${table}"`;
+    if (whereClause) {
+        query += ` WHERE ${whereClause}`;
+    }
+    return { query, params };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * PostgreSQL MCP Server
+ * Entry point - handles initialization and graceful shutdown
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * PostgreSQL MCP Server
+ * Entry point - handles initialization and graceful shutdown
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+import { healthCheck, shutdown } from "./db/pool.js";
+async function main() {
+    try {
+        await healthCheck();
+        const server = createServer();
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        console.error("✓ PostgreSQL MCP Server running on stdio");
+    }
+    catch (error) {
+        console.error("✗ Fatal error during startup:", error);
+        process.exit(1);
+    }
+}
+// Graceful shutdown handlers
+process.on("SIGINT", async () => {
+    await shutdown();
+    process.exit(0);
+});
+process.on("SIGTERM", async () => {
+    await shutdown();
+    process.exit(0);
+});
+// Start the server
+main().catch((error) => {
+    console.error("✗ Unhandled error:", error);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,8 @@
+/**
+ * MCP Server setup and tool registration
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Create and configure the MCP server with all tools
+ */
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,31 @@
+/**
+ * MCP Server setup and tool registration
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerListTablesTool } from "./tools/list-tables.js";
+import { registerListSchemasTool } from "./tools/list-schemas.js";
+import { registerSearchColumnTool } from "./tools/search-column.js";
+import { registerGetTableInfoTool } from "./tools/get-table-info.js";
+import { registerGetTableDataTool } from "./tools/get-table-data.js";
+import { registerExecuteQueryTool } from "./tools/execute-query.js";
+import { registerExplainQueryTool } from "./tools/explain-query.js";
+import { registerExplainAnalyzeTool } from "./tools/explain-analyze.js";
+/**
+ * Create and configure the MCP server with all tools
+ */
+export function createServer() {
+    const server = new McpServer({
+        name: "postgres-server",
+        version: "1.0.0",
+    });
+    // Register all tools
+    registerListSchemasTool(server);
+    registerListTablesTool(server);
+    registerSearchColumnTool(server);
+    registerGetTableInfoTool(server);
+    registerGetTableDataTool(server);
+    registerExecuteQueryTool(server);
+    registerExplainQueryTool(server);
+    registerExplainAnalyzeTool(server);
+    return server;
+}

package/dist/tools/execute-query.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tool: execute_query
+ * Execute a read-only SQL query with database-enforced READ ONLY transaction
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerExecuteQueryTool(server: McpServer): void;

package/dist/tools/execute-query.js

@@ -0,0 +1,34 @@
+/**
+ * Tool: execute_query
+ * Execute a read-only SQL query with database-enforced READ ONLY transaction
+ */
+import { z } from "zod";
+import { executeReadOnly } from "../db/pool.js";
+import { formatQueryResult, formatError } from "../utils/response.js";
+export function registerExecuteQueryTool(server) {
+    server.tool("execute_query", "Execute a read-only SQL query. Query runs in a READ ONLY transaction for safety.", {
+        query: z.string().describe("SQL query to execute"),
+        params: z
+            .array(z.union([z.string(), z.number(), z.boolean(), z.null()]))
+            .optional()
+            .describe("Query parameters for parameterized queries ($1, $2, etc.)"),
+    }, async ({ query, params }) => {
+        const trimmedQuery = query.trim().toUpperCase();
+        // Basic sanity check (still allow SELECT and WITH/CTE)
+        if (!trimmedQuery.startsWith("SELECT") &&
+            !trimmedQuery.startsWith("WITH") &&
+            !trimmedQuery.startsWith("EXPLAIN")) {
+            return formatError("Only SELECT, WITH (CTE), and EXPLAIN queries are allowed");
+        }
+        try {
+            // Execute in READ ONLY transaction - PostgreSQL enforces no writes
+            const result = await executeReadOnly(query, params || []);
+            return formatQueryResult(result.rows, {
+                rowCount: result.rowCount,
+            });
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+}

package/dist/tools/explain-analyze.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tool: explain_analyze
+ * Execute a query and get actual execution statistics
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerExplainAnalyzeTool(server: McpServer): void;

package/dist/tools/explain-analyze.js

@@ -0,0 +1,59 @@
+/**
+ * Tool: explain_analyze
+ * Execute a query and get actual execution statistics
+ */
+import { z } from "zod";
+import { executeReadOnly } from "../db/pool.js";
+import { formatSuccess, formatError } from "../utils/response.js";
+export function registerExplainAnalyzeTool(server) {
+    server.tool("explain_analyze", "Execute a query with EXPLAIN ANALYZE to get actual timing and row statistics. ⚠️ WARNING: This actually executes the query, so it may be slow on large tables.", {
+        query: z.string().describe("SQL query to analyze"),
+        format: z
+            .enum(["text", "json"])
+            .optional()
+            .default("json")
+            .describe("Output format for the analysis"),
+        buffers: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Include buffer usage statistics"),
+        timing: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Include timing information"),
+        verbose: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Include verbose details"),
+    }, async ({ query, format, buffers, timing, verbose }) => {
+        try {
+            const options = [
+                "ANALYZE",
+                `FORMAT ${format?.toUpperCase() || "JSON"}`,
+            ];
+            if (buffers)
+                options.push("BUFFERS");
+            if (!timing)
+                options.push("TIMING OFF");
+            if (verbose)
+                options.push("VERBOSE");
+            const explainQuery = `EXPLAIN (${options.join(", ")}) ${query}`;
+            // Execute in READ ONLY transaction - query runs but can't modify data
+            const result = await executeReadOnly(explainQuery);
+            // For JSON format, parse and format nicely
+            if (format === "json" && result.rows.length > 0) {
+                const row = result.rows[0];
+                return formatSuccess(row["QUERY PLAN"]);
+            }
+            // For text, return as-is
+            const analysis = result.rows.map((row) => row["QUERY PLAN"]).join("\n");
+            return formatSuccess(analysis);
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+}

package/dist/tools/explain-query.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tool: explain_query
+ * Get the execution plan for a query without executing it
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerExplainQueryTool(server: McpServer): void;

package/dist/tools/explain-query.js

@@ -0,0 +1,43 @@
+/**
+ * Tool: explain_query
+ * Get the execution plan for a query without executing it
+ */
+import { z } from "zod";
+import { executeReadOnly } from "../db/pool.js";
+import { formatSuccess, formatError } from "../utils/response.js";
+export function registerExplainQueryTool(server) {
+    server.tool("explain_query", "Get the query execution plan (EXPLAIN) without actually running the query. Useful for understanding how PostgreSQL will execute a query.", {
+        query: z.string().describe("SQL query to analyze"),
+        format: z
+            .enum(["text", "json", "yaml"])
+            .optional()
+            .default("json")
+            .describe("Output format for the plan"),
+        verbose: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Include verbose details in the plan"),
+    }, async ({ query, format, verbose }) => {
+        try {
+            const options = [`FORMAT ${format?.toUpperCase() || "JSON"}`];
+            if (verbose) {
+                options.push("VERBOSE");
+            }
+            const explainQuery = `EXPLAIN (${options.join(", ")}) ${query}`;
+            // Execute in READ ONLY transaction for safety
+            const result = await executeReadOnly(explainQuery);
+            // For JSON format, parse and format nicely
+            if (format === "json" && result.rows.length > 0) {
+                const row = result.rows[0];
+                return formatSuccess(row["QUERY PLAN"]);
+            }
+            // For text/yaml, return as-is
+            const plan = result.rows.map((row) => row["QUERY PLAN"]).join("\n");
+            return formatSuccess(plan);
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+}

package/dist/tools/get-table-data.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tool: get_table_data
+ * Query table data with structured filters and pagination
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerGetTableDataTool(server: McpServer): void;

package/dist/tools/get-table-data.js

@@ -0,0 +1,105 @@
+/**
+ * Tool: get_table_data
+ * Query table data with structured filters and pagination
+ */
+import { z } from "zod";
+import { pool } from "../db/pool.js";
+import { config } from "../config.js";
+import { buildSelectQuery, buildCountQuery } from "../db/queries.js";
+import { formatQueryResult, formatError } from "../utils/response.js";
+import { validateTableExists, validateColumns } from "../utils/validation.js";
+const FilterSchema = z.object({
+    column: z.string().describe("Column name to filter on"),
+    operator: z
+        .enum(["=", "!=", "<", ">", "<=", ">=", "LIKE", "ILIKE", "IN", "IS NULL", "IS NOT NULL"])
+        .describe("Comparison operator"),
+    value: z
+        .union([
+        z.string(),
+        z.number(),
+        z.boolean(),
+        z.null(),
+        z.array(z.union([z.string(), z.number()])),
+    ])
+        .optional()
+        .describe("Value to compare (not needed for IS NULL/IS NOT NULL)"),
+});
+export function registerGetTableDataTool(server) {
+    server.tool("get_table_data", "Retrieve data from a table with optional structured filtering and pagination.", {
+        table_name: z.string().describe("Name of the table to query"),
+        schema: z
+            .string()
+            .optional()
+            .describe("Schema name (default: public)"),
+        columns: z
+            .array(z.string())
+            .optional()
+            .describe("Specific columns to select (default: all)"),
+        filters: z
+            .array(FilterSchema)
+            .optional()
+            .describe("Structured filters for WHERE clause. Example: [{column: 'status', operator: '=', value: 'active'}]"),
+        limit: z
+            .number()
+            .optional()
+            .describe("Maximum number of rows to return (default: 100, max: 1000)"),
+        offset: z
+            .number()
+            .optional()
+            .describe("Number of rows to skip (default: 0)"),
+        order_by: z
+            .string()
+            .optional()
+            .describe("Column name to order by"),
+        order_direction: z
+            .enum(["ASC", "DESC"])
+            .optional()
+            .describe("Sort direction (default: ASC)"),
+    }, async ({ table_name, schema, columns, filters, limit, offset, order_by, order_direction, }) => {
+        const targetSchema = schema || config.schema;
+        const effectiveLimit = Math.min(limit || 100, 1000);
+        const effectiveOffset = offset || 0;
+        try {
+            // Validate table exists
+            const tableExists = await validateTableExists(pool, targetSchema, table_name);
+            if (!tableExists) {
+                return formatError(`Table "${targetSchema}"."${table_name}" does not exist`);
+            }
+            // Validate columns if specified
+            if (columns && columns.length > 0) {
+                const validation = await validateColumns(pool, targetSchema, table_name, columns);
+                if (!validation.valid) {
+                    return formatError(`Invalid columns: ${validation.invalidColumns.join(", ")}`);
+                }
+            }
+            // Build queries
+            const { query, params } = buildSelectQuery({
+                schema: targetSchema,
+                table: table_name,
+                columns,
+                filters: filters,
+                orderBy: order_by,
+                orderDirection: order_direction,
+                limit: effectiveLimit,
+                offset: effectiveOffset,
+            });
+            const { query: countQuery, params: countParams } = buildCountQuery(targetSchema, table_name, filters);
+            // Execute queries in parallel
+            const [dataResult, countResult] = await Promise.all([
+                pool.query(query, params),
+                pool.query(countQuery, countParams),
+            ]);
+            return formatQueryResult(dataResult.rows, {
+                schema: targetSchema,
+                table: table_name,
+                totalRows: parseInt(countResult.rows[0].total, 10),
+                returnedRows: dataResult.rows.length,
+                limit: effectiveLimit,
+                offset: effectiveOffset,
+            });
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+}

package/dist/tools/get-table-info.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tool: get_table_info
+ * Get detailed table schema including columns, constraints, and indexes
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerGetTableInfoTool(server: McpServer): void;

package/dist/tools/get-table-info.js

@@ -0,0 +1,130 @@
+/**
+ * Tool: get_table_info
+ * Get detailed table schema including columns, constraints, and indexes
+ */
+import { z } from "zod";
+import { pool } from "../db/pool.js";
+import { config } from "../config.js";
+import { formatSuccess, formatError } from "../utils/response.js";
+export function registerGetTableInfoTool(server) {
+    server.tool("get_table_info", "Get detailed information about a table including columns, data types, and constraints.", {
+        table_name: z.string().describe("Name of the table to inspect"),
+        schema: z
+            .string()
+            .optional()
+            .describe("Schema name (default: public)"),
+    }, async ({ table_name, schema }) => {
+        const targetSchema = schema || config.schema;
+        // Get column information
+        const columnsQuery = `
+        SELECT
+          c.column_name,
+          c.data_type,
+          c.character_maximum_length,
+          c.numeric_precision,
+          c.numeric_scale,
+          c.is_nullable,
+          c.column_default,
+          c.udt_name
+        FROM information_schema.columns c
+        WHERE c.table_schema = $1
+          AND c.table_name = $2
+        ORDER BY c.ordinal_position
+      `;
+        // Get primary key information
+        const pkQuery = `
+        SELECT
+          kcu.column_name
+        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.table_schema = $1
+          AND tc.table_name = $2
+          AND tc.constraint_type = 'PRIMARY KEY'
+      `;
+        // Get foreign key information
+        const fkQuery = `
+        SELECT
+          kcu.column_name,
+          ccu.table_name AS foreign_table,
+          ccu.column_name AS foreign_column
+        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
+        JOIN information_schema.constraint_column_usage ccu
+          ON ccu.constraint_name = tc.constraint_name
+          AND ccu.table_schema = tc.table_schema
+        WHERE tc.table_schema = $1
+          AND tc.table_name = $2
+          AND tc.constraint_type = 'FOREIGN KEY'
+      `;
+        // Get indexes
+        const indexQuery = `
+        SELECT
+          i.relname AS index_name,
+          a.attname AS column_name,
+          ix.indisunique AS is_unique,
+          ix.indisprimary AS is_primary
+        FROM pg_class t
+        JOIN pg_index ix ON t.oid = ix.indrelid
+        JOIN pg_class i ON i.oid = ix.indexrelid
+        JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(ix.indkey)
+        JOIN pg_namespace n ON n.oid = t.relnamespace
+        WHERE t.relname = $2
+          AND n.nspname = $1
+        ORDER BY i.relname, a.attnum
+      `;
+        try {
+            const [columnsResult, pkResult, fkResult, indexResult] = await Promise.all([
+                pool.query(columnsQuery, [targetSchema, table_name]),
+                pool.query(pkQuery, [targetSchema, table_name]),
+                pool.query(fkQuery, [targetSchema, table_name]),
+                pool.query(indexQuery, [targetSchema, table_name]),
+            ]);
+            const primaryKeys = pkResult.rows.map((row) => row.column_name);
+            const foreignKeys = fkResult.rows.reduce((acc, row) => {
+                acc[row.column_name] = {
+                    references: `${row.foreign_table}.${row.foreign_column}`,
+                };
+                return acc;
+            }, {});
+            const columns = columnsResult.rows.map((row) => ({
+                name: row.column_name,
+                type: row.data_type,
+                udtName: row.udt_name,
+                maxLength: row.character_maximum_length,
+                precision: row.numeric_precision,
+                scale: row.numeric_scale,
+                nullable: row.is_nullable === "YES",
+                default: row.column_default,
+                isPrimaryKey: primaryKeys.includes(row.column_name),
+                foreignKey: foreignKeys[row.column_name] || null,
+            }));
+            // Group indexes
+            const indexes = indexResult.rows.reduce((acc, row) => {
+                if (!acc[row.index_name]) {
+                    acc[row.index_name] = {
+                        name: row.index_name,
+                        columns: [],
+                        isUnique: row.is_unique,
+                        isPrimary: row.is_primary,
+                    };
+                }
+                acc[row.index_name].columns.push(row.column_name);
+                return acc;
+            }, {});
+            const tableInfo = {
+                schema: targetSchema,
+                table: table_name,
+                columns,
+                indexes: Object.values(indexes),
+            };
+            return formatSuccess(tableInfo);
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+}

package/dist/tools/list-schemas.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tool: list_schemas
+ * List all non-system schemas in the database
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerListSchemasTool(server: McpServer): void;

package/dist/tools/list-schemas.js

@@ -0,0 +1,25 @@
+/**
+ * Tool: list_schemas
+ * List all non-system schemas in the database
+ */
+import { pool } from "../db/pool.js";
+import { formatSuccess, formatError } from "../utils/response.js";
+export function registerListSchemasTool(server) {
+    server.tool("list_schemas", "List all non-system schemas in the database.", {}, async () => {
+        const query = `
+        SELECT 
+          schema_name,
+          schema_owner
+        FROM information_schema.schemata
+        WHERE schema_name NOT IN ('pg_catalog', 'information_schema', 'pg_toast')
+        ORDER BY schema_name
+      `;
+        try {
+            const result = await pool.query(query);
+            return formatSuccess(result.rows, { asTable: true });
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+}

package/dist/tools/list-tables.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tool: list_tables
+ * List all tables in a schema
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerListTablesTool(server: McpServer): void;