FastPostgresMCP 🐘⚡️ (全功能多数据库 MCP 服务器)

本项目实现了一个极速、类型安全且功能完善的模型上下文协议 (MCP) 服务器，专为 AI 代理（如 Cursor、Claude Desktop）与多个 PostgreSQL 数据库交互而设计，包括列出表和检查模式。

它基于 Bun、TypeScript、postgres 构建，并利用 fastmcp 框架的先进特性来构建健壮的 MCP 服务器。

目的：用于 AI 代理的 MCP 服务器

这不是一个可以导入到你的代码中的库。它是一个独立的服务器应用程序。 你将其作为一个进程运行，MCP 客户端（如 AI 代理）使用基于 JSON 的模型上下文协议 (v2.0) 与之通信，通常通过客户端应用程序（例如，Cursor）管理的 stdio 连接。

✨ 核心功能

• 🚀 极速： 基于 Bun 和 fastmcp 构建。
• 🔒 类型安全： 端到端 TypeScript，带有 Zod 模式验证。
• 🐘 多数据库支持： 连接并管理跨多个在 .env 中定义的 PostgreSQL 实例的交互。
• 🛡️ 设计安全： 通过 postgres 的参数化查询防止 SQL 注入。
• 🔑 可选身份验证： 使用 API 密钥验证（fastmcp 的 authenticate 钩子）保护基于网络的连接（SSE/HTTP）。
• 📄 通过 MCP 资源访问数据库模式：
  • 列出表： 通过 db://{dbAlias}/schema/tables 获取数据库中的表列表。
  • 检查表模式： 通过 db://{dbAlias}/schema/{tableName} 获取特定表的详细列信息。
• 💬 增强的工具交互：
  • 工具内日志记录： 工具将详细日志发送回客户端（log 上下文）。
  • 进度报告： 长时间运行的操作报告进度（reportProgress 上下文）。
• 🧠 会话感知： 在工具执行上下文（session 上下文）中访问会话信息。
• 📡 事件驱动： 使用 server.on 和 session.on 进行连接/会话事件处理。
• 🔧 现代开发者体验 (DX)： 清晰的配置、直观的 API、使用 fastmcp 工具轻松测试。

包含的内容（利用的 fastmcp 功能）

• FastMCP 服务器核心
• server.addTool（用于 query、execute、transaction）
• server.addResourceTemplate（用于列出表和检查表模式）
• server.start（专注于 stdio，可适应 sse/http）
• 可选： authenticate 钩子（用于 API 密钥验证）
• 工具执行 context（log、reportProgress、session）
• Zod 用于参数模式验证
• server.on（用于连接日志记录）
• （可能）session.on 用于会话特定逻辑

📋 前提条件

• Bun (建议 v1.0 或更高版本)： 已安装并在 PATH 中。
• PostgreSQL 数据库： 访问凭据和连接。 用户需要查询 information_schema 的权限。

⚙️ 安装

1. 克隆存储库：

   # 替换为你的实际存储库 URL
   git clone https://github.com/yourusername/fast-postgres-mcp.git
   cd fast-postgres-mcp
   

2. 安装依赖项：

   bun install
   

🔑 配置（多数据库和可选身份验证）

通过环境变量配置，通常从 .env 加载。

1. 创建 .env 文件： cp .env.example .env
2. 编辑 .env： 定义 DB_ALIASES、DEFAULT_DB_ALIAS、数据库连接详细信息 (DB_<ALIAS>_...) 和可选的 ENABLE_AUTH/MCP_API_KEY。

# .env.example - 关键变量

# 必需：以逗号分隔的唯一数据库别名列表
DB_ALIASES=main,reporting

# 必需：如果在工具调用中省略 'dbAlias'，则使用默认别名
DEFAULT_DB_ALIAS=main

# 可选：启用 API 密钥身份验证（主要用于网络传输）
ENABLE_AUTH=false
MCP_API_KEY=your_super_secret_api_key_here # 更改此项

# 为每个别名定义数据库连接详细信息 (DB_MAIN_*, DB_REPORTING_*, 等)
# 示例：
DB_MAIN_HOST=localhost
DB_MAIN_PORT=5432
DB_MAIN_NAME=app_prod_db
DB_MAIN_USER=app_user         # 需要 information_schema 的权限
DB_MAIN_PASSWORD=app_secret_password
DB_MAIN_SSL=disable           # 建议生产环境使用 'require' 或更严格的设置

DB_REPORTING_HOST=reporting-db.read-replica.internal
# ... 其他 reporting DB 详细信息 ...
DB_REPORTING_USER=readonly_reporter # 需要 information_schema 的权限

# --- 可选：服务器日志记录级别 ---
# LOG_LEVEL=info # debug, info, warn, error (默认为 info)

