# 医学知识检索 MCP 服务器

[![Node.js](https://img.shields.io/badge/Node.js-18.x%2B-green)](https://nodejs.org/)
[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-orange)](https://modelcontextprotocol.io)

一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 的专业医学信息查询工具，集成多个权威医学数据源，支持 Claude Desktop、Cursor、Cherry Studio 等 AI 应用。

## ✨ 核心功能

| 功能 | 数据源 | 说明 |
|------|--------|------|
| 📖 **MSD手册查询** | MSD诊疗手册 | 专业医学知识，结构化内容提取 |
| 🧬 **MeSH主题词** | NLM MeSH浏览器 | 医学主题词层级树结构，精准分类 |
| 🔬 **MedSci编码** | 梅斯医学 | ICD-10/ICD-9医学编码查询 |
| 📚 **术语查询** | 术语在线 | 中英文医学术语翻译 |
| 💊 **药品查询** | 国家药监局 | 药品信息和说明书 |

## 🚀 快速开始

### 一键安装（推荐）

**Windows:**
```powershell
.\setup.ps1
```

**macOS/Linux:**
```bash
chmod +x setup.sh
./setup.sh
```

### 手动安装

```bash
# 1. 安装 Node.js 依赖
npm install

# 2. 安装 Python 依赖
pip install -r requirements.txt

# 3. 安装 Playwright 浏览器
node install-chromium.cjs

# 4. 检查环境
python check_python_env.py

# 5. 测试运行
node test_simple_msd.js
```

> 📖 **完整安装指南**：查看 [SETUP_GUIDE.md](./SETUP_GUIDE.md) 获取详细的环境配置说明。

## 📋 环境要求

### 必需
- **Node.js**: 18.x 或 20.x LTS
- **Python**: 3.10 或更高
- **npm**: 9.x 或更高
- **Playwright**: 1.40+ (自动安装)

### 操作系统
- ✅ Windows 10/11
- ✅ macOS 10.15+
- ✅ Linux (Ubuntu 18.04+)

## 🔧 MCP 客户端配置

### Claude Desktop

**配置文件位置：**
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

**配置示例：**
```json
{
  "mcpServers": {
    "medical-knowledge": {
      "command": "node",
      "args": ["D:\\chenmo\\Desktop\\mcp\\termonline-mcp\\index.js"]
    }
  }
}
```

> ⚠️ 注意：Windows 路径使用双反斜杠 `\\` 或单正斜杠 `/`

### Cursor IDE

在 Cursor 设置中添加 MCP 服务器：

```json
{
  "medical-knowledge": {
    "command": "node",
    "args": ["D:\\chenmo\\Desktop\\mcp\\termonline-mcp\\index.js"]
  }
}
```

### Cherry Studio

查看 `cherry-studio-config-example.json` 获取配置示例。

## 📦 可用工具

| 工具名称 | 功能说明 | 数据源 |
|---------|---------|-------|
| `search_msd` | MSD医学手册查询 | MSD诊疗手册 |
| `search_mesh` | MeSH主题词查询 | NLM MeSH浏览器 |
| `search_medical_code_icd10` | ICD-10疾病编码 | 梅斯医学 |
| `search_medical_code_icd9` | ICD-9手术编码 | 梅斯医学 |
| `search_terminology` | 中英文医学术语 | 术语在线 |
| `batch_search_terminology` | 批量术语查询 | 术语在线 |
| `search_medicine` | 药品信息查询 | 国家药监局 |

### 使用示例

**1. MSD手册查询**
```
请查询"糖尿病"的MSD手册内容
```

**2. MeSH主题词查询**
```
帮我查询"diabetes mellitus"的MeSH分类
```

**3. 医学编码查询**
```
查询"糖尿病"的ICD-10编码
查找"阑尾切除术"的ICD-9编码
```

> 📖 **详细文档**：
> - MSD手册使用：[MSD_README.md](./MSD_README.md)
> - MeSH主题词：[MESH_SCRAPER_README.md](./MESH_SCRAPER_README.md)
> - 快速上手：[MSD_QUICKSTART.md](./MSD_QUICKSTART.md)

## 📜 项目结构

```
termonline-mcp/
├── index.js                    # MCP 服务器主文件
├── msd_scraper.py              # MSD手册爬虫
├── msd_scraper.js              # MSD爬虫 (Node.js版)
├── mesh_scraper.py             # MeSH主题词爬虫
├── medsci_scraper.py           # 医学编码爬虫
├── check_python_env.py         # Python环境检查工具
├── install-chromium.cjs        # Playwright浏览器安装脚本
├── setup.ps1                   # Windows一键安装
├── setup.sh                    # macOS/Linux一键安装
├── package.json                # Node.js依赖配置
├── requirements.txt            # Python依赖配置
├── README.md                   # 项目说明
├── SETUP_GUIDE.md              # 环境配置指南
├── MSD_README.md               # MSD功能说明
├── MESH_SCRAPER_README.md      # MeSH功能说明
└── MSD_QUICKSTART.md           # 快速上手指南
```

## 🛠️ 技术栈

**核心框架：**
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) - MCP 协议实现
- [Playwright](https://playwright.dev/) - 浏览器自动化 (Python)
- [Axios](https://axios-http.com/) + [Cheerio](https://cheerio.js.org/) - HTTP请求和HTML解析

**支持的客户端：**
- Claude Desktop
- Cursor IDE
- Cherry Studio
- 其他支持MCP协议的AI应用

## ⚠️ 注意事项

1. ✅ **网络连接**：需要稳定的互联网连接
2. ✅ **使用频率**：请合理使用，避免频繁请求
3. ✅ **数据来源**：所有数据来自公开的权威医学数据库
4. ✅ **仅供学习交流**：临床决策请咨询专业医生

## 📚 相关资源

**官方文档：**
- [Model Context Protocol](https://modelcontextprotocol.io) - MCP协议规范
- [Claude Desktop MCP](https://docs.anthropic.com/claude/docs/mcp) - Claude官方文档

**数据源：**
- [MSD诊疗手册](https://www.msdmanuals.cn/) - 专业医学知识
- [NLM MeSH](https://meshb.nlm.nih.gov/) - 医学主题词
- [梅斯医学](https://www.medsci.cn/) - 医学编码
- [术语在线](https://www.termonline.cn/) - 医学术语

## 📝 许可证

MIT License - 详见 [LICENSE](./LICENSE)

## 👥 贡献

欢迎提交 Issue 和 Pull Request！

**贡献指南：**
1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交修改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

---

**项目维护者**: MCP Medical Knowledge Team  
**最后更新**: 2025-10  
**版本**: 2.0
- [国家医保信息编码标准数据库](https://code.nhsa.gov.cn/) - ICD-10/ICD-9 编码

### 工具和框架
- [MCP 官方文档](https://modelcontextprotocol.io)
- [Cherry Studio](https://github.com/CherryHQ/cherry-studio)
- [魔塔社区](https://www.modelscope.cn/)
- [Selenium Python](https://selenium-python.readthedocs.io/)

## 常见问题

### Q: 为什么查询不到结果？

A: 可能的原因：
- 网络连接问题
- 关键词拼写错误
- 网站结构变化导致解析失败
- （医保编码）Python 环境未正确配置

### Q: 如何更新服务？

A: 重新拉取代码并安装依赖：
```bash
git pull
npm install
```

### Q: 支持哪些 AI 应用？

A: 理论上支持所有实现了 MCP 协议的应用，包括但不限于：
- Cherry Studio
- Claude Desktop
- 其他支持 MCP 的 AI 应用

### Q: 医保编码查询报错怎么办？

A: 请按以下步骤排查：
1. 检查 Python 是否安装：`python --version`
2. 检查 Selenium 是否安装：`pip show selenium`
3. 运行环境检查：`python check_python_env.py`
4. 查看详细配置指南：[PYTHON_SETUP.md](./PYTHON_SETUP.md)
5. 检查截图文件（`medical-code-*.png`）查看页面实际状态

### Q: 遇到 429 请求限制错误怎么办？

A: 429 错误表示查询过于频繁，服务器对请求频率进行了限制。解决方法：

1. **等待后重试**：等待 60 秒后再次查询
2. **使用功能开关**：临时禁用医疗编码查询（详见 [FEATURE_TOGGLE.md](./FEATURE_TOGGLE.md)）
3. **直接使用 AI**：关闭 MCP 工具，让 AI 直接基于知识回答
4. **智能降级**：系统会返回 `fallback_suggestion: "AI_DIRECT_ANSWER"`，Cherry Studio 可以识别后自动切换到 AI 回答

详细说明请参考：[INTELLIGENT_FALLBACK_GUIDE.md](./INTELLIGENT_FALLBACK_GUIDE.md)

### Q: JSON 输出出现乱码怎么办？

A: 这是 **正常现象**！JSON 中的中文都被转义为 Unicode 编码（`\uXXXX`），以确保跨平台兼容性。

- **在 PowerShell 中**：显示为 `\u7cd6\u5c3f\u75c5`（正常）
- **在 Cherry Studio 中**：会自动解码显示为中文（正常）

无需处理，系统会自动解析。

---

## 🔧 高级功能

### 功能开关

医疗编码查询功能可以通过开关控制启用/禁用：

在 `index.js` 第 649 行：
```javascript
const ENABLE_MEDICAL_CODE = true;  // 设为 false 可禁用区保编码查询
```

详细说明：[FEATURE_TOGGLE.md](./FEATURE_TOGGLE.md)

### 智能降级机制

当查询失败时（如 429 错误），系统会返回特殊的错误格式，建议客户端切换到 AI 直接回答：

```json
{
  "success": false,
  "error_type": "rate_limit",
  "fallback_suggestion": "AI_DIRECT_ANSWER",
  "retry_after": "60"
}
```

Cherry Studio 可以识别这个信号，自动切换到让 AI 基于知识回答。

详细说明：[INTELLIGENT_FALLBACK_GUIDE.md](./INTELLIGENT_FALLBACK_GUIDE.md)

---

## 🧪 测试

### 测试区保编码查询功能

```bash
# 集成测试
node test_medsci.cjs

# 单独测试 Python 脚本
python medsci_scraper.py "糖尿病" icd10

# 测试 429 错误处理
python test_429_error.py
```

### 测试输出示例

✅ **成功查询**：
```
✅ JSON 解析成功

📊 查询结果:
   - 成功: true
   - 来源: 梅斯区学 (ICD-10疾病编码)
   - 关键词: 糖尿病
   - 结果数: 30
```

---

如有问题或建议，欢迎联系！