weixin-mcp 1.0.0

package/README.md

@@ -0,0 +1,168 @@
+# weixin-mcp
+
+`weixin-mcp` 是一个基于 MCP 的微信服务端封装，复用 OpenClaw weixin 插件保存的账号 token，把微信能力暴露给 Claude Desktop 或其他 MCP 客户端。
+
+## 功能
+
+- 发送微信文本消息
+- 获取联系人列表
+- 拉取新消息
+- 查询聊天历史
+- 支持复用 OpenClaw weixin 插件已有登录态
+- 支持独立扫码登录
+
+## 安装
+
+### 方式 1：直接用 `npx`
+
+```bash
+npx weixin-mcp
+```
+
+如果你只想执行扫码登录：
+
+```bash
+npx weixin-mcp weixin-login
+```
+
+更稳妥的做法是先安装到本地或全局，再运行下面的脚本。
+
+### 方式 2：`npm install`
+
+```bash
+npm install
+npm run build
+```
+
+构建后可用以下命令：
+
+```bash
+npm start
+npm run login
+```
+
+## 使用方式
+
+### 场景 A：已经安装 OpenClaw weixin 插件
+
+如果你已经通过 OpenClaw weixin 插件登录过微信，并且本地已有 token 文件：
+
+```bash
+npm start
+```
+
+默认会从下面目录读取账号信息：
+
+```bash
+~/.openclaw/openclaw-weixin/accounts/
+```
+
+如果目录下有多个账号，可通过环境变量 `WEIXIN_ACCOUNT_ID` 指定。
+
+### 场景 B：独立使用
+
+如果你没有 OpenClaw weixin 插件，或者想单独给 `weixin-mcp` 登录：
+
+```bash
+npm run login
+```
+
+终端会显示二维码，扫码确认后会把 token 保存到本地。完成后启动 MCP server：
+
+```bash
+npm start
+```
+
+## Claude Desktop 集成
+
+在 Claude Desktop 的 `claude_desktop_config.json` 中加入：
+
+```json
+{
+  "mcpServers": {
+    "weixin": {
+      "command": "node",
+      "args": ["/absolute/path/to/weixin-mcp/dist/index.js"],
+      "env": {
+        "OPENCLAW_STATE_DIR": "/Users/yourname/.openclaw",
+        "WEIXIN_ACCOUNT_ID": "your-account-id"
+      }
+    }
+  }
+}
+```
+
+如果你是通过 npm 包安装，也可以直接用：
+
+```json
+{
+  "mcpServers": {
+    "weixin": {
+      "command": "npx",
+      "args": ["weixin-mcp"],
+      "env": {
+        "OPENCLAW_STATE_DIR": "/Users/yourname/.openclaw"
+      }
+    }
+  }
+}
+```
+
+修改配置后重启 Claude Desktop。
+
+## 工具说明
+
+| 工具名 | 说明 | 主要参数 |
+| --- | --- | --- |
+| `weixin_send` | 发送文本消息 | `to`, `text` |
+| `weixin_get_contacts` | 获取联系人列表 | 无 |
+| `weixin_poll_messages` | 拉取新消息 | `since_ts` 可选，毫秒时间戳 |
+| `weixin_get_history` | 获取与某个联系人的聊天历史 | `to`, `limit` |
+
+## 环境变量
+
+| 变量名 | 默认值 | 说明 |
+| --- | --- | --- |
+| `OPENCLAW_STATE_DIR` | `~/.openclaw` | OpenClaw 状态目录，账号文件路径会解析为 `${OPENCLAW_STATE_DIR}/openclaw-weixin/accounts/` |
+| `WEIXIN_ACCOUNT_ID` | 账号目录中的第一个账号 | 指定要使用的账号 ID，对应 `accounts/<accountId>.json` |
+
+兼容性说明：
+
+- `src/index.ts` 仍兼容读取旧变量 `CLAWDBOT_STATE_DIR`
+- 若 token 失效，工具会返回清晰错误并提示重新执行 `npm run login`
+
+## 常见问题
+
+### 1. 提示找不到账号
+
+先确认以下目录下是否存在 `*.json`：
+
+```bash
+~/.openclaw/openclaw-weixin/accounts/
+```
+
+如果没有，执行：
+
+```bash
+npm run login
+```
+
+### 2. 提示 token 过期或鉴权失败
+
+重新扫码登录：
+
+```bash
+npm run login
+```
+
+### 3. 网络偶发失败
+
+服务端会对网络错误自动重试 1 次。如果仍失败，请检查网络连接或微信接口可达性。
+
+## 开发
+
+```bash
+npm install
+npm run build
+npm test
+```

