weixin-mcp 1.5.0 → 1.7.0

package/README.en.md

@@ -42,8 +42,8 @@ npx weixin-mcp
 When sending messages, you can use a prefix of the user ID if it uniquely matches a contact:
 
 ```bash
-npx weixin-mcp send o9cq8 "hello"
-# Resolved "o9cq8" → o9cq80x8ou646cs3Tt5EQgfsZRtI@im.wechat
+npx weixin-mcp send abc12 "hello"
+# Resolved "abc12" → abc123xyz456@im.wechat
 ```
 
 ## Claude Desktop Integration

package/README.md

@@ -44,8 +44,8 @@ npx weixin-mcp
 发送消息时可以用用户 ID 的前缀，只要在联系人中唯一匹配即可：
 
 ```bash
-npx weixin-mcp send o9cq8 "hello"
-# Resolved "o9cq8" → o9cq80x8ou646cs3Tt5EQgfsZRtI@im.wechat
+npx weixin-mcp send abc12 "hello"
+# Resolved "abc12" → abc123xyz456@im.wechat
 ```
 
 ## Claude Desktop 集成

package/dist/api.d.ts

@@ -33,3 +33,23 @@ export declare function getConfig(ilinkUserId: string, token: string, baseUrl: s
  * status: 1 = typing, 2 = cancel
  */
 export declare function sendTyping(ilinkUserId: string, typingTicket: string, status: 1 | 2, token: string, baseUrl: string): Promise<unknown>;
+export interface UploadedMedia {
+    filekey: string;
+    downloadEncryptedQueryParam: string;
+    aeskey: string;
+    fileSize: number;
+    fileSizeCiphertext: number;
+    fileName?: string;
+}
+/**
+ * Send an image message using a previously uploaded file.
+ */
+export declare function sendImageMessage(to: string, uploaded: UploadedMedia, token: string, baseUrl: string, contextToken?: string, caption?: string): Promise<void>;
+/**
+ * Send a file attachment using a previously uploaded file.
+ */
+export declare function sendFileMessage(to: string, uploaded: UploadedMedia, token: string, baseUrl: string, contextToken?: string, caption?: string): Promise<void>;
+/**
+ * Send a video message using a previously uploaded file.
+ */
+export declare function sendVideoMessage(to: string, uploaded: UploadedMedia, token: string, baseUrl: string, contextToken?: string, caption?: string): Promise<void>;

package/dist/api.js

@@ -146,3 +146,106 @@ export async function sendTyping(ilinkUserId, typingTicket, status, token, baseU
         base_info: { channel_version: CHANNEL_VERSION },
     }, token, baseUrl);
 }
+/**
+ * Send an image message using a previously uploaded file.
+ */
+export async function sendImageMessage(to, uploaded, token, baseUrl, contextToken, caption) {
+    const items = [];
+    if (caption)
+        items.push({ type: 1, text_item: { text: caption } });
+    items.push({
+        type: 2,
+        image_item: {
+            media: {
+                encrypt_query_param: uploaded.downloadEncryptedQueryParam,
+                // Official SDK does Buffer.from(hexString).toString("base64") — hex as UTF-8 string
+                aes_key: Buffer.from(uploaded.aeskey).toString("base64"),
+                encrypt_type: 1,
+            },
+            aeskey: uploaded.aeskey, // hex string for client decryption
+            mid_size: uploaded.fileSizeCiphertext,
+        },
+    });
+    // Send each item separately (text caption + image)
+    for (const item of items) {
+        await weixinRequest("ilink/bot/sendmessage", {
+            msg: {
+                from_user_id: "",
+                to_user_id: to,
+                client_id: generateClientId(),
+                message_type: 2,
+                message_state: 2,
+                item_list: [item],
+                ...(contextToken ? { context_token: contextToken } : {}),
+            },
+            base_info: { channel_version: CHANNEL_VERSION },
+        }, token, baseUrl);
+    }
+}
+/**
+ * Send a file attachment using a previously uploaded file.
+ */
+export async function sendFileMessage(to, uploaded, token, baseUrl, contextToken, caption) {
+    const items = [];
+    if (caption)
+        items.push({ type: 1, text_item: { text: caption } });
+    items.push({
+        type: 4,
+        file_item: {
+            media: {
+                encrypt_query_param: uploaded.downloadEncryptedQueryParam,
+                aes_key: Buffer.from(uploaded.aeskey).toString("base64"),
+                encrypt_type: 1,
+            },
+            file_name: uploaded.fileName ?? "file",
+            len: String(uploaded.fileSize),
+        },
+    });
+    for (const item of items) {
+        await weixinRequest("ilink/bot/sendmessage", {
+            msg: {
+                from_user_id: "",
+                to_user_id: to,
+                client_id: generateClientId(),
+                message_type: 2,
+                message_state: 2,
+                item_list: [item],
+                ...(contextToken ? { context_token: contextToken } : {}),
+            },
+            base_info: { channel_version: CHANNEL_VERSION },
+        }, token, baseUrl);
+    }
+}
+/**
+ * Send a video message using a previously uploaded file.
+ */
+export async function sendVideoMessage(to, uploaded, token, baseUrl, contextToken, caption) {
+    const items = [];
+    if (caption)
+        items.push({ type: 1, text_item: { text: caption } });
+    items.push({
+        type: 5,
+        video_item: {
+            media: {
+                encrypt_query_param: uploaded.downloadEncryptedQueryParam,
+                aes_key: Buffer.from(uploaded.aeskey).toString("base64"),
+                encrypt_type: 1,
+            },
+            video_size: uploaded.fileSizeCiphertext,
+        },
+    });
+    for (const item of items) {
+        await weixinRequest("ilink/bot/sendmessage", {
+            msg: {
+                from_user_id: "",
+                to_user_id: to,
+                client_id: generateClientId(),
+                message_type: 2,
+                message_state: 2,
+                item_list: [item],
+                ...(contextToken ? { context_token: contextToken } : {}),
+            },
+            base_info: { channel_version: CHANNEL_VERSION },
+        }, token, baseUrl);
+    }
+}

package/dist/cdn.d.ts

