@delta-si/mcp-pg-multidb 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# @delta-si/mcp-pg-multidb
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Servidor [MCP](https://modelcontextprotocol.io) para PostgreSQL que acessa **qualquer database do servidor com uma única configuração**. O nome do database é informado em cada chamada de ferramenta, então não é preciso uma entrada no `mcp.json` por banco.
+
+Por padrão é **somente leitura**: toda consulta roda em `BEGIN TRANSACTION READ ONLY` e aceita um único comando SQL por chamada.
+
+## Ferramentas
+
+| Ferramenta | Parâmetros | Descrição |
+|---|---|---|
+| `list_databases` | — | Lista os databases do servidor |
+| `list_schemas` | `database` | Lista os schemas |
+| `list_tables` | `database`, `schema` (padrão `public`) | Lista tabelas e views |
+| `describe_table` | `database`, `table`, `schema` | Colunas, tipos, defaults, PK/FK/UNIQUE |
+| `query` | `database`, `sql`, `params` | SQL somente leitura, com parâmetros `$1, $2...` |
+| `execute` | `database`, `sql`, `params` | SQL com escrita e `COMMIT`. Só existe com `PG_ALLOW_WRITE=true` |
+
+## Configuração
+
+Exemplo de `mcp.json` (Kiro, Claude Desktop, VS Code e outros clientes MCP):
+
+```json
+{
+  "mcpServers": {
+    "pg-multidb": {
+      "command": "npx",
+      "args": ["-y", "@delta-si/mcp-pg-multidb@1.0.0"],
+      "env": {
+        "PGHOST": "localhost",
+        "PGPORT": "5432",
+        "PGUSER": "postgres",
+        "PG_ALLOW_WRITE": "false"
+      },
+      "autoApprove": ["list_databases", "list_schemas", "list_tables", "describe_table", "query"]
+    }
+  }
+}
+```
+
+Fixe a versão no `args` para não receber atualizações sem revisar.
+
+### Variáveis de ambiente
+
+| Variável | Padrão | Descrição |
+|---|---|---|
+| `PGHOST` | `localhost` | Host do PostgreSQL |
+| `PGPORT` | `5432` | Porta |
+| `PGUSER` | `postgres` | Usuário |
+| `PGPASSWORD` | — | Senha. Prefira o arquivo de senhas (abaixo) |
+| `PG_MAINTENANCE_DB` | `postgres` | Database usado para listar os demais |
+| `PG_ALLOW_WRITE` | `false` | `true` habilita a ferramenta `execute` |
+| `PG_MAX_ROWS` | `500` | Máximo de linhas devolvidas por consulta |
+| `PG_STATEMENT_TIMEOUT` | `30000` | Timeout por comando, em ms |
+
+### Senha fora do mcp.json
+
+Sem `PGPASSWORD`, o driver lê o arquivo de senhas padrão do PostgreSQL:
+
+- Windows: `%APPDATA%\postgresql\pgpass.conf`
+- Linux/macOS: `~/.pgpass` (com `chmod 600`)
+
+Formato, uma linha por servidor (`*` vale para qualquer database):
+
+```
+localhost:5432:*:postgres:suasenha
+```
+
+## Segurança
+
+- Use um usuário com permissão somente de leitura sempre que possível. O modo read-only do servidor é uma segunda barreira, não a única.
+- Com `query` no `autoApprove`, o agente executa qualquer `SELECT` em qualquer database do servidor sem pedir confirmação.
+- Não habilite `PG_ALLOW_WRITE` apontando para bancos de produção.
+
+## Requisitos
+
+Node.js 18 ou superior.
+
+## Licença
+
+MIT

package/index.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+// mcp-pg-multidb: MCP server PostgreSQL multi-database.
+// Conecta no host configurado e recebe o nome do database em cada chamada de ferramenta,
+// então não é preciso fixar o database no mcp.json.
+//
+// Variáveis de ambiente:
+//   PGHOST (localhost), PGPORT (5432), PGUSER (postgres), PGPASSWORD
+//     sem PGPASSWORD, o driver pg usa o pgpass.conf / .pgpass do usuário
+//   PG_MAINTENANCE_DB=postgres  database usado para listar os demais
+//   PG_ALLOW_WRITE=true      habilita a ferramenta "execute" (padrão: somente leitura)
+//   PG_MAX_ROWS=500          limite de linhas devolvidas por consulta
+//   PG_STATEMENT_TIMEOUT=30000  timeout por comando, em ms
+
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import pg from "pg";
+
+const { name: PKG_NAME, version: PKG_VERSION } = createRequire(import.meta.url)("./package.json");
+const SERVER_NAME = "mcp-pg-multidb";
+
+const config = {
+  host: process.env.PGHOST || "localhost",
+  port: Number(process.env.PGPORT || 5432),
+  user: process.env.PGUSER || "postgres",
+  password: process.env.PGPASSWORD,
+};
+const ALLOW_WRITE = String(process.env.PG_ALLOW_WRITE).toLowerCase() === "true";
+const MAX_ROWS = Number(process.env.PG_MAX_ROWS || 500);
+const STATEMENT_TIMEOUT = Number(process.env.PG_STATEMENT_TIMEOUT || 30000);
+const MAINTENANCE_DB = process.env.PG_MAINTENANCE_DB || "postgres";
+
+// Um pool pequeno por database, criado sob demanda.
+const pools = new Map();
+
+function getPool(database) {
+  let pool = pools.get(database);
+  if (!pool) {
+    pool = new pg.Pool({
+      ...config,
+      database,
+      max: 3,
+      idleTimeoutMillis: 60000,
+      statement_timeout: STATEMENT_TIMEOUT,
+      application_name: SERVER_NAME,
+    });
+    // Evita derrubar o processo por erro em conexão ociosa.
+    pool.on("error", (err) => console.error(`[pool ${database}]`, err.message));
+    pools.set(database, pool);
+  }
+  return pool;
+}
+
+// Lista de databases existentes, usada para validar o nome recebido.
+// Sem pg_database_size: em bancos grandes ele estoura o statement_timeout.
+let dbCache = { at: 0, names: [] };
+
+async function listDatabases(force = false) {
+  if (force || Date.now() - dbCache.at > 30000) {
+    const { rows } = await getPool(MAINTENANCE_DB).query(
+      `SELECT datname FROM pg_database
+        WHERE datistemplate = false AND datallowconn = true
+        ORDER BY datname`
+    );
+    dbCache = { at: Date.now(), names: rows.map((r) => r.datname) };
+  }
+  return dbCache.names;
+}
+
+async function assertDatabase(database) {
+  let dbs = await listDatabases();
+  // Banco criado há pouco pode não estar no cache.
+  if (!dbs.includes(database)) dbs = await listDatabases(true);
+  if (!dbs.includes(database)) {
+    throw new Error(`Database "${database}" não encontrado. Disponíveis: ${dbs.join(", ")}`);
+  }
+}
+
+// Executa um único comando (protocolo estendido não aceita múltiplos statements,
+// o que impede escapar da transação read-only com "COMMIT; ...").
+async function run(database, sql, params = [], { readOnly = true } = {}) {
+  await assertDatabase(database);
+  const client = await getPool(database).connect();
+  try {
+    await client.query(readOnly ? "BEGIN TRANSACTION READ ONLY" : "BEGIN");
+    const result = await client.query({ text: sql, values: params, queryMode: "extended" });
+    await client.query(readOnly ? "ROLLBACK" : "COMMIT");
+    return result;
+  } catch (err) {
+    await client.query("ROLLBACK").catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+function ok(data) {
+  const text = JSON.stringify(data, (_k, v) => (typeof v === "bigint" ? v.toString() : v), 2);
+  return { content: [{ type: "text", text }] };
+}
+
+function fail(err) {
+  return { content: [{ type: "text", text: `Erro: ${err.message}` }], isError: true };
+}
+
+function formatResult(result) {
+  const rows = result.rows || [];
+  return {
+    command: result.command,
+    rowCount: result.rowCount,
+    truncated: rows.length > MAX_ROWS,
+    rows: rows.slice(0, MAX_ROWS),
+  };
+}
+
+const databaseArg = z.string().min(1).describe("Nome do database no servidor PostgreSQL");
+const paramsArg = z
+  .array(z.union([z.string(), z.number(), z.boolean(), z.null()]))
+  .optional()
+  .describe("Parâmetros posicionais ($1, $2, ...)");
+
+const server = new McpServer({ name: SERVER_NAME, version: PKG_VERSION });
+
+server.registerTool(
+  "list_databases",
+  { description: `Lista os databases disponíveis em ${config.host}:${config.port}` },
+  async () => {
+    try {
+      return ok(await listDatabases(true));
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+
+server.registerTool(
+  "list_schemas",
+  { description: "Lista os schemas de um database", inputSchema: { database: databaseArg } },
+  async ({ database }) => {
+    try {
+      const r = await run(
+        database,
+        `SELECT schema_name FROM information_schema.schemata
+          WHERE schema_name NOT IN ('pg_catalog', 'information_schema')
+            AND schema_name NOT LIKE 'pg_toast%' AND schema_name NOT LIKE 'pg_temp%'
+          ORDER BY schema_name`
+      );
+      return ok(r.rows.map((x) => x.schema_name));
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+
+server.registerTool(
+  "list_tables",
+  {
+    description: "Lista tabelas e views de um schema",
+    inputSchema: { database: databaseArg, schema: z.string().default("public") },
+  },
+  async ({ database, schema }) => {
+    try {
+      const r = await run(
+        database,
+        `SELECT table_name, table_type FROM information_schema.tables
+          WHERE table_schema = $1 ORDER BY table_name`,
+        [schema]
+      );
+      return ok(r.rows);
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+
+server.registerTool(
+  "describe_table",
+  {
+    description: "Mostra colunas, tipos, nulidade, defaults e chaves de uma tabela",
+    inputSchema: {
+      database: databaseArg,
+      table: z.string().min(1),
+      schema: z.string().default("public"),
+    },
+  },
+  async ({ database, table, schema }) => {
+    try {
+      const cols = await run(
+        database,
+        `SELECT column_name, data_type, character_maximum_length, is_nullable, column_default
+           FROM information_schema.columns
+          WHERE table_schema = $1 AND table_name = $2
+          ORDER BY ordinal_position`,
+        [schema, table]
+      );
+      const keys = await run(
+        database,
+        `SELECT tc.constraint_type, tc.constraint_name, kcu.column_name,
+                ccu.table_name AS ref_table, ccu.column_name AS ref_column
+           FROM information_schema.table_constraints tc
+           JOIN information_schema.key_column_usage kcu
+             ON kcu.constraint_name = tc.constraint_name AND kcu.table_schema = tc.table_schema
+           LEFT JOIN information_schema.constraint_column_usage ccu
+             ON ccu.constraint_name = tc.constraint_name AND tc.constraint_type = 'FOREIGN KEY'
+          WHERE tc.table_schema = $1 AND tc.table_name = $2
+            AND tc.constraint_type IN ('PRIMARY KEY', 'FOREIGN KEY', 'UNIQUE')
+          ORDER BY tc.constraint_type, tc.constraint_name`,
+        [schema, table]
+      );
+      if (cols.rows.length === 0) throw new Error(`Tabela ${schema}.${table} não encontrada em ${database}`);
+      return ok({ columns: cols.rows, constraints: keys.rows });
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+
+server.registerTool(
+  "query",
+  {
+    description: `Executa um único comando SQL somente leitura (transação READ ONLY). Retorna até ${MAX_ROWS} linhas.`,
+    inputSchema: { database: databaseArg, sql: z.string().min(1), params: paramsArg },
+  },
+  async ({ database, sql, params }) => {
+    try {
+      return ok(formatResult(await run(database, sql, params ?? [])));
+    } catch (err) {
+      return fail(err);
+    }
+  }
+);
+
+if (ALLOW_WRITE) {
+  server.registerTool(
+    "execute",
+    {
+      description: "Executa um único comando SQL com escrita (INSERT/UPDATE/DELETE/DDL) e faz COMMIT.",
+      inputSchema: { database: databaseArg, sql: z.string().min(1), params: paramsArg },
+    },
+    async ({ database, sql, params }) => {
+      try {
+        return ok(formatResult(await run(database, sql, params ?? [], { readOnly: false })));
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  );
+}
+
+async function shutdown() {
+  await Promise.allSettled([...pools.values()].map((p) => p.end()));
+  process.exit(0);
+}
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);
+
+await server.connect(new StdioServerTransport());
+console.error(
+  `${PKG_NAME}@${PKG_VERSION} pronto (${config.user}@${config.host}:${config.port}, escrita ${ALLOW_WRITE ? "ON" : "OFF"})`
+);

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@delta-si/mcp-pg-multidb",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "MCP server para PostgreSQL que acessa qualquer database do servidor com uma única configuração; o database é escolhido em cada chamada",
+  "type": "module",
+  "main": "index.mjs",
+  "bin": {
+    "mcp-pg-multidb": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "postgres",
+    "postgresql",
+    "multi-database"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "pg": "8.23.1",
+    "zod": "4.6.7"
+  }
+}