feat: 支持SSE流式传输

Author: liueic

.gitignore

@@ -1,5 +1,3 @@
 .env
-cache/endnote/index.json
-cache/fulltext/index.json
-cache/index.json
-/node_modules
+cache/
+node_modules/

README.md

@@ -69,6 +69,8 @@
 
 ## 🚀 快速部署
 
+> **💡 新功能：支持SSE模式云端部署！** 现在可以通过 `npm run start:sse` 启动SSE服务器，支持远程访问和多客户端并发连接。详见[云端部署指南](#☁️-云端部署指南)
+
 ### 前置要求
 安装Node.js (v18.0.0+)：[nodejs.org](https://nodejs.org/)
 
@@ -122,12 +124,89 @@ PUBMED_EMAIL=你的邮箱地址
 1. 访问 [NCBI API Key Management](https://www.ncbi.nlm.nih.gov/account/settings/)
 2. 登录NCBI账户，生成API密钥
 
-### 步骤四：测试服务器
+### 步骤四：运行模式选择
+
+服务器支持两种运行模式：
+
+#### **stdio 模式（默认）** - 本地开发推荐
+适用于本地开发、MCP客户端集成（如Claude Desktop、Cline等）
+
 ```bash
+# 方式一：使用npm脚本
+npm run start:stdio
+
+# 方式二：直接运行
+node src/index.js --mode=stdio
+
+# 方式三：默认模式（不指定参数时自动使用stdio）
 node src/index.js
+```
+
+**特点：**
+- ✅ 通过标准输入输出与MCP客户端通信
+- ✅ 适合本地开发和MCP客户端集成
+- ✅ 无需配置端口，开箱即用
+
+#### **SSE 模式** - 云端部署推荐
+适用于云端部署、远程访问、多客户端并发访问
+
+```bash
+# 使用npm脚本启动
+npm run start:sse
+
+# 或直接运行
+node src/index.js --mode=sse
+
+# 指定端口（默认3000）
+PORT=8080 node src/index.js --mode=sse
+```
+
+**特点：**
+- ✅ 基于HTTP Server-Sent Events (SSE) 协议
+- ✅ 支持远程访问和云端部署
+- ✅ 支持多客户端并发连接
+- ✅ 提供健康检查端点
+
+**SSE模式端点：**
+- `GET /sse` - 建立SSE连接
+- `POST /message` - 接收客户端消息（需要sessionId参数）
+- `GET /health` - 健康检查端点
+
+**环境变量配置：**
+```env
+# SSE模式端口配置（可选，默认3000）
+PORT=3000
+
+# 或通过命令行参数指定模式
+# --mode=stdio 或 --mode=sse
+# 或通过环境变量 MCP_TRANSPORT=stdio 或 MCP_TRANSPORT=sse
+```
+
+### 步骤五：测试服务器
+
+**测试stdio模式：**
+```bash
+npm run start:stdio
 # 看到 "PubMed Data Server v2.0 running on stdio" 表示成功
 ```
 
+**测试SSE模式：**
+```bash
+npm run start:sse
+# 看到以下信息表示成功：
+# "PubMed Data Server v2.0 running on SSE"
+# "[SSE] Server listening on http://0.0.0.0:3000"
+# "[SSE] SSE endpoint: http://0.0.0.0:3000/sse"
+# "[SSE] Message endpoint: http://0.0.0.0:3000/message"
+# "[SSE] Health check: http://0.0.0.0:3000/health"
+```
+
+**验证SSE模式健康检查：**
+```bash
+curl http://localhost:3000/health
+# 应返回：{"status":"ok","mode":"sse","sessions":0}
+```
+
 > 环境变量说明：项目已内置 `.env` 自动加载（使用 dotenv）。在项目根目录创建 `.env`，例如：
 
 ```env
@@ -146,9 +225,14 @@ FULLTEXT_MODE=disabled
 # enabled：自动导出RIS和BibTeX格式（默认）
 # disabled：禁用EndNote导出
 ENDNOTE_EXPORT=enabled
+# SSE模式端口配置（仅SSE模式需要，默认3000）
+PORT=3000
+# 传输模式选择（可选，默认stdio）
+# 可通过命令行参数 --mode=stdio 或 --mode=sse 覆盖
+MCP_TRANSPORT=stdio
 ```
 
-### 步骤五：MCP客户端配置
+### 步骤六：MCP客户端配置
 
 #### 1. Cline (VS Code Extension) 配置
 
@@ -402,11 +486,87 @@ cp config/claude_desktop_config.json.example config/claude_desktop_config.json
 }
 ```
 
-### 步骤六：验证集成
+### 步骤七：验证集成
 在客户端中测试：`使用pubmed_search工具搜索"acupuncture"`
 
 ---
 
+## ☁️ 云端部署指南
+
+### SSE模式云端部署
+
+SSE模式专为云端部署设计，支持远程访问和多客户端并发连接。
+
+#### **部署步骤：**
+
+1. **准备服务器环境**
+   ```bash
+   # 安装Node.js (v18.0.0+)
+   # 克隆或上传项目到服务器
+   git clone [项目地址]
+   cd mcp-pubmed-server-pancrpal
+   npm install
+   ```
+
+2. **配置环境变量**
+   ```bash
+   # 创建.env文件
+   cp .env.example .env
+   # 编辑.env，填入API密钥和邮箱
+   ```
+
+3. **启动SSE服务器**
+   ```bash
+   # 使用PM2等进程管理器（推荐）
+   npm install -g pm2
+   pm2 start npm --name "pubmed-server" -- run start:sse
+   
+   # 或直接运行
+   PORT=3000 npm run start:sse
+   ```
+
+4. **配置防火墙和反向代理（可选）**
+   ```nginx
+   # Nginx配置示例
+   server {
+       listen 80;
+       server_name your-domain.com;
+       
+       location / {
+           proxy_pass http://localhost:3000;
+           proxy_http_version 1.1;
+           proxy_set_header Upgrade $http_upgrade;
+           proxy_set_header Connection 'keep-alive';
+           proxy_set_header Host $host;
+           proxy_cache_bypass $http_upgrade;
+       }
+   }
+   ```
+
+5. **验证部署**
+   ```bash
+   # 健康检查
+   curl http://your-server:3000/health
+   # 应返回：{"status":"ok","mode":"sse","sessions":0}
+   ```
+
+#### **使用场景对比：**
+
+| 模式 | 适用场景 | 优势 |
+|------|----------|------|
+| **stdio** | 本地开发、MCP客户端集成 | 简单、无需配置端口 |
+| **SSE** | 云端部署、远程访问 | 支持多客户端、可扩展 |
+
+#### **生产环境建议：**
+
+- ✅ 使用进程管理器（PM2、systemd等）确保服务持续运行
+- ✅ 配置反向代理（Nginx、Caddy等）提供HTTPS支持
+- ✅ 设置防火墙规则，仅开放必要端口
+- ✅ 配置日志轮转和监控告警
+- ✅ 定期更新依赖和检查安全漏洞
+
+---
+
 ## 🛠️ 11个高效工具
 
 ### 1. `pubmed_search` - 智能文献搜索
@@ -597,6 +757,18 @@ mcp-pubmed-server/
    - 不要使用 `cwd` 参数
    - 使用正斜杠 `/` 或双反斜杠 `\\`
 
+5. **SSE模式启动失败**
+   - 检查端口是否被占用：`lsof -i :3000` (macOS/Linux) 或 `netstat -ano | findstr :3000` (Windows)
+   - 确认防火墙允许指定端口访问
+   - 检查环境变量 `PORT` 是否正确设置
+   - 验证SSE端点可访问：`curl http://localhost:3000/health`
+
+6. **SSE模式连接问题**
+   - 确保客户端支持SSE协议
+   - 检查网络连接和防火墙设置
+   - 验证sessionId是否正确传递
+   - 查看服务器日志获取详细错误信息
+
 ### 部署清单
 - [ ] Node.js已安装 (v18.0.0+)
 - [ ] npm 包已安装 (`npm install -g mcp-pubmed-llm-server`) 或从源码安装 (`npm install`)

package.json

@@ -9,6 +9,8 @@
   },
   "scripts": {
     "start": "node src/index.js",
+    "start:stdio": "node src/index.js --mode=stdio",
+    "start:sse": "node src/index.js --mode=sse",
     "dev": "node --watch src/index.js",
     "build": "echo 'No build step required'",
     "test": "node test/test.js",