RAG MCP Tool

本项目是一个基于 Model Context Protocol (MCP) 的 RAG (检索增强生成) 工具，旨在为本地文件提供智能检索能力。本项目能够扫描指定目录下的文本文件，生成向量索引，并通过 MCP 协议提供检索服务。

功能特性

增量索引: 智能识别文件变更，仅对新增或修改的文件进行重新索引，提高效率。
自动过滤: 自动忽略以 . 开头的隐藏目录（如 .git, .venv 等）。
多格式支持: 支持常见的纯文本文件格式（.txt, .md, .json, .py, .js 等）。
MCP 协议支持: 提供标准的 MCP 工具 search_rag 和 read_raw_file，可轻松集成到 Claude Desktop 等客户端。
灵活配置: 支持自定义 LLM 服务地址、模型名称和分块策略。

安装

本项目需要使用 Python 3.13 或更高版本。推荐使用 uv 进行包管理和运行。

# 克隆仓库 git clone <repository_url> cd rag_mcp # 安装依赖 uv sync

配置

在项目根目录下创建 config.yaml 文件，参考以下格式进行配置：

llm: service_type: "local" # 或 "openai" 等 base_url: "http://localhost:1234/v1" # LLM 服务 API 地址 api_key: "your-api-key" # 如果需要 timeout: 60 model: name: "text-embedding-qwen3-embedding-4b" # 使用的 Embedding 模型名称 context_window: 4096 temperature: 0.7 processing: chunk_count: 5 # 文本分块数量

使用说明

命令行工具

使用 uv run mcp_rag_tool 运行工具。

1. 建立索引

对指定目录进行索引：

uv run mcp_rag_tool --dir /path/to/your/documents

rag数据会存放在 /path/to/your/documents/.muxue_rag 目录下

2. 启动 MCP 服务器

启动服务器以供 MCP 客户端连接：

uv run mcp_rag_tool --serve

也可以指定目录启动MCP服务器：

uv run mcp_rag_tool --dir /path/to/your/documents --serve

用这种方式启动，serach_rag工具不会有dir_path参数，所有查询会锁定这个目录下。

注意：

此启动方式只用于锁定serach_rag工具的查询目录（即屏蔽掉dir_path参数），不会建立rag索引。
必须先执行uv run mcp_rag_tool --dir /path/to/your/documents建立索引，再启动mcp服务器。

3. 其他命令

清理索引: 删除指定目录的 RAG 数据库。
uv run mcp_rag_tool --clean --dir /path/to/your/documents
备份索引: 备份 RAG 数据库到指定位置。
uv run mcp_rag_tool --backup --dir /path/to/your/documents --backup-path /path/to/backup
查看帮助:
uv run mcp_rag_tool --help

MCP 客户端配置

要将此工具添加到 Claude Desktop，请编辑您的 Claude 配置文件 (macOS 上通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json)：

{ "mcpServers": { "rag-mcp": { "command": "uv", "args": [ "--directory", "/path/to/rag_mcp", "run", "mcp_rag_tool", "--serve" ], "env": { "RAG_MCP_CONFIG": "/path/to/rag_mcp/config.yaml" } } } }

注意：请将 /path/to/rag_mcp 替换为您的实际项目路径。