easy-pg-mcp 1.0.1 → 1.1.2

package/MANUAL.md

@@ -0,0 +1,120 @@
+# easy-pg-mcp Manual
+
+`easy-pg-mcp` 是一個用來操作 PostgreSQL 的 MCP server，提供查詢、寫入、批次執行、CSV 匯入，以及 schema / 權限檢查工具。
+
+## Overview
+
+適合用在：
+- PostgreSQL 資料查詢
+- 參數化寫入
+- `RETURNING` 型流程
+- 需要 CTE、複雜 join、聚合查詢的場景
+
+不適合用在：
+- 多語句 SQL
+- 直接字串拼接參數
+- 過度依賴隱式型別轉換
+
+## When to Consult This Manual
+
+如果你遇到以下情況，先看這份手冊：
+- 不確定 `pg_query`、`pg_execute`、`pg_batch_execute` 要怎麼用
+- SQL 被拒絕或回傳錯誤
+- 不確定 `$1, $2, ...` 參數要怎麼綁定
+- 不確定哪些 SQL 寫法是安全且允許的
+- 不確定應該先查 schema 還是直接執行
+
+## Modes
+
+- `readonly`: 只提供讀取相關工具
+- `readwrite`: 預設模式，允許一般讀寫，但不包含 DDL
+- `advanced`: 允許 schema / DDL 類工具
+
+## Tools
+
+- `pg_query`: 讀取資料
+- `pg_execute`: 執行單一寫入或變更 SQL
+- `pg_batch_execute`: 以多組參數批次執行同一段 SQL
+- `pg_import_csv`: 匯入 UTF-8 CSV
+- `pg_export_csv`: 匯出表格為 UTF-8 CSV
+- `pg_schema_execute`: 執行 schema / DDL 變更，僅 advanced 模式可用
+- `pg_list_pending_approvals`: 列出待審核命令
+- `pg_run_approved_command`: 執行已核准命令
+- `pg_cancel_approval`: 取消審核
+- `explain_query`: 檢查 query plan
+- `list_tables`, `list_views`, `describe_table`, `describe_index`, `list_triggers`
+- `get_current_privileges`
+
+## Execute Usage
+
+`pg_execute` 應使用 PostgreSQL placeholder：
+- `"$1", "$2", "$3"...`
+
+規則：
+- SQL 只描述結構
+- 值由 `params` 陣列提供
+- `$n` 與參數順序必須完全對應
+- 不要用 `?`
+- 不要把使用者輸入直接插入 SQL 字串
+
+`pg_batch_execute` 適合：
+- 同一個 SQL 搭配多組參數重複執行
+- 大量資料寫入
+
+參數寫法補充：
+- SQL 內使用 `$1`, `$2`, ... 代表參數位置
+- `params` 陣列的第 1 個值會綁定到 `$1`
+- `params` 陣列的第 2 個值會綁定到 `$2`
+- 依此類推，順序必須完全一致
+
+## SQL Algebra / Composition Rules
+
+PostgreSQL 查詢組裝可視為一個由上而下的代數式：
+
+1. 先定義中間結果：`WITH`
+2. 選擇欄位：`SELECT`
+3. 指定資料來源：`FROM`
+4. 關聯資料：`JOIN ... ON`
+5. 篩選資料：`WHERE`
+6. 聚合：`GROUP BY`
+7. 聚合後篩選：`HAVING`
+8. 排序：`ORDER BY`
+9. 限制筆數：`LIMIT` / `OFFSET`
+
+PostgreSQL 常用特性：
+- `RETURNING`：寫入後直接取回欄位
+- `::type`：明確型別轉換
+- CTE：提升複雜查詢可讀性
+- 參數化日期區間查詢：搭配 `$1`, `$2`
+
+值與型別的規則：
+- 值優先用參數
+- 型別轉換要明確
+- 時區與日期欄位要一致處理
+
+## Safety Rules
+
+- 不支援 multi-statement
+- 不要把使用者輸入直接嵌入 SQL
+- schema execute 不支援參數化
+- 某些 DDL 解析與授權限制需特別注意
+
+## Examples
+
+- 參數化查詢：
+  - `SELECT * FROM users WHERE id = $1`
+- 寫入後取回 id：
+  - `INSERT INTO users (name) VALUES ($1) RETURNING id`
+- CTE：
+  - `WITH recent_orders AS (...) SELECT * FROM recent_orders`
+- 聚合：
+  - `SELECT status, COUNT(*) FROM orders GROUP BY status`
+- 日期區間查詢：
+  - `SELECT * FROM logs WHERE created_at >= $1 AND created_at < $2`
+
+## Troubleshooting
+
+- 如果參數沒生效，先檢查 `$n` 與 `params` 順序
+- 如果欄位型別不對，補上 `::type`
+- 如果查詢太複雜，先改寫成 `WITH`
+- 如果執行失敗，先用 `describe_table` 確認 schema

package/README.md

