MCP-Ragdocs

一个支持语义搜索和文档检索的模型上下文协议（MCP）服务器，使用向量数据库（Qdrant）。该服务器允许您从URL或本地文件添加文档，然后通过自然语言查询进行搜索。

快速安装指南

1. 全局安装包：

   bash 复制代码

   npm install -g @qpd-v/mcp-server-ragdocs

2. 启动Qdrant（使用Docker）：

   bash 复制代码

   docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

3. 确保Ollama正在运行默认的嵌入模型：

   bash 复制代码

   ollama pull nomic-embed-text

4. 添加到配置文件：

   • Cline：%AppData%\Roaming\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
   • Roo-Code：%AppData%\Roaming\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json
   • Claude Desktop：%AppData%\Claude\claude_desktop_config.json
   json 复制代码

   {
     "mcpServers": {
       "ragdocs": {
         "command": "node",
         "args": ["C:/Users/YOUR_USERNAME/AppData/Roaming/npm/node_modules/@qpd-v/mcp-server-ragdocs/build/index.js"],
         "env": {
           "QDRANT_URL": "http://127.0.0.1:6333",
           "EMBEDDING_PROVIDER": "ollama",
           "OLLAMA_URL": "http://localhost:11434"
         }
       }
     }
   }

5. 验证安装：

   bash 复制代码

   # 检查Qdrant是否运行
   curl http://localhost:6333/collections
   
   # 检查Ollama是否有模型
   ollama list | grep nomic-embed-text

版本

当前版本：0.1.6

功能

• 从URL或本地文件添加文档
• 将文档存储在向量数据库中以进行语义搜索
• 使用自然语言搜索文档
• 列出所有文档来源

安装

使用npm全局安装：

npm install -g @qpd-v/mcp-server-ragdocs

这将服务器安装到全局npm目录中，后续配置步骤需要此路径。

要求

• Node.js 16或更高版本
• Qdrant（本地或云端）
• 以下任一项用于嵌入：
  • 本地运行的Ollama（默认，免费）
  • OpenAI API密钥（可选，付费）

Qdrant设置选项

选项1：本地Qdrant

1. 使用Docker（推荐）：

docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

2. 或从Qdrant官网下载

选项2：Qdrant云服务

1. 在Qdrant Cloud创建账户
2. 创建新集群
3. 从仪表板获取集群URL和API密钥
4. 在配置中使用这些信息（见下方配置部分）

配置

服务器可与Cline/Roo和Claude Desktop一起使用。两者配置略有不同：

Cline配置

添加到Cline设置文件（%AppData%\Roaming\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json）
和/或
添加到Roo-Code设置文件（%AppData%\Roaming\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json）：

1. 使用npm全局安装（推荐）：

{
		"mcpServers": {
				"ragdocs": {
						"command": "node",
      "args": ["C:/Users/YOUR_USERNAME/AppData/Roaming/npm/node_modules/@qpd-v/mcp-server-ragdocs/build/index.js"],
      "env": {
        "QDRANT_URL": "http://127.0.0.1:6333",
        "EMBEDDING_PROVIDER": "ollama",
        "OLLAMA_URL": "http://localhost:11434"
      }
    }
  }
}

使用OpenAI而非Ollama：

