RAG MCP Tool

# RAG的MCP工具需求文档 # 一、文档基础信息 |项目名称|RAG的MCP工具| |---|---| |文档版本|V1.0| |需求提出人|待补充| |文档创建时间|2025年12月14日| |文档状态|初稿| |适用范围|该RAG的MCP工具的开发、测试、运维及使用相关人员| # 二、项目背景与目标 ## 2.1 项目背景 为满足用户对指定目录下文本文件的检索增强生成（RAG）需求，以及对原始文件的读取需求，需开发一款支持灵活配置、多目录适配的MCP工具。该工具需具备自动化处理文本文件、构建专属RAG数据库、提供高效检索及原始文件读取能力，助力AI快速获取目标信息并访问原始文件资源。 ## 2.2 项目目标 - 支持通过配置文件灵活配置LLM模型、相关参数及分片数，适配不同使用场景。 - 支持命令行指定目标目录，自动处理目录下所有纯文本文件，跳过非文本文件（如图片、视频等）。 - 提供search_rag检索能力与read_raw_file原始文件读取能力，满足信息检索与原始内容获取需求。 - search_rag返回结果需包含检索内容及对应原始文件目录，支持AI直接调用read_raw_file工具读取。 - 构建支持多目录的RAG数据库，在各目标目录下生成专属的.muxue_rag目录存储数据库文件。 # 三、核心需求概述 本工具核心定位为一款支持RAG能力的MCP工具，核心需求涵盖四大维度：一是灵活的配置能力，支持LLM、模型及分片数的配置；二是目录文本处理能力，支持命令行指定目录并筛选处理纯文本文件；三是核心工具能力，提供search_rag检索与read_raw_file读取功能；四是数据库适配能力，支持多目录RAG数据库存储与管理。 请使用python完成这项工作，可用LM Studio提供的`text-embedding-qwen3-embedding-4b`模型进行测试 ```sh curl http://127.0.0.1:1234/v1/embeddings \ -H "Content-Type: application/json" \ -d '{ "model": "text-embedding-qwen3-embedding-4b", "input": "Some text to embed" }' ``` 项目已经使用uv管理，你需要用uv add添加各类python的pypi包，使用uv run python替代python命令。 # 四、详细功能需求 ## 4.1 配置文件功能 ### 4.1.1 配置项要求 - LLM配置：支持配置使用的LLM服务类型（如OpenAI、本地化LLM等），需包含LLM服务地址、访问密钥（若有）、请求超时时间等关键参数。 - 模型配置：支持配置RAG过程中使用的具体模型名称（如gpt-4o、llama3等），可指定模型的上下文窗口大小、生成温度等相关参数。 - 分片数配置：支持配置文本文件处理时的分片数量，用户可根据文件大小、处理效率需求自定义分片数，分片需保证文本内容的完整性与逻辑性（避免关键信息被拆分至不同分片）。 ### 4.1.2 配置文件格式与加载 - 配置文件格式：采用通用的配置文件格式（如YAML、JSON），格式清晰、易于编辑，支持注释说明各配置项含义。 - 加载方式：工具启动时自动加载默认配置文件（默认路径可配置），也支持通过命令行参数指定自定义配置文件路径。 - 配置校验：工具启动时需对配置文件进行校验，若存在配置项缺失、格式错误或参数无效等问题，需输出明确的错误提示信息（包含错误位置、原因），并终止启动。 ## 4.2 目录文本处理功能 ### 4.2.1 命令行参数指定目录 - 支持通过命令行参数（如--dir、-d）指定需要进行RAG处理的目标目录路径（支持绝对路径与相对路径）。 - 若指定目录不存在，工具需输出“目录不存在”的错误提示；若指定路径为文件而非目录，需输出“路径不是有效目录”的错误提示。 ### 4.2.2 文本文件筛选与处理 - 文件类型筛选：自动遍历目标目录下的所有文件（包含子目录文件），跳过明显非纯文本的文件类型，具体跳过类型包括但不限于：图片格式（.jpg、.png、.gif、.bmp等）、视频格式（.mp4、.avi、.mov、.flv等）、音频格式（.mp3、.wav、.flac等）、压缩包格式（.zip、.rar、.tar、.gz等）、可执行文件（.exe、.dll、.sh等）。 - 纯文本文件识别：支持处理的纯文本文件格式包括但不限于：.txt、.md、.json、.yaml、.xml、.csv、.log等，可通过文件扩展名结合文件头部内容特征（如是否为文本编码）双重校验是否为纯文本文件。 - 文本处理流程：读取筛选后的纯文本文件内容，根据配置文件中的分片数对文本进行分片处理，处理过程中需保留文件的原始路径信息，为后续RAG检索与原始文件读取提供关联依据。 ## 4.3 核心工具能力 ### 4.3.1 search_rag检索能力 - 检索触发：支持通过MCP接口调用search_rag功能，接收用户输入的检索关键词或检索语句。 - 检索逻辑：基于目标目录下构建的RAG数据库进行检索，匹配与检索关键词/语句相关的文本分片内容。 - 返回结果格式：返回结果需包含以下核心信息： 检索匹配内容：展示与检索需求相关的文本分片内容，标注匹配度（可选，如高、中、低）。 - 原始文件信息：包含匹配内容对应的原始文件的完整目录路径（绝对路径），确保AI可直接使用该路径调用read_raw_file工具读取文件。 - 检索统计信息：检索耗时、匹配到的文件数量、匹配到的分片数量等（可选）。 异常处理：若RAG数据库未构建或损坏，需输出“RAG数据库未就绪，请先处理目标目录构建数据库”的提示；若检索无匹配结果，需输出“未检索到与关键词相关的内容”的提示。 ### 4.3.2 read_raw_file原始文件读取能力 - 读取触发：支持通过MCP接口调用read_raw_file功能，接收用户输入的原始文件完整目录路径（需与search_rag返回的文件目录一致）。 - 读取逻辑：根据输入的文件路径，读取文件的原始文本内容，保留文件的原始格式（如换行、缩进、特殊符号等）。 - 返回结果：返回文件的完整原始文本内容；若文件不存在，输出“文件不存在，请检查路径是否正确”的错误提示；若文件为非纯文本文件，输出“无法读取非纯文本文件”的错误提示。 - 权限处理：若工具无目标文件的读取权限，需输出“无文件读取权限，请检查权限设置”的错误提示。 ## 4.4 RAG数据库功能 ### 4.4.1 数据库创建与存储 - 数据库路径：在用户通过命令行指定的目标目录下自动创建.muxue_rag隐藏目录，用于存储该目录对应的RAG数据库文件（包含文本分片数据、索引信息等）。 - 多目录支持：支持对不同目标目录分别处理，每个目标目录下均生成独立的.muxue_rag目录，各目录的RAG数据库相互独立，互不干扰。 - 数据库初始化：首次处理目标目录时，自动初始化.muxue_rag目录及相关数据库文件；若目标目录下已存在.muxue_rag目录，支持增量更新（仅处理新增/修改的文本文件）或全量更新（重新处理所有文本文件，覆盖原有数据库）。 ### 4.4.2 数据库管理 - 索引构建：处理文本文件时，为每个文本分片构建索引，索引需关联分片内容、原始文件路径等信息，提升search_rag检索效率。 - 数据库清理：支持通过命令行参数（如--clean）清理指定目标目录下的.muxue_rag目录及数据库文件，清理前需提示用户确认（避免误操作）。 - 数据库备份（可选）：支持通过命令行参数（如--backup）备份.muxue_rag目录下的数据库文件，备份文件存储路径可自定义。 # 五、非功能需求 ## 5.1 性能需求 - 处理效率：单目录下1000个以内、单个文件大小不超过100MB的纯文本文件，全量处理时间不超过30分钟；增量处理时间根据新增/修改文件数量自适应，单个文件处理时间不超过10秒。 - 检索效率：search_rag检索响应时间不超过3秒（针对1000个文件构建的RAG数据库）。 - 读取效率：read_raw_file读取单个不超过100MB的文本文件，响应时间不超过5秒。 ## 5.2 兼容性需求 - 系统兼容性：支持Windows（Windows 10及以上）、Linux（CentOS 7及以上、Ubuntu 18.04及以上）、macOS（macOS 12及以上）操作系统。 - 文件编码兼容性：支持处理UTF-8、GBK、GB2312等常见文本编码格式的文件，若遇到不支持的编码格式，需输出“不支持的文件编码格式”的提示。 ## 5.3 可靠性需求 - 容错性：处理文本文件过程中，若单个文件读取失败（如文件损坏、权限不足），工具需记录错误信息（包含文件名、路径、错误原因），并继续处理其他文件，不中断整体处理流程。 - 稳定性：工具连续运行24小时无崩溃、无内存泄漏等问题；并发调用search_rag（不超过10次并发）时，响应正常，无数据错乱问题。 ## 5.4 安全性需求 - 配置文件安全：配置文件中若包含敏感信息（如LLM访问密钥），支持加密存储，工具读取时自动解密；禁止明文打印敏感信息。 - 文件访问控制：仅处理用户指定目录下的文件，禁止访问系统敏感目录（如Windows的System32目录、Linux的/root目录等），除非用户明确授权。 ## 5.5 可维护性需求 - 日志记录：工具运行过程中生成详细日志，包含启动信息、配置加载信息、文件处理信息、检索/读取操作信息、错误信息等，日志支持按时间分割存储，日志保留时间可配置（默认保留7天）。 - 模块化设计：工具采用模块化架构（如配置模块、文件处理模块、数据库模块、检索模块、读取模块等），便于后续功能扩展、bug修复及版本迭代。 # 六、接口需求（MCP接口） ## 6.1 search_rag接口 - 接口名称：search_rag - 接口描述：提供RAG检索能力，返回检索匹配内容及对应原始文件目录 - 请求参数： keyword：字符串类型，必填，检索关键词或检索语句 - dir_path：字符串类型，可选，指定检索的目标目录（若不指定，默认检索所有已处理过的目录的RAG数据库） 返回参数： code：整数类型，响应状态码（200表示成功，500表示失败） message：字符串类型，响应信息（成功时为“检索成功”，失败时为具体错误原因） data：对象类型，成功时返回检索结果，失败时为null match_content：数组类型，存储匹配的文本分片内容，每个元素包含“content”（分片内容）、“match_degree”（匹配度，可选） file_info：数组类型，存储匹配内容对应的原始文件信息，每个元素包含“file_path”（文件完整目录路径）、“file_name”（文件名） stats：对象类型，检索统计信息，包含“cost_time”（检索耗时，单位：秒）、“match_file_count”（匹配文件数量）、“match_chunk_count”（匹配分片数量） ## 6.2 read_raw_file接口 - 接口名称：read_raw_file - 接口描述：读取指定路径的原始文本文件内容 - 请求参数： file_path：字符串类型，必填，原始文件的完整目录路径（需与search_rag返回的file_path一致） 返回参数： code：整数类型，响应状态码（200表示成功，500表示失败） message：字符串类型，响应信息（成功时为“读取成功”，失败时为具体错误原因） data：对象类型，成功时返回文件内容，失败时为null raw_content：字符串类型，文件的完整原始文本内容 file_info：对象类型，文件基本信息，包含“file_path”（文件路径）、“file_size”（文件大小，单位：字节）、“modify_time”（文件最后修改时间） # 七、使用流程示例 1. 配置准备：编辑配置文件（如config.yaml），配置LLM服务地址、访问密钥、使用的模型名称、分片数等参数。 2. 目录处理：通过命令行执行“mcp_rag_tool --dir /path/to/target_dir --config /path/to/config.yaml”，工具自动在target_dir目录下创建.muxue_rag目录，构建RAG数据库。 3. RAG检索：调用search_rag接口，传入检索关键词（如“人工智能发展趋势”），工具返回匹配的文本内容及对应原始文件目录。 4. 原始文件读取：获取search_rag返回的file_path，调用read_raw_file接口传入该路径，工具返回对应文件的原始文本内容。 5. 数据库清理（可选）：通过命令行执行“mcp_rag_tool --dir /path/to/target_dir --clean”，确认后清理该目录下的.muxue_rag目录及数据库文件。 # 八、附录 ## 8.1 支持的文本文件格式 .txt、.md、.json、.yaml、.xml、.csv、.log、.ini、.conf等纯文本格式文件。 ## 8.2 跳过的非文本文件格式 图片：.jpg、.png、.gif、.bmp、.tiff、.svg等；视频：.mp4、.avi、.mov、.flv、.mkv等；音频：.mp3、.wav、.flac、.aac等；压缩包：.zip、.rar、.tar、.gz、.7z等；可执行文件：.exe、.dll、.sh、.bat、.apk等；其他：.pdf（非文本模式）、.docx（非文本模式）、.xlsx等二进制文件。 ## 8.3 命令行参数说明 |参数|缩写|描述|是否必填| |---|---|---|---| |--dir|-d|指定需要处理的目标目录路径|处理目录时必填| |--config|-c|指定配置文件路径|可选（默认加载当前目录下的config.yaml）| |--clean|-cl|清理指定目录下的.muxue_rag目录及数据库文件|清理时必填| |--backup|-b|备份指定目录下的.muxue_rag数据库文件，需配合--backup-path使用|备份时必填| |--backup-path|-bp|指定数据库备份文件存储路径|使用--backup时必填| |--help|-h|查看工具使用帮助信息|可选| |--version|-v|查看工具版本信息|可选| > （注：文档部分内容可能由 AI 生成）