@@ -17,7 +17,7 @@ This project uses Node.js, TypeScript, the official MCP SDK, and [`pg`](https://
 
 ## Requirements
 
-- Node.js 18 or newer
+- Node.js 20 or newer
 - npm
 - A reachable PostgreSQL database
 
@@ -29,7 +29,7 @@ Run the server directly with `npx`:
 npx -y easy-pg-mcp
 ```
 
-For local development:
+For local development after cloning the repository:
 
 ```bash
 cd easy-pg-mcp
@@ -39,6 +39,8 @@ npm run build
 
 ## Configuration
 
+Configure the server with environment variables. You can provide them through your MCP client configuration or by creating a local `.env` file.
+
 | Variable | Required | Default | Description |
 | --- | --- | --- | --- |
 | `PG_CONNECTION_STRING` | No | - | PostgreSQL connection string. When set, host/user/password/database fields are optional |
@@ -73,9 +75,27 @@ PG_PASSWORD=your_password
 PG_DATABASE=your_database
 ```
 
-## MCP Client Examples
+## Usage
+
+Configure your MCP client to launch the package through `npx`.
+
+For local development, build the TypeScript source first:
+
+```bash
+npm run build
+```
+
+Start the MCP server:
+
+```bash
+npm start
+```
 
-Claude Desktop:
+The server communicates over stdio and is normally launched by an MCP client rather than run manually.
+
+If you are unsure how a tool should be used, or an operation fails, call `pg_manual` first. It returns the built-in manual with safe usage rules, placeholder guidance, and SQL composition notes.
+
+## Claude Desktop Example
 
 ```json
 {
@@ -95,7 +115,9 @@ Claude Desktop:
 }
 ```
 
-Codex `config.toml`:
+Restart Claude Desktop after updating the configuration.
+
+## Codex config.toml Example
 
 ```toml
 [mcp_servers.easy-pg-mcp]
@@ -111,10 +133,33 @@ PG_PASSWORD = "YOUR PASSWORD"
 PG_DATABASE = "YOUR DB NAME"
 ```
 
+## OpenCode opencode.jsonc Example
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "easy-pg-mcp": {
+      "type": "local",
+      "command": ["npx", "-y", "easy-pg-mcp"],
+      "enabled": true,
+      "environment": {
+        "PG_HOST": "localhost",
+        "PG_PORT": "5432",
+        "PG_USER": "YOUR USERNAME",
+        "PG_PASSWORD": "YOUR PASSWORD",
+        "PG_DATABASE": "YOUR DB NAME"
+      }
+    }
+  }
+}
+```
+
 ## Available Tools
 
 | Tool | Description |
 | --- | --- |
+| `pg_manual` | Return the built-in manual. Use this first when you are unsure how to use PostgreSQL tools or need help diagnosing an operation error |
 | `pg_query` | Execute a read-only SQL query, such as `SELECT` |
 | `pg_execute` | Execute a data modification statement, such as `INSERT`, `UPDATE`, or `DELETE` |
 | `pg_schema_execute` | Execute advanced schema statements, such as table, view, index, trigger, or function DDL. Only registered when `PG_MCP_MODE=advanced` |

package/README.zh-TW.md

@@ -17,7 +17,7 @@
 
 ## 需求
 
-- Node.js 18 以上
+- Node.js 20 以上
 - npm
 - 可連線的 PostgreSQL 資料庫
 
@@ -113,8 +113,11 @@ PG_DATABASE = "YOUR DB NAME"
 
 ## 可用工具
 
+如果你不確定某個工具該怎麼用，或操作失敗，請先呼叫 `pg_manual`。它會回傳內建手冊，包含安全使用規則、placeholder 指引，以及 SQL 組合方式。
+
 | 工具 | 說明 |
 | --- | --- |
+| `pg_manual` | 回傳內建手冊。當你不確定如何使用 PostgreSQL 工具，或需要排查操作錯誤時，請先查這個工具 |
 | `pg_query` | 執行唯讀 SQL，例如 `SELECT` |
 | `pg_execute` | 執行資料修改 SQL，例如 `INSERT`、`UPDATE`、`DELETE` |
 | `pg_schema_execute` | 執行進階 schema SQL，例如 table、view、index、trigger、function DDL。僅在 `PG_MCP_MODE=advanced` 時註冊 |

package/build/index.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
@@ -13,8 +15,15 @@ const server = new McpServer({
     version: '1.0.1',
     description: `PostgreSQL Database: ${PG_HOST}:${PG_PORT ?? 5432}/${PG_DATABASE}`,
 });
+const manualText = readFileSync(fileURLToPath(new URL('../MANUAL.md', import.meta.url)), 'utf8');
 // --- Register Tools ---
 const transactionModeSchema = z.enum(['all', 'batch', 'each', 'none']);
+server.registerTool('pg_manual', {
+    description: 'Return the PostgreSQL MCP manual. Use this first when you are unsure how to use pg_query, pg_execute, pg_batch_execute, or when an operation fails and you need the safe usage rules, placeholder rules, or SQL composition guidance.',
+    inputSchema: z.object({}),
+}, async () => ({
+    content: [{ type: 'text', text: manualText }],
+}));
 server.registerTool('pg_query', {
     description: 'Execute a read-only SQL query (e.g., SELECT). Use this for data retrieval.',
     inputSchema: z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "easy-pg-mcp",
-  "version": "1.0.1",
+  "version": "1.1.2",
   "description": "High performance PostgreSQL MCP Server using node-postgres",
   "main": "build/index.js",
   "type": "module",
@@ -9,10 +9,12 @@
   },
   "files": [
     "build",
-    "README.md"
+    "README.md",
+    "README.zh-TW.md",
+    "MANUAL.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "keywords": [
     "mcp",
@@ -37,13 +39,13 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "node-sql-parser": "^5.4.0",
-    "pg": "^8.21.0",
+    "pg": "^8.22.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
-    "@types/pg": "^8.15.6",
-    "typescript": "^6.0.3"
+    "@types/node": "^26.1.1",
+    "@types/pg": "^8.20.0",
+    "typescript": "^7.0.2"
   },
   "repository": {
     "type": "git",