自定义 PostgreSQL MCP 服务器用于 RAGmonsters

概述

本仓库展示了一种更高级的方法，通过模型上下文协议（MCP）将大型语言模型（LLMs）与数据库集成。虽然通用的 MCP PostgreSQL 服务器允许 LLMs 通过原始 SQL 查询来探索数据库，但此项目采取了不同的方法，创建了一个自定义 MCP 服务器，提供针对应用程序需求量身定制的特定领域 API。

该实现使用了 FastMCP，这是一种高性能的 Model Context Protocol 实现，为基于工具的 LLM 交互提供了更高的效率和可靠性。

该项目以 RAGmonsters 数据集为基础。RAGmonsters 是一个开源项目，提供了一个丰富的虚构怪物数据集，包含各种属性、能力和关系——特别设计用于演示和测试检索增强生成（RAG）系统。

通用 MCP 数据库访问的问题

通用 MCP PostgreSQL 服务器为 LLMs 提供了一个 query 工具，使它们能够：

• 探索数据库模式
• 根据自然语言问题制定 SQL 查询
• 针对数据库执行这些查询

尽管这种方法有效，但在实际应用中存在几个限制：

• 认知负担：LLM 必须理解整个数据库模式
• 低效性：通常需要多个 SQL 查询才能回答一个问题
• 安全问题：直接 SQL 访问需要仔细的提示工程以防止注入攻击
• 性能：如果 LLM 不了解数据库的索引策略，复杂的查询可能效率低下
• 领域知识差距：LLM 缺乏对业务规则和特定领域约束的理解

关于 RAGmonsters 数据集

RAGmonsters 是一个专门为测试和演示检索增强生成（RAG）系统而设计的开放数据集。它包含了具有丰富属性、能力和关系的虚构怪物信息——非常适合自然语言查询演示。

PostgreSQL 版本的 RAGmonsters 提供了一个结构良好的关系型数据库，包含多个表和关系，包括：

• 具有各种属性（攻击力、防御力、生命值等）的怪物
• 怪物可以拥有的能力
• 具有复杂关系的元素（火、水、土等）
• 可以找到怪物的栖息地
• 进化链和怪物之间的关系

这个丰富且相互关联的数据集非常适合展示特定领域的 API 与通用 SQL 访问相比的优势。

我们的解决方案：特定领域的 MCP API

该项目展示了如何构建一个自定义 MCP 服务器，为 RAGmonsters 数据集提供更高层次的特定领域 API。我们的 MCP 服务器不暴露原始 SQL 功能，而是提供专门构建的功能，这些功能：

1. 抽象数据库复杂性：隐藏底层模式和 SQL 细节
2. 提供特定领域的操作：提供与业务概念一致的功能
3. 优化常见查询：为常见问题实现高效的查询模式
4. 强制执行业务规则：嵌入特定领域的逻辑和约束
5. 提高安全性：通过移除直接 SQL 访问来减少攻击面

Web 界面

该项目包括两个主要界面，用于与 RAGmonsters 数据集进行交互：

探索者界面

一个专注于数据的界面，通过 MCP API 探索和过滤 RAGmonsters 数据集：

• 浏览所有怪物，并按类别、栖息地和稀有度进行筛选
• 查看每个怪物的详细信息
• 使用 Bootstrap 构建的交互式 UI

聊天界面

一个自然语言界面，用于与 RAGmonsters 数据集进行交互：

• 用自然语言询问关于怪物的问题- 获取带有丰富格式的 Markdown 格式响应
• 由 LangGraph 的 ReAct 代理模式驱动
• 与 MCP 工具无缝集成

此界面允许用户：

• 浏览数据集中的所有怪物
• 按栖息地、类别和稀有度筛选怪物
• 查看每个怪物的详细信息，包括能力、技能、优势和劣势

示例：特定领域 API 与通用 SQL

通用 MCP PostgreSQL 方法：

用户: "哪些是最强攻击力量且对火属性脆弱的前3个怪物？"

LLM: (必须理解模式、连接和 SQL 语法)

1. 第一个查询用于理解模式
2. 第二个查询用于查找具有攻击力的怪物
3. 第三个查询用于查找弱点
4. 最终查询用于连接并过滤结果

我们的自定义 MCP 服务器方法：

用户: "哪些是最强攻击力量且对火属性脆弱的前3个怪物？"

LLM: (使用我们的特定领域 API)

1. 单一调用: getMonsters({ vulnerableTo: "fire", sortBy: "attackPower", limit: 3 })

项目结构

├── .env.example # 环境变量示例
├── package.json # Node.js 项目配置
├── README.md # 本文档
├── img/ # 文档图片
├── scripts/
│ ├── testMcpServer.js # MCP 服务器测试脚本
│ └── testLogger.js # 测试脚本日志记录器
├── src/
│ ├── index.js # 主应用程序服务器
│ ├── mcp-server/ # 使用 FastMCP 实现的自定义 MCP 服务器
│ │ ├── index.js # 服务器入口点
│ │ ├── tools/ # 特定领域的工具
│ │ │ ├── index.js # 工具注册
│ │ │ └── monsters.js # 怪物相关操作
│ │ └── utils/ # 辅助工具
│ │ └── logger.js # 日志功能
│ ├── llm.js # LLM 的 LangChain 集成
│ └── public/ # Web 界面文件
│ ├── index.html # 怪物浏览器界面
│ └── chat.html # 用于 LLM 交互的聊天界面

功能

