使用LLM聊天示例的PostgreSQL MCP服务器在Clever Cloud上

概述

此仓库演示了如何在Clever Cloud上部署一个Node.js应用程序，该应用程序使用PostgreSQL的模型上下文协议（MCP）服务器以及语言模型来实现对PostgreSQL数据库的自然语言查询。

应用程序允许用户通过自然语言查询与PostgreSQL数据库进行交互，这些查询被翻译成SQL，并通过MCP服务器执行。

应用程序运行时的截图，显示了对PostgreSQL数据库的自然语言查询

示例数据：RAGmonsters

此示例使用RAGmonsters数据集作为样本数据。RAGmonsters是一个开放数据集，旨在测试和展示检索增强生成（RAG）系统。它包含关于虚构怪物的信息，具有丰富的属性、能力和关系——使其非常适合自然语言查询演示。

RAGmonsters的PostgreSQL版本提供了一个结构良好的关系型数据库，包含多个表和关系，允许进行复杂的查询，展示了结合自然语言处理与通过MCP访问结构化数据库的强大功能。

预备条件

• 一个Clever Cloud账户
• 安装并配置了Clever Tools CLI
• Node.js 23或更高版本
• PostgreSQL数据库
• 访问LLM API（例如，OpenAI）

项目结构

├── .env.example        # 环境变量示例
├── package.json        # Node.js项目配置
├── README.md           # 此文档
├── img/                # 文档图片
│   └── screenshot.jpg  # 应用程序截图
├── scripts/
│   ├── initializeDb.js # 初始化数据库脚本，使用RAGmonsters数据
│   └── testMCP.js      # 测试MCP服务器与LLM集成的脚本
├── src/
│   ├── index.js        # 主应用程序服务器
│   ├── llm.js          # LangChain集成用于LLM
│   ├── mcp-client.js   # PostgreSQL的MCP客户端
│   └── public/         # 网页界面文件
│       └── index.html  # 聊天界面

特性

• 使用自然语言探索PostgreSQL数据库
• 与官方PostgreSQL实现集成的MCP服务器
• LangChain.js集成用于LLM交互
• 简单的网页界面用于与数据库聊天
• 带有API端点的Express.js后端

本地开发

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

npm install

3. 通过复制.env.example到.env并更新值来配置环境变量：

cp .env.example .env

4. 在.env文件中更新您的PostgreSQL连接详情和LLM API密钥。

5. 使用RAGmonsters样本数据初始化数据库：

node scripts/initializeDb.js

此脚本将克隆RAGmonsters存储库并将样本数据填充到您的PostgreSQL数据库中。

6. 测试MCP服务器和LLM集成：

node scripts/testMCP.js

此脚本将使用MCP服务器连接到您的PostgreSQL数据库，并使用LLM将自然语言查询转换为SQL。它展示了应用程序的核心功能，不包括网页界面。

7. 启动开发服务器：

npm run dev

您的应用程序将在http://localhost:8080（或`.env`文件中指定的端口）可用。

工作原理

1. 应用程序使用提供的连接详情连接到您的PostgreSQL数据库
2. MCP服务器提供了与数据库交互的标准方式
3. 当您以自然语言提问时，应用程序：
   • 使用MCP服务器检索数据库模式
   • 将您的问题连同模式一起发送给LLM
   • LLM生成适当的SQL查询
   • 使用MCP服务器执行查询
   • 结果在网页界面上显示

使用testMCP.js测试

testMCP.js脚本展示了应用程序的核心功能，不包括网页界面：

1. 环境设置：从.env文件加载环境变量，包括PostgreSQL连接URI和LLM API密钥
2. MCP服务器初始化：使用StdioClientTransport启动PostgreSQL MCP服务器作为子进程
3. LLM集成：配置ChatOpenAI模型，详细说明PostgreSQL语法
4. 代理创建：设置LangChain ReAct代理，结合LLM和MCP工具
5. 查询执行：处理自然语言查询，将其转换为SQL并执行
6. 结果展示：以格式化的响应显示结果

此脚本可用于：

• 测试您的数据库连接
• 验证MCP服务器是否正常工作
• 确保LLM可以生成有效的PostgreSQL查询
• 探索您的数据库模式和数据，不包括网页界面

部署到Clever Cloud

使用Clever Cloud CLI

1. 安装Clever Cloud CLI：

   npm install -g clever-tools
   

2. 登录到您的Clever Cloud账户：

   clever login
   

3. 创建一个新的应用程序：

   clever create --type node <APP_NAME>
   

4. 添加您的域名（可选但推荐）：

   clever domain add <YOUR_DOMAIN_NAME>
   

5. 创建一个PostgreSQL附加组件并将其链接到您的应用程序：

   clever addon create <APP_NAME>-pg --plan dev
   clever service link-addon <APP_NAME>-pg
   

   这将自动在您的应用程序中设置POSTGRESQL_ADDON_URI环境变量。

6. 设置所需的环境变量：

   clever env set LLM_API_KEY "your-openai-api-key"
   clever env set LLM_API_MODEL "gpt-4o-mini" # 可选，默认为gpt-4o-mini
   clever env set LLM_API_URL "https://api.your-llm-provider.com" # 可选，针对替代的OpenAI兼容提供商
   

7. 部署您的应用程序：

   clever deploy
   

8. 打开您的应用程序：

   clever open
   

使用Clever Cloud控制台

您也可以直接从Clever Cloud控制台部署：

1. 在控制台中创建一个新的应用程序
2. 选择Node.js作为运行时
3. 创建一个PostgreSQL附加组件并将其链接到您的应用程序
4. 在控制台中设置所需的环境变量：
   • LLM_API_KEY：您的OpenAI API密钥
   • LLM_API_MODEL：（可选）要使用的模型，默认为gpt-4o-mini
5. 使用Git或GitHub集成部署您的应用程序

重要提示

• 当您将PostgreSQL附加组件链接到您的应用程序时，Clever Cloud会自动设置POSTGRESQL_ADDON_URI环境变量
• 应用程序需要Node.js 20或更高版本，这是Clever Cloud上可用的
• 应用程序将自动运行在8080端口，这是Clever Cloud上Node.js应用程序的默认端口

环境变量

以下环境变量用于配置您的应用程序：

变量	描述	示例值	必需
POSTGRESQL_ADDON_URI	PostgreSQL连接URI（由Clever Cloud自动提供）	postgresql://user:password@host:port/database	是
PORT	服务器监听的端口	8080	否（默认为8080）
LLM_API_KEY	OpenAI服务的API密钥	sk-...	是
LLM_API_MODEL	LLM服务使用的模型	gpt-4o-mini	否（默认为gpt-4o-mini）
LLM_API_URL	OpenAI兼容API的基础URL	https://api.openai.com/v1	否（默认为OpenAI）

故障排除

如果您遇到问题：

1. 检查应用程序日志：clever logs
2. 验证所有环境变量是否正确设置：clever env
3. 确保您的应用程序正在运行：clever status

资源

• 模型上下文协议文档
• LangChain.js文档
• Clever Cloud Node.js文档
• Clever Cloud控制台

许可证

此示例根据MIT许可证条款提供。