内容
OpenDental MCP 服务器
本仓库包含一个用于查询 OpenDental 文档的 MCP（模型上下文协议）服务器，使用 Qdrant 向量数据库。
## 这是什么？
该工具帮助您通过自然语言问题搜索 OpenDental 文档。您不必搜索确切的关键词，而是可以提出诸如“如何创建预约？”的问题，并从文档中获取相关答案。
## 平台特定指南
对于非技术创建了详细的逐步指南：
- [Windows 安装和使用指南](WINDOWS-GUIDE.md)
- [macOS 安装](MACOS-GUIDE.md)
## 系统需求
- **Windows、macOS 或 Linux**
- Node.js 18 或更高版本（[在此下载](https://nodejs.org/)）
- Python 3.6 或更高版本（[在此下载](https://www.python.org/downloads/)）
- Qdrant 向量数据库（自动使用 Docker 或）
- 用于生成嵌入的 OpenAI API 密钥（[在此获取](https://platform.openai.com/account/api-keys)）
## 关于 API 密钥的重要注意事项
该项目需要 API 密钥才能运行。出于安全原因：
- 永远不要将真实的 API 密钥提交到仓库
- 使用提供的 `.env.example` 文件作为模板
- 使用您实际的密钥创建自己的 `.env` 文件
- `.gitignore` 文件配置为从 Git 中排除 `.env` 文件
如果您需要共享配置，请始终使用 `your_api_key` 之类的占位值代替真实密钥。
## 安装说明
### 步骤 1：克隆仓库
#### Windows
```
git clone https://github.com/yourusername/open-dental-mcp.git
cd open-dental-mcp
```
#### macOS/Linuxbash
git clone https://github.com/yourusername/open-dental-mcp.git
cd open-dental-mcp
```
### 步骤 2：安装 Qdrant
您需要在本地运行 Qdrant。有几种安装方法：
#### 使用 Docker（推荐）
```bash
docker pull qdrant/qdrant
docker run -p3:6333 -p 6334:6334 -v $(pwd)/qdrant_storage:/qdrant/storage qdrdrant
```
#### 在 Windows 上无需 Docker
您可以从 [Qdrant GitHub 发布](https://github.com/qdrant/qdrant/releases) 下载最新版本并在本地运行。
#### 在 macOS 上无需 Docker
您可以使用 Homebrew 安装 Qdrant：
```bash
brew install qdrant/qdrant/qdrant
qdrant
```
### 步骤 3：配置环境变量
您需要为 Qdrant 和 OpenAI（用于嵌入）设置环境变量。
#### Windows
1. 在 `mcp-openai-filesearch` 文件夹中基于 `.env.example` 创建一个名为 `.env` 的文件
2. 添加以下内容（用您的 OpenAI API 密钥替换）：
```
OPENAI_API_KEY=your_openai_api_key
QDRANT_HOST=localhost
QDRANT_PORT=6333
QDRANT_COLLECTION=open_dental_docs
```
#### macOS/Linux
1. 在 `mcp-openai-filesearch` 文件夹中基于 `.env.example` 创建一个名为 `.env` 的文件
2. 添加以下内容（用您的 OpenAI API 密钥替换）：
```
OPENAI_API_KEY=your_openai_api_key
QDRANT_HOST=localhost
QDRANT_PORT=6333
QDRANT_COLLECTION=open_dental_docs
```
### 步骤 4：安装依赖项
从根目录：
```bash
npm run install:deps
```
或手动：
#### Windows
```
cd mcp-openai-filesearch
npm install
```
#### macOS/Linux
```bash
cd mcp-openai-filesearch
npm install
```
### 步骤 5：构建服务器
从根目录：
```bash
npm run build
```
或手动：
#### Windows
```
cd mcp-openai-filesearch
npm run build
```
#### macOS/Linux
```bash
cd mcp-openai-filesearch
npm run build
```
### 步骤 6：设置 Qdrant 集合
在启动服务器之前，您需要设置 Qdrant 集合：
```bash
cd mcp-openai-filesearch
npm run setup:qdrant
```
## 客户端配置
要将您的 MCP 客户端（如 Cursor）连接到 OpenDental MCP 服务器，您需要创建一个配置文件。这将告诉您的客户端如何启动和与服务器通信。
### 设置 mcp.json
1. 在项目的 `.cursor` 目录中（或您的 MCP 客户端查找配置的位置）创建一个名为 `mcp.json` 的文件
2. 添加以下配置，根据您的本地安装调整路径：
#### Windows 配置
```json
{
"mcpServers": {
"OpenDental-MCP": {
"command": "node",
"args": [
"C:\\path\\to\\open-dental-mcp\\mcp-openai-filesearch\\dist\\server-qdrant.js"
],
"stdio",
"description": "基于 Qdrant 的 OpenDental 文档 MCP 服务器。"
}
}
}
```
#### macOS/Linux 配置
{
"mcpServers": {
"OpenDental-MCP": {
"command": "/usr/local/bin/node",
"args": [
"/path/to/open-dental/mcp-openai-filesearch/dist/server-qdrant.js"
],
"transport": "stdio",
"description": "基于 Qdrant 的 OpenDental 文档 MCP }
}
}
```
### 客户端：
1. **命令路径**：
- 对于 Windows，如果 Node.js 在您的 PATH 中，您可以简单地使用 `"command": "node"`
- 对于 macOS/Linux，请使用 Node.js 二进制文件的完整路径（使用 `which node` 查找）
2. **服务器路径**：
- 确保指向 `dist` 目录中的 `server-qdrant.js`
- 使用适合您操作系统的正确路径分隔符（Windows 使用 `\\`，macOS/Linux 使用 `/`）
- 使用绝对路径以避免混淆
3. **验证配置**：
- 创建 `mcp.json` 文件后，确保您的 MCP 客户端可以检测并连接到服务器
- 如果您正在使用 Cursor，请前往设置 > MCP 并检查“OpenDental-MCP”是否出现在可用服务器列表中 运行 MCP 服务器
从根目录：
```bash run start:qdrant # 基于 Qdrant 的服务器
```
或手动：
### Windows
```
cd mcp-openai-filesearch
npm run start:qdrant
```
### macOS/Linux
```bash
cd mcp-openai-filesearch
npm run start:qdrant
```
服务器将在 `http://localhost:3000` 上运行。
## 测试服务器
从根目录：
```bash
npm run query:qdrant -- --query "如何在 Open Dental 中创建预约？"
```
或手动：
### Windows
```
cd mcp-openai-filesearch
npm run test:qdrant
```
### macOS/Linux
```bash
cd mcp-openai-filesearch
npm run test:qdrant
```
## 上传文档
如果您需要将上传到 Qdrant 向量数据库：
1.文档文件放在一个文件夹中
2. 编辑上传脚本以指向您的文档文件夹
3. 运行设置脚本以创建嵌入并将它们上传到 Qdrant
## 故障排除
### Windows 常见问题
1. **路径错误**：确保在配置中使用正确的路径格式（例如 `C:\path\to\file` 或 `C:/path/to/file`）
2. **权限被拒绝**：如果遇到权限问题，请以管理员身份运行命令提示符或 PowerShell
3. **NPM 错误**：确保您的 Node.js 安装是最新的
4. **端口已被占用**：如果端口 3000 或 6333 已被占用，请检查哪个进程正在使用它并终止该进程
### macOS/Linux 常见问题
1. **权限被拒绝**：您可能需要为某些命令使用 `sudo` 或使用 `chmod +x filename.py` 修复文件权限
2. **Python 版本**：如果您安装了多个版本，请显式使用 `python3` 而不是 `python`
3. **端口已被占用**：使用 `lsof -i :3000` 检查端口 3000 是否已被占用，并在需要时终止该进程
4. **Docker 问题**：如果使用 Docker 运行 Qdrant，请确保 Docker 正在运行且 Qdrant 容器处于活动状态
### API 密钥问题
- 确保您的 OpenAI API 密钥有效（仍需要用于生成嵌入）
- 确保 `.env` 文件中没有多余的空格或字符
## 获取帮助
如果您遇到此处未涵盖的问题，请：
1. 查看 [Qdrant 文档](https://qdrant.tech/documentation/)
2. 查看 OpenAI 的 [嵌入](https://platform.openai.com/docs/guides/embeddings) 文档
3. 在此仓库中创建一个
MCP 市场