@@ -0,0 +1,24 @@
+/**
+ * CDN upload utilities for image/video/file sending.
+ * Based on @tencent-weixin/openclaw-weixin official implementation.
+ */
+export type MediaType = "image" | "video" | "file";
+export interface UploadedMedia {
+    filekey: string;
+    downloadEncryptedQueryParam: string;
+    aeskey: string;
+    fileSize: number;
+    fileSizeCiphertext: number;
+    fileName?: string;
+}
+/**
+ * Upload a file (local path or URL) to Weixin CDN.
+ * Returns UploadedMedia with all params needed for sendMessage.
+ */
+export declare function uploadMedia(params: {
+    source: string;
+    mediaType: MediaType;
+    toUserId: string;
+    token: string;
+    baseUrl: string;
+}): Promise<UploadedMedia>;

package/dist/cdn.js

@@ -0,0 +1,130 @@
+/**
+ * CDN upload utilities for image/video/file sending.
+ * Based on @tencent-weixin/openclaw-weixin official implementation.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+const CDN_BASE_URL = "https://novac2c.cdn.weixin.qq.com/c2c";
+// ── AES-128-ECB ────────────────────────────────────────────────────────────
+function encryptAesEcb(plaintext, key) {
+    const cipher = crypto.createCipheriv("aes-128-ecb", key, null);
+    return Buffer.concat([cipher.update(plaintext), cipher.final()]);
+}
+function aesEcbPaddedSize(plaintextSize) {
+    return Math.ceil((plaintextSize + 1) / 16) * 16;
+}
+const MEDIA_TYPE_MAP = {
+    image: 1,
+    video: 2,
+    file: 3,
+};
+// ── API calls ──────────────────────────────────────────────────────────────
+function randomWechatUin() {
+    return crypto.randomBytes(4).toString("base64");
+}
+async function getUploadUrl(params) {
+    const body = JSON.stringify({
+        filekey: params.filekey,
+        media_type: params.mediaType,
+        to_user_id: params.toUserId,
+        rawsize: params.rawsize,
+        rawfilemd5: params.rawfilemd5,
+        filesize: params.filesize,
+        no_need_thumb: true,
+        aeskey: params.aeskey,
+        base_info: { channel_version: "1.0.2" },
+    });
+    const res = await fetch(`${params.baseUrl}/ilink/bot/getuploadurl`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Content-Length": String(Buffer.byteLength(body, "utf-8")),
+            "AuthorizationType": "ilink_bot_token",
+            "Authorization": `Bearer ${params.token}`,
+            "X-WECHAT-UIN": randomWechatUin(),
+        },
+        body,
+    });
+    return res.json();
+}
+async function uploadToCdn(params) {
+    const ciphertext = encryptAesEcb(params.buf, params.aeskey);
+    const cdnUrl = `${CDN_BASE_URL}/upload?encrypted_query_param=${encodeURIComponent(params.uploadParam)}&filekey=${encodeURIComponent(params.filekey)}`;
+    const res = await fetch(cdnUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/octet-stream" },
+        body: new Uint8Array(ciphertext),
+    });
+    if (!res.ok) {
+        const errMsg = res.headers.get("x-error-message") ?? `status ${res.status}`;
+        throw new Error(`CDN upload failed: ${errMsg}`);
+    }
+    const downloadParam = res.headers.get("x-encrypted-param");
+    if (!downloadParam) {
+        throw new Error("CDN response missing x-encrypted-param header");
+    }
+    return downloadParam;
+}
+// ── Main upload function ───────────────────────────────────────────────────
+/**
+ * Upload a file (local path or URL) to Weixin CDN.
+ * Returns UploadedMedia with all params needed for sendMessage.
+ */
+export async function uploadMedia(params) {
+    const { source, mediaType, toUserId, token, baseUrl } = params;
+    // Load file
+    let plaintext;
+    let fileName;
+    if (source.startsWith("http://") || source.startsWith("https://")) {
+        // Download remote file
+        const res = await fetch(source);
+        if (!res.ok)
+            throw new Error(`Failed to download: ${source}`);
+        plaintext = Buffer.from(await res.arrayBuffer());
+        // Extract filename from URL
+        const urlPath = new URL(source).pathname;
+        fileName = path.basename(urlPath);
+    }
+    else {
+        // Read local file
+        plaintext = await fs.readFile(source);
+        fileName = path.basename(source);
+    }
+    // Generate keys and hashes
+    const rawsize = plaintext.length;
+    const rawfilemd5 = crypto.createHash("md5").update(plaintext).digest("hex");
+    const filesize = aesEcbPaddedSize(rawsize);
+    const filekey = crypto.randomBytes(16).toString("hex");
+    const aeskey = crypto.randomBytes(16);
+    // Get upload URL
+    const uploadResp = await getUploadUrl({
+        filekey,
+        mediaType: MEDIA_TYPE_MAP[mediaType],
+        toUserId,
+        rawsize,
+        rawfilemd5,
+        filesize,
+        aeskey: aeskey.toString("hex"),
+        token,
+        baseUrl,
+    });
+    if (!uploadResp.upload_param) {
+        throw new Error(`getUploadUrl returned no upload_param: ${JSON.stringify(uploadResp)}`);
+    }
+    // Upload to CDN
+    const downloadEncryptedQueryParam = await uploadToCdn({
+        buf: plaintext,
+        uploadParam: uploadResp.upload_param,
+        filekey,
+        aeskey,
+    });
+    return {
+        filekey,
+        downloadEncryptedQueryParam,
+        aeskey: aeskey.toString("hex"),
+        fileSize: rawsize,
+        fileSizeCiphertext: filesize,
+        fileName,
+    };
+}

package/dist/cli.js

