easy-pg-admin-mcp 0.1.0

package/README.md

@@ -0,0 +1,139 @@
+# easy-pg-admin-mcp
+
+High-privilege PostgreSQL admin MCP server for database and role/grant management.
+
+This project is a DBA-style tool. It does not provide raw SQL execution and does not manage tables, schemas, views, indexes, triggers, or functions. Use `easy-pg-mcp` for data access and schema/table operations.
+
+## Features
+
+- List, create, inspect, and change owners for databases
+- List, create, update, and drop PostgreSQL roles
+- Grant and revoke role memberships
+- Grant and revoke database-level privileges
+- Protect destructive actions with short-lived confirmation tokens
+
+## Available Tools
+
+| Tool | Description |
+| --- | --- |
+| `pg_list_databases` | List databases in the current PostgreSQL instance |
+| `pg_create_database` | Create a PostgreSQL database |
+| `pg_describe_database` | Inspect a PostgreSQL database |
+| `pg_alter_database_owner` | Change a database owner |
+| `pg_drop_database` | Request database deletion and return a confirmation token |
+| `pg_list_roles` | List PostgreSQL roles |
+| `pg_create_role` | Create a PostgreSQL role without SUPERUSER support |
+| `pg_alter_role_password` | Change a role password |
+| `pg_alter_role_attributes` | Change supported role attributes |
+| `pg_drop_role` | Request role deletion and return a confirmation token |
+| `pg_grant_role` | Grant a role to another role |
+| `pg_revoke_role` | Revoke a role from another role |
+| `pg_show_role_memberships` | Show memberships for a role |
+| `pg_grant_privileges` | Grant database-level privileges to a role |
+| `pg_revoke_privileges` | Revoke database-level privileges from a role |
+| `pg_show_grants` | Show database-level grants for a role |
+| `pg_confirm_task` | Confirm and execute a destructive action token |
+
+## Safety
+
+- No raw SQL passthrough
+- No schema, table, view, index, trigger, or function management
+- SUPERUSER role creation and modification are not supported
+- `pg_drop_database` and `pg_drop_role` require `pg_confirm_task`
+- `pg_drop_role` does not support `REASSIGN OWNED` or `DROP OWNED`
+- Confirmation tokens are random, single-use, and expire quickly
+
+## Configuration
+
+Use environment variables, matching the rest of the `easy-*-mcp` family.
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `PG_CONNECTION_STRING` | Conditional | - | PostgreSQL connection string. Takes precedence when provided |
+| `PG_HOST` | Conditional | - | PostgreSQL host when no connection string is provided |
+| `PG_PORT` | No | `5432` | PostgreSQL port |
+| `PG_USER` | Conditional | - | PostgreSQL admin role name when no connection string is provided |
+| `PG_PASSWORD` | No | - | PostgreSQL password |
+| `PG_DATABASE` | Conditional | - | Default database used for the admin connection |
+| `PG_CONNECTION_LIMIT` | No | `10` | Maximum number of active pool connections |
+| `PG_IDLE_TIMEOUT` | No | `30000` | Idle connection timeout in milliseconds |
+| `PG_ENABLE_KEEP_ALIVE` | No | `true` | Whether TCP keep-alive is enabled |
+| `PG_KEEP_ALIVE_INITIAL_DELAY` | No | `0` | Initial TCP keep-alive delay in milliseconds |
+| `PG_SSL` | No | `false` | Use `true`, `false`, or `no-verify` |
+| `PG_ADMIN_TOKEN_TTL_SECONDS` | No | `120` | Confirmation token lifetime in seconds |
+
+## Example
+
+```env
+PG_HOST=localhost
+PG_PORT=5432
+PG_USER=postgres
+PG_PASSWORD=your_password
+PG_DATABASE=postgres
+PG_SSL=false
+PG_ADMIN_TOKEN_TTL_SECONDS=120
+```
+
+## Claude Desktop Example
+
+```json
+{
+  "mcpServers": {
+    "easy-pg-admin-mcp": {
+      "command": "npx",
+      "args": ["-y", "easy-pg-admin-mcp"],
+      "env": {
+        "PG_HOST": "localhost",
+        "PG_PORT": "5432",
+        "PG_USER": "postgres",
+        "PG_PASSWORD": "your_password",
+        "PG_DATABASE": "postgres",
+        "PG_SSL": "false",
+        "PG_ADMIN_TOKEN_TTL_SECONDS": "120"
+      }
+    }
+  }
+}
+```
+
+## Codex config.toml Example
+
+```
+[mcp_servers.easy-pg-admin-mcp]
+args = ["-y", "easy-pg-admin-mcp"]
+command = "npx"
+enabled = true
+
+[mcp_servers.easy-pg-admin-mcp.env]
+PG_HOST = "localhost"
+PG_PORT = "5432"
+PG_USER = "postgres"
+PG_PASSWORD = "your_password"
+PG_DATABASE = "postgres"
+PG_SSL = "false"
+PG_ADMIN_TOKEN_TTL_SECONDS = "120"
+```
+
+## OpenCode opencode.jsonc Example
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "easy-pg-admin-mcp": {
+      "type": "local",
+      "command": ["npx", "-y", "easy-pg-admin-mcp"],
+      "enabled": true,
+      "environment": {
+        "PG_HOST": "localhost",
+        "PG_PORT": "5432",
+        "PG_USER": "postgres",
+        "PG_PASSWORD": "your_password",
+        "PG_DATABASE": "postgres",
+        "PG_SSL": "false",
+        "PG_ADMIN_TOKEN_TTL_SECONDS": "120",
+      },
+    },
+  },
+}
+```

package/README.zh-TW.md

@@ -0,0 +1,105 @@
+# easy-pg-admin-mcp
+
+一個高權限的 PostgreSQL 管理型 MCP server，專門處理 database、role 與 database-level grants 管理。
+
+這個專案的定位是 DBA 類工具，不提供任意 SQL 執行，也不處理 schema、table、view、index、trigger、function 管理。資料查詢與 schema/table 操作請使用 `easy-pg-mcp`。
+
+## 功能
+
+- 列出、建立、檢視 database，並修改 owner
+- 列出、建立、修改、刪除 PostgreSQL roles
+- 授予與撤銷 role membership
+- 授予與撤銷 database-level privileges
+- 對危險刪除操作提供短效確認 token
+
+## 可用工具
+
+| 工具 | 說明 |
+| --- | --- |
+| `pg_list_databases` | 列出目前 PostgreSQL instance 內的 databases |
+| `pg_create_database` | 建立 PostgreSQL database |
+| `pg_describe_database` | 檢視 PostgreSQL database |
+| `pg_alter_database_owner` | 修改 database owner |
+| `pg_drop_database` | 提出刪除 database 的請求並回傳確認 token |
+| `pg_list_roles` | 列出 PostgreSQL roles |
+| `pg_create_role` | 建立不支援 SUPERUSER 的 PostgreSQL role |
+| `pg_alter_role_password` | 修改 role 密碼 |
+| `pg_alter_role_attributes` | 修改支援的 role attributes |
+| `pg_drop_role` | 提出刪除 role 的請求並回傳確認 token |
+| `pg_grant_role` | 將 role 授予另一個 role |
+| `pg_revoke_role` | 從另一個 role 撤銷 role |
+| `pg_show_role_memberships` | 顯示 role membership |
+| `pg_grant_privileges` | 對 role 授予 database-level privileges |
+| `pg_revoke_privileges` | 從 role 撤銷 database-level privileges |
+| `pg_show_grants` | 顯示 role 的 database-level grants |
+| `pg_confirm_task` | 確認並執行先前產生的危險操作 token |
+
+## 安全性
+
+- 不提供原始 SQL passthrough
+- 不處理 schema、table、view、index、trigger、function 管理
+- 不支援建立或修改 SUPERUSER role
+- `pg_drop_database` 與 `pg_drop_role` 一律要經過 `pg_confirm_task`
+- `pg_drop_role` 不提供 `REASSIGN OWNED` 或 `DROP OWNED`
+- confirmation token 是隨機產生、只能使用一次、且會在短時間後過期
+
+## 設定
+
+請使用環境變數設定，風格與其他 `easy-*-mcp` 專案一致。
+
+| 變數 | 必填 | 預設值 | 說明 |
+| --- | --- | --- | --- |
+| `PG_CONNECTION_STRING` | 條件必填 | - | PostgreSQL connection string；提供時優先使用 |
+| `PG_HOST` | 條件必填 | - | 未提供 connection string 時使用的 PostgreSQL host |
+| `PG_PORT` | 否 | `5432` | PostgreSQL port |
+| `PG_USER` | 條件必填 | - | 未提供 connection string 時使用的 PostgreSQL admin role |
+| `PG_PASSWORD` | 否 | - | PostgreSQL 密碼 |
+| `PG_DATABASE` | 條件必填 | - | 管理連線使用的預設 database |
+| `PG_CONNECTION_LIMIT` | 否 | `10` | pool 最大 active connections |
+| `PG_IDLE_TIMEOUT` | 否 | `30000` | idle connection timeout，單位毫秒 |
+| `PG_ENABLE_KEEP_ALIVE` | 否 | `true` | 是否啟用 TCP keep-alive |
+| `PG_KEEP_ALIVE_INITIAL_DELAY` | 否 | `0` | TCP keep-alive 初始延遲，單位毫秒 |
+| `PG_SSL` | 否 | `false` | 可使用 `true`、`false` 或 `no-verify` |
+| `PG_ADMIN_TOKEN_TTL_SECONDS` | 否 | `120` | confirmation token 的有效秒數 |
+
+## 範例
+
+```env
+PG_HOST=localhost
+PG_PORT=5432
+PG_USER=postgres
+PG_PASSWORD=your_password
+PG_DATABASE=postgres
+PG_SSL=false
+PG_ADMIN_TOKEN_TTL_SECONDS=120
+```
+
+## Claude Desktop 範例
+
+```json
+{
+  "mcpServers": {
+    "easy-pg-admin-mcp": {
+      "command": "npx",
+      "args": ["-y", "easy-pg-admin-mcp"],
+      "env": {
+        "PG_HOST": "localhost",
+        "PG_PORT": "5432",
+        "PG_USER": "postgres",
+        "PG_PASSWORD": "your_password",
+        "PG_DATABASE": "postgres",
+        "PG_SSL": "false",
+        "PG_ADMIN_TOKEN_TTL_SECONDS": "120"
+      }
+    }
+  }
+}
+```
+
+更新設定後，請重新啟動 Claude Desktop。
+
+## 備註
+
+- `pg_drop_database` 與 `pg_drop_role` 不會直接執行
+- 這兩個動作會先產生 token，使用者確認後才會透過 `pg_confirm_task` 真正執行
+- token 是短效且單次使用，不會保留成長期 pending queue

package/build/config.js

@@ -0,0 +1,39 @@
+function parsePositiveInt(value, defaultValue) {
+    const parsed = value ? Number.parseInt(value, 10) : NaN;
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : defaultValue;
+}
+function parseBoolean(value, defaultValue = true) {
+    if (value === undefined)
+        return defaultValue;
+    return value.toLowerCase() !== 'false';
+}
+function parseSslConfig(value) {
+    if (!value || value.toLowerCase() === 'false') {
+        return undefined;
+    }
+    if (value.toLowerCase() === 'true') {
+        return true;
+    }
+    if (value.toLowerCase() === 'no-verify') {
+        return { rejectUnauthorized: false };
+    }
+    return undefined;
+}
+export function parseAdminConfig(env) {
+    return {
+        pg: {
+            connectionString: env.PG_CONNECTION_STRING?.trim() || undefined,
+            host: env.PG_HOST ?? '',
+            port: parsePositiveInt(env.PG_PORT, 5432),
+            user: env.PG_USER ?? '',
+            password: env.PG_PASSWORD,
+            database: env.PG_DATABASE ?? '',
+            connectionLimit: parsePositiveInt(env.PG_CONNECTION_LIMIT, 10),
+            idleTimeout: parsePositiveInt(env.PG_IDLE_TIMEOUT, 30000),
+            enableKeepAlive: parseBoolean(env.PG_ENABLE_KEEP_ALIVE, true),
+            keepAliveInitialDelay: env.PG_KEEP_ALIVE_INITIAL_DELAY ? Number.parseInt(env.PG_KEEP_ALIVE_INITIAL_DELAY, 10) : 0,
+            ssl: parseSslConfig(env.PG_SSL),
+        },
+        tokenTtlSeconds: parsePositiveInt(env.PG_ADMIN_TOKEN_TTL_SECONDS, 120),
+    };
+}

package/build/confirmationStore.js

@@ -0,0 +1,32 @@
+import { randomUUID } from 'node:crypto';
+export function createConfirmationStore(options) {
+    const tasks = new Map();
+    return {
+        create(task) {
+            const token = randomUUID();
+            const now = Date.now();
+            tasks.set(token, {
+                action: task.action,
+                target: task.target,
+                options: task.options,
+                createdAt: now,
+                expiresAt: now + options.defaultTtlMs,
+                used: false,
+            });
+            return token;
+        },
+        consume(token) {
+            const task = tasks.get(token);
+            if (!task) {
+                return undefined;
+            }
+            if (task.used || task.expiresAt <= Date.now()) {
+                tasks.delete(token);
+                return undefined;
+            }
+            task.used = true;
+            tasks.delete(token);
+            return task;
+        },
+    };
+}

package/build/databaseTools.js

@@ -0,0 +1 @@
+export {};

package/build/db.js

@@ -0,0 +1,38 @@
+import { Pool } from 'pg';
+import { parseAdminConfig } from './config.js';
+let pool;
+export function getPool() {
+    if (pool) {
+        return pool;
+    }
+    const config = parseAdminConfig(process.env);
+    if (!config.pg.connectionString && (!config.pg.host || !config.pg.user || !config.pg.database)) {
+        throw new Error('Missing required environment variables for PostgreSQL admin connection.');
+    }
+    pool = new Pool({
+        connectionString: config.pg.connectionString,
+        host: config.pg.connectionString ? undefined : config.pg.host,
+        port: config.pg.connectionString ? undefined : config.pg.port,
+        user: config.pg.connectionString ? undefined : config.pg.user,
+        password: config.pg.connectionString ? undefined : config.pg.password,
+        database: config.pg.connectionString ? undefined : config.pg.database,
+        max: config.pg.connectionLimit,
+        idleTimeoutMillis: config.pg.idleTimeout,
+        keepAlive: config.pg.enableKeepAlive,
+        keepAliveInitialDelayMillis: config.pg.keepAliveInitialDelay,
+        ssl: config.pg.ssl,
+    });
+    return pool;
+}
+export function escapeIdentifier(identifier) {
+    return `"${identifier.replace(/"/g, '""')}"`;
+}
+export async function withClient(callback) {
+    const client = await getPool().connect();
+    try {
+        return await callback(client);
+    }
+    finally {
+        client.release();
+    }
+}

