@tejasanik/postgres-mcp-server 2.2.0 → 2.3.0

package/README.md

@@ -150,12 +150,15 @@ export POSTGRES_SERVERS='{
 
 **Note:** If both formats are used, individual `PG_*` variables take precedence over `POSTGRES_SERVERS`.
 
-#### POSTGRES_ACCESS_MODE (optional)
+#### Access Mode Configuration
 
-Controls whether write operations are allowed:
+Access modes control whether write operations are allowed. You can configure access at three levels with the following priority:
 
-- `full` (default): Full access - allows all SQL operations including INSERT, UPDATE, DELETE, CREATE, DROP, etc.
-- `readonly` / `read-only` / `ro`: Read-only mode - only SELECT and other read operations are allowed
+**Priority:** Database-level > Server-level > Global > default (full)
+
+##### Global Access Mode (POSTGRES_ACCESS_MODE)
+
+Sets the default access mode for all servers and databases:
 
 ```bash
 # For read-only access (recommended for production)
@@ -165,6 +168,59 @@ export POSTGRES_ACCESS_MODE="readonly"
 export POSTGRES_ACCESS_MODE="full"
 ```
 
+**Supported values:**
+- `full` / `rw` / `readwrite`: Full access - allows all SQL operations
+- `readonly` / `ro` / `read-only`: Read-only mode - only SELECT and read operations allowed
+
+##### Server-Level Access Mode (PG_ACCESS_MODE_*)
+
+Override global access mode for specific servers:
+
+```bash
+# Server 1: read-only (production)
+export PG_ACCESS_MODE_1="readonly"
+
+# Server 2: full access (development)
+export PG_ACCESS_MODE_DEV="full"
+```
+
+##### Database-Level Access Mode (PG_DB_ACCESS_MODES_*)
+
+Override server access mode for specific databases. Format: `dbname:mode,dbname:mode`
+
+```bash
+# For server 1: production db is readonly, analytics has full access
+export PG_DB_ACCESS_MODES_1="production:readonly,analytics:full,staging:rw"
+
+# For server PROD: specific database overrides
+export PG_DB_ACCESS_MODES_PROD="users_db:ro,logs:readonly,dev_db:full"
+```
+
+##### JSON Configuration (POSTGRES_SERVERS)
+
+Access modes can also be configured in the JSON format:
+
+```json
+{
+  "production": {
+    "host": "prod.example.com",
+    "username": "user",
+    "password": "pass",
+    "accessMode": "readonly",
+    "databaseAccessModes": {
+      "analytics": "full",
+      "reporting": "readonly"
+    }
+  },
+  "development": {
+    "host": "dev.example.com",
+    "username": "user",
+    "password": "pass",
+    "accessMode": "full"
+  }
+}
+```
+
 ### Claude Desktop Configuration
 
 Add the server to your Claude Desktop MCP configuration (`claude_desktop_config.json`):
