RAG Blob MCP

一个模型上下文协议（MCP）服务器，让 RAG 智能体能够搜索存储在 Azure Blob Storage 中的文档库，同时附带一个用于上传文档并与之对话的 Streamlit 应用。

• MCP 服务器 — 基于 Streamable HTTP 的 FastMCP，负责所有 Azure Blob Storage 访问，暴露 4 个工具和 3 个提示词模板，并在每次启动时从 Blob Storage 重建内存向量索引（OpenAI 嵌入）。

• Streamlit 应用 — 一个“文档库”标签页（上传 / 列出 / 删除文档）和一个“对话”标签页（提问，由调用服务器搜索工具的 LangGraph ReAct 智能体回答）。

快速开始

1. 前置条件

• Python 3.11+（在 3.13 上开发）

• 一个带有 Blob 容器的 Azure 存储账户（如果没有，请参阅下面的 Azure 设置）

• 一个 OpenAI API 密钥

2. 安装

在仓库根目录下执行：

python -m venv .venv
.venv\Scripts\activate          # Windows
pip install -r requirements.txt

3. 配置

将 .env.example（位于仓库根目录）复制为 .env 并填入你的值：

OPENAI_API_KEY=sk-...
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net
AZURE_STORAGE_CONTAINER_NAME=rag-documents

其他所有配置（OPENAI_MODEL、OPENAI_EMBEDDING_MODEL、MCP_SERVER_HOST/PORT/URL）都有可用的默认值——参见 配置。

4. 运行

两个进程，两个终端，都在仓库根目录下运行：

# Terminal 1 — MCP server
python server/mcp_server.py

# Terminal 2 — Streamlit app
streamlit run app/streamlit_app.py

打开 http://localhost:8501。在文档库标签页上传一个 PDF/DOCX/TXT/MD 文件，然后在对话标签页中提问。

Related MCP server: Legal MCP Server

Azure 设置

如果你还没有存储账户：

1. Azure 门户 → 创建资源 → 存储账户。标准性能、LRS 冗余对于个人使用来说足够了。

2. 在新账户中：数据存储 → 容器 → + 容器，命名（例如 rag-documents），访问级别设为“私有”。

3. 安全 + 网络 → 访问密钥 → 显示密钥，复制连接字符串。

4. 将其粘贴到 .env 中作为 AZURE_STORAGE_CONNECTION_STRING，并将 AZURE_STORAGE_CONTAINER_NAME 设置为你选择的容器名称。

项目结构

.
├── server/
│   ├── mcp_server.py      # FastMCP server: tools, prompts, index rebuild, __main__ entrypoint
│   ├── blob_store.py      # Azure Blob Storage wrapper
│   ├── indexing.py        # text extraction (pdf/docx/txt/md) + chunking
│   ├── vector_index.py    # in-memory vector store wrapper
│   └── test_*.py          # automated tests (pytest)
├── agent/
│   └── rag_agent.py       # LangGraph ReAct agent used by the Chat tab
├── app/
│   ├── mcp_client.py      # direct MCP tool-call helpers used by the Library tab
│   └── streamlit_app.py   # the UI
├── scripts/
│   └── smoke_test_server.py  # manual end-to-end smoke test against a running server
├── docs_build/            # scripts that generate PROJECT.docx / PROJECT.pdf
└── pytest.ini

配置

所有变量都位于仓库根目录的 .env 中：

使用方法

文档库标签页 — 上传 PDF/DOCX/TXT/MD 文件（200MB 限制，由 Streamlit 设置）。每次上传都会被分块、嵌入并添加到搜索索引中；文档列表显示 indexed / failed / pending 状态及分块数量。删除操作会同时从 Blob Storage 和索引中移除文档。

对话标签页 — 用纯英文提问。智能体自行决定何时调用搜索工具，检索相关分块，并引用源文档的文件名来回答。如果文档库为空或不相关，它会如实说明，而不是猜测。

测试

pytest server/ -v

29 个测试覆盖了文本提取/分块、向量索引、Azure Blob Storage 封装（模拟）以及全部 4 个 MCP 工具 + 提示词（通过 fastmcp.Client 进程内测试，使用假对象——不涉及真实的 Azure/OpenAI 调用）。Streamlit UI 和实时智能体/服务器接线没有自动化测试覆盖；参见 scripts/smoke_test_server.py，可对真实运行的服务器进行手动冒烟测试。

已知限制

• 内存索引，无持久化。 每次服务器重启都会重新下载、重新提取并重新嵌入容器中的每个文档。对于小型个人文档库没问题；但随着文档库增长，会消耗真实的 OpenAI API 调用和启动时间。

• 单用户，仅限本地。 没有认证，没有并发写入保护，未部署到任何环境。

• 两个进程（MCP 服务器、Streamlit 应用）必须同时运行，应用才能正常工作——更多信息参见完整项目文档。

完整信息——架构、设计决策、已知缺陷和后续步骤——参见 PROJECT.md（也可获取 PROJECT.docx / PROJECT.pdf 版本）。