{
		"mcpServers": {
				"ragdocs": {
						"command": "node",
      "args": ["C:/Users/YOUR_USERNAME/AppData/Roaming/npm/node_modules/@qpd-v/mcp-server-ragdocs/build/index.js"],
      "env": {
        "QDRANT_URL": "http://127.0.0.1:6333",
        "EMBEDDING_PROVIDER": "openai",
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

2. 使用本地开发设置：

{
		"mcpServers": {
				"ragdocs": {
						"command": "node",
						"args": ["PATH_TO_PROJECT/mcp-ragdocs/build/index.js"],
						"env": {
								"QDRANT_URL": "http://127.0.0.1:6333",
								"EMBEDDING_PROVIDER": "ollama",
								"OLLAMA_URL": "http://localhost:11434"
						}
				}
		}
}

Claude Desktop配置

添加到Claude Desktop配置文件：

• Windows：%AppData%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

1. Windows设置与Ollama（使用完整路径）：

{
  "mcpServers": {
    "ragdocs": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\npm\\node_modules\\@qpd-v/mcp-server-ragdocs\\build\\index.js"
      ],
      "env": {
								"QDRANT_URL": "http://127.0.0.1:6333",
								"EMBEDDING_PROVIDER": "ollama",
								"OLLAMA_URL": "http://localhost:11434"
						}
				}
		}
}

Windows设置与OpenAI：

{
		"mcpServers": {
				"ragdocs": {
						"command": "C:\\Program Files\\nodejs\\node.exe",
						"args": [
								"C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\npm\\node_modules\\@qpd-v/mcp-server-ragdocs\\build\\index.js"
						],
						"env": {
								"QDRANT_URL": "http://127.0.0.1:6333",
								"EMBEDDING_PROVIDER": "openai",
								"OPENAI_API_KEY": "your-openai-api-key"
						}
				}
		}
}

2. macOS设置与Ollama：

{
		"mcpServers": {
				"ragdocs": {
						"command": "/usr/local/bin/node",
						"args": [
								"/usr/local/lib/node_modules/@qpd-v/mcp-server-ragdocs/build/index.js"
						],
						"env": {
								"QDRANT_URL": "http://127.0.0.1:6333",
								"EMBEDDING_PROVIDER": "ollama",
								"OLLAMA_URL": "http://localhost:11434"
						}
				}
		}
}

Qdrant云服务配置

对于Cline或Claude Desktop，使用Qdrant云服务时修改env部分：

使用Ollama：

{
		"env": {
				"QDRANT_URL": "https://your-cluster-url.qdrant.tech",
				"QDRANT_API_KEY": "your-qdrant-api-key",
				"EMBEDDING_PROVIDER": "ollama",
				"OLLAMA_URL": "http://localhost:11434"
		}
}

使用OpenAI：

{
		"env": {
				"QDRANT_URL": "https://your-cluster-url.qdrant.tech",
				"QDRANT_API_KEY": "your-qdrant-api-key",
				"EMBEDDING_PROVIDER": "openai",
				"OPENAI_API_KEY": "your-openai-api-key"
		}
}

环境变量

Qdrant配置

• QDRANT_URL（必需）：Qdrant实例的URL
  • 本地：http://localhost:6333
  • 云端：https://your-cluster-url.qdrant.tech
• QDRANT_API_KEY（云端必需）：Qdrant Cloud API密钥

嵌入配置

• EMBEDDING_PROVIDER（可选）：选择'ollama'（默认）或'openai'
• EMBEDDING_MODEL（可选）：
  • Ollama：默认为'nomic-embed-text'
  • OpenAI：默认为'text-embedding-3-small'
• OLLAMA_URL（可选）：Ollama实例的URL（默认为http://localhost:11434）
• OPENAI_API_KEY（使用OpenAI时必需）：OpenAI API密钥

可用工具

1. add_documentation

   • 从URL添加文档到RAG数据库
   • 参数：
     • url：要获取的文档URL

2. search_documentation

   • 搜索存储的文档
   • 参数：
     • query：搜索查询
     • limit（可选）：返回结果的最大数量（默认：5）

3. list_sources

   • 列出当前存储的所有文档来源
   • 无需参数

示例用法

在Claude Desktop或任何其他MCP兼容客户端中：

1. 添加文档：

添加此文档：https://docs.example.com/api

2. 搜索文档：

在文档中搜索关于认证的信息

3. 列出来源：

有哪些可用的文档来源？

开发

1. 克隆仓库：

git clone https://github.com/qpd-v/mcp-server-ragdocs.git
cd mcp-server-ragdocs

2. 安装依赖：

npm install

3. 构建项目：

npm run build

4. 本地运行：

npm start

许可证

MIT

故障排除

常见问题

1. Qdrant连接错误

   复制代码

   错误：无法连接到http://localhost:6333的Qdrant

   • 检查Docker是否运行
   • 验证Qdrant容器是否运行：docker ps | grep qdrant
   • 尝试重启容器

2. Ollama模型缺失

   复制代码

   错误：未找到模型nomic-embed-text

   • 运行：ollama pull nomic-embed-text
   • 验证模型是否安装：ollama list

3. 配置路径问题

   • Windows：将YOUR_USERNAME替换为实际的Windows用户名
   • 检查文件权限
   • 验证路径是否存在

4. npm全局安装问题

   • 尝试使用管理员权限安装
   • 检查npm是否在PATH中：npm -v
   • 验证全局安装：npm list -g @qpd-v/mcp-server-ragdocs

其他问题请检查：

• Docker日志：docker logs $(docker ps -q --filter ancestor=qdrant/qdrant)
• Ollama状态：ollama list
• Node.js版本：node -v（应为16或更高）

贡献

欢迎贡献！请随时提交Pull Request。