@vrs-soft/wecom-aibot-mcp 1.0.2 → 1.0.4

package/README.md

@@ -68,16 +68,59 @@ PermissionRequest Hook 拦截
 
 ### 前置要求
 
-- Node.js >= 18
+- **Node.js >= 18**（必需）
 - 企业微信账号（有创建机器人权限）
 - Claude Code 已安装
 
+### 安装 Node.js
+
+**检查版本**：
+```bash
+node --version
+# 输出应 >= v18.0.0
+```
+
+**安装方式**：
+
+**macOS**：
+```bash
+# 使用 Homebrew
+brew install node
+
+# 或使用 nvm（推荐，可管理多版本）
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+nvm install 18
+nvm use 18
+```
+
+**Windows**：
+```bash
+# 使用 winget
+winget install OpenJS.NodeJS.LTS
+
+# 或下载安装包：https://nodejs.org/
+```
+
+**Linux**：
+```bash
+# Ubuntu/Debian
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# 或使用 nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+nvm install 18
+nvm use 18
+```
+
 ### 方式一：npx 直接运行（推荐）
 
 ```bash
 npx @vrs-soft/wecom-aibot-mcp
 ```
 
+运行后会自动启动配置向导，配置完成后自动退出。
+
 ### 方式二：全局安装
 
 ```bash
@@ -345,6 +388,29 @@ Claude：（设置定时任务）
 
 ## 故障排查
 
+### 认证失败（错误码 40058）
+
+**可能原因**：
+- 机器人未授权
+- Bot ID 或 Secret 配置错误
+- 新建机器人需要等待同步时间
+
+**解决方法**：
+```
+1. 新建机器人需要等待约 2 分钟同步时间，请稍后再试
+
+2. 完成机器人授权（任选其一）：
+   • 在电脑端企业微信APP中打开：机器人详情 → 可使用权限 → 授权
+   • 打开浏览器访问授权页面，使用手机企业微信扫码：
+     https://work.weixin.qq.com/ai/aiHelper/authorizationPage?str_aibotid={BotID}&type=6&from=chat&forceInnerBrowser=1
+
+3. 确认 Bot ID 和 Secret 是否正确：
+   npx @vrs-soft/wecom-aibot-mcp --status
+
+4. 如需重新配置：
+   npx @vrs-soft/wecom-aibot-mcp --config
+```
+
 ### 无法收到消息
 
 **可能原因**：
@@ -395,6 +461,72 @@ ls ~/.wecom-aibot-mcp/port-*
 rm ~/.wecom-aibot-mcp/port-*
 ```
 
+## 卸载
+
+如需完全卸载，运行：
+
+```bash
+npx @vrs-soft/wecom-aibot-mcp --uninstall
+```
+
+这会删除：
+- 配置文件：`~/.wecom-aibot-mcp/config.json`
+- MCP 配置：`~/.claude.json` 中的 `wecom-aibot` 条目
+- Hook 脚本：`~/.wecom-aibot-mcp/permission-hook.sh`
+- Hook 配置：`~/.claude/settings.local.json` 中的 PermissionRequest hook
+- Skill 文件：`~/.claude/skills/headless-mode/`
+
+卸载后如需重新安装：
+
+```bash
+npx @vrs-soft/wecom-aibot-mcp --config
+```
+
+## 修改和增加 Bot
+
+### 修改现有 Bot 配置
+
+如果需要更换机器人或修改目标用户：
+
+```bash
+npx @vrs-soft/wecom-aibot-mcp --config
+```
+
+这会重新启动配置向导，让你输入新的 Bot ID、Secret 和目标用户 ID。
+
+### 增加多个 Bot（多用户场景）
+
+每个用户可以使用独立的机器人，在 `~/.claude.json` 中配置多个 MCP Server 实例：
+
+```json
+{
+  "mcpServers": {
+    "wecom-aibot-zhangsan": {
+      "command": "npx",
+      "args": ["@vrs-soft/wecom-aibot-mcp"],
+      "env": {
+        "WECOM_BOT_ID": "bot_zhangsan",
+        "WECOM_SECRET": "secret_zhangsan",
+        "WECOM_TARGET_USER": "zhangsan"
+      }
+    },
+    "wecom-aibot-lisi": {
+      "command": "npx",
+      "args": ["@vrs-soft/wecom-aibot-mcp"],
+      "env": {
+        "WECOM_BOT_ID": "bot_lisi",
+        "WECOM_SECRET": "secret_lisi",
+        "WECOM_TARGET_USER": "lisi"
+      }
+    }
+  }
+}
+```
+
+使用环境变量配置时，每个实例自动独立运行，无需额外的配置文件。
+
+> ⚠️ 注意：同一个机器人同时只能保持一个 WebSocket 长连接，不要在多个实例中使用相同的 Bot ID。
+
 ## 安全建议
 
 1. **保护凭证**：Bot ID 和 Secret 不要提交到代码仓库

