# Futurmind MCP Server - Docker 部署指南

## 🚀 快速开始

### 1. 准备环境变量

复制环境变量模板并配置：

```bash
cp env.example .env
```

编辑 `.env` 文件，设置您的 API Key：

```bash
FUTURMIND_API_KEY=your-actual-api-key-here
FUTURMIND_API_URL=https://projectflow-api.futurstaff.com
```

### 2. 构建并启动服务

```bash
# 构建镜像
docker-compose build

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f futurmind-mcp
```

### 3. 验证服务

```bash
# 检查服务状态
docker-compose ps

# 测试 MCP 端点
curl -H "Accept: application/json, text/event-stream" http://localhost:8000/mcp
```

## 📊 服务配置

### 环境变量说明

| 变量名 | 必需 | 默认值 | 说明 |
|--------|------|--------|------|
| `FUTURMIND_API_KEY` | ✅ | - | Futurmind API 密钥 |
| `FUTURMIND_API_URL` | ❌ | `https://projectflow-api.futurstaff.com` | API 服务器地址 |
| `MCP_TRANSPORT` | ❌ | `http` | 传输模式（http 或 stdio） |
| `MCP_PORT` | ❌ | `8000` | HTTP 端口 |
| `MCP_HOST` | ❌ | `0.0.0.0` | 监听地址 |
| `LLM_OPENAI_API_KEY` | ❌ | - | OpenAI API Key（可选） |
| `LLM_OPENAI_BASE_URL` | ❌ | `https://api.openai.com/v1` | LLM API 地址 |
| `LLM_MCP_MODEL` | ❌ | `gpt-4o-mini` | LLM 模型 |

### 端口映射

- `8000:8000` - MCP HTTP 端点

## 🔧 常用命令

### 启动和停止

```bash
# 启动服务
docker-compose up -d

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

# 停止并删除容器和网络
docker-compose down -v
```

### 查看日志

```bash
# 查看所有日志
docker-compose logs

# 实时查看日志
docker-compose logs -f

# 查看最近 100 行日志
docker-compose logs --tail=100
```

### 更新服务

```bash
# 重新构建镜像
docker-compose build --no-cache

# 重新启动服务
docker-compose up -d --force-recreate
```

## 🌐 远程访问配置

### Cursor 远程连接配置

在 Cursor 的 `.cursor/mcp.json` 中添加：

```json
{
  "mcpServers": {
    "futurmind": {
      "url": "http://your-server-ip:8000/mcp"
    }
  }
}
```

### 通过反向代理访问（推荐）

#### Nginx 配置示例

```nginx
server {
    listen 80;
    server_name futurmind-mcp.yourdomain.com;

    location /mcp {
        proxy_pass http://localhost:8000/mcp;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # SSE 特定配置
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}
```

#### 使用 HTTPS（推荐）

```bash
# 使用 Let's Encrypt 获取证书
certbot --nginx -d futurmind-mcp.yourdomain.com
```

## 🔍 故障排查

### 检查容器状态

```bash
# 查看容器状态
docker-compose ps

# 查看容器详细信息
docker inspect futurmind-mcp

# 进入容器
docker-compose exec futurmind-mcp sh
```

### 测试 MCP 连接

```bash
# 测试基础连接
curl http://localhost:8000/

# 测试 MCP 端点
curl -H "Accept: application/json, text/event-stream" \
     http://localhost:8000/mcp

# 测试工具调用（需要先建立会话）
# 注意：直接 curl 测试会比较复杂，建议使用 Cursor 测试
```

### 常见问题

#### 1. 服务无法启动

检查日志：
```bash
docker-compose logs futurmind-mcp
```

常见原因：
- 端口 8000 被占用
- 环境变量配置错误
- API Key 无效

#### 2. 连接超时

- 检查防火墙设置
- 确认端口映射正确
- 检查网络连接

#### 3. API 调用失败

- 验证 `FUTURMIND_API_KEY` 是否正确
- 检查 `FUTURMIND_API_URL` 是否可访问
- 查看容器日志了解详细错误

## 📊 监控和维护

### 健康检查

服务包含内置健康检查，每 30 秒检查一次：

```bash
# 查看健康状态
docker-compose ps
```

### 资源监控

```bash
# 查看资源使用
docker stats futurmind-mcp

# 查看容器详细信息
docker inspect futurmind-mcp
```

## 🔒 安全建议

1. **不要暴露在公网** - 使用 VPN 或反向代理
2. **使用 HTTPS** - 通过 Nginx + Let's Encrypt
3. **保护 API Key** - 不要提交到代码库
4. **限制访问** - 使用防火墙规则
5. **定期更新** - 保持镜像和依赖更新

## 📝 备份和恢复

### 备份配置

```bash
# 备份环境变量
cp .env .env.backup

# 备份 docker-compose 配置
cp docker-compose.yaml docker-compose.yaml.backup
```

### 导出镜像

```bash
# 导出镜像
docker save futurmind-mcp:latest | gzip > futurmind-mcp.tar.gz

# 导入镜像
docker load < futurmind-mcp.tar.gz
```

## 🆕 版本更新

```bash
# 1. 拉取最新代码
git pull

# 2. 重新构建镜像
docker-compose build --no-cache

# 3. 重启服务
docker-compose up -d --force-recreate

# 4. 验证服务
docker-compose logs -f futurmind-mcp
```

## 📞 支持

如有问题，请查看：
- [README.md](./README.md) - 基本使用说明
- [GitHub Issues](https://github.com/your-repo/issues) - 提交问题
- 容器日志：`docker-compose logs futurmind-mcp`


