nx-mcp-server 1.0.4 → 1.0.5

package/README.md

@@ -1,167 +1,205 @@
 # NX MCP Server
 
-图像生成 MCP Server——智能生图（通义万相 API）+ 本地图形工具集，支持 Stdio 和 HTTP 双传输模式。
+远程图片压缩 MCP Server，调用 NX API 对图片进行智能压缩，返回七牛 CDN URL 及压缩比。支持 **Stdio** 和 **Streamable HTTP** 双传输模式。
+
+---
 
 ## 工具列表
 
-### 智能生图（通义万相 API）
 | 工具 | 说明 |
 |------|------|
-| `generate_smart` | 文生图，调用通义万相模型 |
+| `nx_compress` | 智能压缩图片，支持 HTTP URL / 本地路径 / dataUrl / base64，可自动覆盖或另存 |
 
-### 本地图形工具（无需网络/API Key）
-| 工具 | 说明 |
-|------|------|
-| `generate_basic` | 图形合成：形状/文字/图片叠加 |
-| `generate_qrcode` | 二维码生成（支持中心 logo + 文字水印） |
-| `generate_barcode` | 条形码生成（CODE128/CODE39/EAN13/EAN8/UPC/ITF） |
-| `compress_image` | 图片压缩（质量/尺寸） |
-| `convert_format` | 格式互转（PNG↔JPEG↔WebP↔BMP↔TIFF→AVIF） |
-| `stitch_images` | 多图拼接/网格布局 |
-| `extract_colors` | 提取图片主色调（hex/rgb/hsl） |
-| `add_watermark` | 文字/图片水印（支持平铺） |
+---
 
-## 快速开始
+## nx_compress 参数
 
-### 方式一：魔搭 MCP 广场（推荐）
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `urls` | `string[]` | 与 files 二选一 | - | 图片列表，支持 HTTP(S) URL、本地绝对路径、data URL |
+| `files` | `string[]` | 与 urls 二选一 | - | dataUrl 格式图片列表（`data:image/...;base64,...`） |
+| `quality` | `integer` | 否 | `90` | 压缩质量 1~100，越大质量越高 |
+| `output` | `string` | 否 | - | `"overwrite"` 覆盖原文件 / 目录路径另存（如 `E:/output/`） |
 
-在魔搭 MCP 广场搜索 **NX MCP Server**，一键同步到 Cherry Studio 或复制配置到其他客户端。
+> `urls` 和 `files` 可同时传，合并后按顺序处理。
+
+---
+
+## 两种请求模式
 
-### 方式二：npx 一键运行
+根据传入内容自动选择：
 
-无需安装，客户端配置中填入：
+| | 模式A：JSON | 模式B：FormData |
+|---|---|---|
+| **触发条件** | 全部是 HTTP(S) URL | 含本地路径 / dataUrl / `files` |
+| **请求头** | `Content-Type: application/json` + `Authorization` | `Authorization`（FormData 自动设 Content-Type） |
+| **请求体** | `{"urls":[...], "quality":90}` | multipart: `files=[Blob,...]`, `quality=90` |
+| **适用** | 远程 MCP / 图片已在 CDN | 本地 MCP / 直接传图片数据 |
+
+> 返回中的 `mode` 字段标明实际使用的模式（`"json"` / `"formdata"`）。
+
+---
+
+## 传入内容限制
+
+| 传入方式 | 本地 MCP（Stdio / localhost HTTP） | 远程 MCP（云端部署） | 说明 |
+|----------|-----------------------------------|---------------------|------|
+| **HTTP(S) URL** | ✅ | ✅ | 远程唯一可用方式 |
+| **本地绝对路径** `C:\...` `/path/...` | ✅ | ❌ | MCP Server 直接读磁盘，远程无法访问 |
+| **data URL** `data:image/...;base64,...` | ✅ | ⚠️ 受限 | HTTP 模式默认 50MB body 限制，超限用本地路径 |
+| **`files` 参数** | ✅ | ⚠️ 受限 | 同上，走 FormData 模式 |
+
+### 各场景推荐用法
+
+```
+# 本地 Claude Code（Stdio，无限制）
+nx_compress urls: ["C:/Users/me/photo.png"] quality: 80 output: "overwrite"
+
+# 远程 / npx（只能传 HTTP 链接）
+nx_compress urls: ["https://cdn.example.com/photo.png"] quality: 80
+```
+
+---
+
+## API Key 配置
+
+**优先级**：参数 `apiKey` > 环境变量 `NX_API_KEY`
+
+### 方式一：MCP 环境变量
 
 ```json
 {
   "mcpServers": {
     "nx-mcp": {
-      "command": "npx",
-      "args": ["-y", "nx-mcp-server"]
+      "command": "node",
+      "args": ["/path/to/mcp-server/src/index.js"],
+      "env": {
+        "NX_API_KEY": "your-key"
+      }
     }
   }
 }
 ```
 
