PostgreSQL MCP 服务器

这是一个提供 PostgreSQL 数据库管理功能的模型上下文协议（MCP）服务器。该服务器有助于分析现有的 PostgreSQL 设置，提供实施指导，调试数据库问题，管理模式，迁移数据以及监控数据库性能。

功能

数据库分析和调试

1. 数据库分析 (analyze_database)

分析 PostgreSQL 数据库配置和性能指标：

• 配置分析
• 性能指标
• 安全评估
• 优化建议

// Example usage
{
  "connectionString": "postgresql://user:password@localhost:5432/dbname",
  "analysisType": "performance" // Optional: "configuration" | "performance" | "security"
}

2. 安装指南 (get_setup_instructions)

提供逐步的 PostgreSQL 安装和配置指南：

• 针对特定平台的安装步骤
• 配置建议
• 安全最佳实践
• 安装后任务

// Example usage
{
  "platform": "linux", // Required: "linux" | "macos" | "windows"
  "version": "15", // Optional: PostgreSQL version
  "useCase": "production" // Optional: "development" | "production"
}

3. 数据库调试 (debug_database)

调试常见的 PostgreSQL 问题：

• 连接问题
• 性能瓶颈
• 锁冲突
• 复制状态

// Example usage
{
  "connectionString": "postgresql://user:password@localhost:5432/dbname",
  "issue": "performance", // Required: "connection" | "performance" | "locks" | "replication"
  "logLevel": "debug" // Optional: "info" | "debug" | "trace"
}

模式管理

4. 模式信息 (get_schema_info)

获取数据库或特定表的详细模式信息：

• 数据库中的表列表
• 列定义
• 约束（主键、外键等）
• 索引

// Example usage
{
  "connectionString": "postgresql://user:password@localhost:5432/dbname",
  "tableName": "users" // Optional: specific table to get info for
}

5. 创建表 (create_table)

使用指定列创建新表：

• 定义列名和类型
• 设置可空约束
• 设置默认值

// Example usage
{
  "connectionString": "postgresql://user:password@localhost:5432/dbname",
  "tableName": "users",
  "columns": [
    { "name": "id", "type": "SERIAL", "nullable": false },
    { "name": "username", "type": "VARCHAR(100)", "nullable": false },
    { "name": "email", "type": "VARCHAR(255)", "nullable": false },
    { "name": "created_at", "type": "TIMESTAMP", "default": "NOW()" }
  ]
}

6. 修改表 (alter_table)

修改现有表：

• 添加新列
• 修改列类型或约束
• 删除列

// Example usage
{
  "connectionString": "postgresql://user:password@localhost:5432/dbname",
  "tableName": "users",
  "operations": [
    { "type": "add", "columnName": "last_login", "dataType": "TIMESTAMP" },
    { "type": "alter", "columnName": "email", "nullable": false },
    { "type": "drop", "columnName": "temporary_field" }
  ]
}

数据迁移

7. 导出表数据 (export_table_data)

将表数据导出为 JSON 或 CSV 格式：

• 使用 WHERE 子句筛选数据
• 限制行数
• 选择输出格式

// Example usage
{
  "connectionString": "postgresql://user:password@localhost:5432/dbname",
  "tableName": "users",
  "outputPath": "./exports/users.json",
  "where": "created_at > '2023-01-01'", // Optional
  "limit": 1000, // Optional
  "format": "json" // Optional: "json" | "csv"
}

8. 导入表数据 (import_table_data)

从 JSON 或 CSV 文件导入数据：

• 可选地在导入前清空表
• 支持不同格式
• 自定义 CSV 分隔符

// Example usage
{
  "connectionString": "postgresql://user:password@localhost:5432/dbname",
  "tableName": "users",
  "inputPath": "./imports/users.json",
  "truncateFirst": false, // Optional
  "format": "json", // Optional: "json" | "csv"
  "delimiter": "," // Optional: for CSV files
}

9. 在数据库之间复制 (copy_between_databases)

在两个 PostgreSQL 数据库之间复制数据：

• 使用 WHERE 子句筛选数据
• 可选地清空目标表

// Example usage
{
  "sourceConnectionString": "postgresql://user:password@localhost:5432/source_db",
  "targetConnectionString": "postgresql://user:password@localhost:5432/target_db",
  "tableName": "users",
  "where": "active = true", // Optional
  "truncateTarget": false // Optional
}

监控

10. 监控数据库 (monitor_database)

实时监控 PostgreSQL 数据库：

• 数据库指标（连接数、缓存命中率等）
• 表指标（大小、行数、死元组）
• 活动查询信息
• 锁信息
• 复制状态
• 可配置的警报

// Example usage
{
  "connectionString": "postgresql://user:password@localhost:5432/dbname",
  "includeTables": true, // Optional
  "includeQueries": true, // Optional
  "includeLocks": true, // Optional
  "includeReplication": false, // Optional
  "alertThresholds": { // Optional
    "connectionPercentage": 80,
    "longRunningQuerySeconds": 30,
    "cacheHitRatio": 0.95,
    "deadTuplesPercentage": 10,
    "vacuumAge": 7
  }
}

先决条件

• Node.js >= 18.0.0
• PostgreSQL 服务器（用于目标数据库操作）
• 对目标 PostgreSQL 实例的网络访问权限

安装

请继续添加有关如何安装此工具的具体步骤。

1. 克隆仓库
2. 安装依赖项：

   npm install
   

3. 构建服务器：

   npm run build
   

4. 添加到 MCP 设置文件中：

   {
     "mcpServers": {
       "postgresql-mcp": {
         "command": "node",
         "args": ["/path/to/postgresql-mcp-server/build/index.js"],
         "disabled": false,
         "alwaysAllow": []
       }
     }
   }
   

开发

• npm run dev - 启动带有热重载的开发服务器
• npm run lint - 运行 ESLint
• npm test - 运行测试

安全注意事项

1. 连接安全

   • 使用连接池
   • 实现连接超时
   • 验证连接字符串
   • 支持 SSL/TLS 连接

2. 查询安全性

   • 验证 SQL 查询
   • 防止危险操作
   • 实现查询超时
   • 记录所有操作

3. 身份验证

   • 支持多种身份验证方法
   • 实现基于角色的访问控制
   • 强制执行密码策略
   • 安全管理连接凭证

最佳实践

1. 始终使用带有适当凭据的安全连接字符串
2. 对敏感环境遵循生产安全建议
3. 定期监控和分析数据库性能
4. 保持 PostgreSQL 版本最新
5. 实施适当的备份策略
6. 使用连接池以更好地管理资源
7. 实施适当的错误处理和日志记录
8. 定期进行安全审计和更新

错误处理

服务器实现了全面的错误处理：

• 连接失败
• 查询超时
• 身份验证错误
• 权限问题
• 资源限制

贡献

1. 叉分仓库
2. 创建功能分支
3. 提交你的更改
4. 推送到该分支
5. 创建一个 Pull Request

许可证

此项目根据 AGPLv3 许可证授权 - 详情请参阅 LICENSE 文件。