# LostInBrittany
## 基本信息
- Slug: `lostinbrittany-ragmonsters-mcp-pg`
- Source: modelscope
- Publisher: @LostInBrittany/RAGmonsters-mcp-pg
- Categories: databases / rag-systems / api-testing
- Hosted: No
- License: Unknown
- Source URL: https://www.modelscope.cn/mcp/servers/@LostInBrittany/RAGmonsters-mcp-pg
## 简介
暂无描述。
## MCP Server 详情

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

## 概述

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

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

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

### 通用 MCP 数据库访问的问题

通用 MCP PostgreSQL 服务器为 LLMs 提供了一个 `query` 工具，使它们能够：
- 探索数据库模式
- 根据自然语言问题制定 SQL 查询
- 针对数据库执行这些查询

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

### 关于 RAGmonsters 数据集

[RAGmonsters](https://github.com/LostInBrittany/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 工具无缝集成

![RAGmonsters Explorer 截图](img/screenshot.jpg)

此界面允许用户：
- 浏览数据集中的所有怪物
- 按栖息地、类别和稀有度筛选怪物
- 查看每个怪物的详细信息，包括能力、技能、优势和劣势

## 示例：特定领域 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 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 (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控制台](https://console…