-如果要用智能生图，传入 API Key：
+### 方式二：npm 包参数传入
+
+```js
+import {compressImage} from 'nx-mcp-server/src/nx-api.js';
+
+const result=await compressImage({
+  urls:['https://example.com/photo.png'],
+  apiKey:'your-key',
+});
+```
+
+---
+
+## output 输出模式
+
+| output 值 | 效果 | 示例 |
+|-----------|------|------|
+| 不传 | 只返回 CDN URL，不写文件 | 预览用 |
+| `"overwrite"` | 下载压缩版覆盖原文件 | 仅本地路径有效 |
+| 目录路径 | 下载压缩版另存到指定目录 | `E:/output/` 或 `/tmp/out/` |
+
+返回示例（含 output）：
 
 ```json
 {
-  "mcpServers": {
-    "nx-mcp": {
-      "command": "npx",
-      "args": ["-y", "nx-mcp-server"],
-      "env": {
-        "DASHSCOPE_API_KEY": "sk-你的key"
-      }
+  "success": true,
+  "mode": "formdata",
+  "items": [
+    {
+      "originalUrl": "E:/images/photo.png",
+      "compressedUrl": "https://qiniucdn.nxtici.cn/compressed/xxx.png",
+      "originalSize": 3156532,
+      "compressedSize": 397952,
+      "ratio": "87.4%",
+      "outputPath": "E:/images/photo.png",
+      "outputSize": 397952
     }
-  }
+  ],
+  "summary": { "total": 1, "success": 1, "failed": 0 },
+  "output": { "mode": "overwrite", "count": 1 }
 }
 ```
 
-### 方式三：源码安装
+---
 
-```bash
-git clone git@gitee.com:san_jing/nx-mcp-server.git
-cd nx-mcp-server
-npm install
-```
+## 快速开始
+
+### 方式一：魔搭 MCP 广场（推荐）
+
+在魔搭 MCP 广场搜索 **NX MCP Server**，一键同步到 Cherry Studio 或复制配置到其他客户端。
 
-客户端配置：
+### 方式二：npx 一键运行（Claude Code / 其他客户端）
 
 ```json
 {
   "mcpServers": {
     "nx-mcp": {
-      "command": "node",
-      "args": ["/你的路径/nx-mcp-server/src/index.js"],
+      "command": "npx",
+      "args": ["-y", "nx-mcp-server"],
       "env": {
-        "DASHSCOPE_API_KEY": "sk-你的key"
+        "NX_API_KEY": "your-key"
       }
     }
   }
 }
 ```
 
-## API Key
-
-智能生图（`generate_smart`）需要通义万相 API Key，四种传入方式按优先级排序：
-
-1. **调用时传参**：使用 `generate_smart` 时传入 `apiKey` 参数
-2. **MCP 客户端 env**：配置中设置 `DASHSCOPE_API_KEY`（见上方示例）
-3. **系统环境变量**：`export DASHSCOPE_API_KEY="sk-xxx"`
-4. **config.json**：项目根目录 `config.json` 中配置 `dashscope_api_key`
-
-> 其余 8 个本地工具无需 API Key，可直接使用。
+---
 
 ## 传输模式
 
-| 模式 | 环境变量 | 适用场景 |
-|------|---------|---------|
-| **Stdio**（默认） | 不设 | 本地 Claude Code、Cherry Studio |
-| **HTTP** | `MCP_TRANSPORT=http` | 魔搭云端托管、远程访问 |
-
-## 使用示例
+| 模式 | 环境变量 | body 限制 | 适用 |
+|------|---------|----------|------|
+| **Stdio**（默认） | 不设 | 无限制 | Claude Code、Cherry Studio 本地 |
+| **HTTP** | `MCP_TRANSPORT=http` | 50MB（JSON/FormData） | 云端托管 |
 
-### 智能生图
+HTTP 模式启动：
 
-```
-用 generate_smart 生成一张 prompt 为 "夕阳下的海边灯塔，水彩风格" 的图片
+```bash
+MCP_TRANSPORT=http MCP_PORT=3000 NX_API_KEY=your-key node src/index.js
+# → http://0.0.0.0:3000/mcp
+# → http://localhost:3000/health
 ```
 
-### 普通生图
+---
 
-```
-用 generate_basic 生成一张 800×400 深蓝色背景、中间白色文字 "Hello World" 的 banner
-```
+## 支持的图片格式
 
-### 图片拼接
+`png` `jpg` `jpeg` `bmp` `webp` `tga`
 
-```
-把这三张图片用 stitch_images 拼成 2 列的网格
-```
+---
 
-### 取色 + 水印
-
-```
-先 extract_colors 提取这张图的 5 个主色，再用 add_watermark 加文字水印，颜色用提取的第一个颜色
-```
+## 注意事项
 
-## 支持的客户端
+1. **远程 MCP 只能传 HTTP(S) 链接**，先上传到 CDN 再调用
+2. 本地 MCP 可传绝对路径，MCP Server 直接读磁盘（免上传）
+3. dataUrl 走 FormData 模式，HTTP body 限制 50MB，大图建议用本地路径
+4. 多张图片顺序处理，单张失败不影响其他
+5. 同步接口，超时 180 秒
+6. 压缩后返回七牛 CDN URL，可下载或配合 `output` 直接写文件
 
-- Cherry Studio（魔搭一键同步）
-- Claude Desktop / Claude Code
-- Cursor / VS Code
-- 通义灵码
-- 任何支持 MCP 协议的客户端
+---
 
 ## 项目结构
 
 ```
 src/
