使用说明
🐘 具有自然语言接口的PostgreSQL MCP服务器
一种模型上下文协议（MCP）服务器，将PostgreSQL数据库操作作为工具公开，可在Vercel上部署。现在与 自然语言接口 由AI驱动！
┌─────────────────────────────────────────────────────────────┐
│ PostgreSQL MCP Server │
│ │
│ ┌──────────────┐ ┌─────────────────┐ │
│ │ Web Chat │────────▶│ /api/chat │ │
│ │ UI │ │ (Natural Lang) │ │
│ └──────────────┘ └────────┬────────┘ │
│ │ │
│ ┌──────────────┐ ▼ │
│ │ Your App │ ┌─────────────────┐ │
│ │ (MCP Client)│────────▶│ GPT-4 AI │ │
│ └──────────────┘ └────────┬────────┘ │
│ │ │
│ ┌──────────────┐ ▼ │
│ │ CLI Tool │ ┌─────────────────┐ │
│ │ │────────▶│ /api/mcp │ │
│ └──────────────┘ │ (MCP Tools) │ │
│ └────────┬────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ PostgreSQL │ │
│ │ Database │ │
│ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
🌟 特性
MCP工具（标准接口）
此MCP服务器提供以下PostgreSQL操作作为工具：
- execute_query：执行SELECT查询并返回结果
- execute_mutation：执行INSERT、UPDATE、DELETE查询
- list_tables：列出架构中的所有表
- describe_table：获取详细的表结构信息
- execute_交易：在事务中执行多个查询
- get_database_info：获取数据库元数据和信息
🤖 自然语言界面（新增！）
用简单的英语与PostgreSQL数据库交互：
- “显示上周注册的所有用户”
- “订单的总收入是多少？”
- “创建一个名为John Doe的新用户”
- “我的数据库中存在哪些表？”
不需要SQL知识！AI自动：
- 发现您的数据库架构
- 生成优化的SQL查询
- 安全地执行它们
- 以自然语言返回结果
👉 看 自然语言.md 获取完整文档
先决条件
- Node.js 18或更高版本
- PostgreSQL数据库
- Vercel帐户（用于部署）
本地开发
-
安装依赖项：
npm install -
创建一个
.env文件：cp .env.example .env -
更新
.env使用您的凭据文件：DATABASE_URL=postgresql://username:password@localhost:5432/database_name DATABASE_SSL=false OPENAI_API_KEY=sk-your-openai-api-key # Required for natural language interface MCP_API_KEY=your-secret-api-key # Optional: Secure your MCP endpoint -
使用Vercel CLI在本地运行：
npm run dev -
测试端点：
# MCP endpoint curl http://localhost:3000/api/mcp # Natural language endpoint curl http://localhost:3000/api/chat -
尝试聊天界面： 打开
example-chat.html在浏览器中
部署到Vercel
-
安装Vercel CLI（如果尚未安装）：
npm install -g vercel -
登录Vercel：
vercel login -
设置环境变量：
vercel env add DATABASE_URL vercel env add DATABASE_SSL出现提示时输入数据库连接字符串。
-
部署：
npm run deploy或者简单地说：
vercel
环境变量
DATABASE_URL：PostgreSQL连接字符串DATABASE_SSL：设置为true如果您的数据库需要SSL（云提供商常用）OPENAI_API_KEY：您的OpenAI API密钥（自然语言接口所需）MCP_API_KEY：（可选）用于验证MCP端点请求的API密钥
API终点
POST/api/mcp
用于工具执行的主MCP处理程序端点。
GET/api/mcp
返回服务器信息和可用工具的健康检查端点。
POST/api/聊天
数据库交互的自然语言界面。用简单的英语发送查询！
GET/api/聊天
聊天端点的健康检查。
🎯 快速入门指南
选项1：自然语言界面（最简单！）
适合任何人-不需要SQL知识！
# 1. Set up environment variables (including OPENAI_API_KEY)
# 2. Start the server
npm run dev
# 3. Open example-chat.html in your browser
# 4. Start chatting with your database!
示例查询：
- “显示所有桌子”
- “上周有多少用户注册？”
- “创建一个名为Alice的新用户”
选项2：直接MCP工具（面向开发人员）
直接使用MCP协议进行编程访问。
// Call tools directly via the MCP endpoint
fetch('http://localhost:3000/api/mcp', {
method: 'POST',
body: JSON.stringify({
tool: 'execute_query',
parameters: { query: 'SELECT * FROM users LIMIT 10' }
})
});
工具使用示例
execute_query
{
"tool": "execute_query",
"parameters": {
"query": "SELECT * FROM users WHERE id = $1",
"params": [1]
}
}
execute_mutation
{
"tool": "execute_mutation",
"parameters": {
"query": "INSERT INTO users (name, email) VALUES ($1, $2)",
"params": ["John Doe", "john@example.com"]
}
}
list_tables
{
"tool": "list_tables",
"parameters": {
"schema": "public"
}
}
describe_table
{
"tool": "describe_table",
"parameters": {
"tableName": "users",
"schema": "public"
}
}
execute_交易
{
"tool": "execute_transaction",
"parameters": {
"queries": [
{
"query": "INSERT INTO users (name) VALUES ($1)",
"params": ["Alice"]
},
{
"query": "UPDATE accounts SET balance = balance - 100 WHERE user_id = $1",
"params": [1]
}
]
}
}
get_database_info
{
"tool": "get_database_info",
"parameters": {}
}
安全考虑
- 这
execute_query出于安全考虑，该工具仅允许SELECT和WITH查询 - 使用参数化查询来防止SQL注入
- 使用Vercel环境变量安全地存储数据库凭据
- 考虑为生产使用实施身份验证
- 使用云提供商时为数据库连接启用SSL
数据库提供程序
此MCP服务器适用于任何PostgreSQL兼容的数据库，包括：
- PostgreSQL（自托管）
- Amazon RDS for PostgreSQL
- PostgreSQL的谷歌云SQL
- PostgreSQL的Azure数据库
- 霓虹
- Supabase
- 铁路
- 渲染
故障排除
连接问题
- 确保您的数据库允许来自Vercel IP范围的连接
- 检查SSL设置是否符合您的数据库要求
- 验证DATABASE_URL格式是否正确
查询超时
- 调整
connectionTimeoutMillis在连接池配置中 - 优化慢速查询
- 检查数据库性能
📖 文档
- 自然语言.md -自然语言界面完整指南
- 部署.md -详细的部署说明
- 认证.md -使用API密钥保护MCP端点的指南
- example-chat.html -与数据库聊天的漂亮web界面
- example-chat-usage.js -程序化使用的Node.js示例
- example-usage.js -直接MCP工具使用示例
🎬 示例用例
商业分析
"Show me monthly revenue trends for the last year"
"Who are my top 10 customers?"
"What's the average order value by product category?"
数据探索
"What tables exist in my database?"
"Show me the structure of the users table"
"Find all users who haven't logged in for 30 days"
数据管理
"Update the email for user id 123"
"Delete all orders older than 2 years"
"Create a new product in the electronics category"
复杂操作
"Transfer $100 from account A to account B"
"Calculate customer lifetime value for all users"
"Generate a sales report for Q4 2024"
🔄 运作原理
MCP端点(/api/mcp)
Client → MCP Request → Tool Execution → Database → Response
自然语言端点(/api/chat)
User Query → AI (GPT-4) → Tool Selection → MCP Tools → Database → Natural Language Response
AI自动：
- 理解你的意图
- 如果需要，发现数据库架构
- 生成适当的SQL
- 通过MCP工具执行
- 自然格式化结果
🛡️ 安全特性
- ✅ 参数化查询（SQL注入保护）
- ✅ 读/写操作分离
- ✅ 连接池
- ✅ SSL/TLS支持
- ✅ 具有回滚功能的事务支持
- ✅ 环境变量保护
推荐用于生产：
- 添加API密钥身份验证
- 实施速率限制
- 设置监控和警报
- 使用具有最小权限的数据库用户
- 启用审核日志记录
🚀 演出
- 连接池实现最佳性能
- 实时反馈的流式响应
- 人工智能高效生成SQL查询
- 支持复杂的查询和联接
💡 提示
- 从发现开始：询问“存在哪些表？”以了解您的数据库
- 具体：更多上下文=更好的结果
- 使用随访：基于对话中之前的问题
- 检查结果：始终验证重要操作
- 杠杆交易：使用事务进行多步骤操作
🤝 贡献
欢迎投稿！请随时提交拉取请求。
需要改进的地方：
- 其他人工智能提供商（Anthropic、谷歌等）
- 查询结果缓存
- 用户认证
- 速率限制
- 查询历史记录和收藏夹
📄 许可证
MIT许可证