package/dist/bin.js

@@ -4,13 +4,30 @@
  *
  * npx 运行入口
  */
-import { getOrInitConfig, runConfigWizard, loadConfig, ensureHookInstalled } from './config-wizard.js';
+import * as readline from 'readline';
+import { runConfigWizard, loadConfig, deleteConfig, uninstall, ensureHookInstalled } from './config-wizard.js';
 import { initClient } from './client.js';
 import { registerTools } from './tools/index.js';
 import { startHttpServer } from './http-server.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 const VERSION = '1.0.0';
+// 等待连接验证（最多等待 10 秒）
+async function waitForConnection(client, timeoutMs = 10000) {
+    return new Promise((resolve) => {
+        const startTime = Date.now();
+        const checkInterval = setInterval(() => {
+            if (client.isConnected()) {
+                clearInterval(checkInterval);
+                resolve(true);
+            }
+            else if (Date.now() - startTime > timeoutMs) {
+                clearInterval(checkInterval);
+                resolve(false);
+            }
+        }, 500);
+    });
+}
 function showHelp() {
     console.log(`
 企业微信智能机器人 MCP 服务 v${VERSION}
@@ -26,6 +43,7 @@ function showHelp() {
   --version, -v   显示版本号
   --config        重新配置（修改 Bot ID / Secret / 目标用户）
   --status        显示当前配置状态
+  --uninstall     卸载并删除所有配置（包括 MCP 配置、hook、skill）
 
 配置方式（按优先级）:
   1. 环境变量（推荐多实例场景）:
@@ -111,7 +129,12 @@ async function main() {
         showStatus();
         process.exit(0);
     }
+    if (args.includes('--uninstall')) {
+        uninstall();
+        process.exit(0);
+    }
     const reconfig = args.includes('--config');
+    const isInteractive = process.stdin.isTTY; // 是否为用户交互模式
     console.log('');
     console.log('  ╔════════════════════════════════════════════════════════╗');
     console.log(`  ║   企业微信智能机器人 MCP 服务 v${VERSION}                   ║`);
@@ -120,12 +143,30 @@ async function main() {
     console.log('');
     // 获取或初始化配置
     let config;
+    let ranWizard = false; // 是否运行了配置向导
     if (reconfig) {
         console.log('[config] 重新配置模式\n');
         config = await runConfigWizard();
+        ranWizard = true;
     }
     else {
-        config = await getOrInitConfig();
+        // 检查是否已有配置
+        const savedConfig = loadConfig();
+        if (savedConfig && savedConfig.botId && savedConfig.secret && savedConfig.targetUserId) {
+            config = savedConfig;
+        }
+        else if (isInteractive) {
+            // TTY 模式下没有配置，启动配置向导
+            console.log('[config] 未找到配置，启动配置向导...\n');
+            config = await runConfigWizard();
+            ranWizard = true;
+        }
+        else {
+            // 非 TTY 模式（MCP stdio），必须有配置
+            console.error('[config] 未找到配置，且当前为非交互模式。');
+            console.error('[config] 请在终端运行: npx @vrs-soft/wecom-aibot-mcp --config');
+            process.exit(1);
+        }
     }
     // 确保 hook 已安装（幂等，每次启动检查）
     ensureHookInstalled();
@@ -133,6 +174,51 @@ async function main() {
     console.log(`[mcp] 初始化企业微信客户端...`);
     console.log(`[mcp] 默认目标用户: ${config.targetUserId}`);
     const wecomClient = initClient(config.botId, config.secret, config.targetUserId);
+    // 等待连接验证
+    console.log('[mcp] 等待连接验证...');
+    const connected = await waitForConnection(wecomClient, 10000);
+    if (!connected) {
+        console.log('[mcp] 连接失败，可能是配置错误或机器人未授权');
+        console.log('[mcp] 请检查上面的错误提示，修复后重新配置');
+        // 删除无效配置，让用户重新输入
+        deleteConfig();
+        if (isInteractive) {
+            // TTY 模式询问是否重新配置
+            console.log('\n是否重新配置？(Y/n): ');
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            const answer = await new Promise((resolve) => {
+                rl.question('', (a) => resolve(a.trim().toLowerCase()));
+            });
+            rl.close();
+            if (answer !== 'n') {
+                console.log('\n[mcp] 启动重新配置...\n');
+                config = await runConfigWizard();
+                const newClient = initClient(config.botId, config.secret, config.targetUserId);
+                const newConnected = await waitForConnection(newClient, 10000);
+                if (!newConnected) {
+                    console.log('[mcp] 连接仍然失败，请稍后再试（新建机器人需等待约 2 分钟同步）');
+                    deleteConfig();
+                    process.exit(1);
+                }
+                // 连接成功，如果是交互模式则退出
+                console.log('\n[mcp] ✅ 配置成功！');
+                console.log('[mcp] 请重启 Claude Code 以加载 MCP 服务\n');
+                process.exit(0);
+            }
+        }
+        process.exit(1);
+    }
+    // 连接成功
+    if (isInteractive && (ranWizard || reconfig)) {
+        // 用户手动运行配置向导，配置成功后退出
+        console.log('\n[mcp] ✅ 配置成功！');
+        console.log('[mcp] 请重启 Claude Code 以加载 MCP 服务\n');
+        process.exit(0);
+    }
+    // 非 TTY 模式（MCP stdio），启动 MCP Server
     // 启动本地 HTTP 服务（用于 hooks 审批）
     await startHttpServer(wecomClient);
     // 创建 MCP Server
@@ -147,10 +233,20 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // 定期清理过期消息
-    setInterval(() => {
+    const cleanupInterval = setInterval(() => {
         wecomClient.cleanupMessages();
     }, 60000);
     console.log('[mcp] MCP Server 已就绪');
+    // 退出处理：清理资源
+    const gracefulShutdown = () => {
+        console.log('[mcp] 正在关闭...');
+        clearInterval(cleanupInterval);
+        wecomClient.disconnect();
+        process.exit(0);
+    };
+    // 监听进程信号
+    process.on('SIGINT', gracefulShutdown);
+    process.on('SIGTERM', gracefulShutdown);
 }
 main().catch((err) => {
     console.error('[mcp] 启动失败:', err);

package/dist/client.d.ts

@@ -19,7 +19,9 @@ declare class WecomClient {
     private messages;
     private connected;
     private targetUserId;
+    private botId;
     constructor(botId: string, secret: string, targetUserId: string);
+    getAuthUrl(): string;
     private setupEventHandlers;
     private handleMessage;
     private handleApprovalResponse;

package/dist/client.js

@@ -11,7 +11,9 @@ class WecomClient {
     messages = [];
     connected = false;
     targetUserId;
+    botId; // 保存 botId 用于生成授权 URL
     constructor(botId, secret, targetUserId) {
+        this.botId = botId;
         this.targetUserId = targetUserId;
         this.wsClient = new AiBot.WSClient({
             botId,
@@ -21,6 +23,10 @@ class WecomClient {
         });
         this.setupEventHandlers();
     }
+    // 生成授权页面 URL
+    getAuthUrl() {
+        return `https://work.weixin.qq.com/ai/aiHelper/authorizationPage?str_aibotid=${this.botId}&type=6&from=chat&forceInnerBrowser=1`;
+    }
     setupEventHandlers() {
         this.wsClient.on('connected', () => {
             console.log('[wecom] WebSocket 连接已建立');
@@ -38,6 +44,19 @@ class WecomClient {
         });
         this.wsClient.on('error', (err) => {
             console.error(`[wecom] 错误: ${err.message}`);
+            // 检测授权相关错误（40058: invalid Request Parameter）
+            if (err.message.includes('40058') || err.message.includes('invalid Request Parameter')) {
+                console.log('');
+                console.log('  ⚠️  机器人未授权或配置有误，请检查以下事项：');
+                console.log('');
+                console.log('  1. 新建机器人需要等待约 2 分钟同步时间，请稍后再试');
+                console.log('  2. 确认 Bot ID 和 Secret 是否正确');
+                console.log('  3. 完成机器人授权（任选其一）：');
+                console.log('     • 在电脑端企业微信APP中打开：机器人详情 → 可使用权限 → 授权');
+                console.log('     • 打开浏览器访问以下地址，使用手机企业微信扫码授权：');
+                console.log(`       ${this.getAuthUrl()}`);
+                console.log('');
+            }
         });
         // 监听所有消息（存储到队列）
         this.wsClient.on('message', (frame) => {

package/dist/config-wizard.d.ts

@@ -5,6 +5,11 @@ export interface WecomConfig {
     targetUserName?: string;
 }
 export declare function loadConfig(): WecomConfig | null;
+export declare function deleteConfig(): void;
+export declare function deleteMcpConfig(): void;
+export declare function deleteHook(): void;
+export declare function deleteSkills(): void;
+export declare function uninstall(): void;
 export declare function ensureHookInstalled(): void;
 export declare function saveConfig(config: WecomConfig): void;
 /**

package/dist/config-wizard.js

@@ -43,6 +43,108 @@ export function loadConfig() {
     }
     return null;
 }
+// 删除已保存的配置（连接失败时让用户重新输入）
+export function deleteConfig() {
+    try {
+        if (fs.existsSync(CONFIG_FILE)) {
+            fs.unlinkSync(CONFIG_FILE);
+            console.log('[config] 已删除配置文件');
+        }
+    }
+    catch (err) {
+        console.error('[config] 删除配置失败:', err);
+    }
+}
+// 删除 MCP Server 配置（从 ~/.claude.json）
+export function deleteMcpConfig() {
+    try {
+        if (fs.existsSync(CLAUDE_CONFIG_FILE)) {
+            const content = fs.readFileSync(CLAUDE_CONFIG_FILE, 'utf-8');
+            const claudeConfig = JSON.parse(content);
+            if (claudeConfig.mcpServers && claudeConfig.mcpServers['wecom-aibot']) {
+                delete claudeConfig.mcpServers['wecom-aibot'];
+                fs.writeFileSync(CLAUDE_CONFIG_FILE, JSON.stringify(claudeConfig, null, 2));
+                console.log('[config] 已从 ~/.claude.json 删除 wecom-aibot MCP 配置');
+            }
+            else {
+                console.log('[config] ~/.claude.json 中未找到 wecom-aibot 配置');
+            }
+        }
+    }
+    catch (err) {
+        console.error('[config] 删除 MCP 配置失败:', err);
+    }
+}
+// 删除 PermissionRequest hook（从 ~/.claude/settings.local.json）
+export function deleteHook() {
+    try {
+        if (fs.existsSync(CLAUDE_SETTINGS_FILE)) {
+            const content = fs.readFileSync(CLAUDE_SETTINGS_FILE, 'utf-8');
+            const settings = JSON.parse(content);
+            if (settings.hooks && settings.hooks['PermissionRequest']) {
+                // 只删除 wecom-aibot 相关的 hook
+                settings.hooks['PermissionRequest'] = settings.hooks['PermissionRequest'].filter((hook) => !hook.hooks?.some?.((h) => h.command?.includes?.('wecom-aibot-mcp')));
+                if (settings.hooks['PermissionRequest'].length === 0) {
+                    delete settings.hooks['PermissionRequest'];
+                }
+                fs.writeFileSync(CLAUDE_SETTINGS_FILE, JSON.stringify(settings, null, 2));
+                console.log('[config] 已删除 PermissionRequest hook');
+            }
+            // 删除 hook 脚本文件
+            if (fs.existsSync(HOOK_SCRIPT_PATH)) {
+                fs.unlinkSync(HOOK_SCRIPT_PATH);
+                console.log('[config] 已删除 hook 脚本文件');
+            }
+        }
+    }
+    catch (err) {
+        console.error('[config] 删除 hook 失败:', err);
+    }
+}
+// 删除 skill 文件
+export function deleteSkills() {
+    try {
+        const skillDir = path.join(os.homedir(), '.claude', 'skills', 'headless-mode');
+        if (fs.existsSync(skillDir)) {
+            fs.rmSync(skillDir, { recursive: true });
+            console.log('[config] 已删除 skill 文件');
+        }
+    }
+    catch (err) {
+        console.error('[config] 删除 skill 失败:', err);
+    }
+}
+// 完全卸载（删除所有相关配置）
+export function uninstall() {
+    console.log('\n[config] 开始卸载 wecom-aibot-mcp...\n');
+    deleteConfig();
+    deleteMcpConfig();
+    deleteHook();
+    deleteSkills();
+    // 删除配置目录
+    if (fs.existsSync(CONFIG_DIR)) {
+        try {
+            // 删除所有 port-* 和 headless-* 文件
+            const files = fs.readdirSync(CONFIG_DIR);
+            for (const file of files) {
+                if (file.startsWith('port-') || file.startsWith('headless-')) {
+                    fs.unlinkSync(path.join(CONFIG_DIR, file));
+                }
+            }
+            // 如果目录为空，删除目录
+            const remainingFiles = fs.readdirSync(CONFIG_DIR);
+            if (remainingFiles.length === 0) {
+                fs.rmSync(CONFIG_DIR);
+                console.log('[config] 已删除配置目录');
+            }
+        }
+        catch (err) {
+            console.error('[config] 删除配置目录失败:', err);
+        }
+    }
+    console.log('\n[config] 卸载完成');
+    console.log('[config] 如需重新安装，请运行: npx @vrs-soft/wecom-aibot-mcp --config\n');
+}
 // 生成并写入 hook 脚本（多实例 + headless 模式支持）
 function writeHookScript() {
     const script = `#!/bin/bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrs-soft/wecom-aibot-mcp",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "企业微信智能机器人 MCP 服务 - Claude Code 审批通道",
   "type": "module",
   "main": "dist/index.js",