package/build/index.js

@@ -0,0 +1,182 @@
+#!/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 { parseAdminConfig } from './config.js';
+import { createConfirmationStore } from './confirmationStore.js';
+import { getPool } from './db.js';
+import { createAdminHandlers } from './toolHandlers.js';
+const config = parseAdminConfig(process.env);
+const store = createConfirmationStore({ defaultTtlMs: config.tokenTtlSeconds * 1000 });
+getPool();
+const handlers = createAdminHandlers(store, config.tokenTtlSeconds);
+const server = new McpServer({
+    name: 'easy-pg-admin-mcp',
+    version: '0.1.0',
+    description: `PostgreSQL Admin: ${config.pg.connectionString ? 'connection-string' : `${config.pg.host}:${config.pg.port}/${config.pg.database}`}`,
+});
+const roleAttributesSchema = {
+    login: z.boolean().optional(),
+    createdb: z.boolean().optional(),
+    createrole: z.boolean().optional(),
+    inherit: z.boolean().optional(),
+    replication: z.boolean().optional(),
+    bypassrls: z.boolean().optional(),
+    connectionLimit: z.number().int().min(-1).optional(),
+    validUntil: z.string().min(1).nullable().optional(),
+};
+function textJson(value) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    };
+}
+server.registerTool('pg_list_databases', {
+    description: 'List databases in the current PostgreSQL instance.',
+    inputSchema: z.object({}),
+}, async () => textJson(await handlers.listDatabases()));
+server.registerTool('pg_create_database', {
+    description: 'Create a PostgreSQL database.',
+    inputSchema: z.object({
+        database: z.string().min(1),
+        owner: z.string().min(1).optional(),
+        encoding: z.string().min(1).optional(),
+        template: z.string().min(1).optional(),
+        locale: z.string().min(1).optional(),
+    }),
+}, async ({ database, owner, encoding, template, locale }) => textJson(await handlers.createDatabase({ database, owner, encoding, template, locale })));
+server.registerTool('pg_describe_database', {
+    description: 'Inspect a PostgreSQL database definition.',
+    inputSchema: z.object({
+        database: z.string().min(1),
+    }),
+}, async ({ database }) => textJson(await handlers.describeDatabase(database)));
+server.registerTool('pg_alter_database_owner', {
+    description: 'Change the owner of a PostgreSQL database.',
+    inputSchema: z.object({
+        database: z.string().min(1),
+        owner: z.string().min(1),
+    }),
+}, async ({ database, owner }) => textJson(await handlers.alterDatabaseOwner(database, owner)));
+server.registerTool('pg_drop_database', {
+    description: 'Request database deletion and return a short-lived confirmation token.',
+    inputSchema: z.object({
+        database: z.string().min(1),
+        force: z.boolean().optional(),
+    }),
+}, async ({ database, force }) => textJson(await handlers.dropDatabase(database, { force })));
+server.registerTool('pg_list_roles', {
+    description: 'List PostgreSQL roles.',
+    inputSchema: z.object({
+        includeSystem: z.boolean().optional(),
+    }),
+}, async ({ includeSystem }) => textJson(await handlers.listRoles({ includeSystem })));
+server.registerTool('pg_create_role', {
+    description: 'Create a PostgreSQL role. SUPERUSER is intentionally not supported.',
+    inputSchema: z.object({
+        role: z.string().min(1),
+        password: z.string().min(1).optional(),
+        ...roleAttributesSchema,
+    }),
+}, async ({ role, password, login, createdb, createrole, inherit, replication, bypassrls, connectionLimit, validUntil }) => textJson(await handlers.createRole({
+    role,
+    password,
+    login,
+    createdb,
+    createrole,
+    inherit,
+    replication,
+    bypassrls,
+    connectionLimit,
+    validUntil,
+})));
+server.registerTool('pg_alter_role_password', {
+    description: 'Change a PostgreSQL role password.',
+    inputSchema: z.object({
+        role: z.string().min(1),
+        password: z.string().min(1),
+    }),
+}, async ({ role, password }) => textJson(await handlers.alterRolePassword(role, password)));
+server.registerTool('pg_alter_role_attributes', {
+    description: 'Change PostgreSQL role attributes. SUPERUSER is intentionally not supported.',
+    inputSchema: z.object({
+        role: z.string().min(1),
+        ...roleAttributesSchema,
+    }),
+}, async ({ role, login, createdb, createrole, inherit, replication, bypassrls, connectionLimit, validUntil }) => textJson(await handlers.alterRoleAttributes(role, {
+    login,
+    createdb,
+    createrole,
+    inherit,
+    replication,
+    bypassrls,
+    connectionLimit,
+    validUntil,
+})));
+server.registerTool('pg_drop_role', {
+    description: 'Request role deletion and return a short-lived confirmation token.',
+    inputSchema: z.object({
+        role: z.string().min(1),
+    }),
+}, async ({ role }) => textJson(await handlers.dropRole(role)));
+server.registerTool('pg_grant_role', {
+    description: 'Grant a PostgreSQL role to another role.',
+    inputSchema: z.object({
+        role: z.string().min(1),
+        member: z.string().min(1),
+        adminOption: z.boolean().optional(),
+    }),
+}, async ({ role, member, adminOption }) => textJson(await handlers.grantRole({ role, member, adminOption })));
+server.registerTool('pg_revoke_role', {
+    description: 'Revoke a PostgreSQL role from another role.',
+    inputSchema: z.object({
+        role: z.string().min(1),
+        member: z.string().min(1),
+        adminOption: z.boolean().optional(),
+    }),
+}, async ({ role, member, adminOption }) => textJson(await handlers.revokeRole({ role, member, adminOption })));
+server.registerTool('pg_show_role_memberships', {
+    description: 'Show memberships for a PostgreSQL role.',
+    inputSchema: z.object({
+        role: z.string().min(1),
+    }),
+}, async ({ role }) => textJson(await handlers.showRoleMemberships(role)));
+server.registerTool('pg_grant_privileges', {
+    description: 'Grant database-level PostgreSQL privileges to a role.',
+    inputSchema: z.object({
+        role: z.string().min(1),
+        database: z.string().min(1),
+        privileges: z.array(z.string().min(1)).min(1),
+        withGrantOption: z.boolean().optional(),
+    }),
+}, async ({ role, database, privileges, withGrantOption }) => textJson(await handlers.grantPrivileges({ role, database, privileges, withGrantOption })));
+server.registerTool('pg_revoke_privileges', {
+    description: 'Revoke database-level PostgreSQL privileges from a role.',
+    inputSchema: z.object({
+        role: z.string().min(1),
+        database: z.string().min(1),
+        privileges: z.array(z.string().min(1)).min(1),
+        grantOptionFor: z.boolean().optional(),
+    }),
+}, async ({ role, database, privileges, grantOptionFor }) => textJson(await handlers.revokePrivileges({ role, database, privileges, grantOptionFor })));
+server.registerTool('pg_show_grants', {
+    description: 'Show database-level PostgreSQL grants for a role.',
+    inputSchema: z.object({
+        role: z.string().min(1),
+        database: z.string().min(1).optional(),
+    }),
+}, async ({ role, database }) => textJson(await handlers.showGrants({ role, database })));
+server.registerTool('pg_confirm_task', {
+    description: 'Confirm and execute a previously issued destructive action token.',
+    inputSchema: z.object({
+        token: z.string().min(1),
+    }),
+}, async ({ token }) => textJson(await handlers.confirmTask(token)));
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('easy-pg-admin-mcp running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error in main():', error);
+    process.exit(1);
+});

