为 RAGmonsters 定制的 PostgreSQL MCP 服务器

概述

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

该实现使用了FastMCP ，这是模型上下文协议的高性能实现，它为基于工具的与 LLM 的交互提供了更高的效率和可靠性。

该项目以RAGmonsters数据集为基础。RAGmonsters 是一个开源项目，它提供了一个丰富的虚构怪物数据集，其中包含各种属性、能力和关系，专为演示和测试检索增强生成 (RAG) 系统而设计。

通用 MCP 数据库访问的问题

通用 MCP PostgreSQL 服务器为 LLM 提供了一个query工具，允许他们：

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

虽然这种方法有效，但它在实际应用中有几个局限性：

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

关于 RAGmonsters 数据集

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

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

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

这个丰富、互联的数据集非常适合展示特定领域 API 与通用 SQL 访问的强大功能。

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

该项目演示了如何构建自定义 MCP 服务器，为 RAGmonsters 数据集提供更高级别、特定领域的 API。我们的 MCP 服务器不提供原始 SQL 功能，而是提供以下专用函数：

抽象数据库复杂性：隐藏底层模式和 SQL 细节
提供特定领域的操作：提供符合业务概念的功能
针对常见查询进行优化：针对常见问题实施高效的查询模式
执行业务规则：嵌入特定领域的逻辑和约束
提高安全性：通过删除直接 SQL 访问来限制攻击面

Web 界面

该项目包括两个用于与 RAGmonsters 数据集交互的主要接口：

资源管理器界面

一个以数据为中心的界面，用于通过 MCP API 探索和过滤 RAGmonsters 数据集：

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

聊天界面

用于与 RAGmonsters 数据集交互的自然语言界面：

用自然语言询问有关怪物的问题
获取具有丰富格式的 Markdown 格式响应
由 LangGraph 的 ReAct 代理模式提供支持
与 MCP 工具无缝集成

RAGmonsters 浏览器截图

该界面允许用户：

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

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

通用 MCP PostgreSQL 方法：

User: "What are the top 3 monsters with the highest attack power that are vulnerable to fire?" LLM: (Must understand schema, joins, and SQL syntax) 1. First query to understand the schema 2. Second query to find monsters with attack power 3. Third query to find vulnerabilities 4. Final query to join and filter results

我们的定制 MCP 服务器方法：

User: "What are the top 3 monsters with the highest attack power that are vulnerable to fire?" LLM: (Uses our domain-specific API) 1. Single call: getMonsters({ vulnerableTo: "fire", sortBy: "attackPower", limit: 3 })

项目结构

├── .env.example # Example environment variables ├── package.json # Node.js project configuration ├── README.md # This documentation ├── img/ # Images for documentation ├── scripts/ │ ├── testMcpServer.js # Test script for the MCP server │ └── testLogger.js # Logger for test script ├── src/ │ ├── index.js # Main application server │ ├── mcp-server/ # Custom MCP server implementation with FastMCP │ │ ├── index.js # Server entry point │ │ ├── tools/ # Domain-specific tools │ │ │ ├── index.js # Tool registration │ │ │ └── monsters.js # Monster-related operations │ │ └── utils/ # Helper utilities │ │ └── logger.js # Logging functionality │ ├── llm.js # LangChain integration for LLM │ └── public/ # Web interface files │ ├── index.html # Monster explorer interface │ └── chat.html # Chat interface for LLM interactions

特征

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

特征

LangChain.js 集成：与 MCP 工具完全集成的 LLM 交互
Web 界面：用于与 RAGmonsters 数据集交互的资源管理器和聊天界面
部署就绪：配置为在 Clever Cloud 等平台上轻松部署

这种方法的好处

改进的性能：优化查询和缓存策略
更好的用户体验：更准确、更快速的响应
减少令牌使用：LLM 不需要处理复杂的 SQL 或模式信息
增强的安全性：没有直接的 SQL 访问意味着降低注入攻击的风险
可维护性：数据库模式的更改不需要重新培训 LLM
可扩展性：可以处理更大、更复杂的数据库

入门

安装

克隆此存储库
安装依赖项： npm install
将.env.example复制到.env并配置 PostgreSQL 连接字符串和 LLM API 密钥
运行 MCP 服务器测试脚本： npm run test
运行 LLM 集成测试脚本： npm run test:llm
启动服务器： npm start

可用工具

MCP 服务器提供以下工具：

getMonsters - 获取怪物列表，并可选择过滤、排序和分页
- 参数：过滤器（类别、栖息地、稀有度）、排序（字段、方向）、限制、偏移
- 返回：包含基本信息的怪物对象数组
getMonsterById - 根据 ID 获取特定怪物的详细信息
- 参数：monsterId
- 返回：具有所有属性、力量、能力、优势和弱点的详细怪物对象
add - 用于添加两个数字的简单实用程序（用于测试）
- 参数：a、b
- 返回：两个数字的和

LLM 集成架构

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

LangGraph ReAct 代理模式

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

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

测试 LLM 集成

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

npm run test:llm

此脚本：

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

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

先决条件

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

环境变量

使用以下变量创建.env文件：

# PostgreSQL connection string POSTGRESQL_ADDON_URI=postgres://username:password@host:port/database # LLM API configuration 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

安装 Clever Cloud CLI：
npm install -g clever-tools
登录您的 Clever Cloud 帐户：
clever login
创建新应用程序：
clever create --type node <APP_NAME>
添加您的域名（可选但建议添加）：
clever domain add <YOUR_DOMAIN_NAME>
创建 PostgreSQL 附加组件并将其链接到您的应用程序：
clever addon create <APP_NAME>-pg --plan dev clever service link-addon <APP_NAME>-pg
这将自动在您的应用程序中设置POSTGRESQL_ADDON_URI环境变量。
设置所需的环境变量：
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
部署您的应用程序：
clever deploy
打开您的应用程序：
clever open

使用 Clever Cloud 控制台

您也可以直接从Clever Cloud Console部署：

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

重要说明

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

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

致谢

RAGmonsters为样本数据集
MCP 规范的模型上下文协议
FastMCP用于高性能 MCP 实现
Clever Cloud提供托管功能

RAGmonsters Custom PostgreSQL MCP Server