package/dist/api.d.ts

@@ -0,0 +1,13 @@
+export declare const DEFAULT_BASE_URL = "https://ilinkai.weixin.qq.com";
+export declare class WeixinAuthError extends Error {
+    constructor(message?: string);
+}
+export declare class WeixinNetworkError extends Error {
+    constructor(message: string);
+}
+export declare function generateClientId(): string;
+export declare function weixinRequest(requestPath: string, body: unknown, token: string, baseUrl?: string, retries?: number): Promise<unknown>;
+export declare function sendTextMessage(to: string, text: string, token: string, baseUrl: string): Promise<unknown>;
+export declare function getContacts(token: string, baseUrl: string): Promise<unknown>;
+export declare function pollMessages(token: string, baseUrl: string, sinceTs?: number): Promise<unknown>;
+export declare function getChatHistory(to: string, limit: number, token: string, baseUrl: string): Promise<unknown>;

package/dist/api.js

@@ -0,0 +1,90 @@
+import crypto from "node:crypto";
+export const DEFAULT_BASE_URL = "https://ilinkai.weixin.qq.com";
+const AUTH_ERROR_STATUSES = new Set([401, 403]);
+export class WeixinAuthError extends Error {
+    constructor(message = "Authentication failed. Run npm run login to re-authenticate.") {
+        super(message);
+        this.name = "WeixinAuthError";
+    }
+}
+export class WeixinNetworkError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WeixinNetworkError";
+    }
+}
+export function generateClientId() {
+    return `openclaw-weixin-mcp-${crypto.randomUUID().replace(/-/g, "").slice(0, 16)}`;
+}
+async function parseErrorResponse(res) {
+    try {
+        const text = await res.text();
+        return text.trim() || `HTTP ${res.status}`;
+    }
+    catch {
+        return `HTTP ${res.status}`;
+    }
+}
+function isTransientNetworkError(error) {
+    return error instanceof TypeError || error instanceof WeixinNetworkError;
+}
+export async function weixinRequest(requestPath, body, token, baseUrl = DEFAULT_BASE_URL, retries = 1) {
+    const url = `${baseUrl}${requestPath}`;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            const res = await fetch(url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${token}`,
+                },
+                body: JSON.stringify(body),
+            });
+            if (AUTH_ERROR_STATUSES.has(res.status)) {
+                throw new WeixinAuthError();
+            }
+            if (!res.ok) {
+                const message = await parseErrorResponse(res);
+                throw new Error(`Weixin API error ${res.status}: ${message}`);
+            }
+            return res.json();
+        }
+        catch (error) {
+            if (error instanceof WeixinAuthError) {
+                throw error;
+            }
+            if (isTransientNetworkError(error) && attempt < retries) {
+                continue;
+            }
+            if (isTransientNetworkError(error)) {
+                throw new WeixinNetworkError(error instanceof Error ? error.message : "Network request failed");
+            }
+            throw error;
+        }
+    }
+    throw new WeixinNetworkError("Network request failed");
+}
+export async function sendTextMessage(to, text, token, baseUrl) {
+    return weixinRequest("/v1/message/send", {
+        msg: {
+            from_user_id: "",
+            to_user_id: to,
+            client_id: generateClientId(),
+            message_type: 2,
+            message_state: 2,
+            item_list: [{ type: 1, text_item: { text } }],
+        },
+    }, token, baseUrl);
+}
+export async function getContacts(token, baseUrl) {
+    return weixinRequest("/v1/contacts/list", { page_size: 50 }, token, baseUrl);
+}
+export async function pollMessages(token, baseUrl, sinceTs) {
+    return weixinRequest("/v1/updates/get", {
+        timeout_ms: 5000,
+        ...(sinceTs ? { since_ts: sinceTs } : {}),
+    }, token, baseUrl);
+}
+export async function getChatHistory(to, limit, token, baseUrl) {
+    return weixinRequest("/v1/message/history", { to_user_id: to, limit }, token, baseUrl);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * WeChat MCP Server
+ * Exposes WeChat messaging as MCP tools, reusing token from OpenClaw weixin plugin.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+/**
+ * WeChat MCP Server
+ * Exposes WeChat messaging as MCP tools, reusing token from OpenClaw weixin plugin.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { DEFAULT_BASE_URL, getChatHistory, getContacts, pollMessages, sendTextMessage, WeixinAuthError, WeixinNetworkError, } from "./api.js";
+// ── Auth / config ──────────────────────────────────────────────────────────
+const STATE_DIR = process.env.OPENCLAW_STATE_DIR?.trim() ||
+    process.env.CLAWDBOT_STATE_DIR?.trim() ||
+    path.join(os.homedir(), ".openclaw");
+const WEIXIN_DIR = path.join(STATE_DIR, "openclaw-weixin", "accounts");
+function loadAccount() {
+    const files = fs.readdirSync(WEIXIN_DIR).filter((f) => f.endsWith(".json") && !f.endsWith(".sync.json"));
+    if (files.length === 0)
+        throw new Error("No WeChat account found. Run: npx @tencent-weixin/openclaw-weixin-cli install");
+    // Pick the first (or explicitly set) account
+    const accountId = process.env.WEIXIN_ACCOUNT_ID ?? files[0].replace(".json", "");
+    const filePath = path.join(WEIXIN_DIR, `${accountId}.json`);
+    const data = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    if (!data.token)
+        throw new Error(`No token for account ${accountId}. Re-run QR login.`);
+    return { ...data, accountId };
+}
+// ── Weixin API ─────────────────────────────────────────────────────────────
+function assertNonEmptyString(value, field) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`Invalid argument "${field}": must be a non-empty string`);
+    }
+    return value.trim();
+}
+function formatToolError(error) {
+    if (error instanceof WeixinAuthError) {
+        return error.message;
+    }
+    if (error instanceof WeixinNetworkError) {
+        return `Network error while calling Weixin API: ${error.message}`;
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+// ── MCP Server ─────────────────────────────────────────────────────────────
+const server = new Server({ name: "weixin-mcp", version: "1.0.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "weixin_send",
+            description: "Send a WeChat message to a user (by user ID or OpenId)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    to: { type: "string", description: "Recipient user ID / OpenId" },
+                    text: { type: "string", description: "Message text to send" },
+                },
+                required: ["to", "text"],
+            },
+        },
+        {
+            name: "weixin_get_contacts",
+            description: "List WeChat contacts",
+            inputSchema: { type: "object", properties: {} },
+        },
+        {
+            name: "weixin_poll_messages",
+            description: "Poll for new WeChat messages since a timestamp",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    since_ts: { type: "number", description: "Unix timestamp in ms (optional)" },
+                },
+            },
+        },
+        {
+            name: "weixin_get_history",
+            description: "Get chat history with a WeChat contact",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    to: { type: "string", description: "Contact user ID / OpenId" },
+                    limit: { type: "number", description: "Number of messages (default 20)" },
+                },
+                required: ["to"],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const account = loadAccount();
+    const { token, baseUrl = DEFAULT_BASE_URL } = account;
+    const { name, arguments: args } = req.params;
+    try {
+        let result;
+        if (name === "weixin_send") {
+            const { to, text } = (args ?? {});
+            const validatedTo = assertNonEmptyString(to, "to");
+            const validatedText = assertNonEmptyString(text, "text");
+            result = await sendTextMessage(validatedTo, validatedText, token, baseUrl);
+        }
+        else if (name === "weixin_get_contacts") {
+            result = await getContacts(token, baseUrl);
+        }
+        else if (name === "weixin_poll_messages") {
+            const { since_ts } = (args ?? {});
+            result = await pollMessages(token, baseUrl, since_ts);
+        }
+        else if (name === "weixin_get_history") {
+            const { to, limit = 20 } = (args ?? {});
+            const validatedTo = assertNonEmptyString(to, "to");
+            result = await getChatHistory(validatedTo, limit, token, baseUrl);
+        }
+        else {
+            throw new Error(`Unknown tool: ${name}`);
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Error: ${formatToolError(err)}` }],
+            isError: true,
+        };
+    }
+});
+// ── Start ──────────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("WeChat MCP server running on stdio");

