pg-lens-mcp 0.1.0-alpha

package/dist/tools/list-tables.js

@@ -0,0 +1,34 @@
+/**
+ * Tool: list_tables
+ * List all tables in a schema
+ */
+import { z } from "zod";
+import { pool } from "../db/pool.js";
+import { config } from "../config.js";
+import { formatSuccess, formatError } from "../utils/response.js";
+export function registerListTablesTool(server) {
+    server.tool("list_tables", "List all tables in the database. Optionally filter by schema.", {
+        schema: z
+            .string()
+            .optional()
+            .describe("Schema name to filter tables (default: public)"),
+    }, async ({ schema }) => {
+        const targetSchema = schema || config.schema;
+        const query = `
+        SELECT
+          table_schema,
+          table_name,
+          table_type
+        FROM information_schema.tables
+        WHERE table_schema = $1
+        ORDER BY table_name
+      `;
+        try {
+            const result = await pool.query(query, [targetSchema]);
+            return formatSuccess(result.rows, { asTable: true });
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+}

package/dist/tools/search-column.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tool: search_column
+ * Find tables containing a column name pattern
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSearchColumnTool(server: McpServer): void;

package/dist/tools/search-column.js

@@ -0,0 +1,34 @@
+/**
+ * Tool: search_column
+ * Find tables containing a column name pattern
+ */
+import { z } from "zod";
+import { pool } from "../db/pool.js";
+import { formatSuccess, formatError } from "../utils/response.js";
+export function registerSearchColumnTool(server) {
+    server.tool("search_column", "Find tables containing a column name pattern (case-insensitive search).", {
+        column_pattern: z
+            .string()
+            .describe("Partial or full column name to search for"),
+    }, async ({ column_pattern }) => {
+        const query = `
+        SELECT 
+          table_schema,
+          table_name,
+          column_name,
+          data_type,
+          is_nullable,
+          column_default
+        FROM information_schema.columns
+        WHERE column_name ILIKE $1
+        ORDER BY table_schema, table_name, column_name
+      `;
+        try {
+            const result = await pool.query(query, [`%${column_pattern}%`]);
+            return formatSuccess(result.rows, { asTable: true });
+        }
+        catch (error) {
+            return formatError(error);
+        }
+    });
+}

package/dist/utils/response.d.ts

@@ -0,0 +1,39 @@
+/**
+ * MCP response formatting utilities
+ *
+ * Token-optimized responses using markdown tables instead of verbose JSON
+ */
+interface McpTextContent {
+    type: "text";
+    text: string;
+}
+interface McpResponse {
+    [key: string]: unknown;
+    content: McpTextContent[];
+    isError?: boolean;
+}
+/**
+ * Format database rows as a compact markdown table
+ * Significantly reduces token usage compared to JSON
+ */
+export declare function formatTableAsMarkdown(rows: Record<string, unknown>[]): string;
+/**
+ * Format metadata (table schema, etc.) as compact summary
+ */
+export declare function formatMeta(data: Record<string, unknown>): string;
+/**
+ * Format a successful response
+ */
+export declare function formatSuccess(data: unknown, options?: {
+    asTable?: boolean;
+    asMeta?: boolean;
+}): McpResponse;
+/**
+ * Format an error response
+ */
+export declare function formatError(error: unknown): McpResponse;
+/**
+ * Format a response with row count metadata and table data
+ */
+export declare function formatQueryResult(rows: Record<string, unknown>[], metadata?: Record<string, unknown>): McpResponse;
+export {};

package/dist/utils/response.js

@@ -0,0 +1,99 @@
+/**
+ * MCP response formatting utilities
+ *
+ * Token-optimized responses using markdown tables instead of verbose JSON
+ */
+/**
+ * Format database rows as a compact markdown table
+ * Significantly reduces token usage compared to JSON
+ */
+export function formatTableAsMarkdown(rows) {
+    if (rows.length === 0) {
+        return "_No results_";
+    }
+    const headers = Object.keys(rows[0]);
+    const headerRow = `| ${headers.join(" | ")} |`;
+    const separator = `| ${headers.map(() => "---").join(" | ")} |`;
+    const dataRows = rows
+        .map((row) => {
+        const values = headers.map((h) => {
+            const value = row[h];
+            if (value === null || value === undefined)
+                return "NULL";
+            if (typeof value === "object")
+                return JSON.stringify(value);
+            return String(value);
+        });
+        return `| ${values.join(" | ")} |`;
+    })
+        .join("\n");
+    return `${headerRow}\n${separator}\n${dataRows}`;
+}
+/**
+ * Format metadata (table schema, etc.) as compact summary
+ */
+export function formatMeta(data) {
+    return Object.entries(data)
+        .map(([key, value]) => `**${key}**: ${JSON.stringify(value, null, 2)}`)
+        .join("\n");
+}
+/**
+ * Format a successful response
+ */
+export function formatSuccess(data, options = {}) {
+    let text;
+    if (options.asTable && Array.isArray(data)) {
+        text = formatTableAsMarkdown(data);
+    }
+    else if (options.asMeta && typeof data === "object" && data !== null) {
+        text = formatMeta(data);
+    }
+    else {
+        text = JSON.stringify(data, null, 2);
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text,
+            },
+        ],
+    };
+}
+/**
+ * Format an error response
+ */
+export function formatError(error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return {
+        content: [
+            {
+                type: "text",
+                text: `❌ **Error**: ${errorMessage}`,
+            },
+        ],
+        isError: true,
+    };
+}
+/**
+ * Format a response with row count metadata and table data
+ */
+export function formatQueryResult(rows, metadata) {
+    const parts = [];
+    if (metadata) {
+        parts.push("### Query Result\n");
+        Object.entries(metadata).forEach(([key, value]) => {
+            parts.push(`- **${key}**: ${value}`);
+        });
+        parts.push("");
+    }
+    parts.push(formatTableAsMarkdown(rows));
+    return {
+        content: [
+            {
+                type: "text",
+                text: parts.join("\n"),
+            },
+        ],
+    };
+}

package/dist/utils/validation.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Validation utilities for database identifiers and inputs
+ */
+import type { Pool } from "pg";
+/**
+ * Basic identifier validation for table/column names
+ * Note: PostgreSQL allows quoted identifiers with special characters,
+ * so we validate existence rather than format
+ */
+export declare const IDENTIFIER_REGEX: RegExp;
+/**
+ * Validate that a table exists in the specified schema
+ */
+export declare function validateTableExists(pool: Pool, schema: string, tableName: string): Promise<boolean>;
+/**
+ * Validate that a schema exists
+ */
+export declare function validateSchemaExists(pool: Pool, schema: string): Promise<boolean>;
+/**
+ * Validate column names against a table
+ */
+export declare function validateColumns(pool: Pool, schema: string, tableName: string, columns: string[]): Promise<{
+    valid: boolean;
+    invalidColumns: string[];
+}>;

package/dist/utils/validation.js

@@ -0,0 +1,37 @@
+/**
+ * Validation utilities for database identifiers and inputs
+ */
+/**
+ * Basic identifier validation for table/column names
+ * Note: PostgreSQL allows quoted identifiers with special characters,
+ * so we validate existence rather than format
+ */
+export const IDENTIFIER_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+/**
+ * Validate that a table exists in the specified schema
+ */
+export async function validateTableExists(pool, schema, tableName) {
+    const result = await pool.query(`SELECT 1 FROM information_schema.tables 
+     WHERE table_schema = $1 AND table_name = $2`, [schema, tableName]);
+    return result.rowCount !== null && result.rowCount > 0;
+}
+/**
+ * Validate that a schema exists
+ */
+export async function validateSchemaExists(pool, schema) {
+    const result = await pool.query(`SELECT 1 FROM information_schema.schemata WHERE schema_name = $1`, [schema]);
+    return result.rowCount !== null && result.rowCount > 0;
+}
+/**
+ * Validate column names against a table
+ */
+export async function validateColumns(pool, schema, tableName, columns) {
+    const result = await pool.query(`SELECT column_name FROM information_schema.columns
+     WHERE table_schema = $1 AND table_name = $2`, [schema, tableName]);
+    const validColumns = new Set(result.rows.map((row) => row.column_name));
+    const invalidColumns = columns.filter((col) => !validColumns.has(col));
+    return {
+        valid: invalidColumns.length === 0,
+        invalidColumns,
+    };
+}

package/mcp-config.example.json

@@ -0,0 +1,16 @@
+{
+  "mcpServers": {
+    "postgres": {
+      "command": "node",
+      "args": ["/home/yohann/Lab/MCP/postgres-server/dist/index.js"],
+      "env": {
+        "DB_HOST": "localhost",
+        "DB_PORT": "5432",
+        "DB_DATABASE": "your_database",
+        "DB_USERNAME": "your_username",
+        "DB_PASSWORD": "your_password",
+        "DB_SCHEMA": "public"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "pg-lens-mcp",
+  "version": "0.1.0-alpha",
+  "description": "Secure PostgreSQL integration for AI assistants via Model Context Protocol",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "pg-lens-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "keywords": [
+    "mcp",
+    "postgres",
+    "postgresql",
+    "database",
+    "ai",
+    "claude",
+    "model-context-protocol",
+    "anthropic",
+    "sql",
+    "read-only"
+  ],
+  "author": "Yohann",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YhannHommet/pg-lens-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/YhannHommet/pg-lens-mcp/issues"
+  },
+  "homepage": "https://github.com/YhannHommet/pg-lens-mcp#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "pg": "^8.13.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/pg": "^8.11.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}