🚀 运行服务器（作为进程）

使用 Bun 直接运行此服务器。 AI 客户端（如 Cursor）通常会为你启动和管理此命令。

• 手动运行（用于测试）： bun run src/index.ts
• 手动开发模式： bun run --watch src/index.ts

使用 fastmcp CLI 工具进行测试

• 交互式终端： bunx fastmcp dev src/index.ts
• Web UI 检查器： bunx fastmcp inspect src/index.ts

🔌 与 AI 客户端（Cursor、Claude Desktop）连接

配置你的 AI 代理（MCP 客户端）以通过其命令/参数机制执行此服务器脚本。

Cursor AI - 详细示例

1. 打开 Cursor 设置/首选项 (Cmd+, 或 Ctrl+,)。

2. 导航到 "Extensions" -> "MCP"。

3. 单击 "Add MCP Server" 或编辑 settings.json。

4. 添加以下 JSON 配置：

   // 在 Cursor 的 settings.json 或 MCP 配置 UI 中
   {
     "mcpServers": {
       "fast-postgres-mcp": { // Cursor 的唯一名称
         "description": "MCP Server for PostgreSQL DBs (Main, Reporting)",
         "command": "bun",  // 使用 'bun' 或提供绝对路径："/Users/your_username/.bun/bin/bun"
         "args": [
           "run",
           // *** 关键：服务器入口点的绝对路径 ***
           "/Users/your_username/projects/fast-postgres-mcp/src/index.ts" // 更改此项
         ],
         "env": {
           // 项目目录中的 .env 文件由 Bun 自动加载。
           // 如果需要，在此处添加覆盖或 Cursor 特定的变量。
         },
         "enabled": true
       }
     }
   }
   

5. 保存并重启 Cursor 或 "Reload MCP Servers"。

6. 验证 Cursor 的 MCP 状态/日志中的连接。

Claude Desktop

1. 找到并编辑 config.json（有关路径，请参见之前的 README）。
2. 在 mcpServers 下添加类似的条目，在 args 中使用绝对路径。
3. 重启 Claude Desktop。

🛠️ 公开的 MCP 功能

身份验证（可选）

• 如果 ENABLE_AUTH=true，则通过与 MCP_API_KEY 匹配的 X-API-Key 标头保护网络传输（HTTP/SSE）。
• stdio 连接（Cursor/Claude 的默认设置）通常会绕过此检查。

资源

1. 列出数据库表

• URI 模板： db://{dbAlias}/schema/tables
• 描述： 检索指定数据库别名中的用户表名称列表（通常来自 'public' 模式）。
• 资源定义 (addResourceTemplate)：
  • uriTemplate: "db://{dbAlias}/schema/tables"
  • arguments:
    • dbAlias: (string, required) - 数据库的别名（来自 .env）。
  • load({ dbAlias }): 连接到数据库，查询 information_schema.tables（过滤公共模式中的基本表，可在实现中自定义），将结果格式化为 JSON 字符串数组 ["table1", "table2", ...]，并返回 { text: "..." }。

示例用法（AI 提示）： "获取资源 db://main/schema/tables 以列出主数据库中的表。"

2. 检查表模式

• URI 模板： db://{dbAlias}/schema/{tableName}
• 描述： 提供特定表的详细模式信息（列、类型、可空性、默认值）。
• 资源定义 (addResourceTemplate)：
  • uriTemplate: "db://{dbAlias}/schema/{tableName}"
  • arguments:
    • dbAlias: (string, required) - 数据库别名。
    • tableName: (string, required) - 表名。
  • load({ dbAlias, tableName }): 连接，查询特定表的 information_schema.columns，格式化为列对象的 JSON 字符串数组，返回 { text: "..." }。

示例用法（AI 提示）： "描述资源 db://reporting/schema/daily_sales。"

示例请求：

{
  "tool_name": "schema_tool",
  "arguments": {
    "tableName": "user_sessions",
    "dbAlias": "main"
  }
}

示例响应内容（JSON 字符串）：

"[{\"column_name\":\"session_id\",\"data_type\":\"uuid\",\"is_nullable\":\"NO\",\"column_default\":\"gen_random_uuid()\"},{\"column_name\":\"user_id\",\"data_type\":\"integer\",\"is_nullable\":\"NO\",\"column_default\":null},{\"column_name\":\"created_at\",\"data_type\":\"timestamp with time zone\",\"is_nullable\":\"YES\",\"column_default\":\"now()\"},{\"column_name\":\"expires_at\",\"data_type\":\"timestamp with time zone\",\"is_nullable\":\"YES\",\"column_default\":null}]"

工具

工具接收 context 对象（log、reportProgress、session）。

---

1. query_tool

执行只读 SQL 查询。

