# Reasonix Qwen MCP Server

> 专为 **Reasonix** 设计的 MCP 插件：把阿里云百炼（DashScope）的通义千问（Qwen）模型接入 Reasonix，提供视觉理解、联网搜索、通用对话三个工具。
> A Qwen MCP server built for Reasonix: vision understanding, real web search and chat via Alibaba Cloud DashScope.

一个轻量 Node.js MCP server，提供三个即用工具：**视觉理解（qwen3-vl-plus）**、**真实联网搜索（enable_search）**、**通用文本对话（qwen-plus）**。

A lightweight Node.js MCP server exposing three ready-to-use tools: **vision (qwen3-vl-plus)**, **real web search (enable_search)**, **chat (qwen-plus)**.

> 📖 详细中文使用手册：**[使用说明.md](./使用说明.md)**

---

## ✨ 功能特性 / Features

| 工具 / Tool | 说明 / Description | 模型 / Model |
|---|---|---|
| `qwen_vision` | 视觉理解：传本地图片路径或 http(s) 图片 URL，让模型"看图"并回答 | `qwen3-vl-plus` |
| `qwen_search` | 联网搜索：实时检索最新信息，返回带来源的综合回答 | `qwen-plus` |
| `qwen_chat` | 通用文本对话（总结 / 翻译 / 改写 / 写代码等） | `qwen-plus` |

关键特性：

> - 🖼️ **视觉提速**：本地图片自动用 `sharp` 预压缩（>300KB 或分辨率 >1568px 才压缩，小图零损耗），网络图片先下载压缩再送模型（下载限 10MB）；
- 🔍 **真联网**：走百炼**原生**接口的 `enable_search`（OpenAI 兼容端点会静默忽略该参数，详见下方"工作原理"）；
- ⚡ **生成长度可控**：`max_tokens` 参数随时可调，快慢由你决定；
- 🔐 **Key 安全**：支持环境变量 `DASHSCOPE_API_KEY` 或本地 `config.json`（已被 `.gitignore` 忽略，不会入库）。

## 📦 环境要求 / Requirements

- Node.js ≥ 20.9（内置 `fetch`）
- 阿里云百炼（DashScope）API Key：https://bailian.console.aliyun.com/

## 🚀 快速开始 / Quick Start

> 🤖 **Reasonix 用户**：无需手动配置——克隆/下载本项目后，在 Reasonix 中打开项目目录，直接让 Reasonix "安装并配置这个 MCP 插件"，它会自动注册、连接并引导你填写 API Key。

### 1. 安装 / Install

```bash
git clone https://github.com/HUAN425/reasonix-qwen-mcp.git qwen-mcp
cd qwen-mcp
npm install
```

### 2. 配置 / Configure

二选一：

**方式 A：环境变量（推荐）**

```bash
# Windows PowerShell
$env:DASHSCOPE_API_KEY = "sk-..."

# macOS / Linux
export DASHSCOPE_API_KEY="sk-..."
```

**方式 B：配置文件**

```bash
cp config.example.json config.json   # Windows: copy config.example.json config.json
# 然后编辑 config.json 填入 apiKey
```

`config.json` 支持的自定义项：

```jsonc
{
  "apiKey": "sk-...",                                  // 必填；环境变量优先
  "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1", // 可选；仅影响对话与视觉，联网搜索固定使用国内原生端点
  "visionModel": "qwen3-vl-plus",                      // 可选，视觉模型
  "searchModel": "qwen-plus",                          // 可选，搜索模型
  "chatModel": "qwen-plus"                             // 可选，对话模型
}
```

> 注意：修改 `config.json` 后需重启 MCP server 生效（配置有进程内缓存）。

### 3. 注册到 MCP 客户端 / Register with your client

> ⚠️ **兼容性说明**：本项目目前**仅在 Reasonix 上实际测试使用过**。技术实现基于标准 MCP 协议（stdio 传输），理论上适用于其他支持 MCP 的客户端（如 Claude Desktop、Cursor 等），但**尚未在它们上面实测验证**。如在其他客户端遇到问题，欢迎反馈。

**Claude Desktop** — `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "qwen-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/qwen-mcp/server.js"]
    }
  }
}
```

**项目级 `.mcp.json`**（Reasonix 等支持）：

```json
{
  "mcpServers": {
    "qwen-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/qwen-mcp/server.js"]
    }
  }
}
```

### 4. 使用 / Usage

三个工具会以 `mcp__qwen-mcp__qwen_vision` 等名称出现在你的客户端里。

| 工具 | 参数 | 说明 |
|---|---|---|
| `qwen_vision` | `image`（必填）、`prompt`、`detail`（low/high）、`max_tokens` | `image` 支持本地绝对/相对路径或 http(s) URL；默认输出 150 字内简要描述、`max_tokens=800` |
| `qwen_search` | `query`（必填）、`max_tokens` | 返回头标注 `[已联网检索 N 条实时结果]`，未联网时会明确提示 |
| `qwen_chat` | `message`（必填） | 纯文本对话 |

## ⚙️ 工作原理 / How it works

- **对话与视觉**：调用 DashScope OpenAI 兼容端点 `POST /compatible-mode/v1/chat/completions`（多模态走 `image_url` + base64 data URL）；
- **联网搜索**：调用百炼**原生**端点 `POST /api/v1/services/aigc/text-generation/generation` 并携带 `enable_search: true`。
  > ⚠️ 实测：OpenAI 兼容端点会**静默忽略** `enable_search`（返回模型自身知识而非实时结果），所以搜索必须走原生端点。

## 🧪 测试 / Test

```bash
npm test   # 等价于 node test-handshake.js（MCP 握手 + 工具列表，无需 API Key）
```

## 📁 项目结构 / Structure

```
qwen-mcp/
├── server.js            # MCP server 主程序
├── config.example.json  # 配置模板（复制为 config.json 使用）
├── package.json
├── .gitignore
└── test-handshake.js    # 握手自测脚本
```

## 🔒 安全说明 / Security

- `config.json`、`node_modules/` 已在 `.gitignore` 中，不会提交到仓库；
- 请勿将任何真实 API Key 写入会进入版本库的文件；
- ⚠️ `qwen_vision` 可读取本机任意路径的图片文件并发送至阿里云，请仅在可信环境使用；网络图片下载上限 10MB，超限自动回退原 URL。

## 📄 许可证 / License

[MIT](./LICENSE)

## ⚠️ 免责声明 / Disclaimer

本项目与阿里云无官方关联。模型能力、价格与接口行为以百炼官方文档为准。