# 直接部署方案（推荐）

## 概述

直接在服务器上运行 MCP 服务器（不使用 Docker），这样可以直接使用 MCP 工具进行部署，无需 SSH 连接。

## 优势

✅ **无需 SSH** - MCP 工具直接在服务器上运行  
✅ **更简单** - 不需要配置 Runner、Webhook 等  
✅ **更直接** - 在 Cursor 中直接触发部署  
✅ **更灵活** - 可以直接访问服务器文件系统  

## 安装步骤

### 1. 在服务器上安装 Bun

```bash
# 安装 Bun
curl -fsSL https://bun.sh/install | bash

# 验证安装
bun --version
```

### 2. 克隆项目

```bash
git clone <your-gitea-repo-url> /opt/cloud-mcp
cd /opt/cloud-mcp
```

### 3. 安装依赖

```bash
bun install
```

### 4. 配置环境变量

```bash
cp env.template .env
nano .env  # 编辑配置
```

### 5. 运行 MCP 服务器

#### 方式一：直接运行（测试）

```bash
bun run src/index.ts
```

#### 方式二：使用 PM2（推荐）

```bash
# 安装 PM2
bun add -g pm2

# 启动服务
pm2 start "bun run src/index.ts" --name cloud-mcp

# 设置开机自启
pm2 save
pm2 startup
```

#### 方式三：使用 systemd（生产环境）

创建服务文件：

```bash
sudo tee /etc/systemd/system/cloud-mcp.service > /dev/null <<EOF
[Unit]
Description=Cloud MCP Server
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/cloud-mcp
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
ExecStart=/usr/local/bin/bun run src/index.ts
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# 启用并启动服务
sudo systemctl daemon-reload
sudo systemctl enable cloud-mcp
sudo systemctl start cloud-mcp
sudo systemctl status cloud-mcp
```

## 在 Cursor 中配置 MCP

### 1. 配置 MCP 服务器

编辑 Cursor 的 MCP 配置（通常在 `~/.cursor/mcp.json` 或类似位置）：

```json
{
  "mcpServers": {
    "cloud-mcp": {
      "command": "ssh",
      "args": [
        "user@your-server",
        "cd /opt/cloud-mcp && bun run src/index.ts"
      ]
    }
  }
}
```

**或者**，如果 MCP 服务器已经在运行，通过 stdio 连接：

```json
{
  "mcpServers": {
    "cloud-mcp": {
      "command": "ssh",
      "args": [
        "user@your-server",
        "bun run /opt/cloud-mcp/src/index.ts"
      ]
    }
  }
}
```

### 2. 使用部署工具

配置完成后，在 Cursor 中可以直接使用：

- `deploy_update` - 拉取最新代码并重新部署
- `deploy_status` - 查看部署状态
- `deploy_logs` - 查看部署日志

## 部署流程

### 自动部署（通过 MCP 工具）

1. **在 Cursor 中**，直接调用 `deploy_update` 工具
2. 工具会自动：
   - 拉取最新代码
   - 更新依赖（如果需要）
   - 重启服务

### 手动部署

```bash
cd /opt/cloud-mcp
git pull origin main
bun install  # 如果依赖有变化
pm2 restart cloud-mcp  # 或 systemctl restart cloud-mcp
```

## 部署工具说明

### deploy_update

拉取最新代码并重新部署：

```
参数：
- branch: Git 分支（默认: main）
- rebuild: 是否强制重建（默认: false）
```

### deploy_status

查看当前部署状态：
- Git 状态
- 服务运行状态
- 是否有未提交的更改

### deploy_logs

查看部署日志：
- 参数：lines（显示行数，默认 50）

## 与 Docker 方案对比

| 特性 | 直接运行 | Docker |
|------|---------|--------|
| 部署复杂度 | ⭐ 简单 | ⭐⭐ 中等 |
| 资源占用 | 较低 | 较高 |
| 隔离性 | 较低 | 高 |
| MCP 工具访问 | ✅ 直接访问 | ❌ 需要 SSH |
| 适合场景 | 个人/小项目 | 生产环境 |

## 迁移 from Docker

如果之前使用 Docker，迁移步骤：

```bash
# 1. 停止 Docker 容器
docker-compose down

# 2. 备份数据
cp -r data data.backup

# 3. 安装 Bun（如果还没有）
curl -fsSL https://bun.sh/install | bash

# 4. 安装依赖
cd /opt/cloud-mcp
bun install

# 5. 启动服务（选择一种方式）
# PM2
pm2 start "bun run src/index.ts" --name cloud-mcp

# 或 systemd
sudo systemctl start cloud-mcp
```

## 故障排查

### MCP 服务器无法启动

```bash
# 检查 Bun 是否安装
bun --version

# 检查依赖
bun install

# 查看错误
bun run src/index.ts
```

### 部署工具执行失败

1. **检查 Git 仓库**：
   ```bash
   cd /opt/cloud-mcp
   git status
   ```

2. **检查权限**：
   ```bash
   ls -la /opt/cloud-mcp
   chmod +x deploy-gitea.sh
   ```

3. **检查服务状态**：
   ```bash
   # PM2
   pm2 status
   
   # systemd
   sudo systemctl status cloud-mcp
   ```

### 查看日志

```bash
# PM2 日志
pm2 logs cloud-mcp

# systemd 日志
sudo journalctl -u cloud-mcp -f

# 部署日志
tail -f /opt/cloud-mcp/deploy.log
```

## 安全建议

1. **使用非 root 用户运行**（如果可能）：
   ```bash
   sudo adduser mcpuser
   sudo chown -R mcpuser:mcpuser /opt/cloud-mcp
   ```

2. **限制文件权限**：
   ```bash
   chmod 600 .env
   ```

3. **定期更新**：
   ```bash
   bun update
   ```

## 下一步

- 配置自动备份
- 设置监控告警
- 优化性能配置