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

---

✨ 功能特性 / 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

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

2. 配置 / Configure

二选一：

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

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

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

方式 B：配置文件

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

config.json 支持的自定义项：

{
  "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：

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

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

{
  "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

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

⚠️ 免责声明 / Disclaimer

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