cloud-mcp/DIRECT_DEPLOY.md

直接部署方案（推荐）

概述

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

优势

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

安装步骤

1. 在服务器上安装 Bun

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

# 验证安装
bun --version

2. 克隆项目

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

3. 安装依赖

bun install

4. 配置环境变量

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

5. 运行 MCP 服务器

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

bun run src/index.ts

方式二：使用 PM2（推荐）

# 安装 PM2
bun add -g pm2

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

# 设置开机自启
pm2 save
pm2 startup

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

创建服务文件：

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 或类似位置）：

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

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

{
  "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. 工具会自动：
   • 拉取最新代码
   • 更新依赖（如果需要）
   • 重启服务

手动部署

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，迁移步骤：

# 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 服务器无法启动

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

# 检查依赖
bun install

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

部署工具执行失败

1. 检查 Git 仓库：

   cd /opt/cloud-mcp
   git status
   

2. 检查权限：

   ls -la /opt/cloud-mcp
   chmod +x deploy-gitea.sh
   

3. 检查服务状态：

   # PM2
   pm2 status
   
   # systemd
   sudo systemctl status cloud-mcp
   

查看日志

# PM2 日志
pm2 logs cloud-mcp

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

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

安全建议

1. 使用非 root 用户运行（如果可能）：

   sudo adduser mcpuser
   sudo chown -R mcpuser:mcpuser /opt/cloud-mcp
   

2. 限制文件权限：

   chmod 600 .env
   

3. 定期更新：

   bun update
   

下一步

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