-├── index.js                # MCP Server 主入口
-├── providers/
-│   └── tongyi.js           # 通义万相 API
-├── tools/
-│   ├── smart.js            # 智能生图
-│   ├── basic.js            # 普通生图
-│   ├── qrcode.js           # 二维码
-│   ├── barcode.js          # 条形码
-│   ├── compress.js         # 图片压缩
-│   ├── convert.js          # 格式转换
-│   ├── stitch.js           # 图片拼接
-│   ├── colors.js           # 取色
-│   └── watermark.js        # 水印
-└── utils/
-    ├── output.js           # 文件输出
-    └── gradient.js         # 渐变背景
+├── index.js           # MCP Server 主入口（Stdio/HTTP 双模式）
+├── config.js          # 配置加载（config.json + 环境变量）
+├── nx-api.js          # 压缩 API 客户端（JSON/FormData 双模式 + 本地文件读取）
+└── tools/
+    ├── definitions.js # MCP 工具定义
+    └── handlers.js    # 工具处理函数
 ```
 
 ## 依赖
 
 - `@modelcontextprotocol/sdk` — MCP 协议
-- `sharp` — 高性能图片处理
-- `qrcode` — 二维码生成
-- `axios` — HTTP 请求
+- `express` — HTTP 传输模式的 body 解析（50MB 限制）
 
 ## License
 

package/config.json

@@ -1,7 +1,5 @@
 {
-  "dashscope_api_key": "",
-  "outputDir": "./output",
-  "defaultModel": "wanx-v1",
-  "defaultWidth": 1024,
-  "defaultHeight": 1024
+  "api": {
+    "baseUrl": "https://ai.nxtici.com"
+  }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nx-mcp-server",
-  "version": "1.0.4",
-  "description": "图像生成 MCP Server — 智能生图(万相API) + 本地图形工具集",
+  "version": "1.0.5",
+  "description": "NX MCP Server — 远程图片压缩 MCP 工具",
   "type": "module",
   "main": "src/index.js",
   "bin": {
@@ -9,26 +9,20 @@
   },
   "scripts": {
     "start": "node src/index.js",
-    "start:http": "cross-env MCP_TRANSPORT=http MCP_PORT=3000 node src/index.js",
+    "start:http": "MCP_TRANSPORT=http MCP_PORT=3000 node src/index.js",
     "dev": "node --watch src/index.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "sharp": "^0.33.0",
-    "qrcode": "^1.5.3",
-    "axios": "^1.7.0",
-    "express": "^4.19.0",
-    "zod": "^3.25.0"
+    "express": "^4.19.0"
   },
   "engines": {
     "node": ">=18.0.0"
   },
   "keywords": [
     "mcp",
-    "image-generation",
-    "qrcode",
-    "watermark",
-    "image-processing"
+    "image-compression",
+    "nx-image-api"
   ],
   "license": "MIT"
 }

package/src/config.js

@@ -0,0 +1,48 @@
+import {readFileSync} from 'fs';
+import {join,dirname} from 'path';
+import {fileURLToPath} from 'url';
+
+const __dirname=dirname(fileURLToPath(import.meta.url));
+const ROOT_DIR=join(__dirname,'..');
+
+let _config=null;
+
+// 加载 config.json
+function loadConfigFile(){
+  try{
+    const raw=readFileSync(join(ROOT_DIR,'config.json'),'utf-8');
+    return JSON.parse(raw);
+  }catch(_e){
+    return {};
+  }
+}
+
+// 获取配置（单例缓存）
+function getConfig(){
+  if(_config) return _config;
+
+  const fileConfig=loadConfigFile();
+
+  // API 配置
+  const apiBaseUrl=process.env.NX_API_BASE_URL
+    ||(fileConfig.api&&fileConfig.api.baseUrl)
+    ||'https://ai.nxtici.com';
+  const apiKey=process.env.NX_API_KEY||'';
+
+  if(!apiKey){
+    console.error('⚠ 未配置 API Key，请设置环境变量 NX_API_KEY。获取 Key 请联系微信 zhjian_2026');
+  }
+
+  _config={
+    api:{baseUrl:apiBaseUrl,apiKey},
+  };
+
+  return _config;
+}
+
+// 测试用：重置缓存
+function resetConfig(){
+  _config=null;
+}
+
+export {getConfig,resetConfig};