为 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 工具无缝集成
该界面允许用户：
- 浏览数据集中的所有怪物
- 按栖息地、类别和稀有度筛选怪物
- 查看每个怪物的详细信息，包括力量、能力、优势和劣势
示例：特定领域 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 - 用于添加两个数字的简单实用程序（用于测试）
LLM 集成架构
该项目采用现代方法将 LLM 与特定领域工具集成：
LangGraph ReAct 代理模式
该应用程序使用 LangGraph 的 ReAct（推理和代理）代理模式，该模式：
- 处理用户查询以了解意图
- 根据查询确定要使用的工具
- 自动执行适当的工具
- 将结果综合成连贯的响应
- 在需要时处理多步骤推理
测试 LLM 集成
该项目包含一个测试脚本，演示如何使用 LangChain.js 将 LLM 与 MCP 服务器集成：
此脚本：
- 使用 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 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 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 文件。
致谢