package/dist/login.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * weixin-login — standalone QR login for weixin-mcp
+ * Usage: node dist/login.js
+ *
+ * Fetches a QR code from Weixin API, renders it in terminal,
+ * polls for scan confirmation, then saves token to:
+ *   ~/.openclaw/openclaw-weixin/accounts/<accountId>.json
+ */
+export {};

package/dist/login.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * weixin-login — standalone QR login for weixin-mcp
+ * Usage: node dist/login.js
+ *
+ * Fetches a QR code from Weixin API, renders it in terminal,
+ * polls for scan confirmation, then saves token to:
+ *   ~/.openclaw/openclaw-weixin/accounts/<accountId>.json
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import crypto from "node:crypto";
+// @ts-ignore — no types for qrcode-terminal
+import qrcode from "qrcode-terminal";
+const BASE_URL = "https://ilinkai.weixin.qq.com";
+const BOT_TYPE = "3";
+const STATE_DIR = process.env.OPENCLAW_STATE_DIR?.trim() ||
+    path.join(os.homedir(), ".openclaw");
+const ACCOUNTS_DIR = path.join(STATE_DIR, "openclaw-weixin", "accounts");
+async function fetchQRCode() {
+    const url = `${BASE_URL}/ilink/bot/get_bot_qrcode?bot_type=${BOT_TYPE}`;
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`QR fetch failed: ${res.status}`);
+    return res.json();
+}
+async function pollStatus(qrcodeVal) {
+    const url = `${BASE_URL}/ilink/bot/get_qrcode_status?qrcode=${encodeURIComponent(qrcodeVal)}`;
+    const res = await fetch(url, {
+        headers: { "iLink-App-ClientVersion": "1" },
+    });
+    if (!res.ok)
+        throw new Error(`Status poll failed: ${res.status}`);
+    return res.json();
+}
+function saveAccount(accountId, token, baseUrl, userId) {
+    fs.mkdirSync(ACCOUNTS_DIR, { recursive: true });
+    const filePath = path.join(ACCOUNTS_DIR, `${accountId}.json`);
+    const existing = fs.existsSync(filePath)
+        ? JSON.parse(fs.readFileSync(filePath, "utf-8"))
+        : {};
+    fs.writeFileSync(filePath, JSON.stringify({
+        ...existing,
+        token,
+        baseUrl,
+        ...(userId ? { userId } : {}),
+        savedAt: new Date().toISOString(),
+    }, null, 2));
+    console.log(`\n✅ Token saved to: ${filePath}`);
+}
+async function main() {
+    console.log("🔐 WeChat MCP — QR Login\n");
+    console.log("Fetching QR code...");
+    const { qrcode: qrcodeVal } = await fetchQRCode();
+    // Render QR in terminal
+    console.log("\nScan this QR code with WeChat:\n");
+    qrcode.generate(qrcodeVal, { small: true });
+    console.log("\nWaiting for scan...");
+    // Poll until confirmed or expired
+    let attempts = 0;
+    while (attempts < 60) {
+        await new Promise((r) => setTimeout(r, 2000));
+        attempts++;
+        const status = await pollStatus(qrcodeVal);
+        if (status.status === "scaned") {
+            process.stdout.write("\r✓ Scanned! Waiting for confirmation...");
+        }
+        else if (status.status === "confirmed") {
+            const token = status.bot_token;
+            if (!token)
+                throw new Error("No token in confirmed response");
+            const baseUrl = status.baseurl ?? BASE_URL;
+            const userId = status.ilink_user_id ?? status.ilink_bot_id;
+            // Use bot_id or a random ID as account identifier
+            const accountId = status.ilink_bot_id?.replace("@", "-").replace(".", "-")
+                ?? crypto.randomBytes(6).toString("hex") + "-im-bot";
+            saveAccount(accountId, token, baseUrl, userId ? `${userId}@im.wechat` : undefined);
+            console.log(`\n🎉 Logged in! Account: ${accountId}`);
+            console.log(`   UserId: ${userId ?? "(unknown)"}`);
+            console.log("\nYou can now start the MCP server:");
+            console.log("  node dist/index.js\n");
+            process.exit(0);
+        }
+        else if (status.status === "expired") {
+            console.error("\n❌ QR code expired. Please run again.");
+            process.exit(1);
+        }
+    }
+    console.error("\n❌ Timeout waiting for scan.");
+    process.exit(1);
+}
+main().catch((err) => {
+    console.error("Error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "weixin-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for WeChat (Weixin) — send messages via OpenClaw weixin plugin auth",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "login": "node dist/login.js",
+    "dev": "npx ts-node --esm src/index.ts",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "bin": {
+    "weixin-mcp": "./dist/index.js",
+    "weixin-login": "./dist/login.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/api.ts

@@ -0,0 +1,131 @@
+import crypto from "node:crypto";
+
+export const DEFAULT_BASE_URL = "https://ilinkai.weixin.qq.com";
+
+const AUTH_ERROR_STATUSES = new Set([401, 403]);
+
+export class WeixinAuthError extends Error {
+  constructor(message = "Authentication failed. Run npm run login to re-authenticate.") {
+    super(message);
+    this.name = "WeixinAuthError";
+  }
+}
+
+export class WeixinNetworkError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "WeixinNetworkError";
+  }
+}
+
+export function generateClientId(): string {
+  return `openclaw-weixin-mcp-${crypto.randomUUID().replace(/-/g, "").slice(0, 16)}`;
+}
+
+async function parseErrorResponse(res: Response): Promise<string> {
+  try {
+    const text = await res.text();
+    return text.trim() || `HTTP ${res.status}`;
+  } catch {
+    return `HTTP ${res.status}`;
+  }
+}
+
+function isTransientNetworkError(error: unknown): boolean {
+  return error instanceof TypeError || error instanceof WeixinNetworkError;
+}
+
+export async function weixinRequest(
+  requestPath: string,
+  body: unknown,
+  token: string,
+  baseUrl = DEFAULT_BASE_URL,
+  retries = 1,
+): Promise<unknown> {
+  const url = `${baseUrl}${requestPath}`;
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify(body),
+      });
+
+      if (AUTH_ERROR_STATUSES.has(res.status)) {
+        throw new WeixinAuthError();
+      }
+
+      if (!res.ok) {
+        const message = await parseErrorResponse(res);
+        throw new Error(`Weixin API error ${res.status}: ${message}`);
+      }
+
+      return res.json();
+    } catch (error) {
+      if (error instanceof WeixinAuthError) {
+        throw error;
+      }
+
+      if (isTransientNetworkError(error) && attempt < retries) {
+        continue;
+      }
+
+      if (isTransientNetworkError(error)) {
+        throw new WeixinNetworkError(
+          error instanceof Error ? error.message : "Network request failed",
+        );
+      }
+
+      throw error;
+    }
+  }
+
+  throw new WeixinNetworkError("Network request failed");
+}
+
+export async function sendTextMessage(to: string, text: string, token: string, baseUrl: string) {
+  return weixinRequest(
+    "/v1/message/send",
+    {
+      msg: {
+        from_user_id: "",
+        to_user_id: to,
+        client_id: generateClientId(),
+        message_type: 2,
+        message_state: 2,
+        item_list: [{ type: 1, text_item: { text } }],
+      },
+    },
+    token,
+    baseUrl,
+  );
+}
+
+export async function getContacts(token: string, baseUrl: string) {
+  return weixinRequest("/v1/contacts/list", { page_size: 50 }, token, baseUrl);
+}
+
+export async function pollMessages(token: string, baseUrl: string, sinceTs?: number) {
+  return weixinRequest(
+    "/v1/updates/get",
+    {
+      timeout_ms: 5000,
+      ...(sinceTs ? { since_ts: sinceTs } : {}),
+    },
+    token,
+    baseUrl,
+  );
+}
+
+export async function getChatHistory(to: string, limit: number, token: string, baseUrl: string) {
+  return weixinRequest(
+    "/v1/message/history",
+    { to_user_id: to, limit },
+    token,
+    baseUrl,
+  );
+}

