使用说明

RAG MCP 服务器

一个实现模型上下文协议（MCP）的检索增强生成（RAG）服务器。该服务器允许您使用向量数据库技术来嵌入、搜索和管理文档，非常适合与人工智能工具和大型语言模型（LLMs）结合使用。

✨ 特点

📚 书籍 文档嵌入支持多种文档格式（PDF、DOCX、TXT、MD）
🔍 语义搜索使用自然语言查询搜索文档
💾 表示“软盘驱动器”或“保存数据”。 向量数据库高效存储和检索文档嵌入表示
🤖 机器人 MCP协议实现了模型上下文协议，以标准化AI/ML服务交互
🔧 修理工具或螺丝刀的符号，常用于表示需要修理或调整的物品或情境。 易于使用的API简洁的文档管理与搜索界面
🔄 旋转或循环的符号，常用来表示重复、循环、刷新等含义。 双模式支持HTTP和stdio两种通信模式

🚀 快速入门

先决条件

Python 3.12 或更高版本
使用uv（推荐）或pip进行包管理
Docker（可选，用于容器化部署）

安装方法

1. 使用 `uv` （推荐）

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/Hitesh-Saha/RAG-MCP-Server.git
cd RAG-MCP-Server

# Install dependencies
uv sync

2. 使用 `pip`

git clone https://github.com/Hitesh-Saha/RAG-MCP-Server.git
cd RAG-MCP-Server
pip install -e .

🖥️ 运行服务器

1. 本地运行（源模式）

HTTP 模式

# Run using the src package layout
PYTHONPATH=src python -m rag_mcp_server.server --mode http --port 8000

stdio 模式

# For stdio mode (useful for IDE integrations)
PYTHONPATH=src python -m rag_mcp_server.server --mode stdio

2. 使用 `uv run`

# HTTP mode
uv run rag-mcp-server --mode http --port 8000

# stdio mode
uv run rag-mcp-server --mode stdio

3. Docker 设置

# Build the image
docker build -t rag-mcp-server .

# Run in HTTP mode
docker run -p 8000:8000 rag-mcp-server

# Run in stdio mode
docker run -i rag-mcp-server --mode stdio

🔌 集成开发环境（IDE）集成

VS Code 设置

安装Claude AI助手或GitHub Copilot扩展
配置MCP服务器：
- 以HTTP或stdio模式启动RAG MCP服务器
- 对于HTTP模式，请使用端点： http://localhost:8000/mcp
- 对于stdio模式，请将扩展指向服务器进程

VS Code 设置：

{
  "claude.mcp.endpoint": "http://localhost:8000/mcp",  // For HTTP mode
  // OR
  "github.copilot.advanced": {
    "mcpServer": "http://localhost:8000/mcp"  // For HTTP mode
  }
}

Claude 桌面版设置

以HTTP模式启动RAG MCP服务器：

uv run rag-mcp-server --mode http --port 8000

配置Claude桌面版：
- 打开设置
- 导航至“高级”部分
- 将MCP服务器URL设置为： http://localhost:8000/mcp
- 点击“测试连接”以验证

🧪 开发

本地开发环境设置

# Clone the repository
git clone https://github.com/Hitesh-Saha/RAG-MCP-Server.git
cd RAG-MCP-Server

# Install in editable mode with dev dependencies
uv sync

# Run tests
python -m pytest

# Run with auto-reload for development
uvicorn rag_mcp_server.server:app --reload --port 8000

环境变量

创建一个 .env 项目根目录下的文件：

EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
RAG_DB_PATH=./data/vector_db
LOG_LEVEL=INFO

📦 构建与分发

构建包

# Using uv
uv pip build .

# Using pip
pip install build
python -m build

从构建包安装

uv pip install dist/rag_mcp_server-0.1.0.whl

API 文档

当以HTTP模式运行时，请访问：

API 文档： http://localhost:8000/docs
OpenAPI 规范： http://localhost:8000/openapi.json

🤝 贡献（或“参与贡献”）

为仓库创建分支（或“克隆仓库”）
创建你的特性分支（git checkout -b feature/amazing-feature)
提交您的更改（git commit -m 'Add some amazing feature')
推送至分支（git push origin feature/amazing-feature）
提交一个拉取请求

📄 许可证

这个项目遵循MIT许可证授权——详见许可证文件中包含详细信息许可证 = { 文本 = "MIT" } 关键词 = ["mcp", "rag", "向量", "嵌入"] 分类器 = [ “开发状态 :: 4 - 测试版”， “许可证 :: 开放源代码促进会（OSI）批准 :: MIT 许可证”， “编程语言 :: Python :: 3”， ]


2) Ensure console script entry point is configured

We added a console script in `pyproject.toml`:

