PostgreSQL MCP Server with LLM Chat Example on Clever Cloud

Clever Cloud 上的 PostgreSQL MCP 服务及 LLM 聊天示例

概述

本仓库演示如何在 Clever Cloud 上部署 Node.js 应用。该应用使用 PostgreSQL 的模型上下文协议（MCP）服务，并结合语言模型，实现对 PostgreSQL 数据库的自然语言查询。

用户可以使用自然语言查询与 PostgreSQL 数据库交互。查询会通过 LLM 转换为 SQL，然后由 MCP 服务对数据库执行。

应用运行截图，展示了如何通过自然语言查询 PostgreSQL 数据库

示例数据：RAGmonsters

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

RAGmonsters 的 PostgreSQL 版本提供了结构完善的关系型数据库，包含多个表及其关系，可支持复杂查询，展示通过 MCP 将自然语言处理与结构化数据库访问相结合的强大能力。

先决条件

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

项目结构

├── .env.example        # Example environment variables
├── package.json        # Node.js project configuration
├── README.md           # This documentation
├── img/                # Images for documentation
│   └── screenshot.jpg  # Application screenshot
├── scripts/
│   ├── initializeDb.js # Script to initialize the database with RAGmonsters data
│   └── testMCP.js      # Script to test MCP server with LLM integration
├── src/
│   ├── index.js        # Main application server
│   ├── llm.js          # LangChain integration for LLM
│   ├── mcp-client.js   # MCP client for PostgreSQL
│   └── public/         # Web interface files
│       └── index.html  # Chat interface

功能

• 使用自然语言探索 PostgreSQL 数据库
• 集成官方 PostgreSQL 实现的 MCP 服务
• 集成 LangChain.js，支持与 LLM 交互
• 简单的 Web 界面，可与数据库聊天
• 提供 API 端点的 Express.js 后端

本地开发

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

npm install

3. 将 .env.example 复制为 .env 并更新其中的值，以配置环境变量：

cp .env.example .env

4. 使用 PostgreSQL 连接详情和 LLM API 密钥更新 .env 文件。

5. 使用 RAGmonsters 示例数据初始化数据库：

node scripts/initializeDb.js

此脚本会克隆 RAGmonsters 仓库，并将示例数据填充到 PostgreSQL 数据库中。

6. 测试 MCP 服务与 LLM 集成：

node scripts/testMCP.js

此脚本会通过 MCP 服务连接到 PostgreSQL 数据库，并使用 LLM 将自然语言查询转换为 SQL。它演示了应用的核心功能，不涉及 Web 界面。

7. 启动开发服务器：

npm run dev

应用将在 http://localhost:8080 上运行（或使用 .env 文件中指定的端口）。

工作原理

1. 应用使用提供的连接详情连接到 PostgreSQL 数据库
2. MCP 服务提供与数据库交互的标准化方式
3. 当你用自然语言提问时，应用会：
   • 通过 MCP 服务获取数据库架构
   • 将你的问题和数据库架构一起发送给 LLM
   • LLM 生成合适的 SQL 查询
   • 通过 MCP 服务对数据库执行查询
   • 在 Web 界面中显示结果

使用 testMCP.js 进行测试

testMCP.js 脚本演示了应用程序的核心功能，无需使用 Web 界面：

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

此脚本适用于：

• 测试数据库连接
• 验证 MCP 服务是否正常运行
• 确保 LLM 能够生成有效的 PostgreSQL 查询
• 无需使用 Web 界面即可探索数据库架构和数据

部署到 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" # Optional, defaults to gpt-4o-mini
   clever env set LLM_API_URL "https://api.your-llm-provider.com" # Optional, for alternative OpenAI-compatible providers
   

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

资源

• Model Context Protocol 文档
• LangChain.js 文档
• Clever Cloud Node.js 文档
• Clever Cloud 控制台

许可证

此示例遵循 MIT 许可证条款。