@edelciomolina/postgres-mcp 1.0.0

package/README.md

@@ -0,0 +1,138 @@
+# 🐘 Postgres MCP
+
+> 🔌 MCP server wrapper for PostgreSQL - reads credentials from `.env` at runtime with flexible key mapping, configurable tool selection, and **safe read-only defaults**.
+
+[![npm version](https://img.shields.io/npm/v/@edelciomolina/postgres-mcp)](https://www.npmjs.com/package/@edelciomolina/postgres-mcp)
+[![license](https://img.shields.io/npm/l/@edelciomolina/postgres-mcp)](./LICENSE)
+
+---
+
+## ✨ What it does
+
+This package wraps [@henkey/postgres-mcp-server](https://github.com/HenkDz/postgresql-mcp-server) and adds:
+
+- 🔐 **Runtime credential resolution** - reads database credentials from your `.env` file at startup, so no secrets are stored in `mcp.json`
+- 🗝️ **Flexible key mapping** - use any `.env` variable names; tell the server which ones to use via `env` in `mcp.json`
+- 🎯 **Explicit tool selection** - pass `tool=<name>` args to choose exactly which MCP tools to expose
+- 🛡️ **Read-only by default** - if no tools are specified, only safe introspection tools are enabled (no writes, no arbitrary SQL execution)
+
+---
+
+## 📋 Requirements
+
+- ⚙️ Node.js >= 18
+- 📄 A `.env` file in your project root with the database credentials
+
+---
+
+## 🚀 Usage in VS Code (`mcp.json`)
+
+```json
+{
+  "servers": {
+    "Postgres": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "@edelciomolina/postgres-mcp",
+        "tool=pg_explain_query",
+        "tool=pg_get_schema_info",
+        "tool=pg_get_indexes",
+        "tool=pg_get_slow_queries",
+        "tool=pg_monitor_database"
+      ],
+      "env": {
+        "MCP_KEY_HOST":    "DB_HOST",
+        "MCP_KEY_PORT":    "DB_PORT",
+        "MCP_KEY_NAME":    "DB_NAME",
+        "MCP_KEY_SSLMODE": "DB_SSLMODE",
+        "MCP_KEY_USER":    "DB_USER",
+        "MCP_KEY_PASS":    "DB_PASS"
+      }
+    }
+  }
+}
+```
+
+The corresponding `.env` in your project root:
+
+```env
+DB_HOST=db.your-project.supabase.co
+DB_PORT=5432
+DB_NAME=postgres
+DB_SSLMODE=require
+DB_USER=readonly_user
+DB_PASS=your_password
+```
+
+---
+
+## ⚙️ How `mcp.json` configuration works
+
+### 🗝️ `env` - credential key mapping
+
+The `env` block does **not** contain the actual credentials. It maps each `MCP_KEY_*` to the name of the variable in your `.env` file.
+
+| Key in `env`   | Points to `.env` variable | Example value           |
+|----------------|---------------------------|-------------------------|
+| `MCP_KEY_HOST` | `DB_HOST`                 | `db.example.supabase.co`|
+| `MCP_KEY_PORT` | `DB_PORT`                 | `5432`                  |
+| `MCP_KEY_NAME` | `DB_NAME`                 | `postgres`              |
+| `MCP_KEY_SSLMODE` | `DB_SSLMODE`           | `require`               |
+| `MCP_KEY_USER` | `DB_USER`                 | `readonly_user`         |
+| `MCP_KEY_PASS` | `DB_PASS`                 | `secret`                |
+
+This indirection means you can use **any variable names** in your `.env` - useful when sharing an `.env` across multiple services with different naming conventions.
+
+### 🔧 `args` - tool selection via `tool=` prefix
+
+Each enabled MCP tool is declared as a separate arg using the `tool=<name>` format:
+
+```json
+"args": [
+  "npx @edelciomolina/postgres-mcp",
+  "tool=pg_get_schema_info",
+  "tool=pg_get_indexes"
+]
+```
+
+This makes the tool list **explicit and auditable** directly in `mcp.json` - no hidden config files. 🔍
+
+---
+
+## 🛡️ Why read-only is the default
+
+If you omit all `tool=` args, the server starts with a **curated read-only set** - every tool that can retrieve, analyze, or explain data, but nothing that can modify it.
+
+**⚠️ Excluded from defaults (write-capable):**
+
+| Tool | Risk |
+|------|------|
+| `pg_execute_query` | Runs arbitrary SQL - including `INSERT`, `UPDATE`, `DELETE`, `DROP` |
+| `pg_manage_query`  | Executes saved queries - can include mutations |
+
+**✅ Included in defaults (safe read-only):**
+
+```
+pg_explain_query       pg_get_schema_info     pg_get_indexes
+pg_get_constraints     pg_get_functions       pg_get_triggers
+pg_get_rls_policies    pg_get_enums           pg_get_setup_instructions
+pg_get_slow_queries    pg_get_query_stats     pg_get_user_permissions
+pg_analyze_database    pg_analyze_index_usage pg_monitor_database
+pg_debug_database
+```
+
+> 💡 **Tip:** While this MCP is secure and customizable via tools, for maximum safety, pair the read-only tool set with a database user that only has `SELECT` privileges.
+
+---
+
+## 🧰 Available tools
+
+See the full list of available tools in the underlying server:  
+📦 [@henkey/postgres-mcp-server](https://github.com/HenkDz/postgresql-mcp-server)
+
+---
+
+## 📄 License
+
+MIT © [Edelcio Molina](https://github.com/edelciomolina)

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * @edelciomolina/postgres-mcp
+ * MCP server wrapper for PostgreSQL - reads credentials from .env at runtime.
+ *
+ * Author: Edelcio Molina <https://github.com/edelciomolina>
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * @edelciomolina/postgres-mcp
+ * MCP server wrapper for PostgreSQL - reads credentials from .env at runtime.
+ *
+ * Author: Edelcio Molina <https://github.com/edelciomolina>
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+// ---------------------------------------------------------------------------
+// Default read-only tools (no pg_execute_query / pg_manage_query)
+// ---------------------------------------------------------------------------
+const DEFAULT_READONLY_TOOLS = [
+    "pg_explain_query",
+    "pg_get_schema_info",
+    "pg_get_indexes",
+    "pg_get_constraints",
+    "pg_get_functions",
+    "pg_get_triggers",
+    "pg_get_rls_policies",
+    "pg_get_enums",
+    "pg_get_setup_instructions",
+    "pg_get_slow_queries",
+    "pg_get_query_stats",
+    "pg_get_user_permissions",
+    "pg_analyze_database",
+    "pg_analyze_index_usage",
+    "pg_monitor_database",
+    "pg_debug_database"
+];
+// ---------------------------------------------------------------------------
+// .env reader
+// ---------------------------------------------------------------------------
+function loadEnvFile(envPath) {
+    if (!(0, fs_1.existsSync)(envPath)) {
+        throw new Error(`.env file not found at: ${envPath}`);
+    }
+    const env = {};
+    for (const line of (0, fs_1.readFileSync)(envPath, "utf8").split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eqIdx = trimmed.indexOf("=");
+        if (eqIdx === -1)
+            continue;
+        const key = trimmed.slice(0, eqIdx).trim();
+        const value = trimmed
+            .slice(eqIdx + 1)
+            .trim()
+            .replace(/^["']|["']$/g, "");
+        env[key] = value;
+    }
+    return env;
+}
+// ---------------------------------------------------------------------------
+// Resolve credential from .env using MCP_KEY_* mapping
+// ---------------------------------------------------------------------------
+function resolveCredential(envVars, dotenv, mcpKey, fallback) {
+    const mappedKey = envVars[mcpKey] ?? fallback;
+    const value = dotenv[mappedKey] ?? "";
+    return value;
+}
+// ---------------------------------------------------------------------------
+// Build PostgreSQL connection string with URL-encoded password
+// ---------------------------------------------------------------------------
+function buildConnectionString(creds) {
+    const encodedUser = encodeURIComponent(creds.user);
+    const encodedPass = encodeURIComponent(creds.pass);
+    return `postgresql://${encodedUser}:${encodedPass}@${creds.host}:${creds.port}/${creds.name}?sslmode=${creds.sslmode}`;
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+function main() {
+    // Locate .env - walk up from cwd to find it
+    const cwd = process.cwd();
+    const envPath = (0, path_1.resolve)(cwd, ".env");
+    let dotenv;
+    try {
+        dotenv = loadEnvFile(envPath);
+    }
+    catch (err) {
+        process.stderr.write(`ERROR: ${err.message}\n`);
+        process.exit(1);
+    }
+    const envVars = process.env;
+    const host = resolveCredential(envVars, dotenv, "MCP_KEY_HOST", "DB_HOST");
+    const port = resolveCredential(envVars, dotenv, "MCP_KEY_PORT", "DB_PORT");
+    const name = resolveCredential(envVars, dotenv, "MCP_KEY_NAME", "DB_NAME");
+    const sslmode = resolveCredential(envVars, dotenv, "MCP_KEY_SSLMODE", "DB_SSLMODE");
+    const user = resolveCredential(envVars, dotenv, "MCP_KEY_USER", "DB_USER");
+    const pass = resolveCredential(envVars, dotenv, "MCP_KEY_PASS", "DB_PASS");
+    const missing = [];
+    if (!host)
+        missing.push(envVars["MCP_KEY_HOST"] ?? "DB_HOST");
+    if (!port)
+        missing.push(envVars["MCP_KEY_PORT"] ?? "DB_PORT");
+    if (!name)
+        missing.push(envVars["MCP_KEY_NAME"] ?? "DB_NAME");
+    if (!sslmode)
+        missing.push(envVars["MCP_KEY_SSLMODE"] ?? "DB_SSLMODE");
+    if (!user)
+        missing.push(envVars["MCP_KEY_USER"] ?? "DB_USER");
+    if (!pass)
+        missing.push(envVars["MCP_KEY_PASS"] ?? "DB_PASS");
+    if (missing.length > 0) {
+        process.stderr.write(`ERROR: Missing keys in .env: ${missing.join(", ")}\n`);
+        process.stderr.write(`Check the mapping in mcp.json (env field > MCP_KEY_*) and the .env file.\n`);
+        process.exit(1);
+    }
+    // Collect tools from args: tool=<name>
+    const tools = process.argv
+        .slice(2)
+        .filter((a) => a.startsWith("tool="))
+        .map((a) => a.slice(5));
+    const enabledTools = tools.length > 0 ? tools : DEFAULT_READONLY_TOOLS;
+    // Write temp tools config
+    const toolsFile = (0, path_1.join)((0, os_1.tmpdir)(), `mcp-pg-tools-${process.pid}.json`);
+    (0, fs_1.writeFileSync)(toolsFile, JSON.stringify({ enabledTools }, null, 2));
+    const connStr = buildConnectionString({
+        host,
+        port,
+        name,
+        sslmode,
+        user,
+        pass
+    });
+    process.env["POSTGRES_CONNECTION_STRING"] = connStr;
+    process.env["NODE_TLS_REJECT_UNAUTHORIZED"] = "0";
+    try {
+        (0, child_process_1.execFileSync)("npx", ["-y", "@henkey/postgres-mcp-server", "--tools-config", toolsFile], { stdio: "inherit", env: process.env });
+    }
+    finally {
+        try {
+            (0, fs_1.unlinkSync)(toolsFile);
+        }
+        catch { }
+    }
+}
+main();

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@edelciomolina/postgres-mcp",
+  "version": "1.0.0",
+  "description": "MCP server wrapper for PostgreSQL - reads credentials from .env with configurable key mapping and safe read-only defaults.",
+  "bin": {
+    "postgres-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@henkey/postgres-mcp-server": "^1.0.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.42",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "Edelcio Molina <https://github.com/edelciomolina>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/edelciomolina/postgres-mcp.git"
+  },
+  "homepage": "https://github.com/edelciomolina/postgres-mcp#readme",
+  "keywords": [
+    "mcp",
+    "postgresql",
+    "postgres",
+    "database",
+    "model-context-protocol",
+    "copilot",
+    "ai",
+    "vscode"
+  ]
+}