enhanced-postgres-mcp-server

Executes arbitrary SQL queries (SELECT, INSERT, UPDATE, DELETE) against PostgreSQL databases through the Model Context Protocol, enabling LLMs to read and write data directly. Implements MCP's tool-calling interface to expose database operations as callable functions with schema validation, parameter binding, and result serialization back to the LLM context.

Automatically discovers PostgreSQL table schemas (columns, types, constraints, primary/foreign keys) and exposes them as MCP resources that the LLM can query to understand database structure. Uses PostgreSQL information_schema queries to build a schema graph and serialize it into LLM-readable format, enabling context-aware query generation.

Registers database operations as MCP tools with JSON Schema definitions for parameters, enabling the LLM to understand required/optional arguments, data types, and constraints before calling. Implements schema validation on incoming tool calls to reject malformed queries before execution, with detailed error messages that guide the LLM to correct syntax.

Manages PostgreSQL client connections using a connection pool (likely pg.Pool or similar) to reuse connections across multiple queries, reducing connection overhead. Handles connection initialization, error recovery, and graceful shutdown of the MCP server while ensuring no queries are orphaned. Implements connection timeout and idle timeout settings to prevent resource exhaustion.

Catches PostgreSQL errors (syntax errors, constraint violations, permission denied, etc.) and translates them into human-readable messages that are returned to the LLM. Preserves error context (line number, SQL state code) to help the LLM understand what went wrong and retry with corrected queries. Implements timeout handling for long-running queries.

Optionally restricts the MCP server to execute only SELECT queries, blocking INSERT/UPDATE/DELETE operations at the MCP layer before they reach the database. Implements a query parser or regex-based filter to detect write operations and reject them with a clear error message. Useful for read-only access patterns or multi-user scenarios where only certain users should modify data.

Handles large query result sets by implementing pagination or streaming, preventing the MCP server from loading entire tables into memory. Returns results in chunks with metadata (total row count, current page) to allow the LLM to request additional data if needed. Implements configurable result limits to prevent runaway queries from consuming all available memory.

Optionally supports executing multiple SQL statements in a single transaction (BEGIN/COMMIT/ROLLBACK), allowing the LLM to perform atomic multi-step operations. Implements transaction isolation and rollback on error, ensuring data consistency. May support savepoints for nested transactions or partial rollbacks.