使用说明
MCP矢量存储服务器
一种模型上下文协议（MCP）服务器，为文档搜索、PDF处理和信息检索提供高级矢量存储操作。此服务器封装了以下功能 vectorstore.py 成为标准化的MCP接口。
特性
- 矢量存储操作：创建、搜索和管理文档矢量存储
- PDF处理：使用LLMSherpa从PDF文档中提取内容并建立索引
- 语义搜索：使用HuggingFace嵌入进行高级文档搜索
- Web搜索集成：谷歌、维基百科和DuckDuckGo搜索功能
- 文件操作：读取和处理本地文件
- 数学计算：内置计算器功能
先决条件
系统要求
- python：3.8或更高
- 操作系统：Linux、macOS或Windows
- 记忆：最低4GB RAM（建议用于大型文档收藏的8GB+）
- 存储：至少2GB的可用空间用于模型和矢量存储
- 网络：用于下载模型和网络搜索的互联网连接
可选GPU支持
为了提高大型文档集合的性能：
- 流处理器：11.8或更高
- 图形处理器：配备4GB+VRAM的NVIDIA GPU
- cuDNN：CUDA安装的兼容版本
安装
步骤1：克隆或下载存储库
# If you have the files locally, navigate to the directory
cd /path/to/McpDocServer
# Or clone from a repository (if available)
# git clone <repository-url>
# cd McpDocServer
步骤2：创建虚拟环境
# Create a virtual environment
python3 -m venv venv
# Activate the virtual environment
# On Linux/macOS:
source venv/bin/activate
# On Windows:
# venv\Scripts\activate
步骤3：安装依赖项
# Upgrade pip
pip install --upgrade pip
# Install all required packages
pip install -r requirements.txt
步骤4：安装LLMSherpa（可选但推荐）
为了优化PDF处理，请在本地安装LLMSherpa：
# Install LLMSherpa
pip install llmsherpa
# Start the LLMSherpa server (in a separate terminal)
llmsherpa --port 5001
步骤5：下载嵌入模型
服务器将在首次使用时自动下载所需的嵌入模型，但您可以预先下载：
# Download the embedding model
python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('sentence-transformers/all-mpnet-base-v2')"
配置
环境变量
创建一个 .env 项目目录中的文件：
# LLMSherpa API URL (use local if available, otherwise cloud)
LLMSHERPA_API_URL=http://localhost:5001/api/parseDocument?renderFormat=all
# Vector store directory
VECTORSTORE_DIR=/path/to/your/documents
# User agent for web scraping
USER_AGENT=Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36
# Optional: CUDA device for GPU acceleration
CUDA_VISIBLE_DEVICES=0
目录结构
准备您的文档目录：
your_documents/
├── pdfs/
│ ├── document1.pdf
│ ├── document2.pdf
│ └── ...
├── text_files/
│ ├── notes.txt
│ └── ...
└── other_documents/
└── ...
用法
启动MCP服务器
# Make the server executable
chmod +x mcp_vectorstore_server.py
# Start the server on linux
python /home/em/McpDocServer/mcp_vectorstore_server.py
or windows with wsl
wsl -d Ubuntu-24.04 bash -c "/mnt/c/Users/emanu/Desktop/McpDocServer/start_mcp.sh"
与MCP客户端一起使用
0.克劳德桌面
添加到MCP配置中：
{
"mcpServers": {
"vectorstore": {
"command": "python",
"args": ["/home/em/McpDocServer/mcp_vectorstore_server.py"],
"env": {
"PYTHONPATH": "/home/em/McpDocServer/McpDocServer"
}
}
}
}
1.GitHub副本
- 点击GitHub Copilot聊天窗口中的配置工具：
- 单击顶部搜索栏中的“添加更多工具”。
- 单击顶部搜索栏中的添加MCP服务器。
- 单击顶部搜索栏中的命令（stdio）。
- 输入要运行的命令：
- python/home/em/McpDocServer/mcp_vectorstore_server.py
或在窗户上： wsl-d Ubuntu-24.04/mnt/c/用户/emanu/桌面/McpDocServer/start_mcp.sh - 输入mcp服务器id/名称，例如McpDocServer-19be5552
- 配置settings.json
{
"security.workspace.trust.untrustedFiles": "open",
"python.defaultInterpreterPath": "/mnt/c/Users/emanu/Desktop/LLM/venv/venv/bin/python",
"terminal.integrated.inheritEnv": false,
"git.openRepositoryInParentFolders": "never",
"terminal.integrated.scrollback": 100000,
"mcp": {
"servers": {
"McpDocServer-19be5552": {
"type": "stdio",
"command": "python",
"args": [
"/mnt/c/Users/emanu/Desktop/McpDocServer/mcp_vectorstore_server.py"
]
}
}
}
}
- 当您单击GitHub Copilot Chat窗口中的Configure tools并滚动到底部时，检查mcp服务器工具列表中是否有以下工具：
矢量库搜索
矢量库创建
vectorstore_info
矢量库_耳朵
read_file
谷歌搜索
维基百科搜索
duckduckgo_search
计算 - 在GitHub Copilot聊天窗口中选择代理模式，并使用vectorstore_search获取信息：
使用vectorstore_search获取单元测试信息
11） 确认工具调用的使用情况。
2.继续MCP客户端
name: McpDocServer
version: 1.0.1
schema: v1
mcpServers:
- name: McpDocServer
command: wsl -d Ubuntu-24.04
args:
- "/mnt/c/Users/emanu/Desktop/McpDocServer/start_mcp.sh"
env: {}
mcp_timeout: 180 # set timeout to 180 sec
timeout: 9999
connectionTimeout: 120000 # 120 seconds = 2 minutes
3.其他MCP客户端
配置您的MCP客户端以使用服务器：
# Example with a generic MCP client
mcp-client --server python --args /path/to/McpDocServer/mcp_vectorstore_server.py
可用工具
矢量存储操作
vectorstore_search
在矢量库中搜索相关文档。
参数：
query（字符串，必填）：搜索查询k（整数，可选）：结果数量（默认值：2）
例子：
{
"name": "vectorstore_search",
"arguments": {
"query": "machine learning algorithms",
"k": 5
}
}
vectorstore_create
从目录中的文档创建新的矢量存储。
参数：
directory_path（字符串，必填）：包含文档的目录路径
例子：
{
"name": "vectorstore_create",
"arguments": {
"directory_path": "/home/user/documents/research_papers"
}
}
vectorstore_info
获取有关当前矢量存储的信息。
例子：
{
"name": "vectorstore_info",
"arguments": {}
}
vectorstore_clear
从矢量存储中清除所有文档。
例子：
{
"name": "vectorstore_clear",
"arguments": {}
}
文件操作
read_file
读取系统上文件的内容。
参数：
filename（string，必填）：要读取的文件的路径
例子：
{
"name": "read_file",
"arguments": {
"filename": "/home/user/documents/notes.txt"
}
}
Web搜索操作
google_search
在谷歌上搜索信息。
参数：
query（字符串，必填）：搜索查询max_results（整数，可选）：最大结果数（默认值：3）
例子：
{
"name": "google_search",
"arguments": {
"query": "latest AI developments 2024",
"max_results": 5
}
}
wikipedia_search
在维基百科上搜索信息。
参数：
query（字符串，必填）：搜索查询
例子：
{
"name": "wikipedia_search",
"arguments": {
"query": "artificial intelligence"
}
}
duckduckgo_search
在DuckDuckGo中搜索信息。
参数：
query（字符串，必填）：搜索查询
例子：
{
"name": "duckduckgo_search",
"arguments": {
"query": "privacy-focused search engines"
}
}
公用事业运营
calculate
进行数学计算。
参数：
operation（字符串，必填）：要执行的数学运算
例子：
{
"name": "calculate",
"arguments": {
"operation": "2 + 2 * 3"
}
}
资源
服务器提供以下资源：
vectorstore://info
以JSON格式返回有关当前向量存储的信息。
示例响应：
{
"num_documents": 150,
"directory": "/home/user/documents",
"embeddings_model": "sentence-transformers/all-mpnet-base-v2"
}
故障排除
常见问题
1.导入错误
问题： ModuleNotFoundError 适用于各种包装
解决方案： 确保安装了所有依赖项：
pip install -r requirements.txt
2.CUDA/GPU问题
问题： CUDA相关错误 解决方案： 仅安装CPU版本：
pip uninstall faiss-gpu torch
pip install faiss-cpu
3.LLMSherpa连接问题
问题： 无法连接到LLMSherpa API 解决方案：
- 启动LLMSherpa服务器：
llmsherpa --port 5001 - 或者通过更新代码中的URL来使用云API
4.内存问题
问题： 大型文档出现内存不足错误 解决方案：
- 减小文本拆分器中的块大小
- 使用较小的嵌入模型
- 分批处理文件
5.许可问题
问题： 无法读取文件或目录 解决方案： 检查文件权限：
chmod 644 /path/to/documents/*
chmod 755 /path/to/documents/
性能优化
用于大型文档收藏
-
使用GPU加速：
# In vectorstore.py, ensure CUDA is enabled model_kwargs={'device': 'cuda'} -
优化块大小：
# Adjust in PDFVectorStoreTool.__init__ chunk_size=1000, # Smaller chunks for better performance chunk_overlap=100, -
批量处理：
# Process documents in smaller batches batch_size = 10
为了获得更好的搜索结果
-
调整相似性阈值：
# In vectorstore_search method similarity_threshold = 0.7 -
使用不同的嵌入模型：
# Try different models for better results model_name="sentence-transformers/all-MiniLM-L6-v2" # Faster model_name="sentence-transformers/all-mpnet-base-v2" # Better quality
发展
项目结构
McpDocServer/
├── mcp_vectorstore_server.py # Main MCP server
├── vectorstore.py # Original vectorstore implementation
├── requirements.txt # Python dependencies
├── README.md # This documentation
└── .env # Environment variables (create this)
贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 如果适用，添加测试
- 提交拉取请求
测试
# Run basic functionality tests
python -c "
from mcp_vectorstore_server import *
print('Server imports successfully')
"
# Test vector store operations
python -c "
from vectorstore import PDFVectorStoreTool
tool = PDFVectorStoreTool()
print(f'Vector store initialized with {tool.vectorstore_get_num_items()} documents')
"
许可证
本项目按原样提供，用于教育和研究目的。请确保您遵守所有包含的依赖项的许可证。
支持
对于问题和疑问：
- 检查上面的故障排除部分
- 查看错误日志
- 确保所有依赖项都已正确安装
- 验证您的系统是否符合要求
更新日志
版本1.0.0
- 初始版本
- MCP服务器实现
- 矢量存储操作
- Web搜索集成
- 文件 操作
- 数学计算