```toml
[project.scripts]
rag-mcp-server = "rag_mcp_server.cli:run"

这映射了 rag-mcp-server 命令以 rag_mcp_server.cli.run()。

构建分发版

安装构建工具（如果您还没有安装）：

pip install --upgrade build twine

构建源代码和轮子（wheel）文件：

python -m build
# artifacts appear in dist/

上传测试至测试版 PyPI（推荐）

python -m twine upload --repository testpypi dist/*

# Verify install from Test PyPI
pip install --index-url https://test.pypi.org/simple/ --no-deps rag-mcp-server

发布到 PyPI（Python 软件包索引）

准备好后，上传到真实的PyPI：

python -m twine upload dist/*

验证

pip install rag-mcp-server
rag-mcp-server --mode http --port 8000

小贴士与最佳实践

使用专门的PyPI账户，并启用双因素认证（2FA）。
增加 version 在Git中，为每次发布以及为标签发布（例如。 git tag v0.1.0）。
通过GitHub Actions在标签推送时自动发布，以简化发布流程（如果您需要，我可以添加一个模板工作流）。
将秘密信息保留在代码库之外；在CI（持续集成）密钥中存储PyPI API令牌，并在CI中使用Twine进行发布。

🧭 发布后安装并运行

一旦发布到PyPI（Python Package Index），用户就可以轻松安装并运行该服务器。

通过 pip 安装：

pip install rag-mcp-server

与……一起奔跑 uv （推荐）— uv 将定位包的入口点并运行它。示例（安装后） uv):

# Run the server (default HTTP on 127.0.0.1:8000)
uv run rag-mcp-server

# Or run via the console script directly (if project.scripts was configured):
rag-mcp-server --mode http --port 8000

如果你更倾向于直接运行该模块：

python -m rag_mcp_server.server --mode http

🧪 冒烟测试/验证

安装后，请尝试进行快速健康检查（HTTP模式）：

curl -v http://127.0.0.1:8000/health || true

对于stdio模式，请使用符合规范的MCP客户端，该客户端能够写入带有Content-Length头的帧化JSON请求，并读取帧化响应。

🐳 Docker 笔记（打包版）

所包含的 Dockerfile 已经使用 uv 运行服务器。在打包时，您可以选择：

从源代码（原样）构建Docker镜像，或者
在更小的运行时镜像中使用 PyPI 包（多阶段构建）：使用以下命令安装已发布的 wheel 包 pip install rag-mcp-server 并运行控制台脚本。

发布到 PyPI 后的 Docker 命令示例：

FROM python:3.12-slim
RUN pip install rag-mcp-server uv
CMD ["uv", "run", "rag-mcp-server"]

🛠️ API及工具使用

📥 嵌入文档

将文档嵌入到向量数据库中：

embed_document(file_path: str, metadata: Optional[dict] = None) -> EmbedDocumentResponse

响应模型： EmbedDocumentResponse 示例回复：

✅ Document 'example.pdf' embedded! 3 chunks created from 7539 characters. 🚀

🔍 搜索文档

使用自然语言搜索嵌入式文档：

search_documents(query: str, top_k: int = 5, min_similarity: float = 0.4) -> SearchDocumentsResponse

响应模型： SearchDocumentsResponse 示例回复：

🔍 Found 2 similar documents! 📄✨
1. 📄 somatosensory.pdf (chunk 0) | 📊 Similarity: 0.53
   📝 This is a sample document to showcase page-based formatting...

📚 列出文件

查看数据库中的所有文档：

list_documents() -> ListDocumentsResponse

响应模型： ListDocumentsResponse 示例回复：

📚 2 documents in the database! 🗃️
1. 📄 somatosensory.pdf (3 chunks)
2. 📄 TopCSSFrameworks.docx (2 chunks)

📊 获取数据库统计信息

查看数据库的统计信息：

get_database_stats() -> DatabaseStatsResponse

响应模型： DatabaseStatsResponse 示例回复：

📊 Database loaded! 2 documents and 5 chunks stored. 🗂️

🗑️ 删除文档

从数据库中移除一个文档：

delete_document(filename: str) -> DeleteDocumentResponse

响应模型： DeleteDocumentResponse 示例回复：

🗑️ Document 'example.pdf' deleted! 3 chunks removed. 👋

❓ 提问

使用RAG系统提问并获得答案：

ask_question(request: QuestionRequest) -> QuestionAnswer

请求模型： QuestionRequest 响应模型： QuestionAnswer 示例回复：

🤖 Answer: The somatosensory system consists of sensors in the skin, muscles, tendons, and joints...
Sources: somatosensory.pdf
Confidence: 0.92

📄 获取文档详细信息

通过文档块的ID获取其详细信息：

get_document(document_id: str) -> GetDocumentResponse

响应模型： GetDocumentResponse 示例回复：

{
	"document": {
		"id": 3,
		"filename": "somatosensory.pdf",
		"content": "This is a sample document...",
		"chunk_id": 0,
		"metadata": {},
		"created_at": "2025-08-20 09:38:11"
	}
}

⚙️ 技术细节

嵌入模型：all-MiniLM-L6-v2
数据库：基于SQLite的向量数据库
协议：通过FastMCP的模型上下文协议（MCP）

📄 许可证

此项目根据LICENSE文件中包含的条款进行授权。

🤝 贡献

欢迎贡献！请随时提交拉取请求。

使用说明

RAG MCP 服务器

✨ 特点

🚀 快速入门

先决条件

安装方法

1. 使用 uv （推荐）

2. 使用 pip

🖥️ 运行服务器

1. 本地运行（源模式）

HTTP 模式

stdio 模式

2. 使用 uv run

3. Docker 设置

🔌 集成开发环境（IDE）集成

VS Code 设置

Claude 桌面版设置

🧪 开发

本地开发环境设置

环境变量

📦 构建与分发

构建包

从构建包安装

API 文档

🤝 贡献（或“参与贡献”）

📄 许可证

🧭 发布后安装并运行

🧪 冒烟测试/验证

🐳 Docker 笔记（打包版）

🛠️ API及工具使用

📥 嵌入文档

🔍 搜索文档

📚 列出文件

📊 获取数据库统计信息

🗑️ 删除文档

❓ 提问

📄 获取文档详细信息

⚙️ 技术细节

📄 许可证

🤝 贡献

相关 MCP

AI持久记忆服务器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

本地LLM模型控制协议

文档搜索服务

文档管理服务

1. 使用 `uv` （推荐）

2. 使用 `pip`

2. 使用 `uv run`