• 使用 FastMCP 的自定义 MCP 服务器：针对 RAGmonsters 数据的高性能特定领域 API
• 优化查询：预构建的高效数据库操作
• 业务逻辑层：嵌入在 API 中的领域规则和约束
• 结构化响应格式：一致的 JSON 响应供 LLM 使用
• 全面的日志记录：详细的调试和监控日志
• 测试套件：验证服务器功能和 LLM 集成的脚本
• LLM 集成：
  • 通过 LangChain.js 与 OpenAI 及其他兼容的 LLM 提供商集成
  • 使用 LangGraph ReAct 代理模式实现高效的工具使用
  • 自动处理工具调用和响应
• Web 界面：
  • 用于浏览和筛选怪物的浏览器界面
  • 支持 Markdown 渲染的自然语言交互聊天界面

功能

• LangChain.js 集成：完全集成的 LLM 与 MCP 工具交互
• Web 界面：用于与 RAGmonsters 数据集交互的浏览器和聊天界面
• 部署就绪：配置为易于在如 Clever Cloud 等平台上部署

此方法的优势

1. 性能提升：优化查询和缓存策略
2. 更好的用户体验：更准确且更快的响应
3. 减少 Token 使用：LLM 不需要处理复杂的 SQL 或模式信息
4. 增强安全性：无直接 SQL 访问意味着减少了注入攻击的风险
5. 可维护性：更改数据库模式不需要重新训练 LLM
6. 可扩展性：能够处理更大和更复杂的数据库

开始使用

安装

1. 克隆此仓库
2. 安装依赖项: npm install3. 将 .env.example 复制为 .env 并配置您的 PostgreSQL 连接字符串和 LLM API 密钥
3. 运行 MCP 服务器测试脚本：npm run test
4. 运行 LLM 集成测试脚本：npm run test:llm
5. 启动服务器：npm start

可用工具

MCP 服务器提供了以下工具：

1. getMonsters - 获取怪物列表，可选过滤、排序和分页

   • 参数：filters (category, habitat, rarity), sort (field, direction), limit, offset
   • 返回：包含基本信息的怪物对象数组

2. getMonsterById - 根据 ID 获取特定怪物的详细信息

   • 参数：monsterId
   • 返回：包含所有属性、力量、能力、优势和弱点的详细怪物对象

3. add - 简单的工具用于添加两个数字（用于测试）

   • 参数：a, b
   • 返回：两个数字的和

LLM 集成架构

该项目使用现代方法将 LLM 与特定领域的工具集成：

LangGraph ReAct 代理模式

应用程序使用了 LangGraph 的 ReAct（推理和行动）代理模式，该模式：

1. 处理用户查询以理解意图
2. 根据查询确定使用哪些工具
3. 自动执行适当的工具
4. 将结果综合成连贯的响应
5. 在需要时处理多步骤推理

测试 LLM 集成

项目包括一个测试脚本，演示如何使用 LangChain.js 将 LLM 与 MCP 服务器集成：

npm run test:llm

此脚本：

1. 使用 StdioClientTransport 连接到 MCP 服务器
2. 使用 LangChain 的 MCP 适配器加载所有可用的 MCP 工具
3. 使用 OpenAI API 创建 LangChain 代理
4. 处理关于怪物的自然语言查询
5. 展示 LLM 如何调用工具来检索信息
6. 记录交互的详细信息

您可以在脚本中修改测试查询以探索系统的不同功能。脚本位于 scripts/testLlmWithMcpServer.js。

前提条件

• Node.js 23 或更高版本
• 包含 RAGmonsters 数据的 PostgreSQL 数据库
• 访问 LLM API（例如，OpenAI）
• FastMCP 包（已包含在依赖项中）

环境变量

创建一个 .env 文件，并设置以下变量：

PostgreSQL 连接字符串

POSTGRESQL_ADDON_URI=postgres://username:password@host:port/database

LLM API 配置

LLM_API_KEY=your_openai_api_key
LLM_API_MODEL=gpt-4o-mini
LLM_API_URL=https://api.openai.com/v1

LLM 配置

• LLM_API_KEY: 您的 OpenAI API 密钥或兼容提供商密钥
• LLM_API_MODEL: 要使用的模型（默认：gpt-4o-mini）
• LLM_API_URL: API 端点（默认：OpenAI 的端点）

应用程序支持任何与 OpenAI 兼容的 API，包括自托管模型和替代提供商。

部署到 Clever Cloud

使用 Clever Cloud CLI

1. 安装 Clever Cloud CLI：
   bash
   npm install -g clever-tools

2. 登录您的 Clever Cloud 账户：
   bash
   clever login

3. 创建一个新的应用程序：
   bash
   clever create --type node <APP_NAME>

4. 添加您的域名（可选但推荐）：
   bash
   clever domain add <YOUR_DOMAIN_NAME>

5. 创建 PostgreSQL 插件并将其链接到您的应用程序：
   bash
   clever addon create <APP_NAME>-pg --plan dev
   clever service link-addon <APP_NAME>-pg

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

6. 设置所需的环境变量：
   bash
   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. 部署您的应用程序：
   bash
   clever deploy

8. 打开您的应用程序：
   bash
   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应用程序的默认端口

许可证

本项目根据MIT许可证发布 - 详情请参阅LICENSE文件。

致谢

• RAGmonsters 提供了示例数据集
• Model Context Protocol 提供了MCP规范
• FastMCP 提供了高性能的MCP实现
• Clever Cloud 提供了托管能力