• 描述： 安全地执行只读 SQL，获取结果，并进行执行日志记录/进度报告。
• 参数： statement (string), params (array, opt), dbAlias (string, opt)。
• 上下文用法： log.info/debug，可选 reportProgress，访问 session。
• 返回： 行数组的 JSON 字符串。

示例请求：

{
  "tool_name": "query_tool",
  "arguments": {
    "statement": "SELECT product_id, name, price FROM products WHERE category = $1 AND price < $2 ORDER BY name LIMIT 10",
    "params": ["electronics", 500],
    "dbAlias": "main"
  }
}

示例响应内容（JSON 字符串）：

"[{\"product_id\":123,\"name\":\"Example Gadget\",\"price\":499.99},{\"product_id\":456,\"name\":\"Another Device\",\"price\":350.00}]"

---

---

2. execute_tool

执行数据修改 SQL 语句。

• 描述： 安全地执行数据修改 SQL，并进行执行日志记录。
• 参数： statement (string), params (array, opt), dbAlias (string, opt)。
• 上下文用法： log.info/debug，访问 session。
• 返回： 指示受影响的行数的字符串。

示例请求：

{
  "tool_name": "execute_tool",
  "arguments": {
    "statement": "UPDATE users SET last_login = NOW() WHERE user_id = $1",
    "params": [54321]
    // dbAlias 省略，使用 DEFAULT_DB_ALIAS
  }
}

示例响应内容（字符串）：

---

3. transaction_tool

原子地执行多个 SQL 语句。

• 描述： 在事务中执行 SQL 序列，并进行步骤日志记录/进度报告。
• 参数： operations (array of {statement, params}), dbAlias (string, opt)。
• 上下文用法： log.info/debug/error，reportProgress，访问 session。
• 返回： 总结成功/失败的 JSON 字符串：{"success": true, "results": [...]} 或 {"success": false, "error": ..., "failedOperationIndex": ...}。

示例请求：

{
  "tool_name": "transaction_tool",
  "arguments": {
    "operations": [
      {
        "statement": "INSERT INTO orders (customer_id, order_date, status) VALUES ($1, NOW(), 'pending') RETURNING order_id",
        "params": [101]
        // 注意：简单版本不会自动处理在操作之间传递 RETURNING 值。
        // 更复杂的工作流程可能需要单独的工具调用或增强的逻辑。
      },
      {
        "statement": "INSERT INTO order_items (order_id, product_sku, quantity, price) VALUES ($1, $2, $3, $4)",
        "params": [/* 返回的 order_id 的占位符 */ 9999, "GADGET-X", 2, 49.99]
      },
      {
        "statement": "UPDATE inventory SET stock_count = stock_count - $1 WHERE product_sku = $2 AND stock_count >= $1",
        "params": [2, "GADGET-X"]
      }
    ],
    "dbAlias": "main"
  }
}

示例成功响应内容（JSON 字符串）：

"{\"success\":true,\"results\":[{\"operation\":0,\"rowsAffected\":1},{\"operation\":1,\"rowsAffected\":1},{\"operation\":2,\"rowsAffected\":1}]}"

示例错误响应内容（JSON 字符串）：

"{\"success\":false,\"error\":\"Error executing operation 2: new row for relation \\\"inventory\\\" violates check constraint \\\"stock_count_non_negative\\\"\",\"failedOperationIndex\":2}"

---

服务器和会话事件

• 使用 server.on('connect'/'disconnect') 记录客户端连接。
• 如果需要，可以使用 session.on(...) 进行更精细的会话事件处理。

🔒 安全注意事项

• SQL 注入： 通过参数化查询缓解。 没有直接的输入连接。
• 数据库权限： 至关重要。 为每个 DB_<ALIAS>_USER 分配最小权限，包括对 information_schema 的读取访问权限，以用于模式/表列出资源。
• SSL/TLS： 生产环境必不可少 (DB_<ALIAS>_SSL=require 或更严格)。
• 密钥管理： 保护 .env 文件（添加到 .gitignore）。 对生产环境使用安全的密钥管理（Vault、Doppler、云密钥）。
• 身份验证范围： authenticate 钩子主要保护网络传输。 stdio 安全性依赖于执行环境。
• 数据敏感性： 注意可通过连接/工具访问的数据。
• 资源查询： 用于列出表 (information_schema.tables) 和模式 (information_schema.columns) 的查询通常是安全的，但依赖于数据库权限。 确保配置的用户具有适当的读取访问权限。 如果需要出于安全或清晰起见，请自定义表列出查询（例如，模式过滤）。

📜 许可证

本项目根据 MIT 许可证 获得许可。 有关详细信息，请参见 LICENSE 文件。 （确保存在 LICENSE 文件）。