package/build/roleTools.js

@@ -0,0 +1 @@
+export {};

package/build/toolHandlers.js

@@ -0,0 +1,260 @@
+import { escapeIdentifier, getPool } from './db.js';
+import { assertNoSuperuser, formatPrivilegeList, parseRoleAttributes, validateDatabaseName, validateExistingRoleName, validateRoleName, } from './validation.js';
+export function formatError(error, code = 'ADMIN_OPERATION_FAILED') {
+    return {
+        error: error instanceof Error ? error.message : String(error),
+        code,
+    };
+}
+export function createAdminHandlers(store, tokenTtlSeconds) {
+    const pool = getPool();
+    return {
+        listDatabases: async () => {
+            const result = await pool.query(databaseQuery('ORDER BY d.datname'));
+            return result.rows;
+        },
+        createDatabase: async (input) => {
+            const database = validateDatabaseName(input.database);
+            const clauses = [escapeIdentifier(database)];
+            if (input.owner !== undefined) {
+                clauses.push(`OWNER ${escapeIdentifier(validateExistingRoleName(input.owner))}`);
+            }
+            if (input.encoding !== undefined) {
+                clauses.push(`ENCODING ${formatSqlString(validateEncoding(input.encoding))}`);
+            }
+            if (input.template !== undefined) {
+                clauses.push(`TEMPLATE ${escapeIdentifier(validateDatabaseName(input.template))}`);
+            }
+            if (input.locale !== undefined) {
+                clauses.push(`LOCALE ${formatSqlString(validateLocale(input.locale))}`);
+            }
+            await pool.query(`CREATE DATABASE ${clauses.join(' ')}`);
+            return { ok: true, database };
+        },
+        describeDatabase: async (database) => {
+            const safeDatabase = validateDatabaseName(database);
+            const result = await pool.query(databaseQuery('WHERE d.datname = $1'), [safeDatabase]);
+            return result.rows;
+        },
+        alterDatabaseOwner: async (database, owner) => {
+            const safeDatabase = validateDatabaseName(database);
+            const safeOwner = validateExistingRoleName(owner);
+            await pool.query(`ALTER DATABASE ${escapeIdentifier(safeDatabase)} OWNER TO ${escapeIdentifier(safeOwner)}`);
+            return { ok: true, database: safeDatabase, owner: safeOwner };
+        },
+        dropDatabase: async (database, options) => {
+            const safeDatabase = validateDatabaseName(database);
+            await assertDatabaseCanBeDropped(safeDatabase);
+            const token = store.create({ action: 'drop_database', target: safeDatabase, options: { force: Boolean(options?.force) } });
+            return { status: 'confirmation_required', token, expiresInSeconds: tokenTtlSeconds };
+        },
+        listRoles: async (input) => {
+            const result = await pool.query(`
+        SELECT
+          rolname AS role,
+          rolsuper AS superuser,
+          rolinherit AS inherit,
+          rolcreaterole AS "createRole",
+          rolcreatedb AS "createDb",
+          rolcanlogin AS login,
+          rolreplication AS replication,
+          rolbypassrls AS "bypassRls",
+          rolconnlimit AS "connectionLimit",
+          rolvaliduntil AS "validUntil"
+        FROM pg_catalog.pg_roles
+        WHERE ($1::boolean OR rolname !~ '^pg_')
+        ORDER BY rolname
+      `, [Boolean(input?.includeSystem)]);
+            return result.rows;
+        },
+        createRole: async (input) => {
+            assertNoSuperuser(input);
+            const role = validateRoleName(input.role);
+            const clauses = [escapeIdentifier(role)];
+            clauses.push(...roleAttributeClauses(input));
+            if (input.password !== undefined) {
+                clauses.push(`PASSWORD ${formatSqlString(validateRolePassword(input.password))}`);
+            }
+            await pool.query(`CREATE ROLE ${clauses.join(' ')}`);
+            return { ok: true, role };
+        },
+        alterRolePassword: async (role, password) => {
+            const safeRole = validateRoleName(role);
+            await pool.query(`ALTER ROLE ${escapeIdentifier(safeRole)} PASSWORD ${formatSqlString(validateRolePassword(password))}`);
+            return { ok: true, role: safeRole };
+        },
+        alterRoleAttributes: async (role, attributes) => {
+            assertNoSuperuser(attributes);
+            const safeRole = validateRoleName(role);
+            const clauses = roleAttributeClauses(attributes);
+            if (clauses.length === 0) {
+                throw new Error('at least one role attribute is required');
+            }
+            await pool.query(`ALTER ROLE ${escapeIdentifier(safeRole)} ${clauses.join(' ')}`);
+            return { ok: true, role: safeRole };
+        },
+        dropRole: async (role) => {
+            const safeRole = validateRoleName(role);
+            await assertRoleCanBeDropped(safeRole);
+            const token = store.create({ action: 'drop_role', target: safeRole });
+            return { status: 'confirmation_required', token, expiresInSeconds: tokenTtlSeconds };
+        },
+        grantRole: async (input) => {
+            const role = validateExistingRoleName(input.role);
+            const member = validateExistingRoleName(input.member);
+            const adminOption = input.adminOption ? ' WITH ADMIN OPTION' : '';
+            await pool.query(`GRANT ${escapeIdentifier(role)} TO ${escapeIdentifier(member)}${adminOption}`);
+            return { ok: true, role, member, adminOption: Boolean(input.adminOption) };
+        },
+        revokeRole: async (input) => {
+            const role = validateExistingRoleName(input.role);
+            const member = validateExistingRoleName(input.member);
+            const adminOption = input.adminOption ? 'ADMIN OPTION FOR ' : '';
+            await pool.query(`REVOKE ${adminOption}${escapeIdentifier(role)} FROM ${escapeIdentifier(member)}`);
+            return { ok: true, role, member, adminOption: Boolean(input.adminOption) };
+        },
+        showRoleMemberships: async (role) => {
+            const safeRole = validateExistingRoleName(role);
+            const result = await pool.query(`
+        SELECT 'member_of' AS direction, parent.rolname AS role, child.rolname AS member, m.admin_option AS "adminOption"
+        FROM pg_catalog.pg_auth_members m
+        JOIN pg_catalog.pg_roles parent ON parent.oid = m.roleid
+        JOIN pg_catalog.pg_roles child ON child.oid = m.member
+        WHERE child.rolname = $1
+        UNION ALL
+        SELECT 'has_member' AS direction, parent.rolname AS role, child.rolname AS member, m.admin_option AS "adminOption"
+        FROM pg_catalog.pg_auth_members m
+        JOIN pg_catalog.pg_roles parent ON parent.oid = m.roleid
+        JOIN pg_catalog.pg_roles child ON child.oid = m.member
+        WHERE parent.rolname = $1
+        ORDER BY direction, role, member
+      `, [safeRole]);
+            return result.rows;
+        },
+        grantPrivileges: async (input) => {
+            const role = validateExistingRoleName(input.role);
+            const database = validateDatabaseName(input.database);
+            const privileges = formatPrivilegeList(input.privileges);
+            const grantOption = input.withGrantOption ? ' WITH GRANT OPTION' : '';
+            await pool.query(`GRANT ${privileges} ON DATABASE ${escapeIdentifier(database)} TO ${escapeIdentifier(role)}${grantOption}`);
+            return { ok: true, role, database, privileges: input.privileges, withGrantOption: Boolean(input.withGrantOption) };
+        },
+        revokePrivileges: async (input) => {
+            const role = validateExistingRoleName(input.role);
+            const database = validateDatabaseName(input.database);
+            const privileges = formatPrivilegeList(input.privileges);
+            const grantOption = input.grantOptionFor ? 'GRANT OPTION FOR ' : '';
+            await pool.query(`REVOKE ${grantOption}${privileges} ON DATABASE ${escapeIdentifier(database)} FROM ${escapeIdentifier(role)}`);
+            return { ok: true, role, database, privileges: input.privileges, grantOptionFor: Boolean(input.grantOptionFor) };
+        },
+        showGrants: async (input) => {
+            const role = validateExistingRoleName(input.role);
+            const database = input.database === undefined ? null : validateDatabaseName(input.database);
+            const result = await pool.query(`
+        SELECT
+          d.datname AS database,
+          grantee.rolname AS grantee,
+          grantor.rolname AS grantor,
+          acl.privilege_type AS privilege,
+          acl.is_grantable AS "isGrantable"
+        FROM pg_catalog.pg_database d
+        CROSS JOIN LATERAL pg_catalog.aclexplode(d.datacl) AS acl
+        JOIN pg_catalog.pg_roles grantee ON grantee.oid = acl.grantee
+        JOIN pg_catalog.pg_roles grantor ON grantor.oid = acl.grantor
+        WHERE grantee.rolname = $1
+          AND ($2::text IS NULL OR d.datname = $2)
+        ORDER BY d.datname, acl.privilege_type
+      `, [role, database]);
+            return result.rows;
+        },
+        confirmTask: async (token) => {
+            const task = store.consume(token);
+            if (!task) {
+                return { status: 'error', error: 'token not found or expired', code: 'TOKEN_INVALID' };
+            }
+            if (task.action === 'drop_database') {
+                const force = Boolean(task.options?.force);
+                await assertDatabaseCanBeDropped(task.target);
+                await pool.query(`DROP DATABASE ${escapeIdentifier(task.target)}${force ? ' WITH (FORCE)' : ''}`);
+                return { status: 'confirmed', ok: true, action: task.action, target: task.target, force };
+            }
+            await assertRoleCanBeDropped(task.target);
+            await pool.query(`DROP ROLE ${escapeIdentifier(task.target)}`);
+            return { status: 'confirmed', ok: true, action: task.action, target: task.target };
+        },
+    };
+}
+function databaseQuery(suffix) {
+    return `
+    SELECT
+      d.datname AS name,
+      pg_catalog.pg_get_userbyid(d.datdba) AS owner,
+      pg_catalog.pg_encoding_to_char(d.encoding) AS encoding,
+      d.datcollate AS collation,
+      d.datctype AS ctype,
+      d.datallowconn AS "allowConnections",
+      d.datconnlimit AS "connectionLimit",
+      d.datistemplate AS "isTemplate"
+    FROM pg_catalog.pg_database d
+    ${suffix}
+  `;
+}
+function roleAttributeClauses(input) {
+    const rawClauses = parseRoleAttributes(input);
+    const clauses = [];
+    for (const clause of rawClauses) {
+        if (clause === 'VALID UNTIL') {
+            clauses.push(`VALID UNTIL ${formatSqlString(validateValidUntil(input.validUntil))}`);
+        }
+        else {
+            clauses.push(clause);
+        }
+    }
+    return clauses;
+}
+async function assertDatabaseCanBeDropped(database) {
+    const result = await getPool().query('SELECT current_database() AS current_database');
+    if (result.rows[0]?.current_database === database) {
+        throw new Error('cannot drop the current connection database');
+    }
+    const databaseResult = await getPool().query('SELECT datistemplate AS "isTemplate" FROM pg_catalog.pg_database WHERE datname = $1', [database]);
+    if (databaseResult.rows.length === 0) {
+        throw new Error('database not found');
+    }
+    if (databaseResult.rows[0].isTemplate) {
+        throw new Error('cannot drop a template database');
+    }
+}
+async function assertRoleCanBeDropped(role) {
+    const result = await getPool().query('SELECT current_user AS current_user');
+    if (result.rows[0]?.current_user === role) {
+        throw new Error('cannot drop the current connection role');
+    }
+}
+function validateEncoding(value) {
+    if (!value || value.includes('\0')) {
+        throw new Error('invalid encoding');
+    }
+    return value;
+}
+function validateLocale(value) {
+    if (!value || value.includes('\0')) {
+        throw new Error('invalid locale');
+    }
+    return value;
+}
+function validateRolePassword(value) {
+    if (value.includes('\0')) {
+        throw new Error('invalid role password');
+    }
+    return value;
+}
+function validateValidUntil(value) {
+    if (value === undefined || value === null || !value.trim() || value.includes('\0')) {
+        throw new Error('invalid validUntil');
+    }
+    return value;
+}
+function formatSqlString(value) {
+    return `'${value.replace(/'/g, "''")}'`;
+}