@@ -32,8 +32,10 @@ else if (command === "status") {
 else if (command === "start") {
     const portArg = process.argv.indexOf("--port");
     const port = portArg !== -1 ? Number(process.argv[portArg + 1]) : undefined;
+    const webhookArg = process.argv.indexOf("--webhook");
+    const webhook = webhookArg !== -1 ? process.argv[webhookArg + 1] : undefined;
     const { startDaemon } = await import("./daemon.js");
-    await startDaemon(port);
+    await startDaemon(port, webhook);
 }
 else if (command === "stop") {
     const { stopDaemon } = await import("./daemon.js");
@@ -113,7 +115,7 @@ Commands:
   (no args)                    Start stdio MCP server (Claude Desktop mode)
   login                        QR code login
   status                       Show account and daemon status
-  start [--port n]             Start HTTP MCP daemon in background (default: 3001)
+  start [--port n] [--webhook url]  Start HTTP daemon (with optional webhook push)
   stop                         Stop daemon
   restart                      Restart daemon
   logs [-f]                    Show daemon logs (-f to follow)

package/dist/daemon.d.ts

@@ -13,7 +13,7 @@ export declare function daemonStatus(): {
     running: boolean;
     info: DaemonInfo | null;
 };
-export declare function startDaemon(port?: number): Promise<void>;
+export declare function startDaemon(port?: number, webhook?: string): Promise<void>;
 export declare function stopDaemon(): void;
 export declare function restartDaemon(port?: number): Promise<void>;
 export declare function showLogs(follow?: boolean): void;

package/dist/daemon.js

@@ -44,7 +44,7 @@ export function daemonStatus() {
     }
     return { running, info: running ? info : null };
 }
-export async function startDaemon(port = DEFAULT_PORT) {
+export async function startDaemon(port = DEFAULT_PORT, webhook) {
     const { running, info } = daemonStatus();
     if (running && info) {
         console.log(`⚠️  Daemon already running (pid ${info.pid}, port ${info.port})`);
@@ -55,10 +55,13 @@ export async function startDaemon(port = DEFAULT_PORT) {
     const __dirname = path.dirname(__filename);
     const serverScript = path.join(__dirname, "server-http.js");
     const logFd = fs.openSync(LOG_FILE, "a");
-    const child = spawn(process.execPath, [serverScript, String(port)], {
+    const serverArgs = ["--port", String(port)];
+    if (webhook)
+        serverArgs.push("--webhook", webhook);
+    const child = spawn(process.execPath, [serverScript, ...serverArgs], {
         detached: true,
         stdio: ["ignore", logFd, logFd],
-        env: { ...process.env, WEIXIN_MCP_PORT: String(port) },
+        env: { ...process.env, WEIXIN_MCP_PORT: String(port), WEIXIN_WEBHOOK_URL: webhook ?? "" },
     });
     child.unref();
     fs.closeSync(logFd);
@@ -79,6 +82,8 @@ export async function startDaemon(port = DEFAULT_PORT) {
     console.log(`   PID:  ${child.pid}`);
     console.log(`   Port: ${port}`);
     console.log(`   URL:  http://localhost:${port}/mcp`);
+    if (webhook)
+        console.log(`   Webhook: ${webhook}`);
     console.log(`   Logs: ${LOG_FILE}`);
 }
 export function stopDaemon() {

package/dist/index.js

@@ -8,7 +8,8 @@ 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 { DEFAULT_BASE_URL, getUpdates, getConfig, sendTextMessage, loadCursor, saveCursor, WeixinAuthError, WeixinNetworkError, } from "./api.js";
+import { DEFAULT_BASE_URL, getUpdates, getConfig, sendTextMessage, sendImageMessage, sendFileMessage, loadCursor, saveCursor, WeixinAuthError, WeixinNetworkError, } from "./api.js";
+import { uploadMedia } from "./cdn.js";
 import { ACCOUNTS_DIR } from "./paths.js";
 import { updateContactsFromMsgs, loadContacts } from "./contacts.js";
 /** Resolve short userId prefix to full ID from contacts. */
@@ -90,6 +91,34 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: "List users who have messaged the bot. Returns userId, lastSeen, lastText, contextToken, msgCount. Use userId as 'to' in weixin_send.",
             inputSchema: { type: "object", properties: {} },
         },
+        {
+            name: "weixin_send_image",
+            description: "Send an image to a WeChat user. Source can be a local file path or URL. Optionally include a text caption.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    to: { type: "string", description: "Recipient user ID (full or short prefix)" },
+                    source: { type: "string", description: "Image source: local file path or URL" },
+                    caption: { type: "string", description: "Optional text caption to send with the image" },
+                    context_token: { type: "string", description: "Optional context_token to link reply" },
+                },
+                required: ["to", "source"],
+            },
+        },
+        {
+            name: "weixin_send_file",
+            description: "Send a file attachment to a WeChat user. Source can be a local file path or URL.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    to: { type: "string", description: "Recipient user ID (full or short prefix)" },
+                    source: { type: "string", description: "File source: local file path or URL" },
+                    caption: { type: "string", description: "Optional text caption to send with the file" },
+                    context_token: { type: "string", description: "Optional context_token to link reply" },
+                },
+                required: ["to", "source"],
+            },
+        },
         {
             name: "weixin_get_config",
             description: "Get bot config for a user — includes typing_ticket needed for sendTyping. Call before sending typing indicators.",
@@ -131,6 +160,36 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         else if (name === "weixin_contacts") {
             result = Object.values(loadContacts());
         }
+        else if (name === "weixin_send_image") {
+            const { to, source, caption, context_token } = (args ?? {});
+            const validatedTo = assertNonEmptyString(to, "to");
+            const resolvedTo = resolveUserId(validatedTo, loadContacts());
+            const validatedSource = assertNonEmptyString(source, "source");
+            const uploaded = await uploadMedia({
+                source: validatedSource,
+                mediaType: "image",
+                toUserId: resolvedTo,
+                token: token,
+                baseUrl,
+            });
+            await sendImageMessage(resolvedTo, uploaded, token, baseUrl, context_token, caption);
+            result = { success: true, filekey: uploaded.filekey };
+        }
+        else if (name === "weixin_send_file") {
+            const { to, source, caption, context_token } = (args ?? {});
+            const validatedTo = assertNonEmptyString(to, "to");
+            const resolvedTo = resolveUserId(validatedTo, loadContacts());
+            const validatedSource = assertNonEmptyString(source, "source");
+            const uploaded = await uploadMedia({
+                source: validatedSource,
+                mediaType: "file",
+                toUserId: resolvedTo,
+                token: token,
+                baseUrl,
+            });
+            await sendFileMessage(resolvedTo, uploaded, token, baseUrl, context_token, caption);
+            result = { success: true, filekey: uploaded.filekey, fileName: uploaded.fileName };
+        }
         else if (name === "weixin_get_config") {
             const { user_id, context_token } = (args ?? {});
             const validatedUserId = assertNonEmptyString(user_id, "user_id");

package/dist/server-http.d.ts

@@ -2,6 +2,10 @@
  * HTTP MCP server — runs as a daemon process.
  * Spawned by `weixin-mcp start`, listens on a given port.
  *
- * Clients connect via: http://localhost:<port>/mcp
+ * Features:
+ * - MCP endpoint at /mcp (StreamableHTTP)
+ * - Health check at /health
+ * - Webhook push: --webhook <url> to receive new messages via POST
+ * - Auto-poll: when webhook is set, background polling forwards messages
  */
 export {};

package/dist/server-http.js

@@ -2,19 +2,28 @@
  * HTTP MCP server — runs as a daemon process.
  * Spawned by `weixin-mcp start`, listens on a given port.
  *
- * Clients connect via: http://localhost:<port>/mcp
+ * Features:
+ * - MCP endpoint at /mcp (StreamableHTTP)
+ * - Health check at /health
+ * - Webhook push: --webhook <url> to receive new messages via POST
+ * - Auto-poll: when webhook is set, background polling forwards messages
  */
 import express from "express";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { randomUUID } from "node:crypto";
-// Reuse the same tool definitions and handlers from the main server
 import { DEFAULT_BASE_URL, getUpdates, getConfig, sendTextMessage, loadCursor, saveCursor, WeixinAuthError, WeixinNetworkError, } from "./api.js";
 import { ACCOUNTS_DIR } from "./paths.js";
+import { updateContactsFromMsgs, loadContacts } from "./contacts.js";
 import fs from "node:fs";
 import path from "node:path";
-const port = Number(process.env.WEIXIN_MCP_PORT ?? process.argv[2] ?? 3001);
+// Parse CLI args
+const args = process.argv.slice(2);
+const portIdx = args.indexOf("--port");
+const port = portIdx >= 0 ? Number(args[portIdx + 1]) : Number(process.env.WEIXIN_MCP_PORT ?? 3001);
+const webhookIdx = args.indexOf("--webhook");
+const webhookUrl = webhookIdx >= 0 ? args[webhookIdx + 1] : process.env.WEIXIN_WEBHOOK_URL;
 function loadAccount() {
     const files = fs.readdirSync(ACCOUNTS_DIR).filter((f) => f.endsWith(".json") && !f.endsWith(".sync.json") && !f.endsWith(".cursor.json"));
     if (files.length === 0)
@@ -35,9 +44,18 @@ function fmtErr(e) {
         return e.message;
     return String(e);
 }
+function resolveUserId(input, contacts) {
+    if (!input || input.includes("@"))
+        return input;
+    const ids = Object.keys(contacts);
+    const matches = ids.filter((id) => id.startsWith(input) || id.includes(input));
+    if (matches.length === 1)
+        return matches[0];
+    return input;
+}
 // ── MCP server factory ─────────────────────────────────────────────────────
 function createMCPServer() {
-    const server = new Server({ name: "weixin-mcp", version: "1.2.2" }, { capabilities: { tools: {} } });
+    const server = new Server({ name: "weixin-mcp", version: "1.5.0" }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: [
             {
@@ -46,7 +64,7 @@ function createMCPServer() {
                 inputSchema: {
                     type: "object",
                     properties: {
-                        to: { type: "string" },
+                        to: { type: "string", description: "Recipient (full ID or short prefix)" },
                         text: { type: "string" },
                         context_token: { type: "string" },
                     },
@@ -61,6 +79,11 @@ function createMCPServer() {
                     properties: { reset_cursor: { type: "boolean" } },
                 },
             },
+            {
+                name: "weixin_contacts",
+                description: "List users who have messaged the bot.",
+                inputSchema: { type: "object", properties: {} },
+            },
             {
                 name: "weixin_get_config",
                 description: "Get user config (typing ticket, etc.).",
@@ -82,7 +105,8 @@ function createMCPServer() {
             let result;
             if (name === "weixin_send") {
                 const a = (args ?? {});
-                result = await sendTextMessage(assertStr(a.to, "to"), assertStr(a.text, "text"), token, baseUrl, a.context_token);
+                const resolvedTo = resolveUserId(assertStr(a.to, "to"), loadContacts());
+                result = await sendTextMessage(resolvedTo, assertStr(a.text, "text"), token, baseUrl, a.context_token);
             }
             else if (name === "weixin_poll") {
                 const { reset_cursor } = (args ?? {});
@@ -90,8 +114,13 @@ function createMCPServer() {
                 const resp = await getUpdates(token, baseUrl, cursor);
                 if (resp.get_updates_buf)
                     saveCursor(accountId, resp.get_updates_buf);
+                if (resp.msgs && resp.msgs.length > 0)
+                    updateContactsFromMsgs(resp.msgs);
                 result = resp;
             }
+            else if (name === "weixin_contacts") {
+                result = Object.values(loadContacts());
+            }
             else if (name === "weixin_get_config") {
                 const a = (args ?? {});
                 result = await getConfig(assertStr(a.user_id, "user_id"), token, baseUrl, a.context_token);
@@ -107,17 +136,55 @@ function createMCPServer() {
     });
     return server;
 }
+// ── Webhook push ───────────────────────────────────────────────────────────
+async function pushToWebhook(msgs) {
+    if (!webhookUrl || msgs.length === 0)
+        return;
+    try {
+        await fetch(webhookUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ event: "weixin_messages", messages: msgs, timestamp: new Date().toISOString() }),
+        });
+    }
+    catch (err) {
+        console.error("[weixin-mcp] webhook push failed:", fmtErr(err));
+    }
+}
+// ── Background poller (when webhook is set) ────────────────────────────────
+async function startBackgroundPoller() {
+    if (!webhookUrl)
+        return;
+    console.log(`[weixin-mcp] Webhook enabled: ${webhookUrl}`);
+    console.log("[weixin-mcp] Starting background poller...");
+    while (true) {
+        try {
+            const { token, baseUrl = DEFAULT_BASE_URL, accountId } = loadAccount();
+            const cursor = loadCursor(accountId);
+            const resp = await getUpdates(token, baseUrl, cursor);
+            if (resp.get_updates_buf)
+                saveCursor(accountId, resp.get_updates_buf);
+            if (resp.msgs && resp.msgs.length > 0) {
+                updateContactsFromMsgs(resp.msgs);
+                await pushToWebhook(resp.msgs);
+                console.log(`[weixin-mcp] Pushed ${resp.msgs.length} message(s) to webhook`);
+            }
+        }
+        catch (err) {
+            console.error("[weixin-mcp] poll error:", fmtErr(err));
+            await new Promise((r) => setTimeout(r, 5000)); // backoff on error
+        }
+        // getUpdates is long-poll (~30s timeout), so no extra delay needed
+    }
+}
 // ── Express HTTP server ────────────────────────────────────────────────────
 const app = express();
 app.use(express.json());
-// Session store for stateful transports
 const sessions = new Map();
 app.post("/mcp", async (req, res) => {
-    // Check if this is an existing session
     const sessionId = req.headers["mcp-session-id"];
     let transport = sessionId ? sessions.get(sessionId) : undefined;
     if (!transport) {
-        // New session
         const newSessionId = randomUUID();
         transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: () => newSessionId,
@@ -148,9 +215,11 @@ app.delete("/mcp", async (req, res) => {
     await transport.handleRequest(req, res);
 });
 app.get("/health", (_req, res) => {
-    res.json({ status: "ok", port, sessions: sessions.size });
+    res.json({ status: "ok", port, sessions: sessions.size, webhook: webhookUrl ?? null });
 });
 app.listen(port, () => {
-    console.log(`[weixin-mcp] HTTP MCP server listening on port ${port}`);
-    console.log(`[weixin-mcp] MCP endpoint: http://localhost:${port}/mcp`);
+    console.log(`[weixin-mcp] HTTP MCP server on port ${port}`);
+    console.log(`[weixin-mcp] MCP: http://localhost:${port}/mcp`);
+    if (webhookUrl)
+        startBackgroundPoller();
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weixin-mcp",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "MCP server for WeChat (Weixin) — send messages via OpenClaw weixin plugin auth",
   "type": "module",
   "main": "dist/index.js",

package/src/api.ts

@@ -202,3 +202,156 @@ export async function sendTyping(
     baseUrl,
   );
 }
+
+// ── Media message types ────────────────────────────────────────────────────
+
+export interface UploadedMedia {
+  filekey: string;
+  downloadEncryptedQueryParam: string;
+  aeskey: string;
+  fileSize: number;
+  fileSizeCiphertext: number;
+  fileName?: string;
+}
+
+/**
+ * Send an image message using a previously uploaded file.
+ */
+export async function sendImageMessage(
+  to: string,
+  uploaded: UploadedMedia,
+  token: string,
+  baseUrl: string,
+  contextToken?: string,
+  caption?: string,
+) {
+  const items: Array<{ type: number; text_item?: { text: string }; image_item?: unknown }> = [];
+  if (caption) items.push({ type: 1, text_item: { text: caption } });
+  items.push({
+    type: 2,
+    image_item: {
+      media: {
+        encrypt_query_param: uploaded.downloadEncryptedQueryParam,
+        // Official SDK does Buffer.from(hexString).toString("base64") — hex as UTF-8 string
+        aes_key: Buffer.from(uploaded.aeskey).toString("base64"),
+        encrypt_type: 1,
+      },
+      aeskey: uploaded.aeskey, // hex string for client decryption
+      mid_size: uploaded.fileSizeCiphertext,
+    },
+  });
+
+  // Send each item separately (text caption + image)
+  for (const item of items) {
+    await weixinRequest(
+      "ilink/bot/sendmessage",
+      {
+        msg: {
+          from_user_id: "",
+          to_user_id: to,
+          client_id: generateClientId(),
+          message_type: 2,
+          message_state: 2,
+          item_list: [item],
+          ...(contextToken ? { context_token: contextToken } : {}),
+        },
+        base_info: { channel_version: CHANNEL_VERSION },
+      },
+      token,
+      baseUrl,
+    );
+  }
+}
+
+/**
+ * Send a file attachment using a previously uploaded file.
+ */
+export async function sendFileMessage(
+  to: string,
+  uploaded: UploadedMedia,
+  token: string,
+  baseUrl: string,
+  contextToken?: string,
+  caption?: string,
+) {
+  const items: Array<{ type: number; text_item?: { text: string }; file_item?: unknown }> = [];
+  if (caption) items.push({ type: 1, text_item: { text: caption } });
+  items.push({
+    type: 4,
+    file_item: {
+      media: {
+        encrypt_query_param: uploaded.downloadEncryptedQueryParam,
+        aes_key: Buffer.from(uploaded.aeskey).toString("base64"),
+        encrypt_type: 1,
+      },
+      file_name: uploaded.fileName ?? "file",
+      len: String(uploaded.fileSize),
+    },
+  });
+
+  for (const item of items) {
+    await weixinRequest(
+      "ilink/bot/sendmessage",
+      {
+        msg: {
+          from_user_id: "",
+          to_user_id: to,
+          client_id: generateClientId(),
+          message_type: 2,
+          message_state: 2,
+          item_list: [item],
+          ...(contextToken ? { context_token: contextToken } : {}),
+        },
+        base_info: { channel_version: CHANNEL_VERSION },
+      },
+      token,
+      baseUrl,
+    );
+  }
+}
+
+/**
+ * Send a video message using a previously uploaded file.
+ */
+export async function sendVideoMessage(
+  to: string,
+  uploaded: UploadedMedia,
+  token: string,
+  baseUrl: string,
+  contextToken?: string,
+  caption?: string,
+) {
+  const items: Array<{ type: number; text_item?: { text: string }; video_item?: unknown }> = [];
+  if (caption) items.push({ type: 1, text_item: { text: caption } });
+  items.push({
+    type: 5,
+    video_item: {
+      media: {
+        encrypt_query_param: uploaded.downloadEncryptedQueryParam,
+        aes_key: Buffer.from(uploaded.aeskey).toString("base64"),
+        encrypt_type: 1,
+      },
+      video_size: uploaded.fileSizeCiphertext,
+    },
+  });
+
+  for (const item of items) {
+    await weixinRequest(
+      "ilink/bot/sendmessage",
+      {
+        msg: {
+          from_user_id: "",
+          to_user_id: to,
+          client_id: generateClientId(),
+          message_type: 2,
+          message_state: 2,
+          item_list: [item],
+          ...(contextToken ? { context_token: contextToken } : {}),
+        },
+        base_info: { channel_version: CHANNEL_VERSION },
+      },
+      token,
+      baseUrl,
+    );
+  }
+}

package/src/cdn.ts

@@ -0,0 +1,185 @@
+/**
+ * CDN upload utilities for image/video/file sending.
+ * Based on @tencent-weixin/openclaw-weixin official implementation.
+ */
+
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const CDN_BASE_URL = "https://novac2c.cdn.weixin.qq.com/c2c";
+
+// ── AES-128-ECB ────────────────────────────────────────────────────────────
+
+function encryptAesEcb(plaintext: Buffer, key: Buffer): Buffer {
+  const cipher = crypto.createCipheriv("aes-128-ecb", key, null);
+  return Buffer.concat([cipher.update(plaintext), cipher.final()]);
+}
+
+function aesEcbPaddedSize(plaintextSize: number): number {
+  return Math.ceil((plaintextSize + 1) / 16) * 16;
+}
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export type MediaType = "image" | "video" | "file";
+
+const MEDIA_TYPE_MAP: Record<MediaType, number> = {
+  image: 1,
+  video: 2,
+  file: 3,
+};
+
+export interface UploadedMedia {
+  filekey: string;
+  downloadEncryptedQueryParam: string;
+  aeskey: string;
+  fileSize: number;
+  fileSizeCiphertext: number;
+  fileName?: string;
+}
+
+// ── API calls ──────────────────────────────────────────────────────────────
+
+function randomWechatUin(): string {
+  return crypto.randomBytes(4).toString("base64");
+}
+
+async function getUploadUrl(params: {
+  filekey: string;
+  mediaType: number;
+  toUserId: string;
+  rawsize: number;
+  rawfilemd5: string;
+  filesize: number;
+  aeskey: string;
+  token: string;
+  baseUrl: string;
+}): Promise<{ upload_param?: string; errcode?: number; errmsg?: string }> {
+  const body = JSON.stringify({
+    filekey: params.filekey,
+    media_type: params.mediaType,
+    to_user_id: params.toUserId,
+    rawsize: params.rawsize,
+    rawfilemd5: params.rawfilemd5,
+    filesize: params.filesize,
+    no_need_thumb: true,
+    aeskey: params.aeskey,
+    base_info: { channel_version: "1.0.2" },
+  });
+  const res = await fetch(`${params.baseUrl}/ilink/bot/getuploadurl`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Content-Length": String(Buffer.byteLength(body, "utf-8")),
+      "AuthorizationType": "ilink_bot_token",
+      "Authorization": `Bearer ${params.token}`,
+      "X-WECHAT-UIN": randomWechatUin(),
+    },
+    body,
+  });
+  return res.json();
+}
+
+async function uploadToCdn(params: {
+  buf: Buffer;
+  uploadParam: string;
+  filekey: string;
+  aeskey: Buffer;
+}): Promise<string> {
+  const ciphertext = encryptAesEcb(params.buf, params.aeskey);
+  const cdnUrl = `${CDN_BASE_URL}/upload?encrypted_query_param=${encodeURIComponent(params.uploadParam)}&filekey=${encodeURIComponent(params.filekey)}`;
+
+  const res = await fetch(cdnUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/octet-stream" },
+    body: new Uint8Array(ciphertext),
+  });
+
+  if (!res.ok) {
+    const errMsg = res.headers.get("x-error-message") ?? `status ${res.status}`;
+    throw new Error(`CDN upload failed: ${errMsg}`);
+  }
+
+  const downloadParam = res.headers.get("x-encrypted-param");
+  if (!downloadParam) {
+    throw new Error("CDN response missing x-encrypted-param header");
+  }
+
+  return downloadParam;
+}
+
+// ── Main upload function ───────────────────────────────────────────────────
+
+/**
+ * Upload a file (local path or URL) to Weixin CDN.
+ * Returns UploadedMedia with all params needed for sendMessage.
+ */
+export async function uploadMedia(params: {
+  source: string;       // file path or URL
+  mediaType: MediaType;
+  toUserId: string;
+  token: string;
+  baseUrl: string;
+}): Promise<UploadedMedia> {
+  const { source, mediaType, toUserId, token, baseUrl } = params;
+
+  // Load file
+  let plaintext: Buffer;
+  let fileName: string | undefined;
+
+  if (source.startsWith("http://") || source.startsWith("https://")) {
+    // Download remote file
+    const res = await fetch(source);
+    if (!res.ok) throw new Error(`Failed to download: ${source}`);
+    plaintext = Buffer.from(await res.arrayBuffer());
+    // Extract filename from URL
+    const urlPath = new URL(source).pathname;
+    fileName = path.basename(urlPath);
+  } else {
+    // Read local file
+    plaintext = await fs.readFile(source);
+    fileName = path.basename(source);
+  }
+
+  // Generate keys and hashes
+  const rawsize = plaintext.length;
+  const rawfilemd5 = crypto.createHash("md5").update(plaintext).digest("hex");
+  const filesize = aesEcbPaddedSize(rawsize);
+  const filekey = crypto.randomBytes(16).toString("hex");
+  const aeskey = crypto.randomBytes(16);
+
+  // Get upload URL
+  const uploadResp = await getUploadUrl({
+    filekey,
+    mediaType: MEDIA_TYPE_MAP[mediaType],
+    toUserId,
+    rawsize,
+    rawfilemd5,
+    filesize,
+    aeskey: aeskey.toString("hex"),
+    token,
+    baseUrl,
+  });
+
+  if (!uploadResp.upload_param) {
+    throw new Error(`getUploadUrl returned no upload_param: ${JSON.stringify(uploadResp)}`);
+  }
+
+  // Upload to CDN
+  const downloadEncryptedQueryParam = await uploadToCdn({
+    buf: plaintext,
+    uploadParam: uploadResp.upload_param,
+    filekey,
+    aeskey,
+  });
+
+  return {
+    filekey,
+    downloadEncryptedQueryParam,
+    aeskey: aeskey.toString("hex"),
+    fileSize: rawsize,
+    fileSizeCiphertext: filesize,
+    fileName,
+  };
+}

package/src/cli.ts

@@ -35,8 +35,10 @@ if (command === "login") {
 } else if (command === "start") {
   const portArg = process.argv.indexOf("--port");
   const port = portArg !== -1 ? Number(process.argv[portArg + 1]) : undefined;
+  const webhookArg = process.argv.indexOf("--webhook");
+  const webhook = webhookArg !== -1 ? process.argv[webhookArg + 1] : undefined;
   const { startDaemon } = await import("./daemon.js");
-  await startDaemon(port);
+  await startDaemon(port, webhook);
 
 } else if (command === "stop") {
   const { stopDaemon } = await import("./daemon.js");
@@ -115,7 +117,7 @@ Commands:
   (no args)                    Start stdio MCP server (Claude Desktop mode)
   login                        QR code login
   status                       Show account and daemon status
-  start [--port n]             Start HTTP MCP daemon in background (default: 3001)
+  start [--port n] [--webhook url]  Start HTTP daemon (with optional webhook push)
   stop                         Stop daemon
   restart                      Restart daemon
   logs [-f]                    Show daemon logs (-f to follow)

package/src/daemon.ts

@@ -50,7 +50,7 @@ export function daemonStatus(): { running: boolean; info: DaemonInfo | null } {
   return { running, info: running ? info : null };
 }
 
-export async function startDaemon(port = DEFAULT_PORT): Promise<void> {
+export async function startDaemon(port = DEFAULT_PORT, webhook?: string): Promise<void> {
   const { running, info } = daemonStatus();
   if (running && info) {
     console.log(`⚠️  Daemon already running (pid ${info.pid}, port ${info.port})`);
@@ -64,10 +64,13 @@ export async function startDaemon(port = DEFAULT_PORT): Promise<void> {
   const serverScript = path.join(__dirname, "server-http.js");
 
   const logFd = fs.openSync(LOG_FILE, "a");
-  const child = spawn(process.execPath, [serverScript, String(port)], {
+  const serverArgs = ["--port", String(port)];
+  if (webhook) serverArgs.push("--webhook", webhook);
+
+  const child = spawn(process.execPath, [serverScript, ...serverArgs], {
     detached: true,
     stdio: ["ignore", logFd, logFd],
-    env: { ...process.env, WEIXIN_MCP_PORT: String(port) },
+    env: { ...process.env, WEIXIN_MCP_PORT: String(port), WEIXIN_WEBHOOK_URL: webhook ?? "" },
   });
 
   child.unref();
@@ -93,6 +96,7 @@ export async function startDaemon(port = DEFAULT_PORT): Promise<void> {
   console.log(`   PID:  ${child.pid}`);
   console.log(`   Port: ${port}`);
   console.log(`   URL:  http://localhost:${port}/mcp`);
+  if (webhook) console.log(`   Webhook: ${webhook}`);
   console.log(`   Logs: ${LOG_FILE}`);
 }
 

package/src/index.ts

@@ -17,11 +17,14 @@ import {
   getUpdates,
   getConfig,
   sendTextMessage,
+  sendImageMessage,
+  sendFileMessage,
   loadCursor,
   saveCursor,
   WeixinAuthError,
   WeixinNetworkError,
 } from "./api.js";
+import { uploadMedia } from "./cdn.js";
 import { ACCOUNTS_DIR } from "./paths.js";
 import { updateContactsFromMsgs, loadContacts, type ContactBook } from "./contacts.js";
 
@@ -126,6 +129,36 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         "List users who have messaged the bot. Returns userId, lastSeen, lastText, contextToken, msgCount. Use userId as 'to' in weixin_send.",
       inputSchema: { type: "object", properties: {} },
     },
+    {
+      name: "weixin_send_image",
+      description:
+        "Send an image to a WeChat user. Source can be a local file path or URL. Optionally include a text caption.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          to: { type: "string", description: "Recipient user ID (full or short prefix)" },
+          source: { type: "string", description: "Image source: local file path or URL" },
+          caption: { type: "string", description: "Optional text caption to send with the image" },
+          context_token: { type: "string", description: "Optional context_token to link reply" },
+        },
+        required: ["to", "source"],
+      },
+    },
+    {
+      name: "weixin_send_file",
+      description:
+        "Send a file attachment to a WeChat user. Source can be a local file path or URL.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          to: { type: "string", description: "Recipient user ID (full or short prefix)" },
+          source: { type: "string", description: "File source: local file path or URL" },
+          caption: { type: "string", description: "Optional text caption to send with the file" },
+          context_token: { type: "string", description: "Optional context_token to link reply" },
+        },
+        required: ["to", "source"],
+      },
+    },
     {
       name: "weixin_get_config",
       description:
@@ -177,6 +210,44 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       result = resp;
     } else if (name === "weixin_contacts") {
       result = Object.values(loadContacts());
+    } else if (name === "weixin_send_image") {
+      const { to, source, caption, context_token } = (args ?? {}) as {
+        to?: string;
+        source?: string;
+        caption?: string;
+        context_token?: string;
+      };
+      const validatedTo = assertNonEmptyString(to, "to");
+      const resolvedTo = resolveUserId(validatedTo, loadContacts());
+      const validatedSource = assertNonEmptyString(source, "source");
+      const uploaded = await uploadMedia({
+        source: validatedSource,
+        mediaType: "image",
+        toUserId: resolvedTo,
+        token: token!,
+        baseUrl,
+      });
+      await sendImageMessage(resolvedTo, uploaded, token!, baseUrl, context_token, caption);
+      result = { success: true, filekey: uploaded.filekey };
+    } else if (name === "weixin_send_file") {
+      const { to, source, caption, context_token } = (args ?? {}) as {
+        to?: string;
+        source?: string;
+        caption?: string;
+        context_token?: string;
+      };
+      const validatedTo = assertNonEmptyString(to, "to");
+      const resolvedTo = resolveUserId(validatedTo, loadContacts());
+      const validatedSource = assertNonEmptyString(source, "source");
+      const uploaded = await uploadMedia({
+        source: validatedSource,
+        mediaType: "file",
+        toUserId: resolvedTo,
+        token: token!,
+        baseUrl,
+      });
+      await sendFileMessage(resolvedTo, uploaded, token!, baseUrl, context_token, caption);
+      result = { success: true, filekey: uploaded.filekey, fileName: uploaded.fileName };
     } else if (name === "weixin_get_config") {
       const { user_id, context_token } = (args ?? {}) as {
         user_id?: string;

package/src/server-http.ts

@@ -2,7 +2,11 @@
  * HTTP MCP server — runs as a daemon process.
  * Spawned by `weixin-mcp start`, listens on a given port.
  *
- * Clients connect via: http://localhost:<port>/mcp
+ * Features:
+ * - MCP endpoint at /mcp (StreamableHTTP)
+ * - Health check at /health
+ * - Webhook push: --webhook <url> to receive new messages via POST
+ * - Auto-poll: when webhook is set, background polling forwards messages
  */
 
 import express from "express";
@@ -14,7 +18,6 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import { randomUUID } from "node:crypto";
 
-// Reuse the same tool definitions and handlers from the main server
 import {
   DEFAULT_BASE_URL,
   getUpdates,
@@ -26,10 +29,16 @@ import {
   WeixinNetworkError,
 } from "./api.js";
 import { ACCOUNTS_DIR } from "./paths.js";
+import { updateContactsFromMsgs, loadContacts, type ContactBook } from "./contacts.js";
 import fs from "node:fs";
 import path from "node:path";
 
-const port = Number(process.env.WEIXIN_MCP_PORT ?? process.argv[2] ?? 3001);
+// Parse CLI args
+const args = process.argv.slice(2);
+const portIdx = args.indexOf("--port");
+const port = portIdx >= 0 ? Number(args[portIdx + 1]) : Number(process.env.WEIXIN_MCP_PORT ?? 3001);
+const webhookIdx = args.indexOf("--webhook");
+const webhookUrl = webhookIdx >= 0 ? args[webhookIdx + 1] : process.env.WEIXIN_WEBHOOK_URL;
 
 // ── Account loader ─────────────────────────────────────────────────────────
 
@@ -56,11 +65,19 @@ function fmtErr(e: unknown): string {
   return String(e);
 }
 
+function resolveUserId(input: string, contacts: ContactBook): string {
+  if (!input || input.includes("@")) return input;
+  const ids = Object.keys(contacts);
+  const matches = ids.filter((id) => id.startsWith(input) || id.includes(input));
+  if (matches.length === 1) return matches[0];
+  return input;
+}
+
 // ── MCP server factory ─────────────────────────────────────────────────────
 
 function createMCPServer() {
   const server = new Server(
-    { name: "weixin-mcp", version: "1.2.2" },
+    { name: "weixin-mcp", version: "1.5.0" },
     { capabilities: { tools: {} } },
   );
 
@@ -72,7 +89,7 @@ function createMCPServer() {
         inputSchema: {
           type: "object",
           properties: {
-            to: { type: "string" },
+            to: { type: "string", description: "Recipient (full ID or short prefix)" },
             text: { type: "string" },
             context_token: { type: "string" },
           },
@@ -87,6 +104,11 @@ function createMCPServer() {
           properties: { reset_cursor: { type: "boolean" } },
         },
       },
+      {
+        name: "weixin_contacts",
+        description: "List users who have messaged the bot.",
+        inputSchema: { type: "object", properties: {} },
+      },
       {
         name: "weixin_get_config",
         description: "Get user config (typing ticket, etc.).",
@@ -109,13 +131,17 @@ function createMCPServer() {
       let result: unknown;
       if (name === "weixin_send") {
         const a = (args ?? {}) as { to?: string; text?: string; context_token?: string };
-        result = await sendTextMessage(assertStr(a.to, "to"), assertStr(a.text, "text"), token!, baseUrl, a.context_token);
+        const resolvedTo = resolveUserId(assertStr(a.to, "to"), loadContacts());
+        result = await sendTextMessage(resolvedTo, assertStr(a.text, "text"), token!, baseUrl, a.context_token);
       } else if (name === "weixin_poll") {
         const { reset_cursor } = (args ?? {}) as { reset_cursor?: boolean };
         const cursor = reset_cursor ? "" : loadCursor(accountId);
         const resp = await getUpdates(token!, baseUrl, cursor);
         if (resp.get_updates_buf) saveCursor(accountId, resp.get_updates_buf);
+        if (resp.msgs && resp.msgs.length > 0) updateContactsFromMsgs(resp.msgs as unknown[]);
         result = resp;
+      } else if (name === "weixin_contacts") {
+        result = Object.values(loadContacts());
       } else if (name === "weixin_get_config") {
         const a = (args ?? {}) as { user_id?: string; context_token?: string };
         result = await getConfig(assertStr(a.user_id, "user_id"), token!, baseUrl, a.context_token);
@@ -131,21 +157,61 @@ function createMCPServer() {
   return server;
 }
 
+// ── Webhook push ───────────────────────────────────────────────────────────
+
+async function pushToWebhook(msgs: unknown[]) {
+  if (!webhookUrl || msgs.length === 0) return;
+  try {
+    await fetch(webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ event: "weixin_messages", messages: msgs, timestamp: new Date().toISOString() }),
+    });
+  } catch (err) {
+    console.error("[weixin-mcp] webhook push failed:", fmtErr(err));
+  }
+}
+
+// ── Background poller (when webhook is set) ────────────────────────────────
+
+async function startBackgroundPoller() {
+  if (!webhookUrl) return;
+  console.log(`[weixin-mcp] Webhook enabled: ${webhookUrl}`);
+  console.log("[weixin-mcp] Starting background poller...");
+
+  while (true) {
+    try {
+      const { token, baseUrl = DEFAULT_BASE_URL, accountId } = loadAccount();
+      const cursor = loadCursor(accountId);
+      const resp = await getUpdates(token!, baseUrl, cursor);
+
+      if (resp.get_updates_buf) saveCursor(accountId, resp.get_updates_buf);
+
+      if (resp.msgs && resp.msgs.length > 0) {
+        updateContactsFromMsgs(resp.msgs as unknown[]);
+        await pushToWebhook(resp.msgs);
+        console.log(`[weixin-mcp] Pushed ${resp.msgs.length} message(s) to webhook`);
+      }
+    } catch (err) {
+      console.error("[weixin-mcp] poll error:", fmtErr(err));
+      await new Promise((r) => setTimeout(r, 5000)); // backoff on error
+    }
+    // getUpdates is long-poll (~30s timeout), so no extra delay needed
+  }
+}
+
 // ── Express HTTP server ────────────────────────────────────────────────────
 
 const app = express();
 app.use(express.json());
 
-// Session store for stateful transports
 const sessions = new Map<string, StreamableHTTPServerTransport>();
 
 app.post("/mcp", async (req, res) => {
-  // Check if this is an existing session
   const sessionId = req.headers["mcp-session-id"] as string | undefined;
   let transport = sessionId ? sessions.get(sessionId) : undefined;
 
   if (!transport) {
-    // New session
     const newSessionId = randomUUID();
     transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: () => newSessionId,
@@ -174,10 +240,11 @@ app.delete("/mcp", async (req, res) => {
 });
 
 app.get("/health", (_req, res) => {
-  res.json({ status: "ok", port, sessions: sessions.size });
+  res.json({ status: "ok", port, sessions: sessions.size, webhook: webhookUrl ?? null });
 });
 
 app.listen(port, () => {
-  console.log(`[weixin-mcp] HTTP MCP server listening on port ${port}`);
-  console.log(`[weixin-mcp] MCP endpoint: http://localhost:${port}/mcp`);
+  console.log(`[weixin-mcp] HTTP MCP server on port ${port}`);
+  console.log(`[weixin-mcp] MCP: http://localhost:${port}/mcp`);
+  if (webhookUrl) startBackgroundPoller();
 });