使用说明

RAG游戏手册

英语 | 泰语

英语

RAG（检索增强生成）实现和工具的全面集合，用于构建基于人工智能的文档搜索和问答系统。

项目

RAG MCP服务器

实现模型上下文协议（MCP）的生产就绪RAG服务器，可与Claude Code和其他兼容MCP的AI助手无缝集成。

主要特点：

多格式文档支持：PDF、DOCX、PPTX、XLSX、CSV、HTML、JSON、RTF、TXT
语义搜索：使用Qdrant矢量数据库的BGE-M3多语言嵌入
混合检索：向量相似度+BM25关键字搜索，采用互序融合（RRF）
LLM驱动的增强功能:
- 用于查询扩展的HyDE（假设文档嵌入）
- 查询增强和重写
- 自动摘要和标记
- 交叉编码器重新排序
安全强化：路径遍历保护、速率限制、输入验证、UUID验证
生产就绪：529多项自动化测试，全面的错误处理

快速开始

# Clone repository
git clone https://github.com/Nuttapon-Moohammadaree/rag-playbook.git
cd rag-playbook/rag-mcp-server

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your API keys

# Build and run
npm run build
npm run mcp

与Claude Code集成

添加到MCP配置(~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "rag": {
      "command": "node",
      "args": ["/path/to/rag-mcp-server/dist/mcp/server.js"],
      "env": {
        "LITELLM_API_KEY": "your-api-key",
        "LITELLM_BASE_URL": "http://localhost:4000/v1",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

MCP工具参考

工具	说明	参数
`rag_search`	跨文档的语义搜索	`query`, `limit`, `threshold`, `fileTypes`, `useHyde`, `useReranking`
`rag_ask`	根据上下文回答问题	`question`, `limit`, `useHyde`, `useReranking`
`rag_index_document`	从路径索引文件	`path`, `force`
`rag_index_text`	索引原始文本	`content`, `title`, `metadata`
`rag_list_documents`	列出索引文档	`status`, `fileType`
`rag_delete_document`	按ID删除	`documentId`
`rag_enhance_query`	LLM查询增强	`query`, `method`

建筑

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code / MCP Client                  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       MCP Server Layer                       │
│    search │ ask │ documents │ llm-enhance                   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                        Core Services                         │
│  Retrieval │ Ask │ Ingestion │ Chunking │ Embedding │ LLM   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Storage Layer                           │
│              Qdrant (Vectors) │ SQLite (Metadata)           │
└─────────────────────────────────────────────────────────────┘

技术栈

组件	技术
运行时	Node.js 18+/Bun
语言	TypeScript
矢量数据库	Qdrant
元数据存储	SQLite（better-splite3）
嵌入	通过LiteLLM嵌入BGE-M3
协议	模型上下文协议（MCP）
测试	Vitest（529+次测试）
验证	Zod

泰语

用于创建文档搜索和人工智能查询的RAG（检索增强版）工具集

主要项目

RAG MCP服务器

生产级RAG服务器，具有实施模型上下文协议（MCP），可与云代码和其他支持MCP的AI助手一起使用。

主要特点：

支持多种文档格式：PDF、DOCX、PPTX、XLSX、CSV、HTML、JSON、RTF、TXT
语义搜索：使用多语言BGE-M3嵌入+Qdrant矢量数据库
混合检索：将矢量相似性+BM25关键字搜索与往复排名融合（RRF）相结合
由LLM补充:
- 用于扩展查询的Hyde（低光学文档嵌入）
- 更新和重写查询
- 自动文档汇总
- 使用交叉编码器对结果进行重新排序
安全：路径保护、速率限制、输入检查、UUID检查
可用生产：529多个自动测试可用

安装方法

基本要求

Node.js 18+或Bun
Qdrant矢量数据库（使用Docker或云运行）
LiteLLM兼容API端点（用于嵌入和LLM）

安装步骤

# 1. Clone repository
git clone https://github.com/Nuttapon-Moohammadaree/rag-playbook.git
cd rag-playbook/rag-mcp-server

# 2. ติดตั้ง dependencies
npm install

# 3. คัดลอกไฟล์ config
cp .env.example .env

# 4. แก้ไขไฟล์ .env ตามการตั้งค่าของคุณ
nano .env

# 5. Build โปรเจกต์
npm run build

# 6. รันเซิร์ฟเวอร์
npm run mcp

.env设置示例

# LiteLLM API Configuration
LITELLM_API_KEY=your-api-key-here
LITELLM_BASE_URL=http://localhost:4000/v1

# Embedding Model
EMBEDDING_MODEL=bge-m3
EMBEDDING_DIMENSION=1024

# Qdrant Vector Database
QDRANT_URL=http://localhost:6333
QDRANT_COLLECTION=documents

# LLM Features (ตั้งเป็น true เพื่อเปิดใช้งาน)
LLM_MODEL=gpt-4o-mini
AUTO_SUMMARY=false
AUTO_TAGS=false
HYDE_ENABLED=false
RERANKING_ENABLED=false

# Storage Path
SQLITE_PATH=./data/rag.db

使用云代码

MCP配置~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "rag": {
      "command": "node",
      "args": ["/path/to/rag-mcp-server/dist/mcp/server.js"],
      "env": {
        "LITELLM_API_KEY": "your-api-key",
        "LITELLM_BASE_URL": "http://localhost:4000/v1",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

设置云代码后，可以使用以下命令：

MCP工具

1. `rag_search` -搜索文档

使用语义搜索搜索文档

ค้นหาเอกสารเกี่ยวกับ "วิธีการตั้งค่า Docker"

参数：

参数	类型	描述
`query`	字符串	搜索词（必填）
`limit`	数字	最大结果数（默认值：10）
`threshold`	数字	最低相似性得分0-1（默认值：0.5）
`fileTypes`	string[]	按文件类型筛选，如[“PDF”、“docx”]
`useHyde`	Boolean	启用海德查询扩展
`useReranking`	Boolean	启用新排名

2. `rag_ask` -问问题。

提出问题并从可搜索的上下文中获得答案

ถามคำถาม: "Docker Compose ใช้ยังไง?"

参数：

参数	类型	描述
`question`	字符串	问题（必填）
`limit`	编号	用作上下文的块数
`useHyde`	Boolean	启用海德
`useReranking`	Boolean	启用新排名

3. `rag_index_document` -从文件索引文档

Index ไฟล์ /path/to/document.pdf

参数：

参数	类型	描述
`path`	字符串	文件路径（必填）
`force`	布尔安	强制索引，即使已经存在

4. `rag_index_text` -文本索引

Index ข้อความนี้เป็นเอกสารชื่อ "บันทึกการประชุม"

参数：

参数	类型	描述
`content`	字符串	文本内容（必填）
`title`	字符串	文档名称（必填）
`metadata`	object	更多元数据

5. `rag_list_documents` -显示文档列表

แสดงเอกสารทั้งหมดที่ index แล้ว

参数：

参数	类型	描述
`status`	string	按状态过滤：indexed、processing、failed
`fileType`	string	按文件类型筛选

6. `rag_delete_document` -删除文档

ลบเอกสาร ID: abc-123-def

参数：

参数	类型	描述
`documentId`	字符串	UUID文档（必填）

7. `rag_enhance_query` -改进查询

ปรับปรุง query "docker" ให้ดีขึ้น

参数：

参数	类型	描述
`query`	字符串	原始查询（必填）
`method`	string	方法：expand，rewrite，both

支持的文件格式

类型	姓氏	使用的Parser
PDF	`.pdf`	pdf解析
Word	`.docx`	猛犸象
PowerPoint	`.pptx`	office解析器
Excel	`.xlsx`, `.xls`	xlsx
CSV	`.csv`	内置
HTML	`.html`, `.htm`	干杯
JSON	`.json`	内置
RTF	`.rtf`	内置
文本	`.txt`, `.md`	内置

项目结构

rag-playbook/
├── rag-mcp-server/              # RAG MCP Server หลัก
│   ├── src/
│   │   ├── config/              # การตั้งค่า
│   │   ├── core/
│   │   │   ├── ask/             # บริการตอบคำถาม
│   │   │   ├── chunking/        # แบ่งข้อความเป็น chunks
│   │   │   ├── embedding/       # สร้าง embeddings
│   │   │   ├── ingestion/       # นำเข้าเอกสาร
│   │   │   │   └── parsers/     # ตัวแปลงไฟล์แต่ละประเภท
│   │   │   ├── llm/             # บริการ LLM (HyDE, summarizer)
│   │   │   ├── reranking/       # จัดอันดับผลลัพธ์ใหม่
│   │   │   └── retrieval/       # ค้นหาและดึงข้อมูล
│   │   ├── mcp/
│   │   │   ├── server.ts        # MCP server หลัก
│   │   │   └── tools/           # MCP tools แต่ละตัว
│   │   ├── storage/
│   │   │   ├── qdrant.ts        # เก็บ vectors
│   │   │   └── sqlite.ts        # เก็บ metadata
│   │   ├── types/               # TypeScript definitions
│   │   └── utils/               # utilities (security, cache)
│   ├── .env.example             # ตัวอย่างการตั้งค่า
│   ├── package.json
│   └── README.md                # เอกสารละเอียด
├── rag-mcp-complete-design.md   # เอกสารออกแบบต้นฉบับ
├── CLAUDE.md                    # การตั้งค่า Claude Code
└── README.md                    # ไฟล์นี้

安全功能

特征	描述
路径横向保护	每次检查和扫描路径，防止在范围外访问文件
速率限制	每段时间限制请求数量。防止DoS
输入验证	用Zod schemas检查所有输入。
UUID验证	文档ID必须是有效的UUID。
错误清理	隐藏内部错误不让客户看到
文档锁定	在index集同时防止race condition。
大小限制	限制内容和元数据大小

发展

cd rag-mcp-server

# รัน tests ทั้งหมด
npm test

# รัน tests พร้อม coverage
npm run test:coverage

# ตรวจสอบ TypeScript
npx tsc --noEmit

# Development mode (auto-rebuild)
npm run dev

测试统计

测试次数: 529+
测试文件: 23
覆盖区域:
- 核心服务（摄取、检索、询问）
- 解析器（PDF、DOCX、PPTX等）
- 存储（SQLite、Qdrant）
- MCP工具
- 安全设施

许可证

麻省理工学院

作者

努塔蓬·穆哈马达雷

贡献

Fork存储库
创建功能分支（git checkout -b feature/amazing-feature)
承诺改变git commit -m 'Add amazing feature')
推到分支git push origin feature/amazing-feature)
打开拉请求

使用说明

RAG游戏手册

英语

项目

RAG MCP服务器

快速开始

与Claude Code集成

MCP工具参考

建筑

技术栈

泰语

主要项目

RAG MCP服务器

安装方法

基本要求

安装步骤

.env设置示例

使用云代码

MCP工具

1. rag_search -搜索文档

2. rag_ask -问问题。

3. rag_index_document -从文件索引文档

4. rag_index_text -文本索引

5. rag_list_documents -显示文档列表

6. rag_delete_document -删除文档

7. rag_enhance_query -改进查询

支持的文件格式

项目结构

安全功能

发展

测试统计

许可证

作者

贡献

相关 MCP

AI持久记忆服务器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

开发者辅助工具

Gemini API文档搜索服务

本地LLM模型控制协议

1. `rag_search` -搜索文档

2. `rag_ask` -问问题。

3. `rag_index_document` -从文件索引文档

4. `rag_index_text` -文本索引

5. `rag_list_documents` -显示文档列表

6. `rag_delete_document` -删除文档

7. `rag_enhance_query` -改进查询