# Qwen API MCP Server

一个支持 `npx` 直接启动的 Qwen API MCP (Model Context Protocol) 服务器，提供聊天、图片生成和获取图片功能，无需安装即可使用！

[![npm version](https://img.shields.io/npm/v/qwen-api-mcp.svg)](https://www.npmjs.com/package/qwen-api-mcp)
[![Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen.svg)](https://nodejs.org/)
[![License](https://img.shields.io/badge/license-ISC-blue.svg)](LICENSE)

## ✨ 功能特性

- 💬 **聊天功能**: 与Qwen3大语言模型进行智能对话
- 🖼️ **图片生成**: 使用Qwen-Image模型生成高质量图片
- 📋 **状态查询**: 实时查询图片生成任务状态
- 🔗 **结果获取**: 获取已完成的图片生成结果
- 🚀 **npx支持**: 无需安装，直接运行
- 🔒 **安全可靠**: API密钥安全，支持环境变量管理
- 🐛 **调试友好**: 详细的调试日志和错误提示
- ⚡ **轻量级**: 包体积小，启动快速

## 🚀 快速开始

### 方式1: 直接使用npx启动（推荐）

```bash
# 设置API密钥环境变量
export MODELSCOPE_API_KEY=your_api_key_here

# 启动MCP服务器（自动确认安装）
npx --yes qwen-api-mcp

# 或者如果已安装过，直接运行
npx qwen-api-mcp

# 或者指定具体版本
npx --yes qwen-api-mcp@1.0.31
```

### 方式2: 使用配置文件

在当前目录创建 `.env` 文件：

```env
MODELSCOPE_API_KEY=your_api_key_here
DEBUG=true
```

然后启动：

```bash
npx qwen-api-mcp
```

### 方式3: 直接传递API密钥

```bash
npx qwen-api-mcp --key your_api_key_here
```

### 方式4: 全局安装

```bash
# 全局安装
npm install -g qwen-api-mcp

# 直接使用
qwen-api-mcp
```

## 📋 命令行选项

```bash
npx qwen-api-mcp [选项]
```

| 选项 | 描述 | 示例 |
|------|------|------|
| `-h, --help` | 显示帮助信息 | `npx qwen-api-mcp --help` |
| `-v, --version` | 显示版本信息 | `npx qwen-api-mcp --version` |
| `-d, --debug` | 启用调试模式 | `npx qwen-api-mcp --debug` |
| `--key <api_key>` | 直接设置API密钥 | `npx qwen-api-mcp --key xxx` |

## 🔧 环境变量配置

| 环境变量 | 描述 | 必需 | 默认值 | 示例 |
|----------|------|------|--------|------|
| `MODELSCOPE_API_KEY` | ModelScope API密钥 | ✅ | 无 | `ms-b428598d-e19a-4823-bd8e-d4335737e0c7` |
| `DEBUG` | 调试模式 | ❌ | `false` | `true` |
| `MODELSCOPE_TIMEOUT` | 请求超时时间(毫秒) | ❌ | `30000` | `60000` |

**注意**：API 基础地址已固定为 `https://api-inference.modelscope.cn/`，无需额外配置。

### 🎯 获取API密钥

1. 访问 [ModelScope](https://modelscope.cn/)
2. 注册并登录账号
3. 进入控制台获取API密钥
4. 复制密钥格式类似：`ms-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`

## 🛠️ MCP工具

### 1. chat - 聊天对话

与Qwen3大语言模型进行智能对话。

**参数:**
- `prompt` (必需): 聊天提示词或问题
- `model` (可选): 模型名称，默认为 "qwen3"

**示例:**
```json
{
  "name": "chat",
  "arguments": {
    "prompt": "你好，请简单介绍一下你自己"
  }
}
```

**响应示例:**
```json
{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "model": "Qwen/Qwen3-235B-A22B-Instruct-2507",
          "content": "你好！我是Qwen3大语言模型...",
          "usage": {
            "prompt_tokens": 8,
            "completion_tokens": 25,
            "total_tokens": 33
          },
          "finish_reason": "stop"
        }
      }
    }
  ]
}
```

### 2. generate_image - 生成图片

使用Qwen-Image模型生成高质量图片。

**参数:**
- `prompt` (必需): 图片描述提示词，越详细越好

**示例:**
```json
{
  "name": "generate_image",
  "arguments": {
    "prompt": "一座美丽的山峰，在夕阳下呈现金色光芒，高清摄影风格，自然光线"
  }
}
```

**响应示例:**
```json
{
  "content": [
    {
      "type": "text", 
      "text": {
        "success": true,
        "data": {
          "task_id": "ba21f49c-bee9-4235-a385-5dd0702f2881",
          "task_status": "PENDING",
          "request_id": "fdf7db12-545b-4c5a-b627-9f52c0019d5d",
          "message": "图片生成任务已创建，使用 get_image_status 查询状态"
        }
      }
    }
  ]
}
```

### 3. get_image_status - 查询图片状态

查询图片生成任务的实时状态。

**参数:**
- `task_id` (必需): 图片生成任务的ID

**示例:**
```json
{
  "name": "get_image_status",
  "arguments": {
    "task_id": "ba21f49c-bee9-4235-a385-5dd0702f2881"
  }
}
```

**状态说明:**
- `PENDING`: 任务正在等待处理
- `PROCESSING`: 任务正在处理中
- `SUCCEED`: 任务处理成功
- `FAILED`: 任务处理失败

### 4. get_image_result - 获取图片结果

获取已完成的图片生成任务的结果。

**参数:**
- `task_id` (必需): 图片生成任务的ID

**示例:**
```json
{
  "name": "get_image_result",
  "arguments": {
    "task_id": "ba21f49c-bee9-4235-a385-5dd0702f2881"
  }
}
```

**成功响应示例:**
```json
{
  "content": [
    {
      "type": "text",
      "text": {
        "success": true,
        "data": {
          "task_id": "ba21f49c-bee9-4235-a385-5dd0702f2881",
          "task_status": "SUCCEED",
          "image_url": "https://example.com/generated-image.jpg",
          "images": ["https://example.com/generated-image.jpg"],
          "message": "图片生成成功"
        }
      }
    }
  ]
}
```

## 📝 使用示例

### Claude Desktop 配置

在Claude Desktop的配置文件中添加：

```json
{
    "mcpServers": {
        "qwen-api": {
            "command": "npx",
            "args": [
                "--yes", "--no-cache",
                "qwen-api-mcp@1.0.48",
                "--token=your_actual_api_key_here"
            ],
            "disabled": false
        }
    }
}


```

**⚠️ 重要提示：**
- **推荐使用** `--token=your_api_key` 方式传递密钥，更安全可靠
- **不要**使用 `"${MODELSCOPE_API_KEY}"`，这种变量替换在大多数MCP客户端中不被支持
- 如果仍想使用环境变量方式，也可以用以下配置：

```json
{
    "mcpServers": {
        "qwen-api": {
            "command": "npx",
            "args": [
                "--yes", "--no-cache",
                "qwen-api-mcp@1.0.48"
            ],
            "env": {
                "MODELSCOPE_API_KEY": "your_actual_api_key_here",
                "DEBUG": "true"
            },
            "disabled": false
        }
    }
}
```

**环境变量设置:**
```bash
# macOS/Linux
export MODELSCOPE_API_KEY=your_api_key_here

# Windows
set MODELSCOPE_API_KEY=your_api_key_here

# PowerShell
$env:MODELSCOPE_API_KEY="your_api_key_here"
```

**支持的新用法（推荐）:**
```bash
# 使用 --token 参数
npx qwen-api-mcp --token=your_api_key_here

# 使用 --key 参数
npx qwen-api-mcp --key=your_api_key_here
```

### 基本使用流程

1. **启动服务器:**
```bash
npx qwen-api-mcp --debug
```

2. **聊天对话:**
```json
{
  "name": "chat",
  "arguments": {
    "prompt": "请解释一下量子计算的基本原理"
  }
}
```

3. **生成图片:**
```json
{
  "name": "generate_image", 
  "arguments": {
    "prompt": "一只可爱的橘猫在阳光下的窗台上睡觉"
  }
}
```

4. **查询状态:**
```json
{
  "name": "get_image_status",
  "arguments": {
    "task_id": "ba21f49c-bee9-4235-a385-5dd0702f2881"
  }
}
```

5. **获取结果:**
```json
{
  "name": "get_image_result",
  "arguments": {
    "task_id": "ba21f49c-bee9-4235-a385-5dd0702f2881"
  }
}
```

## 🔒 安全性

- ✅ **API密钥安全**: 从不在日志或输出中显示完整密钥
- ✅ **环境隔离**: npx运行在临时环境中，不会污染系统
- ✅ **输入验证**: 自动验证API密钥格式和长度
- ✅ **错误处理**: 完善的错误捕获和处理机制
- ✅ **HTTPS加密**: 所有API请求都通过HTTPS传输

## 🐛 故障排除

### 常见问题

**1. API密钥错误**
```bash
❌ 错误: 未找到 MODELSCOPE_API_KEY 环境变量
```
**解决方案:**
```bash
# 方式1: 设置环境变量
export MODELSCOPE_API_KEY=your_key_here

# 方式2: 创建.env文件
echo "MODELSCOPE_API_KEY=your_key_here" > .env

# 方式3: 直接传递
npx qwen-api-mcp --key your_key_here
```

**2. 网络连接问题**
```bash
npx qwen-api-mcp --debug  # 查看详细错误信息
```

**3. 图片生成失败**
- 检查提示词是否合适
- 确认API配额是否充足
- 查看调试日志了解具体错误

**4. 权限问题**
```bash
# 确保有当前目录的写入权限
chmod 755 .
```

### 调试技巧

1. **启用调试模式:** `npx qwen-api-mcp --debug`
2. **检查配置:** 查看启动时的配置信息输出
3. **环境变量检查:** `env | grep MODELSCOPE`
4. **网络测试:** `curl -I https://api-inference.modelscope.cn/`

## 📊 性能优化

### 建议配置
```bash
# 增加超时时间（处理复杂图片生成）
export MODELSCOPE_TIMEOUT=60000

# 启用调试模式（开发时）
export DEBUG=true
```

### 最佳实践
1. **图片提示词**: 提供详细、具体的描述
2. **批量操作**: 合理安排图片生成，避免频繁请求
3. **错误重试**: 实现适当的重试机制
4. **缓存结果**: 缓存聊天和图片结果

## 📈 更新日志

### v1.0.0
- ✨ 初始版本发布
- 🚀 支持npx直接启动
- 💬 聊天功能支持
- 🖼️ 图片生成功能
- 🔍 状态查询功能
- 📥 结果获取功能

## 🤝 贡献

欢迎提交Issue和Pull Request！

### 开发环境设置
```bash
# 克隆项目
git clone https://github.com/your-repo/qwen-api-mcp.git
cd qwen-api-mcp

# 安装依赖
npm install

# 运行测试
npm test

# 启动开发模式
npm start
```

## 📄 许可证

ISC License - 详见 [LICENSE](LICENSE) 文件

## 🔗 相关链接

- [📦 npm包](https://www.npmjs.com/package/qwen-api-mcp) - npm包页面
- [🔑 ModelScope](https://modelscope.cn/) - 获取API密钥
- [📋 MCP协议](https://modelcontextprotocol.io/) - 了解MCP协议
- [🐛 问题反馈](https://github.com/your-repo/qwen-api-mcp/issues) - 报告问题
- [💬 讨论区](https://github.com/your-repo/qwen-api-mcp/discussions) - 功能讨论

## 🙏 致谢

感谢 [ModelScope](https://modelscope.cn/) 提供强大的AI服务支持！

---

**⚠️ 重要提示**: 
- 使用本工具需要有效的ModelScope API密钥
- 请遵守ModelScope的使用条款和政策
- 注意API调用频率限制和费用
- 生成的内容请遵守相关法律法规