快速接入

先看主来源和安装命令，再打开仓库或文档；下面只保留这个条目的关键接入事实。

命令预览

uvx micro-rag-mcp --data-folder /some/hr_docs --title "HR RAG" --inst "HR instance for confidential search"

详细介绍

micro-rag-mcp：最小本地rag mcp服务器

最小化本地检索增强生成索引和搜索MCP服务器上的文档文件夹。通过具有不同数据文件夹的uvx为多个实例而设计。在索引目录中的每个数据文件夹下存储一个持久的FAISS索引。

目标

简洁而优雅：一个带有两个工具的stdio MCP服务器进程：搜索和重新索引
仅限本地：无网络呼叫；模型下载后即可脱机工作
快速启动：通过内容校验和验证按文件时间增量索引
占用空间小：句子转换器全MiniLM-L6-v2，FAISS IndexFlatIP，numpy

默认行为

嵌入：句子转换器全MiniLM-L6-v2
文件类型：.txt、.md、.pdf、.docx
分块：1000个字符，200个重叠，段落感知
相似性：通过L2归一化向量和FAISS IndexFlatIP的余弦
索引位置：\/Index
启动：扫描文件并对索引应用增量更改
并发：简单的文件锁index.lock，用于序列化reindex操作
日志记录：将人工日志记录到stderr；工具结果是结构化的

多实例支持

您可以通过指定不同的MCP服务器来运行多个独立的MCP服务器实例 --title 和 --inst 每个过程的论点。
两者 --title 和 --inst 是 必需的.
这 --title 用作FastMCP服务器名称。
这 --inst 作为FastMCP指令逐字传递（可以是句子、多行等）。
默认索引位置保持不变 /index 对于所有实例，除非您使用覆盖 --index-folder.

具有两个实例的MCP配置示例

{
  "mcpServers": {
    "team_alpha": {
      "command": "uvx",
      "args": [
        "micro-rag-mcp@0.1.4",
        "--data-folder", "/docs/teamA",
        "--title", "Secret Islands",
        "--inst", "Team Alpha read-only mode with nightly refresh"
      ]
    },
    "team_beta": {
      "command": "uvx",
      "args": [
        "micro-rag-mcp@0.1.4",
        "--data-folder", "/docs/teamB",
        "--title", "Secret Islands",
        "--inst", "Team Beta write-enabled with manual refresh"
      ]
    }
  }
}

要使用多行指令，请使用 \n 在字符串内部：

- "--inst", "Team Alpha\nRead-only\nRefresh: 02:00 IST"

中的每个项目 args array是一个单一的参数；空格和换行符作为字符串的一部分保留。

最小架构

计划源文件

数据流

flowchart LR
  C[Client] --> S[Micro RAG MCP]
  S --> FS[Data folder]
  S --> E[Embedder]
  S --> I[Index manager]
  I --> FI[FAISS index]
  I --> MF[Manifest jsonl]

启动顺序

sequenceDiagram
  participant C as Client
  participant S as MCP server
  participant I as Index manager
  C->>S: connect via stdio
  S->>I: open or create index
  I->>I: scan data folder and apply incremental changes
  I-->>S: ready with index
  S-->>C: tools ready

\/index下的存储布局

faiss.index：序列化faiss索引
manifest.jsonl：每个块一个JSON记录
files.json：每个文件的摘要和最后处理的状态
version：架构版本字符串
index.lock：重新索引时锁定文件

manifest.jsonl记录

{
  "id": 12345,
  "path": "/abs/or/relative/path/to/file.md",
  "ext": ".md",
  "mtime": 1739650000.123,
  "checksum": "sha256:ab...cd",
  "chunk_index": 7,
  "char_start": 4200,
  "char_end": 5200,
  "text": "chunk text...",
  "embedding_dim": 384,
  "deleted": false
}

files.json记录

{
  "path": "/abs/or/relative/path/to/file.md",
  "mtime": 1739650000.123,
  "checksum": "sha256:ab...cd",
  "chunk_ids": [1201, 1202, 1203],
  "ext": ".md"
}

增量索引算法

获取index.lock；如果存在，则工具调用失败，并显示明显错误
将文件.json和manifest.jsonl加载到内存映射中
允许扩展名的漫游数据文件夹
对于每个文件

- 如果是新文件、摄取、块化、嵌入、添加向量和清单记录 - 如果mtime不同或校验和不同，请删除旧块，添加新块

对于files.json中不在磁盘上的文件，将其块标记为已删除，并可选择稍后回收id
持久失败、manifest.jsonl追加、files.json
解锁并返回计数

搜索算法

将查询编码为嵌入
L2规范化查询和索引向量
通过FAISS搜索前k名
对于每个命中，获取清单记录，计算代码段，返回结果

MCP工具

工具名称：搜索

参数

- 查询：字符串，必填 - top_k：整数，默认值5，最小值1，最大值50 - score_threshold：浮点数，默认值0.2，0..1

退货

- 结果：数组 - 路径：字符串 - 分数：浮动 - 代码段：字符串 - chunk_index：整数 - char_start：整数 - char_end：整数 - mtime：浮动 - ext:字符串

错误

- 如果缺少索引，服务器将返回空列表并记录警告