@@ -176,15 +232,16 @@ Add the server to your Claude Desktop MCP configuration (`claude_desktop_config.
       "command": "npx",
       "args": ["@tejasanik/postgres-mcp-server"],
       "env": {
-        "PG_NAME_1": "dev",
-        "PG_HOST_1": "your-host.com",
+        "PG_NAME_1": "prod",
+        "PG_HOST_1": "prod.example.com",
         "PG_PORT_1": "5432",
         "PG_USERNAME_1": "user",
         "PG_PASSWORD_1": "pass",
         "PG_DATABASE_1": "mydb",
         "PG_SSL_1": "true",
         "PG_DEFAULT_1": "true",
-        "POSTGRES_ACCESS_MODE": "readonly"
+        "PG_ACCESS_MODE_1": "readonly",
+        "PG_DB_ACCESS_MODES_1": "analytics:full,staging:rw"
       }
     }
   }
@@ -200,20 +257,22 @@ claude mcp add-json postgres_dbs --scope user '{
   "command": "npx",
   "args": ["-y","@tejasanik/postgres-mcp-server"],
   "env": {
-    "PG_NAME_1": "dev",
-    "PG_HOST_1": "dev.example.com",
+    "PG_NAME_1": "prod",
+    "PG_HOST_1": "prod.example.com",
     "PG_PORT_1": "5432",
     "PG_USERNAME_1": "user",
     "PG_PASSWORD_1": "pass",
     "PG_DATABASE_1": "mydb",
     "PG_SSL_1": "true",
     "PG_DEFAULT_1": "true",
-    "PG_NAME_2": "staging",
-    "PG_HOST_2": "staging.example.com",
+    "PG_ACCESS_MODE_1": "readonly",
+    "PG_DB_ACCESS_MODES_1": "analytics:full",
+    "PG_NAME_2": "dev",
+    "PG_HOST_2": "dev.example.com",
     "PG_USERNAME_2": "user",
     "PG_PASSWORD_2": "pass",
     "PG_SSL_2": "true",
-    "POSTGRES_ACCESS_MODE": "readonly"
+    "PG_ACCESS_MODE_2": "full"
   }
 }'
 ```
@@ -955,7 +1014,7 @@ When `execute_sql_file` or multi-statement execution encounters errors, line num
 
 ## Security
 
-- **Access Mode**: By default, the server runs in **full access mode**. Set `POSTGRES_ACCESS_MODE=readonly` to prevent write operations (INSERT, UPDATE, DELETE, DROP, etc.). Recommended for production environments.
+- **Access Mode**: By default, the server runs in **full access mode**. Configure access at global (`POSTGRES_ACCESS_MODE`), server (`PG_ACCESS_MODE_*`), or database (`PG_DB_ACCESS_MODES_*`) levels. Database-level settings override server-level, which override global. Recommended: set production servers/databases to `readonly`.
 - **SQL Injection Protection**: All user inputs are validated and parameterized queries are used where possible.
 - **Query Timeout**: Default 30-second timeout prevents runaway queries.
 - **Credentials**: Managed via environment variables and never logged or exposed through the MCP interface.

package/dist/db-manager.js

@@ -36,12 +36,66 @@ function getSslConfig(ssl) {
     return undefined;
 }
 /**
- * Determines the access mode from environment variable.
+ * Parses access mode from a string value.
+ * Accepts: 'readonly', 'read-only', 'ro' for readonly mode
+ *          'full', 'readwrite', 'read-write', 'rw' for full mode
+ * Returns undefined if the value is not a valid access mode.
+ */
+function parseAccessMode(value) {
+    if (!value)
+        return undefined;
+    const mode = value.toLowerCase().trim();
+    if (mode === "readonly" || mode === "read-only" || mode === "ro") {
+        return "readonly";
+    }
+    if (mode === "full" || mode === "readwrite" || mode === "read-write" || mode === "rw") {
+        return "full";
+    }
+    return undefined;
+}
+/**
+ * Parses database access modes from a comma-separated string.
+ * Format: "dbname:readonly,otherdb:full" or "mydb:ro,staging:rw"
+ * Supported mode values: readonly, read-only, ro, full, readwrite, read-write, rw
+ */
+function parseDatabaseAccessModes(value) {
+    if (!value)
+        return undefined;
+    const result = {};
+    const pairs = value.split(",");
+    for (const pair of pairs) {
+        const trimmed = pair.trim();
+        if (!trimmed)
+            continue;
+        const colonIndex = trimmed.lastIndexOf(":");
+        if (colonIndex === -1) {
+            console.error(`Warning: Invalid database access mode format '${trimmed}', expected 'dbname:mode'`);
+            continue;
+        }
+        const dbName = trimmed.substring(0, colonIndex).trim();
+        const modeStr = trimmed.substring(colonIndex + 1).trim();
+        if (!dbName) {
+            console.error(`Warning: Empty database name in '${trimmed}'`);
+            continue;
+        }
+        const parsedMode = parseAccessMode(modeStr);
+        if (parsedMode) {
+            result[dbName] = parsedMode;
+        }
+        else {
+            console.error(`Warning: Invalid access mode '${modeStr}' for database '${dbName}', ` +
+                `expected: readonly, ro, full, rw`);
+        }
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+/**
+ * Determines the global access mode from environment variable.
  * POSTGRES_ACCESS_MODE can be 'readonly' or 'full' (default).
  */
-function getAccessModeFromEnv() {
-    const mode = process.env.POSTGRES_ACCESS_MODE?.toLowerCase().trim();
-    return mode === "readonly" || mode === "read-only" || mode === "ro";
+function getGlobalAccessModeFromEnv() {
+    const mode = parseAccessMode(process.env.POSTGRES_ACCESS_MODE);
+    return mode === "readonly";
 }
 /**
  * Parses SSL configuration from environment variable string.
@@ -77,7 +131,8 @@ function parseSslFromEnv(sslValue) {
 /**
  * Loads server configurations from individual PG_* environment variables.
  * Pattern: PG_NAME_1, PG_HOST_1, PG_PORT_1, PG_USERNAME_1, PG_PASSWORD_1,
- *          PG_DATABASE_1, PG_SCHEMA_1, PG_SSL_1, PG_DEFAULT_1, PG_CONTEXT_1
+ *          PG_DATABASE_1, PG_SCHEMA_1, PG_SSL_1, PG_DEFAULT_1, PG_CONTEXT_1,
+ *          PG_ACCESS_MODE_1, PG_DB_ACCESS_MODES_1
  */
 function loadServersFromEnvVars() {
     const servers = {};
@@ -115,6 +170,8 @@ function loadServersFromEnvVars() {
             isDefault: process.env[`PG_DEFAULT${suffix}`]?.toLowerCase() === "true",
             ssl: parseSslFromEnv(process.env[`PG_SSL${suffix}`]),
             context: process.env[`PG_CONTEXT${suffix}`],
+            accessMode: parseAccessMode(process.env[`PG_ACCESS_MODE${suffix}`]),
+            databaseAccessModes: parseDatabaseAccessModes(process.env[`PG_DB_ACCESS_MODES${suffix}`]),
         };
         servers[name] = config;
     }
@@ -122,7 +179,7 @@ function loadServersFromEnvVars() {
 }
 /**
  * Loads server configurations from POSTGRES_SERVERS JSON environment variable.
- * (Legacy format for backward compatibility)
+ * Supports accessMode and databaseAccessModes for per-server and per-database access control.
  */
 function loadServersFromJson() {
     const configEnv = process.env.POSTGRES_SERVERS;
@@ -143,6 +200,45 @@ function loadServersFromJson() {
             if (!serverConfig.host || typeof serverConfig.host !== "string") {
                 throw new Error(`Server '${name}' must have a valid 'host' string`);
             }
+            // Validate accessMode if provided
+            if (serverConfig.accessMode !== undefined) {
+                const validModes = ["full", "readonly"];
+                if (!validModes.includes(serverConfig.accessMode)) {
+                    console.error(`Warning: Invalid accessMode '${serverConfig.accessMode}' for server '${name}', ` +
+                        `must be 'full' or 'readonly'. Using default.`);
+                    delete serverConfig.accessMode;
+                }
+            }
+            // Validate databaseAccessModes if provided
+            if (serverConfig.databaseAccessModes !== undefined) {
+                // Support both string format ("db:mode,db2:mode") and object format
+                if (typeof serverConfig.databaseAccessModes === "string") {
+                    const parsed = parseDatabaseAccessModes(serverConfig.databaseAccessModes);
+                    if (parsed) {
+                        serverConfig.databaseAccessModes = parsed;
+                    }
+                    else {
+                        delete serverConfig.databaseAccessModes;
+                    }
+                }
+                else {
+                    const dbModes = serverConfig.databaseAccessModes;
+                    if (typeof dbModes !== "object" || dbModes === null) {
+                        console.error(`Warning: Invalid databaseAccessModes for server '${name}', must be an object or string. Ignoring.`);
+                        delete serverConfig.databaseAccessModes;
+                    }
+                    else {
+                        const validModes = ["full", "readonly"];
+                        for (const [dbName, mode] of Object.entries(dbModes)) {
+                            if (!validModes.includes(mode)) {
+                                console.error(`Warning: Invalid accessMode '${mode}' for database '${dbName}' on server '${name}', ` +
+                                    `must be 'full' or 'readonly'. Ignoring.`);
+                                delete dbModes[dbName];
+                            }
+                        }
+                    }
+                }
+            }
         }
         return parsed;
     }
@@ -420,15 +516,16 @@ export class DatabaseManager {
     }
     getConnectionInfo() {
         const currentServer = this.connectionState.currentServer;
+        const currentDatabase = this.connectionState.currentDatabase;
         const serverConfig = currentServer
             ? this.serversConfig[currentServer]
             : null;
         return {
             isConnected: this.isConnected(),
             server: currentServer,
-            database: this.connectionState.currentDatabase,
+            database: currentDatabase,
             schema: this.connectionState.currentSchema,
-            accessMode: this.readOnlyMode ? "readonly" : "full",
+            accessMode: this.getEffectiveAccessMode(currentServer, currentDatabase),
             context: serverConfig?.context,
             user: serverConfig?.username,
         };
@@ -474,7 +571,7 @@ export class DatabaseManager {
             throw new Error("SQL query is required and must be a string");
         }
         // Check for read-only mode violations using improved validation
-        if (this.readOnlyMode) {
+        if (this.isReadOnlyFor()) {
             const { isReadOnly, reason } = isReadOnlySql(sql);
             if (!isReadOnly) {
                 throw new Error(`Read-only mode violation: ${reason}`);
@@ -761,8 +858,10 @@ export class DatabaseManager {
         if (!sql || typeof sql !== "string") {
             throw new Error("SQL query is required and must be a string");
         }
-        // Check for read-only mode violations
-        if (this.readOnlyMode) {
+        // Check for read-only mode violations using the target server/database
+        const targetServer = override?.server ?? this.connectionState.currentServer;
+        const targetDatabase = override?.database ?? this.connectionState.currentDatabase;
+        if (this.isReadOnlyFor(targetServer, targetDatabase)) {
             const { isReadOnly, reason } = isReadOnlySql(sql);
             if (!isReadOnly) {
                 throw new Error(`Read-only mode violation: ${reason}`);
@@ -980,12 +1079,51 @@ export class DatabaseManager {
         }
         return false;
     }
+    /**
+     * Returns whether global read-only mode is enabled.
+     * For context-aware access mode, use getEffectiveAccessMode().
+     */
     isReadOnly() {
         return this.readOnlyMode;
     }
     setReadOnlyMode(readOnly) {
         this.readOnlyMode = readOnly;
     }
+    /**
+     * Gets the effective access mode for a specific server/database combination.
+     * Priority: Database-level > Server-level > Global env > default (full)
+     *
+     * @param serverName The server name (or null to use current server)
+     * @param database The database name (or null to use current database)
+     * @returns The effective access mode ('full' or 'readonly')
+     */
+    getEffectiveAccessMode(serverName, database) {
+        const server = serverName ?? this.connectionState.currentServer;
+        const db = database ?? this.connectionState.currentDatabase;
+        if (server) {
+            const serverConfig = this.serversConfig[server];
+            if (serverConfig) {
+                // Check database-level access mode first
+                if (db && serverConfig.databaseAccessModes?.[db]) {
+                    return serverConfig.databaseAccessModes[db];
+                }
+                // Fall back to server-level access mode
+                if (serverConfig.accessMode) {
+                    return serverConfig.accessMode;
+                }
+            }
+        }
+        // Fall back to global mode
+        return this.readOnlyMode ? "readonly" : "full";
+    }
+    /**
+     * Checks if access mode is read-only for a specific server/database combination.
+     * @param serverName The server name (or null to use current server)
+     * @param database The database name (or null to use current database)
+     */
+    isReadOnlyFor(serverName, database) {
+        return this.getEffectiveAccessMode(serverName, database) === "readonly";
+    }
     setQueryTimeout(timeoutMs) {
         this.queryTimeoutMs = Math.min(Math.max(1000, timeoutMs), MAX_QUERY_TIMEOUT_MS);
     }
@@ -1067,8 +1205,8 @@ export class DatabaseManager {
         if (!transaction) {
             throw new Error(`Transaction not found: ${transactionId}`);
         }
-        // Check for read-only mode violations
-        if (this.readOnlyMode) {
+        // Check for read-only mode violations using the transaction's server/database
+        if (this.isReadOnlyFor(transaction.info.server, transaction.info.database)) {
             const { isReadOnly, reason } = isReadOnlySql(sql);
             if (!isReadOnly) {
                 throw new Error(`Read-only mode violation: ${reason}`);
@@ -1116,15 +1254,18 @@ export class DatabaseManager {
 let dbManager = null;
 /**
  * Gets the singleton DatabaseManager instance.
- * The access mode is determined by the POSTGRES_ACCESS_MODE environment variable:
+ * The global access mode is determined by the POSTGRES_ACCESS_MODE environment variable:
  * - 'readonly', 'read-only', 'ro': Read-only mode (prevents write operations)
  * - 'full' (default): Full access mode (allows all operations)
+ *
+ * Note: Server-level and database-level access modes can override the global setting.
+ * Use PG_ACCESS_MODE_{suffix} for server-level and PG_DB_ACCESS_MODES_{suffix} for database-level.
  */
 export function getDbManager() {
     if (!dbManager) {
-        const readOnlyMode = getAccessModeFromEnv();
+        const readOnlyMode = getGlobalAccessModeFromEnv();
         dbManager = new DatabaseManager(readOnlyMode);
-        console.error(`PostgreSQL MCP: Access mode = ${readOnlyMode ? "readonly" : "full"}`);
+        console.error(`PostgreSQL MCP: Global access mode = ${readOnlyMode ? "readonly" : "full"}`);
     }
     return dbManager;
 }

package/package.json

@@ -1,10 +1,9 @@
 {
   "name": "@tejasanik/postgres-mcp-server",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "A Model Context Protocol (MCP) server for PostgreSQL database management and analysis",
   "type": "module",
   "main": "dist/index.js",
-  "types": "dist/index.d.ts",
   "bin": {
     "postgres-mcp-server": "./dist/index.js"
   },
@@ -17,7 +16,7 @@
     "lint": "eslint src --ignore-pattern '__tests__'",
     "lint:fix": "eslint src --ignore-pattern '__tests__' --fix",
     "prepare": "npm run build",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm i && npm run build && npm test"
   },
   "keywords": [
     "mcp",
@@ -54,7 +53,7 @@
     "node": ">=18.0.0"
   },
   "files": [
-    "dist",
+    "dist/**/*.js",
     "README.md"
   ],
   "repository": {

package/dist/db-manager/index.d.ts

@@ -1,7 +0,0 @@
-/**
- * Database Manager Utilities
- *
- * Re-exports all utility modules for the database manager.
- */
-export * from './validation.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/db-manager/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/db-manager/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,iBAAiB,CAAC"}

package/dist/db-manager/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/db-manager/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,iBAAiB,CAAC"}

package/dist/db-manager/validation.d.ts

@@ -1,35 +0,0 @@
-/**
- * Database Manager Validation Utilities
- *
- * Centralized validation functions for database and schema names.
- * Prevents SQL injection and ensures PostgreSQL-compatible identifiers.
- */
-/**
- * Validates a database name for PostgreSQL compatibility and SQL injection prevention.
- *
- * @param name - The database name to validate
- * @throws Error if the database name is invalid
- */
-export declare function validateDatabaseName(name: string): void;
-/**
- * Validates a schema name for PostgreSQL compatibility.
- *
- * @param name - The schema name to validate
- * @throws Error if the schema name is invalid
- */
-export declare function validateSchemaName(name: string): void;
-/**
- * Checks if a database name is valid without throwing.
- *
- * @param name - The database name to check
- * @returns true if valid, false otherwise
- */
-export declare function isValidDatabaseName(name: string): boolean;
-/**
- * Checks if a schema name is valid without throwing.
- *
- * @param name - The schema name to check
- * @returns true if valid, false otherwise
- */
-export declare function isValidSchemaName(name: string): boolean;
-//# sourceMappingURL=validation.d.ts.map

package/dist/db-manager/validation.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/db-manager/validation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAOvD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAIrD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD"}

package/dist/db-manager/validation.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/db-manager/validation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qGAAqG;AACrG,MAAM,qBAAqB,GAAG,2BAA2B,CAAC;AAE1D,kFAAkF;AAClF,MAAM,qBAAqB,GAAG,YAAY,CAAC;AAE3C,iGAAiG;AACjG,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1E,MAAM,IAAI,KAAK,CACb,yEAAyE;YACvE,gDAAgD,CACnD,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,gFAAgF,CAAC,CAAC;IACpG,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,OAAO,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC"}