星战科技xingzhan.cloud
返回市场
RAG怪物-MCP-数据库

RAG怪物-MCP-数据库

作者：LostInBrittany2 星标更新：2025-05-14
安装使用来源：spider==github.com

项目介绍

用于RAGmonsters的自定义PostgreSQL MCP服务器

概述

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

本实现使用FastMCP，这是一个高性能的模型上下文协议实现，它为工具与LLMs之间的交互提供了改进的效率和可靠性。

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

通用MCP数据库访问的问题

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

  • 探索数据库模式
  • 根据自然语言问题构建SQL查询
  • 执行这些查询以获取数据库结果

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

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

关于RAGmonsters数据集

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

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

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

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

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

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

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

Web界面

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

探索者界面

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

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

聊天界面

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

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

RAGmonsters探索者截图

该界面允许用户：

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

示例：领域特定API vs. 通用SQL

通用MCP PostgreSQL方法：

用户："哪些是攻击力最高的前三只怪物，且对火元素脆弱？"

LLM：（必须理解模式、连接和SQL语法）
1. 第一个查询了解模式
2. 第二个查询找到攻击力高的怪物
3. 第三个查询找到脆弱的怪物
4. 最终查询连接并筛选结果

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

用户："哪些是攻击力最高的前三只怪物，且对火元素脆弱？"

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. 减少令牌使用：LLM不需要处理复杂的SQL或模式信息
  4. 增强的安全性：没有直接SQL访问意味着减少了注入攻击的风险
  5. 可维护性：更改数据库模式不需要重新训练LLM
  6. 可扩展性：能够处理更大和更复杂的数据库

开始使用

安装

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

可用工具

MCP服务器提供以下工具：

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

    • 参数：filters（类别、栖息地、稀有度），sort（字段、方向），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://用户名:密码@主机:端口/数据库

# LLM API配置
LLM_API_KEY=您的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：

    npm install -g clever-tools

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

    clever login

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

    clever create --type node <APP_NAME>

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

    clever domain add <您的域名>

  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 "您的-openai-api-key"
clever env set LLM_API_MODEL "gpt-4o-mini" # 可选，默认为gpt-4o-mini
clever env set LLM_API_URL "https://api.您的-llm提供商.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应用程序的默认端口

许可证

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

致谢