@spec-this/mcp-postgres-sql 1.0.0

package/README.md

@@ -0,0 +1,183 @@
+# MCP PostgreSQL
+
+A Model Context Protocol (MCP) server that provides PostgreSQL database query capabilities with built-in connection management.
+
+## Features
+
+- PostgreSQL database support using the `pg` driver
+- Connection management via MCP tools (add, list, update, remove)
+- Connections stored in `~/.mcp-postgres-sql/connections.json`
+- No environment variables needed — manage connections through the tools
+- Passwords hidden when listing connections
+- SSL support
+- Stdio transport for MCP integration
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## MCP Configuration
+
+Add to your Claude Desktop or Claude Code MCP config:
+
+```json
+{
+  "mcpServers": {
+    "postgres": {
+      "command": "node",
+      "args": ["/path/to/mcp-postgres-sql/dist/index.js"]
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "postgres": {
+      "command": "mcp-postgres-sql"
+    }
+  }
+}
+```
+
+## Tools
+
+### `add_connection`
+
+Save a new PostgreSQL connection configuration.
+
+| Parameter  | Type    | Required | Default | Description        |
+|------------|---------|----------|---------|--------------------|
+| `name`     | string  | yes      |         | Name for this connection |
+| `host`     | string  | yes      |         | Database host      |
+| `port`     | number  | no       | 5432    | Database port      |
+| `database` | string  | yes      |         | Database name      |
+| `user`     | string  | yes      |         | Database user      |
+| `password` | string  | yes      |         | Database password  |
+| `ssl`      | boolean | no       | false   | Use SSL connection |
+
+### `list_connections`
+
+List all saved connections. Passwords are hidden from the output.
+
+### `update_connection`
+
+Update an existing connection. Only the fields you provide will be changed.
+
+| Parameter  | Type    | Required | Description              |
+|------------|---------|----------|--------------------------|
+| `name`     | string  | yes      | Connection name to update |
+| `host`     | string  | no       | New host                 |
+| `port`     | number  | no       | New port                 |
+| `database` | string  | no       | New database name        |
+| `user`     | string  | no       | New user                 |
+| `password` | string  | no       | New password             |
+| `ssl`      | boolean | no       | New SSL setting          |
+
+### `remove_connection`
+
+Remove a saved connection. If this is the active connection, it will be disconnected first.
+
+| Parameter | Type   | Required | Description              |
+|-----------|--------|----------|--------------------------|
+| `name`    | string | yes      | Connection name to remove |
+
+### `connect`
+
+Connect to a saved connection by name. Disconnects any existing connection first.
+
+| Parameter | Type   | Required | Description                  |
+|-----------|--------|----------|------------------------------|
+| `name`    | string | yes      | Connection name to connect to |
+
+### `disconnect`
+
+Disconnect from the current database.
+
+### `query`
+
+Execute a SQL query against the connected database.
+
+| Parameter | Type   | Required | Description          |
+|-----------|--------|----------|----------------------|
+| `sql`     | string | yes      | The SQL query to run |
+
+Returns JSON-formatted query results.
+
+## Usage Example
+
+Once configured as an MCP server, use the tools in sequence:
+
+```
+1. add_connection  →  name: "local-dev", host: "localhost", database: "myapp", user: "postgres", password: "secret"
+2. connect         →  name: "local-dev"
+3. query           →  sql: "SELECT * FROM users LIMIT 10"
+4. disconnect
+```
+
+## Connection Storage
+
+Connections are stored at `~/.mcp-postgres-sql/connections.json`:
+
+```json
+{
+  "connections": {
+    "local-dev": {
+      "host": "localhost",
+      "port": 5432,
+      "database": "myapp",
+      "user": "postgres",
+      "password": "secret",
+      "ssl": false
+    }
+  }
+}
+```
+
+The directory is created with `0700` permissions and the file with `0600` permissions.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Build for production
+npm run build
+
+# Type check
+npx tsc --noEmit
+```
+
+## Testing
+
+Tests require Docker.
+
+```bash
+# Start PostgreSQL test container
+npm run test:up
+
+# Run tests
+npm test
+
+# Stop and clean up
+npm run test:down
+
+# Or run everything at once
+npm run test:ci
+```
+
+The test container runs PostgreSQL 16 on port 5433 to avoid conflicts with any local instance.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,394 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import pg from "pg";
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { join } from "path";
+import { homedir } from "os";
+import { existsSync } from "fs";
+const { Client } = pg;
+class ConnectionManager {
+    configPath;
+    constructor() {
+        const configDir = join(homedir(), ".mcp-postgres-sql");
+        this.configPath = join(configDir, "connections.json");
+    }
+    async ensureConfigDir() {
+        const configDir = join(homedir(), ".mcp-postgres-sql");
+        if (!existsSync(configDir)) {
+            await mkdir(configDir, { recursive: true, mode: 0o700 });
+        }
+    }
+    async loadConnections() {
+        await this.ensureConfigDir();
+        if (!existsSync(this.configPath)) {
+            return { connections: {} };
+        }
+        try {
+            const data = await readFile(this.configPath, "utf-8");
+            return JSON.parse(data);
+        }
+        catch (error) {
+            console.error("Error loading connections:", error);
+            return { connections: {} };
+        }
+    }
+    async saveConnections(data) {
+        await this.ensureConfigDir();
+        await writeFile(this.configPath, JSON.stringify(data, null, 2), {
+            encoding: "utf-8",
+            mode: 0o600,
+        });
+    }
+    async addConnection(name, config) {
+        const data = await this.loadConnections();
+        data.connections[name] = config;
+        await this.saveConnections(data);
+    }
+    async updateConnection(name, config) {
+        const data = await this.loadConnections();
+        if (!data.connections[name]) {
+            throw new Error(`Connection '${name}' not found`);
+        }
+        data.connections[name] = {
+            ...data.connections[name],
+            ...config,
+        };
+        await this.saveConnections(data);
+    }
+    async removeConnection(name) {
+        const data = await this.loadConnections();
+        if (!data.connections[name]) {
+            throw new Error(`Connection '${name}' not found`);
+        }
+        delete data.connections[name];
+        await this.saveConnections(data);
+    }
+    async getConnection(name) {
+        const data = await this.loadConnections();
+        if (!data.connections[name]) {
+            throw new Error(`Connection '${name}' not found`);
+        }
+        return data.connections[name];
+    }
+    async listConnections() {
+        const data = await this.loadConnections();
+        const result = {};
+        for (const [name, config] of Object.entries(data.connections)) {
+            const { password, ...safeConfig } = config;
+            result[name] = safeConfig;
+        }
+        return result;
+    }
+}
+class PostgresDatabase {
+    client = null;
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    async connect() {
+        this.client = new Client({
+            host: this.config.host,
+            port: this.config.port,
+            database: this.config.database,
+            user: this.config.user,
+            password: this.config.password,
+            ssl: this.config.ssl ? { rejectUnauthorized: false } : false,
+        });
+        await this.client.connect();
+    }
+    async query(sql) {
+        if (!this.client) {
+            throw new Error("Not connected to database");
+        }
+        const result = await this.client.query(sql);
+        return result.rows;
+    }
+    async disconnect() {
+        if (this.client) {
+            await this.client.end();
+            this.client = null;
+        }
+    }
+    isConnected() {
+        return this.client !== null;
+    }
+}
+async function main() {
+    const connectionManager = new ConnectionManager();
+    let database = null;
+    let currentConnectionName = null;
+    const server = new McpServer({
+        name: "mcp-postgres-sql",
+        description: "PostgreSQL query server for MCP with connection management",
+        version: "1.0.0",
+    });
+    // Tool: add_connection
+    server.tool("add_connection", "Add a new PostgreSQL connection configuration", {
+        name: z.string().describe("Name for this connection"),
+        host: z.string().describe("Database host"),
+        port: z.number().default(5432).describe("Database port"),
+        database: z.string().describe("Database name"),
+        user: z.string().describe("Database user"),
+        password: z.string().describe("Database password"),
+        ssl: z.boolean().default(false).describe("Use SSL connection"),
+    }, async ({ name, host, port, database, user, password, ssl }) => {
+        try {
+            await connectionManager.addConnection(name, {
+                host,
+                port,
+                database,
+                user,
+                password,
+                ssl,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Connection '${name}' added successfully`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Error adding connection: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+    // Tool: list_connections
+    server.tool("list_connections", "List all saved PostgreSQL connections (passwords hidden)", {}, async () => {
+        try {
+            const connections = await connectionManager.listConnections();
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(connections, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Error listing connections: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+    // Tool: update_connection
+    server.tool("update_connection", "Update an existing PostgreSQL connection configuration", {
+        name: z.string().describe("Name of the connection to update"),
+        host: z.string().optional().describe("Database host"),
+        port: z.number().optional().describe("Database port"),
+        database: z.string().optional().describe("Database name"),
+        user: z.string().optional().describe("Database user"),
+        password: z.string().optional().describe("Database password"),
+        ssl: z.boolean().optional().describe("Use SSL connection"),
+    }, async ({ name, host, port, database, user, password, ssl }) => {
+        try {
+            const updates = {};
+            if (host !== undefined)
+                updates.host = host;
+            if (port !== undefined)
+                updates.port = port;
+            if (database !== undefined)
+                updates.database = database;
+            if (user !== undefined)
+                updates.user = user;
+            if (password !== undefined)
+                updates.password = password;
+            if (ssl !== undefined)
+                updates.ssl = ssl;
+            await connectionManager.updateConnection(name, updates);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Connection '${name}' updated successfully`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Error updating connection: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+    // Tool: remove_connection
+    server.tool("remove_connection", "Remove a saved PostgreSQL connection", {
+        name: z.string().describe("Name of the connection to remove"),
+    }, async ({ name }) => {
+        try {
+            // Disconnect if this is the current connection
+            if (currentConnectionName === name && database) {
+                await database.disconnect();
+                database = null;
+                currentConnectionName = null;
+            }
+            await connectionManager.removeConnection(name);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Connection '${name}' removed successfully`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Error removing connection: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+    // Tool: connect
+    server.tool("connect", "Connect to a saved PostgreSQL database connection", {
+        name: z.string().describe("Name of the connection to use"),
+    }, async ({ name }) => {
+        try {
+            // Disconnect from current connection if any
+            if (database) {
+                await database.disconnect();
+                database = null;
+                currentConnectionName = null;
+            }
+            const config = await connectionManager.getConnection(name);
+            database = new PostgresDatabase(config);
+            await database.connect();
+            currentConnectionName = name;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Connected to '${name}' at ${config.host}:${config.port}/${config.database}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            database = null;
+            currentConnectionName = null;
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Error connecting to database: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+    // Tool: disconnect
+    server.tool("disconnect", "Disconnect from the current PostgreSQL database", {}, async () => {
+        try {
+            if (!database) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "No active database connection",
+                        },
+                    ],
+                };
+            }
+            const connectionName = currentConnectionName;
+            await database.disconnect();
+            database = null;
+            currentConnectionName = null;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Disconnected from '${connectionName}'`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Error disconnecting: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+    // Tool: query
+    server.tool("query", "Execute a SQL query against the connected PostgreSQL database", {
+        sql: z.string().describe("The SQL query to execute"),
+    }, async ({ sql }) => {
+        try {
+            if (!database || !database.isConnected()) {
+                throw new Error("Not connected to any database. Use 'connect' tool first.");
+            }
+            const results = await database.query(sql);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(results, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Error executing query: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP PostgreSQL Server running on stdio");
+    // Graceful shutdown handlers
+    const shutdown = async () => {
+        if (database) {
+            await database.disconnect();
+        }
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@spec-this/mcp-postgres-sql",
+  "version": "1.0.0",
+  "description": "MCP server for PostgreSQL database queries",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "mcp-postgres-sql": "dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 dist/index.js",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test:up": "docker compose up -d",
+    "test:down": "docker compose down -v",
+    "test": "tsx --test test/*.test.ts",
+    "test:ci": "docker compose up -d && sleep 10 && npm test && docker compose down -v",
+    "semantic-release": "semantic-release"
+  },
+  "keywords": [
+    "modelcontextprotocol",
+    "mcp",
+    "server",
+    "postgresql",
+    "postgres",
+    "database"
+  ],
+  "author": "",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.2",
+    "pg": "^8.13.1"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/node": "^22.13.14",
+    "@types/pg": "^8.11.10",
+    "semantic-release": "^24.0.0",
+    "tsx": "^4.17.0",
+    "typescript": "^5.8.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}