工具名称：reindex

参数

- force：布尔值，默认值为false - path_glob:string，相对于数据文件夹的可选外壳模式

退货

- files_added：整数 - files_updated：整数 - files_removed：整数 - chunks_total：整数 - elapsed_ms：整数

错误

- 如果索引已在进行中，则返回忙碌错误

通过uvx使用CLI

一次性跑步

uvx micro-rag-mcp --data-folder /some/hr_docs --title "HR RAG" --inst "HR instance for confidential search"

覆盖默认值

uvx micro-rag-mcp --data-folder /some/docs --index-folder /some/docs/index --exts .txt,.md,.pdf,.docx --title "Docs RAG" --inst "Docs instance"

PyPI上传前的本地测试

在上传到PyPI之前，请在本地测试您的包，以确保它与 uvx:

1.开发安装

# Install in development mode for rapid iteration
uv pip install -e .
micro-rag-mcp --help

2.本地紫外线检测

# Test uvx with local package
uvx --from ./ micro-rag-mcp --help

# Create test data and test functionality
mkdir -p test_data
echo "This is a test document about Python programming." > test_data/doc1.txt
echo "Another document about machine learning and AI." > test_data/doc2.md

# Test with real data
uvx --from ./ micro-rag-mcp --data-folder test_data

3.在本地构建和安装

# Build the package
uv build

# Install the built wheel
uv pip install dist/micro_rag_mcp-0.1.0-py3-none-any.whl

# Test uvx with installed package
uvx micro-rag-mcp --help

4.清洁环境测试

# Test in isolated virtual environment
uv venv test_env
source test_env/bin/activate
uv pip install dist/micro_rag_mcp-0.1.0-py3-none-any.whl
micro-rag-mcp --help
deactivate

5.包装验证

# Check package metadata
uv pip show micro-rag-mcp

# Verify entry points
uv pip show -f micro-rag-mcp | grep -A5 "Entry-points"

# Test import
python -c "import micro_rag_mcp; print('Import successful')"

MCP客户端配置示例

请参阅上面的“多实例支持”部分，了解所需的推荐配置 --title 和 --inst 论据。

要声明的依赖项 pyproject.toml

主控程序
句子变换器
faiss cpu
数值Python
pypdf
python docx
皮丹提克
字符集归一化器

实现注意事项

使用Python mcp包中的stdio传输
始终将人工日志写入stderr，以避免污染工具响应
在添加到IndexFlatIP之前对嵌入进行归一化以近似余弦
批量嵌入以管理内存；建议批量64
对于pdf提取，如果页面失败，则回退到文本；跳过图像
对于docx，用双换行符连接段落
使用UTF-8替换文本文件中的错误
在校验和的规范化文本上使用SHA256

安全和隐私

仅对显式传递的本地文件夹进行操作
除了首次使用时的模型下载外，运行时没有网络调用
没有PII离开机器

测试计划

创建混合文件类型的示例文件夹
运行uvx micro-rag mcp--数据文件夹示例
使用客户端的搜索工具验证结果和分数
修改文件并重新运行重新索引工具；确保更新得到反映
删除文件并重新运行reindex；确保使用墓碑

路线图

背景压实以重建faiss和掉落墓碑
可选的重新分级器可提高质量
html和csv的附加阅读器
使用BM25混合搜索降价标题

存储库布局目标

批准

如果此设计符合预期，接下来的步骤是更新依赖关系、脚手架文件并实现这两个工具。请查看此工作区中的待办事项列表。

首次运行和模型初始化行为

在服务器启动时，句子转换器模型在后台下载。
模型准备就绪后，会自动触发后台初始重新索引（无需在第一次运行时手动调用重新索引）。
如果在模型设置之前或期间调用搜索，它将等待最多5秒，直到模型准备就绪。如果模型在5秒内未就绪，搜索将返回一个空结果集（无错误）。
一旦模型准备就绪，后台重新索引完成，搜索将按预期返回结果。
这确保了搜索永远不会失败或无限期阻塞，即使在服务器启动后立即调用。

目录标签

本地搜索Python搜索本地部署文档索引RAG技术离线搜索增量索引

接入字段

传输方式（transport，传输协议）

stdio

鉴权方式（authType，认证方式）

none

运行时（runtime，运行环境）

Python

工具数量（toolCount，工具数）

0

资源数量（resourceCount，资源数）

0

提示词数量（promptCount，提示词数）

0

权限和风险

stdionone部署方式未说明

接入前请确认传输方式、认证方式和部署位置，并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限；先核对安装命令和配置内容。

来源信息

MCP World

mcpworld.com

/detail/d19cf3e2987f79d07b2a0f3b14f45fd0

一个最小化的本地检索增强生成(RAG)索引和搜索MCP服务器，用于文档文件夹的快速离线搜索和增量索引。

继续浏览同类 MCP

更多搜索检索 MCP（7,303）返回 MCP 目录

上一个 MCP

MiAI MCP

Demo of building and intergraition MCP Server

下一个 MCP

Microshift MCP Server

MCP Server for MicroShift 是一个将MicroShift管理操作标准化为AI模型工具的服务，支持本地和远程执行、服务管理、日志检索、Pod管理和配置管理。

micro rag MCP