nx-mcp-server 1.0.8 → 1.0.9

package/README.md

@@ -173,6 +173,41 @@ MCP_TRANSPORT=http MCP_PORT=3000 NX_API_KEY=your-key node src/index.js
 
 ---
 
+## 错误响应
+
+失败时返回 `isError: true`，`content[0].text` 为 JSON 字符串：
+
+```json
+{
+  "error": "未配置 API Key",
+  "code": "MISSING_API_KEY",
+  "help": "请设置环境变量 NX_API_KEY 或传入 apiKey 参数…",
+  "doc": ""
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `error` | `string` | 错误描述 |
+| `code` | `string` | 错误码，用于客户端程序判断（如 `MISSING_API_KEY`、`NETWORK_ERROR`、`REQUEST_TIMEOUT`） |
+| `help` | `string` | 建议/帮助信息，可直接展示给用户 |
+| `doc` | `string` | 文档链接（可选） |
+
+**常见错误码：**
+
+| code | 说明 |
+|------|------|
+| `MISSING_API_KEY` | 未配置 API Key |
+| `MISSING_PARAMS` | 缺少 urls/files 参数 |
+| `FILE_NOT_FOUND` | 本地文件不存在 |
+| `DOWNLOAD_FAILED` | 远程图片下载失败 |
+| `NETWORK_ERROR` | 网络请求失败 |
+| `REQUEST_TIMEOUT` | 压缩请求超时 |
+| `API_AUTH_FAILED` | API Key 无效 |
+| `API_MISSING_AUTH` | 缺少认证头 |
+
+---
+
 ## 注意事项
 
 1. **远程 MCP 只能传 HTTP(S) 链接**，先上传到 CDN 再调用
@@ -190,6 +225,7 @@ MCP_TRANSPORT=http MCP_PORT=3000 NX_API_KEY=your-key node src/index.js
 src/
 ├── index.js           # MCP Server 主入口（Stdio/HTTP 双模式）
 ├── config.js          # 配置加载（config.json + 环境变量）
+├── errors.js          # 统一错误类（NxError：结构化 code/help/doc）
 ├── nx-api.js          # 压缩 API 客户端（JSON/FormData 双模式 + 本地文件读取）
 └── tools/
     ├── definitions.js # MCP 工具定义

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "nx-mcp-server",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "NX MCP Server — 远程图片压缩 MCP 工具",
   "type": "module",
   "main": "src/index.js",
   "bin": {
-    "nx-mcp": "./src/index.js"
+    "nx-mcp": "src/index.js"
   },
   "scripts": {
     "start": "node src/index.js",

package/src/config.js

@@ -29,10 +29,6 @@ function getConfig(){
     ||'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},
   };

package/src/errors.js

@@ -0,0 +1,24 @@
+// MCP 统一错误类 —— 附带结构化字段，客户端可解析展示
+
+class NxError extends Error{
+  constructor(message,{code,help,doc}={}){
+    super(message);
+    this.name='NxError';
+    this.code=code||'UNKNOWN';
+    this.help=help||'';
+    this.doc=doc||'';
+  }
+
+  // 序列化为 MCP content text（JSON 字符串）
+  toMcpText(){
+    const payload={
+      error:this.message,
+      code:this.code,
+      help:this.help,
+      doc:this.doc,
+    };
+    return JSON.stringify(payload);
+  }
+}
+
+export {NxError};

package/src/index.js

@@ -28,8 +28,10 @@ function createServer(){
         content:[{type:'text',text:JSON.stringify(result,null,2)}],
       };
     }catch(err){
+      // 结构化错误（NxError）→ JSON；普通 Error → 纯文本，兼容旧格式
+      const text=err.toMcpText?err.toMcpText():`错误: ${err.message}`;
       return {
-        content:[{type:'text',text:`错误: ${err.message}`}],
+        content:[{type:'text',text}],
         isError:true,
       };
     }
@@ -109,7 +111,7 @@ async function startHttp(){
   app.delete('/mcp',mcpDeleteHandler);
 
   // 全局错误处理 — 捕获 async handler 的异常
-  app.use((err,_req,res)=>{
+  app.use((err,_req,res,_next)=>{
     console.error('[MCP HTTP Error]',err.message);
     res.status(500).json({jsonrpc:'2.0',error:{code:-32603,message:err.message||'Internal error'},id:null});
   });

package/src/nx-api.js

@@ -1,4 +1,5 @@
 import {getConfig} from './config.js';
+import {NxError} from './errors.js';
 import {readFileSync,existsSync,writeFileSync,mkdirSync} from 'fs';
 import {basename,dirname,join} from 'path';
 
@@ -11,7 +12,7 @@ function isFilePath(str){
 async function loadImageBuffer(src){
   // 本地文件路径
   if(isFilePath(src)){
-    if(!existsSync(src)) throw new Error(`文件不存在: ${src}`);
+    if(!existsSync(src)) throw new NxError(`文件不存在: ${src}`,{code:'FILE_NOT_FOUND'});
     const buf=readFileSync(src);
     const ext=basename(src).split('.').pop()||'png';
     const mime=ext==='jpg'?'jpeg':ext;
@@ -20,7 +21,7 @@ async function loadImageBuffer(src){
   // data URL
   if(src.startsWith('data:')){
     const [head,base64]=src.split(',');
-    if(!base64) throw new Error('data URL 格式无效');
+    if(!base64) throw new NxError('data URL 格式无效',{code:'INVALID_DATA_URL'});
     const mime=head.match(/:(.*?);/)?.[1]||'image/png';
     const ext=(mime.split('/')[1]||'png').replace('jpeg','jpg');
     const buf=Buffer.from(base64,'base64');
@@ -28,7 +29,7 @@ async function loadImageBuffer(src){
   }
   // HTTP(S) URL
   const res=await fetch(src);
-  if(!res.ok) throw new Error(`下载失败 HTTP ${res.status}`);
+  if(!res.ok) throw new NxError(`下载失败 HTTP ${res.status}`,{code:'DOWNLOAD_FAILED'});
   const buf=Buffer.from(await res.arrayBuffer());
   const ext=src.split('.').pop().split('?')[0]||'png';
   const contentType=res.headers.get('content-type')||'';
@@ -40,7 +41,7 @@ async function loadImageBuffer(src){
 // 下载 CDN 压缩图并写入本地
 async function downloadToFile(cdnUrl,localPath){
   const res=await fetch(cdnUrl);
-  if(!res.ok) throw new Error(`下载 CDN 失败 HTTP ${res.status}`);
+  if(!res.ok) throw new NxError(`下载 CDN 失败 HTTP ${res.status}`,{code:'CDN_DOWNLOAD_FAILED'});
   const buf=Buffer.from(await res.arrayBuffer());
   const dir=dirname(localPath);
   if(!existsSync(dir)) mkdirSync(dir,{recursive:true});
@@ -65,12 +66,15 @@ async function compressImage({urls=[],files=[],quality=90,output=null,apiKey=nul
   // API Key：参数传入 > 环境变量 NX_API_KEY
   const key=apiKey||api.apiKey;
   if(!key){
-    throw new Error('未配置 API Key，请设置环境变量 NX_API_KEY 或传入 apiKey 参数');
+    throw new NxError('未配置 API Key',{
+      code:'MISSING_API_KEY',
+      help:'请设置环境变量 NX_API_KEY 或传入 apiKey 参数。获取 Key 请联系微信 zhjian_2026。',
+    });
   }
 
   // 合并所有来源，保持顺序和原始引用
   const sources=[...urls,...files];
-  if(!sources.length) throw new Error('请提供 urls 或 files 参数，至少需要一个');
+  if(!sources.length) throw new NxError('请提供 urls 或 files 参数，至少需要一个',{code:'MISSING_PARAMS'});
 
   // 判断请求模式：全是 HTTP URL → JSON 模式；否则 → FormData 模式
   const allHttp=sources.every(u=>isHttpUrl(u));
@@ -100,14 +104,15 @@ async function compressImage({urls=[],files=[],quality=90,output=null,apiKey=nul
         const {buffer,name,mime}=await loadImageBuffer(src);
         return {blob:new Blob([buffer],{type:mime}),name,src};
       }catch(e){
-        throw new Error(`加载 ${src} 失败: ${e.message}`);
+        throw new NxError(`加载图片失败: ${e.message}`,{code:'LOAD_IMAGE_FAILED'});
       }
     }));
     loaded.forEach((r)=>{
       if(r.status==='fulfilled'){
         fd.append('files',r.value.blob,r.value.name);
       }else{
-        throw new Error(r.reason.message);
+        // 保留原始 NxError 结构，普通 Error 则包装
+        throw r.reason instanceof NxError?r.reason:new NxError(r.reason.message,{code:'LOAD_IMAGE_FAILED'});
       }
     });
     fd.append('quality',String(quality));
@@ -121,9 +126,9 @@ async function compressImage({urls=[],files=[],quality=90,output=null,apiKey=nul
   }catch(err){
     clearTimeout(timer);
     if(err.name==='AbortError'){
-      throw new Error('压缩请求超时 (180s)，图片可能过大，建议换小图重试');
+      throw new NxError('压缩请求超时 (180s)',{code:'REQUEST_TIMEOUT',help:'图片可能过大，建议换小图重试'});
     }
-    throw new Error(`网络请求失败: ${err.message}`);
+    throw new NxError('网络请求失败',{code:'NETWORK_ERROR',help:err.message});
   }
   clearTimeout(timer);
 
@@ -138,7 +143,7 @@ async function compressImage({urls=[],files=[],quality=90,output=null,apiKey=nul
       missing_params:'缺少 urls 或 files 参数',
     };
     const hint=errMap[errType]||data.message||'未知错误';
-    throw new Error(`压缩API错误 [${errType}]: ${hint}`);
+    throw new NxError(hint,{code:`API_${errType.toUpperCase()}`});
   }
 
   const rawItems=(data.data&&data.data.items)||[];