package/src/index.ts

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * WeChat MCP Server
+ * Exposes WeChat messaging as MCP tools, reusing token from OpenClaw weixin plugin.
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import {
+  DEFAULT_BASE_URL,
+  getChatHistory,
+  getContacts,
+  pollMessages,
+  sendTextMessage,
+  WeixinAuthError,
+  WeixinNetworkError,
+} from "./api.js";
+
+// ── Auth / config ──────────────────────────────────────────────────────────
+
+const STATE_DIR =
+  process.env.OPENCLAW_STATE_DIR?.trim() ||
+  process.env.CLAWDBOT_STATE_DIR?.trim() ||
+  path.join(os.homedir(), ".openclaw");
+
+const WEIXIN_DIR = path.join(STATE_DIR, "openclaw-weixin", "accounts");
+
+interface AccountData {
+  token?: string;
+  baseUrl?: string;
+  userId?: string;
+  savedAt?: string;
+}
+
+function loadAccount(): AccountData & { accountId: string } {
+  const files = fs.readdirSync(WEIXIN_DIR).filter((f) => f.endsWith(".json") && !f.endsWith(".sync.json"));
+  if (files.length === 0) throw new Error("No WeChat account found. Run: npx @tencent-weixin/openclaw-weixin-cli install");
+
+  // Pick the first (or explicitly set) account
+  const accountId = process.env.WEIXIN_ACCOUNT_ID ?? files[0].replace(".json", "");
+  const filePath = path.join(WEIXIN_DIR, `${accountId}.json`);
+  const data = JSON.parse(fs.readFileSync(filePath, "utf-8")) as AccountData;
+  if (!data.token) throw new Error(`No token for account ${accountId}. Re-run QR login.`);
+  return { ...data, accountId };
+}
+
+// ── Weixin API ─────────────────────────────────────────────────────────────
+
+function assertNonEmptyString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`Invalid argument "${field}": must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function formatToolError(error: unknown): string {
+  if (error instanceof WeixinAuthError) {
+    return error.message;
+  }
+
+  if (error instanceof WeixinNetworkError) {
+    return `Network error while calling Weixin API: ${error.message}`;
+  }
+
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}
+
+// ── MCP Server ─────────────────────────────────────────────────────────────
+
+const server = new Server(
+  { name: "weixin-mcp", version: "1.0.0" },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "weixin_send",
+      description: "Send a WeChat message to a user (by user ID or OpenId)",
+      inputSchema: {
+        type: "object",
+        properties: {
+          to: { type: "string", description: "Recipient user ID / OpenId" },
+          text: { type: "string", description: "Message text to send" },
+        },
+        required: ["to", "text"],
+      },
+    },
+    {
+      name: "weixin_get_contacts",
+      description: "List WeChat contacts",
+      inputSchema: { type: "object", properties: {} },
+    },
+    {
+      name: "weixin_poll_messages",
+      description: "Poll for new WeChat messages since a timestamp",
+      inputSchema: {
+        type: "object",
+        properties: {
+          since_ts: { type: "number", description: "Unix timestamp in ms (optional)" },
+        },
+      },
+    },
+    {
+      name: "weixin_get_history",
+      description: "Get chat history with a WeChat contact",
+      inputSchema: {
+        type: "object",
+        properties: {
+          to: { type: "string", description: "Contact user ID / OpenId" },
+          limit: { type: "number", description: "Number of messages (default 20)" },
+        },
+        required: ["to"],
+      },
+    },
+  ],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const account = loadAccount();
+  const { token, baseUrl = DEFAULT_BASE_URL } = account;
+
+  const { name, arguments: args } = req.params;
+
+  try {
+    let result: unknown;
+
+    if (name === "weixin_send") {
+      const { to, text } = (args ?? {}) as { to?: string; text?: string };
+      const validatedTo = assertNonEmptyString(to, "to");
+      const validatedText = assertNonEmptyString(text, "text");
+      result = await sendTextMessage(validatedTo, validatedText, token!, baseUrl);
+    } else if (name === "weixin_get_contacts") {
+      result = await getContacts(token!, baseUrl);
+    } else if (name === "weixin_poll_messages") {
+      const { since_ts } = (args ?? {}) as { since_ts?: number };
+      result = await pollMessages(token!, baseUrl, since_ts);
+    } else if (name === "weixin_get_history") {
+      const { to, limit = 20 } = (args ?? {}) as { to?: string; limit?: number };
+      const validatedTo = assertNonEmptyString(to, "to");
+      result = await getChatHistory(validatedTo, limit, token!, baseUrl);
+    } else {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: `Error: ${formatToolError(err)}` }],
+      isError: true,
+    };
+  }
+});
+
+// ── Start ──────────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("WeChat MCP server running on stdio");

package/src/login.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * weixin-login — standalone QR login for weixin-mcp
+ * Usage: node dist/login.js
+ *
+ * Fetches a QR code from Weixin API, renders it in terminal,
+ * polls for scan confirmation, then saves token to:
+ *   ~/.openclaw/openclaw-weixin/accounts/<accountId>.json
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import crypto from "node:crypto";
+// @ts-ignore — no types for qrcode-terminal
+import qrcode from "qrcode-terminal";
+
+const BASE_URL = "https://ilinkai.weixin.qq.com";
+const BOT_TYPE = "3";
+const STATE_DIR =
+  process.env.OPENCLAW_STATE_DIR?.trim() ||
+  path.join(os.homedir(), ".openclaw");
+const ACCOUNTS_DIR = path.join(STATE_DIR, "openclaw-weixin", "accounts");
+
+async function fetchQRCode(): Promise<{ qrcode: string; qrcode_img_content: string }> {
+  const url = `${BASE_URL}/ilink/bot/get_bot_qrcode?bot_type=${BOT_TYPE}`;
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`QR fetch failed: ${res.status}`);
+  return res.json() as Promise<{ qrcode: string; qrcode_img_content: string }>;
+}
+
+async function pollStatus(qrcodeVal: string): Promise<{
+  status: "wait" | "scaned" | "confirmed" | "expired";
+  bot_token?: string;
+  ilink_bot_id?: string;
+  baseurl?: string;
+  ilink_user_id?: string;
+}> {
+  const url = `${BASE_URL}/ilink/bot/get_qrcode_status?qrcode=${encodeURIComponent(qrcodeVal)}`;
+  const res = await fetch(url, {
+    headers: { "iLink-App-ClientVersion": "1" },
+  });
+  if (!res.ok) throw new Error(`Status poll failed: ${res.status}`);
+  return res.json() as Promise<{
+    status: "wait" | "scaned" | "confirmed" | "expired";
+    bot_token?: string;
+    ilink_bot_id?: string;
+    baseurl?: string;
+    ilink_user_id?: string;
+  }>;
+}
+
+function saveAccount(accountId: string, token: string, baseUrl: string, userId?: string) {
+  fs.mkdirSync(ACCOUNTS_DIR, { recursive: true });
+  const filePath = path.join(ACCOUNTS_DIR, `${accountId}.json`);
+  const existing = fs.existsSync(filePath)
+    ? (JSON.parse(fs.readFileSync(filePath, "utf-8")) as Record<string, unknown>)
+    : {};
+  fs.writeFileSync(
+    filePath,
+    JSON.stringify(
+      {
+        ...existing,
+        token,
+        baseUrl,
+        ...(userId ? { userId } : {}),
+        savedAt: new Date().toISOString(),
+      },
+      null,
+      2,
+    ),
+  );
+  console.log(`\n✅ Token saved to: ${filePath}`);
+}
+
+async function main() {
+  console.log("🔐 WeChat MCP — QR Login\n");
+
+  console.log("Fetching QR code...");
+  const { qrcode: qrcodeVal } = await fetchQRCode();
+
+  // Render QR in terminal
+  console.log("\nScan this QR code with WeChat:\n");
+  qrcode.generate(qrcodeVal, { small: true });
+
+  console.log("\nWaiting for scan...");
+
+  // Poll until confirmed or expired
+  let attempts = 0;
+  while (attempts < 60) {
+    await new Promise((r) => setTimeout(r, 2000));
+    attempts++;
+
+    const status = await pollStatus(qrcodeVal);
+
+    if (status.status === "scaned") {
+      process.stdout.write("\r✓ Scanned! Waiting for confirmation...");
+    } else if (status.status === "confirmed") {
+      const token = status.bot_token;
+      if (!token) throw new Error("No token in confirmed response");
+      const baseUrl = status.baseurl ?? BASE_URL;
+      const userId = status.ilink_user_id ?? status.ilink_bot_id;
+      // Use bot_id or a random ID as account identifier
+      const accountId = status.ilink_bot_id?.replace("@", "-").replace(".", "-")
+        ?? crypto.randomBytes(6).toString("hex") + "-im-bot";
+      saveAccount(accountId, token, baseUrl, userId ? `${userId}@im.wechat` : undefined);
+      console.log(`\n🎉 Logged in! Account: ${accountId}`);
+      console.log(`   UserId: ${userId ?? "(unknown)"}`);
+      console.log("\nYou can now start the MCP server:");
+      console.log("  node dist/index.js\n");
+      process.exit(0);
+    } else if (status.status === "expired") {
+      console.error("\n❌ QR code expired. Please run again.");
+      process.exit(1);
+    }
+  }
+
+  console.error("\n❌ Timeout waiting for scan.");
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error("Error:", err);
+  process.exit(1);
+});

package/test/api.test.mjs

@@ -0,0 +1,52 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+test("weixinRequest retries once on transient network error", async () => {
+  const { weixinRequest } = await import("../dist/api.js");
+  const originalFetch = global.fetch;
+  let calls = 0;
+
+  global.fetch = async () => {
+    calls += 1;
+    if (calls === 1) {
+      throw new TypeError("temporary network failure");
+    }
+
+    return new Response(JSON.stringify({ ok: true }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  };
+
+  try {
+    const result = await weixinRequest("/v1/test", { hello: "world" }, "token", "https://example.com");
+    assert.deepEqual(result, { ok: true });
+    assert.equal(calls, 2);
+  } finally {
+    global.fetch = originalFetch;
+  }
+});
+
+test("weixinRequest returns auth guidance for expired token", async () => {
+  const { weixinRequest, WeixinAuthError } = await import("../dist/api.js");
+  const originalFetch = global.fetch;
+
+  global.fetch = async () =>
+    new Response("expired", {
+      status: 401,
+      headers: { "Content-Type": "text/plain" },
+    });
+
+  try {
+    await assert.rejects(
+      () => weixinRequest("/v1/test", {}, "token", "https://example.com"),
+      (error) => {
+        assert.ok(error instanceof WeixinAuthError);
+        assert.match(error.message, /Run npm run login to re-authenticate/);
+        return true;
+      },
+    );
+  } finally {
+    global.fetch = originalFetch;
+  }
+});

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src"]
+}