package/build/validation.js

@@ -0,0 +1,74 @@
+const DATABASE_PRIVILEGES = new Set(['CONNECT', 'CREATE', 'TEMPORARY', 'TEMP', 'ALL']);
+export function validateDatabaseName(name) {
+    return validateIdentifierName(name, 'database name');
+}
+export function validateRoleName(name) {
+    const role = validateIdentifierName(name, 'role name');
+    if (role.toLowerCase().startsWith('pg_')) {
+        throw new Error('system role names starting with pg_ are not allowed');
+    }
+    return role;
+}
+export function validateExistingRoleName(name) {
+    return validateIdentifierName(name, 'role name');
+}
+export function parsePrivilegeList(input) {
+    const privileges = input.map((privilege) => privilege.trim().toUpperCase());
+    for (const privilege of privileges) {
+        if (!DATABASE_PRIVILEGES.has(privilege)) {
+            throw new Error(`invalid privilege: ${privilege}`);
+        }
+    }
+    if (privileges.includes('ALL') && privileges.length > 1) {
+        throw new Error('ALL cannot be combined with other privileges');
+    }
+    return privileges.map((privilege) => privilege === 'TEMP' ? 'TEMPORARY' : privilege);
+}
+export function formatPrivilegeList(input) {
+    const privileges = parsePrivilegeList(input);
+    return privileges[0] === 'ALL' ? 'ALL PRIVILEGES' : privileges.join(', ');
+}
+export function parseRoleAttributes(input) {
+    const clauses = [];
+    pushBooleanClause(clauses, input.login, 'LOGIN', 'NOLOGIN');
+    pushBooleanClause(clauses, input.createdb, 'CREATEDB', 'NOCREATEDB');
+    pushBooleanClause(clauses, input.createrole, 'CREATEROLE', 'NOCREATEROLE');
+    pushBooleanClause(clauses, input.inherit, 'INHERIT', 'NOINHERIT');
+    pushBooleanClause(clauses, input.replication, 'REPLICATION', 'NOREPLICATION');
+    pushBooleanClause(clauses, input.bypassrls, 'BYPASSRLS', 'NOBYPASSRLS');
+    if (input.connectionLimit !== undefined) {
+        if (!Number.isInteger(input.connectionLimit) || input.connectionLimit < -1) {
+            throw new Error('connectionLimit must be an integer greater than or equal to -1');
+        }
+        clauses.push(`CONNECTION LIMIT ${input.connectionLimit}`);
+    }
+    if (input.validUntil !== undefined) {
+        if (input.validUntil === null) {
+            clauses.push("VALID UNTIL 'infinity'");
+        }
+        else if (!input.validUntil.trim()) {
+            throw new Error('validUntil cannot be empty');
+        }
+        else {
+            clauses.push('VALID UNTIL');
+        }
+    }
+    return clauses;
+}
+export function assertNoSuperuser(input) {
+    if (input.superuser !== undefined) {
+        throw new Error('SUPERUSER role management is not supported by this MCP server');
+    }
+}
+function validateIdentifierName(name, label) {
+    if (!name || name.includes('\0')) {
+        throw new Error(`invalid ${label}`);
+    }
+    return name;
+}
+function pushBooleanClause(clauses, value, enabled, disabled) {
+    if (value === undefined) {
+        return;
+    }
+    clauses.push(value ? enabled : disabled);
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "easy-pg-admin-mcp",
+  "version": "0.1.0",
+  "description": "High privilege PostgreSQL admin MCP server for database and role management",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "postgresql",
+    "postgres",
+    "database",
+    "admin",
+    "dba",
+    "claude",
+    "codex",
+    "opencode"
+  ],
+  "homepage": "https://github.com/chenkumi/easy-pg-admin-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/chenkumi/easy-pg-admin-mcp/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chenkumi/easy-pg-admin-mcp.git"
+  },
+  "license": "MIT",
+  "author": "Chenkumi",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "easy-pg-admin-mcp": "build/index.js"
+  },
+  "directories": {
+    "test": "test"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "README.zh-TW.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node build/index.js",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "pg": "^8.21.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.3",
+    "@types/pg": "^8.20.0",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}