qiniu-mcp/RAYCAST_SETUP.md

A Model Context Protocol server for Qiniu Cloud Storage services with optimized local file upload support

# 🚀 在Raycast中配置七牛云MCP

## 前提条件

确保你的系统已安装Node.js (>=18.0.0)：
```bash
node --version
npm --version
```

## 方法1：使用npx（推荐，无需全局安装）

### 1. 复制配置JSON

将以下配置复制到剪贴板：

```json
{
  "name": "Qiniu Cloud Storage",
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "qiniu-mcp"],
  "env": {
    "QINIU_ACCESS_KEY": "你的七牛AccessKey",
    "QINIU_SECRET_KEY": "你的七牛SecretKey",
    "QINIU_BUCKET": "你的默认bucket",
    "QINIU_REGION": "z0",
    "QINIU_DOMAIN": "https://你的自定义域名.com"
  }
}
```

### 2. 在Raycast中安装

1. 打开Raycast (⌘ + Space)
2. 搜索并运行 `Install Server` 命令
3. Raycast会自动填充表单（因为你复制了配置JSON）
4. 点击 `Install` 完成安装

## 方法2：全局安装后使用

### 1. 全局安装包

```bash
npm install -g qiniu-mcp
```

### 2. 配置Raycast

使用以下配置：

```json
{
  "name": "Qiniu Cloud Storage",
  "type": "stdio",
  "command": "qiniu-mcp",
  "args": [],
  "env": {
    "QINIU_ACCESS_KEY": "你的七牛AccessKey",
    "QINIU_SECRET_KEY": "你的七牛SecretKey",
    "QINIU_BUCKET": "你的默认bucket",
    "QINIU_REGION": "z0",
    "QINIU_DOMAIN": "https://你的自定义域名.com"
  }
}
```

## 方法3：使用Deeplink安装

你也可以通过以下链接直接安装：

```bash
raycast://extensions/install-mcp-server?config={"name":"Qiniu Cloud Storage","type":"stdio","command":"npx","args":["-y","qiniu-mcp"],"env":{"QINIU_ACCESS_KEY":"你的AccessKey","QINIU_SECRET_KEY":"你的SecretKey","QINIU_BUCKET":"你的bucket","QINIU_REGION":"z0","QINIU_DOMAIN":"https://你的域名.com"}}
```

## 🔧 使用方法

安装完成后，你可以在Raycast中：

### 1. 在AI Chat中使用

1. 打开Raycast AI Chat
2. 输入 `@Qiniu` 来调用七牛云MCP服务器
3. 使用自然语言描述你的需求：
   - "上传这个文件到我的七牛云存储"
   - "列出我的bucket中的所有图片文件"
   - "生成这个文件的下载链接"
   - "删除指定的文件"

### 2. 在Quick AI中使用

1. 选择文件或文本
2. 使用Quick AI (⌘ + Shift + 1)
3. 提及 `@Qiniu` 来处理文件操作

### 3. 在AI Commands中使用

创建自定义AI命令，预设七牛云操作指令。

## 🛠️ 可用功能

- **文件上传** (`qiniu_upload_file`)
- **文件列表** (`qiniu_list_files`)
- **文件删除** (`qiniu_delete_file`)
- **文件信息** (`qiniu_get_file_info`)
- **下载链接生成** (`qiniu_generate_download_url`)
- **文件复制** (`qiniu_copy_file`)
- **文件移动** (`qiniu_move_file`)

## 🔍 管理MCP服务器

使用 `Manage Servers` 命令来：
- 查看已安装的MCP服务器
- 卸载不需要的服务器
- 启动与特定服务器的新对话

## ⚠️ 注意事项

1. **环境变量安全**：你的API密钥只存储在本地Raycast配置中，不会发送到任何第三方服务
2. **网络要求**：需要能够访问 `mcp.qiaomu.ai:8766` 服务器
3. **Node.js版本**：确保Node.js版本 >= 18.0.0
4. **PATH配置**：如果修改了系统PATH，需要重启Raycast

## 🐛 故障排除

### 问题：命令找不到
- 确保Node.js和npm已正确安装
- 重启Raycast以刷新PATH环境变量

### 问题：连接失败
- 检查网络连接
- 确认服务器 `mcp.qiaomu.ai:8766` 可访问

### 问题：认证失败
- 检查QINIU_ACCESS_KEY和QINIU_SECRET_KEY是否正确
- 确认bucket名称和region设置正确

## 📞 支持

如有问题，请检查：
1. Raycast控制台日志
2. 网络连接状态
3. 七牛云API密钥权限