micro rag MCP

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是一个单一的参数；空格和换行符作为字符串的一部分保留。

最小架构

计划源文件

• src/micro_rag_mcp/server.py
• src/micro_rag_mcp/index.py
• src/micro_rag_mcp/embedder.py
• src/micro_rag_mcp/ingest.py
• src/micro_rag_mcp/types.py
• src/micro_rag_mcp/utils.py
• src/micro_rag_mcp/__主要的__南美国家巴拉圭的缩写（Paraguay）
• src/micro_rag_mcp/__初始化__南美国家巴拉圭的缩写（Paraguay）

数据流

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混合搜索降价标题

存储库布局目标

• README.md
• pyproject.toml
• src/micro_rag_mcp/__主要的__南美国家巴拉圭的缩写（Paraguay）
• src/micro_rag_mcp/server.py
• src/micro_rag_mcp/index.py
• src/micro_rag_mcp/ingest.py
• src/micro_rag_mcp/embedder.py
• src/micro_rag_mcp/types.py
• src/micro_rag_mcp/utils.py

批准

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

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

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