weixin-mcp 1.0.2 → 1.1.0

package/dist/api.d.ts

@@ -6,13 +6,30 @@ export declare class WeixinNetworkError extends Error {
     constructor(message: string);
 }
 export declare function generateClientId(): string;
+export declare function loadCursor(accountId: string): string;
+export declare function saveCursor(accountId: string, cursor: string): void;
 export declare function weixinRequest(endpoint: string, body: unknown, token: string, baseUrl?: string, retries?: number): Promise<unknown>;
-/** Send a text message. Uses real endpoint: ilink/bot/sendmessage */
-export declare function sendTextMessage(to: string, text: string, token: string, baseUrl: string): Promise<unknown>;
-/** Long-poll for new messages. Uses real endpoint: ilink/bot/getupdates */
-export declare function pollMessages(token: string, baseUrl: string, timeoutMs?: number): Promise<unknown>;
-/** Get bot config for a user (includes context_token for replies). */
-export declare function getConfig(ilinkUserId: string, token: string, baseUrl: string): Promise<unknown>;
-export declare function getContacts(_token: string, _baseUrl: string): Promise<{
-    note: string;
+/**
+ * Send a text message.
+ * Pass contextToken from the received message to link the reply to the conversation.
+ */
+export declare function sendTextMessage(to: string, text: string, token: string, baseUrl: string, contextToken?: string): Promise<unknown>;
+/**
+ * Long-poll for new messages.
+ * Pass the cursor from the previous response to avoid re-receiving old messages.
+ */
+export declare function getUpdates(token: string, baseUrl: string, cursor?: string): Promise<{
+    msgs?: unknown[];
+    get_updates_buf?: string;
+    ret?: number;
+    errcode?: number;
 }>;
+/**
+ * Get bot config for a user (includes typing_ticket and context_token).
+ */
+export declare function getConfig(ilinkUserId: string, token: string, baseUrl: string, contextToken?: string): Promise<unknown>;
+/**
+ * Send typing indicator.
+ * status: 1 = typing, 2 = cancel
+ */
+export declare function sendTyping(ilinkUserId: string, typingTicket: string, status: 1 | 2, token: string, baseUrl: string): Promise<unknown>;

package/dist/api.js

@@ -1,8 +1,11 @@
 import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
 export const DEFAULT_BASE_URL = "https://ilinkai.weixin.qq.com";
-const AUTH_ERROR_STATUSES = new Set([401, 403]);
+const CHANNEL_VERSION = "1.0.2";
 export class WeixinAuthError extends Error {
-    constructor(message = "Authentication failed. Run npm run login to re-authenticate.") {
+    constructor(message = "Authentication failed. Run: npm run login") {
         super(message);
         this.name = "WeixinAuthError";
     }
@@ -13,21 +16,56 @@ export class WeixinNetworkError extends Error {
         this.name = "WeixinNetworkError";
     }
 }
+// ── Helpers ────────────────────────────────────────────────────────────────
 export function generateClientId() {
-    return `openclaw-weixin-mcp-${crypto.randomUUID().replace(/-/g, "").slice(0, 16)}`;
+    return `weixin-mcp-${crypto.randomUUID().replace(/-/g, "").slice(0, 16)}`;
 }
+/** X-WECHAT-UIN: base64-encoded random uint32, required by backend */
+function randomWechatUin() {
+    const buf = crypto.randomBytes(4);
+    return buf.toString("base64");
+}
+function buildHeaders(token, bodyStr) {
+    return {
+        "Content-Type": "application/json",
+        "Content-Length": String(Buffer.byteLength(bodyStr, "utf-8")),
+        "AuthorizationType": "ilink_bot_token",
+        "Authorization": `Bearer ${token}`,
+        "X-WECHAT-UIN": randomWechatUin(),
+    };
+}
+// ── Cursor persistence ─────────────────────────────────────────────────────
+const STATE_DIR = process.env.OPENCLAW_STATE_DIR?.trim() ||
+    path.join(os.homedir(), ".openclaw");
+function cursorPath(accountId) {
+    return path.join(STATE_DIR, "openclaw-weixin", "accounts", `${accountId}.cursor.json`);
+}
+export function loadCursor(accountId) {
+    try {
+        const data = JSON.parse(fs.readFileSync(cursorPath(accountId), "utf-8"));
+        return data.cursor ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+export function saveCursor(accountId, cursor) {
+    try {
+        fs.writeFileSync(cursorPath(accountId), JSON.stringify({ cursor }));
+    }
+    catch {
+        // non-fatal
+    }
+}
+// ── Core request ───────────────────────────────────────────────────────────
 async function parseErrorResponse(res) {
     try {
-        const text = await res.text();
-        return text.trim() || `HTTP ${res.status}`;
+        return (await res.text()).trim() || `HTTP ${res.status}`;
     }
     catch {
         return `HTTP ${res.status}`;
     }
 }
-function isTransientNetworkError(error) {
-    return error instanceof TypeError || error instanceof WeixinNetworkError;
-}
 export async function weixinRequest(endpoint, body, token, baseUrl = DEFAULT_BASE_URL, retries = 1) {
     const base = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
     const url = new URL(endpoint, base).toString();
@@ -36,40 +74,35 @@ export async function weixinRequest(endpoint, body, token, baseUrl = DEFAULT_BAS
         try {
             const res = await fetch(url, {
                 method: "POST",
-                headers: {
-                    "Content-Type": "application/json",
-                    "Content-Length": String(Buffer.byteLength(bodyStr, "utf-8")),
-                    "AuthorizationType": "ilink_bot_token",
-                    "Authorization": `Bearer ${token}`,
-                },
+                headers: buildHeaders(token, bodyStr),
                 body: bodyStr,
             });
-            if (AUTH_ERROR_STATUSES.has(res.status)) {
+            if (res.status === 401 || res.status === 403)
                 throw new WeixinAuthError();
-            }
             if (!res.ok) {
-                const message = await parseErrorResponse(res);
-                throw new Error(`Weixin API error ${res.status}: ${message}`);
+                const msg = await parseErrorResponse(res);
+                throw new Error(`Weixin API error ${res.status}: ${msg}`);
             }
             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;
+        catch (err) {
+            if (err instanceof WeixinAuthError)
+                throw err;
+            if (err instanceof TypeError && attempt < retries)
+                continue; // network retry
+            if (err instanceof TypeError)
+                throw new WeixinNetworkError(String(err));
+            throw err;
         }
     }
-    throw new WeixinNetworkError("Network request failed");
+    throw new WeixinNetworkError("Network request failed after retries");
 }
-/** Send a text message. Uses real endpoint: ilink/bot/sendmessage */
-export async function sendTextMessage(to, text, token, baseUrl) {
+// ── API functions ──────────────────────────────────────────────────────────
+/**
+ * Send a text message.
+ * Pass contextToken from the received message to link the reply to the conversation.
+ */
+export async function sendTextMessage(to, text, token, baseUrl, contextToken) {
     return weixinRequest("ilink/bot/sendmessage", {
         msg: {
             from_user_id: "",
@@ -78,27 +111,40 @@ export async function sendTextMessage(to, text, token, baseUrl) {
             message_type: 2, // BOT
             message_state: 2, // FINISH
             item_list: [{ type: 1, text_item: { text } }],
+            ...(contextToken ? { context_token: contextToken } : {}),
         },
-        base_info: { channel_version: "1.0.1" },
+        base_info: { channel_version: CHANNEL_VERSION },
     }, token, baseUrl);
 }
-/** Long-poll for new messages. Uses real endpoint: ilink/bot/getupdates */
-export async function pollMessages(token, baseUrl, timeoutMs = 5000) {
+/**
+ * Long-poll for new messages.
+ * Pass the cursor from the previous response to avoid re-receiving old messages.
+ */
+export async function getUpdates(token, baseUrl, cursor = "") {
     return weixinRequest("ilink/bot/getupdates", {
-        timeout_ms: timeoutMs,
-        base_info: { channel_version: "1.0.1" },
+        get_updates_buf: cursor,
+        base_info: { channel_version: CHANNEL_VERSION },
     }, token, baseUrl);
 }
-/** Get bot config for a user (includes context_token for replies). */
-export async function getConfig(ilinkUserId, token, baseUrl) {
+/**
+ * Get bot config for a user (includes typing_ticket and context_token).
+ */
+export async function getConfig(ilinkUserId, token, baseUrl, contextToken) {
     return weixinRequest("ilink/bot/getconfig", {
         ilink_user_id: ilinkUserId,
-        base_info: { channel_version: "1.0.1" },
+        ...(contextToken ? { context_token: contextToken } : {}),
+        base_info: { channel_version: CHANNEL_VERSION },
     }, token, baseUrl);
 }
-// Note: WeChat bot API does not have a standalone contacts/history endpoint.
-// Contacts are tracked from incoming messages (getupdates).
-// Keeping a stub for MCP compatibility:
-export async function getContacts(_token, _baseUrl) {
-    return { note: "WeChat bot API does not support listing contacts. Use weixin_poll_messages to receive incoming messages and track senders." };
+/**
+ * Send typing indicator.
+ * status: 1 = typing, 2 = cancel
+ */
+export async function sendTyping(ilinkUserId, typingTicket, status, token, baseUrl) {
+    return weixinRequest("ilink/bot/sendtyping", {
+        ilink_user_id: ilinkUserId,
+        typing_ticket: typingTicket,
+        status,
+        base_info: { channel_version: CHANNEL_VERSION },
+    }, token, baseUrl);
 }

package/dist/index.js

@@ -9,25 +9,26 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
-import { DEFAULT_BASE_URL, getContacts, pollMessages, sendTextMessage, WeixinAuthError, WeixinNetworkError, } from "./api.js";
+import { DEFAULT_BASE_URL, getUpdates, getConfig, sendTextMessage, loadCursor, saveCursor, 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"));
+    const files = fs
+        .readdirSync(WEIXIN_DIR)
+        .filter((f) => f.endsWith(".json") && !f.endsWith(".sync.json") && !f.endsWith(".cursor.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
+        throw new Error("No WeChat account found. Run: npm run login");
     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.`);
+        throw new Error(`No token for account ${accountId}. Re-run: npm run login`);
     return { ...data, accountId };
 }
-// ── Weixin API ─────────────────────────────────────────────────────────────
+// ── Helpers ────────────────────────────────────────────────────────────────
 function assertNonEmptyString(value, field) {
     if (typeof value !== "string" || value.trim() === "") {
         throw new Error(`Invalid argument "${field}": must be a non-empty string`);
@@ -35,84 +36,86 @@ function assertNonEmptyString(value, field) {
     return value.trim();
 }
 function formatToolError(error) {
-    if (error instanceof WeixinAuthError) {
+    if (error instanceof WeixinAuthError)
         return error.message;
-    }
-    if (error instanceof WeixinNetworkError) {
-        return `Network error while calling Weixin API: ${error.message}`;
-    }
-    if (error instanceof Error) {
+    if (error instanceof WeixinNetworkError)
+        return `Network error: ${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: {} } });
+const server = new Server({ name: "weixin-mcp", version: "1.0.2" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
         {
             name: "weixin_send",
-            description: "Send a WeChat message to a user (by user ID or OpenId)",
+            description: "Send a WeChat text message to a user. Pass context_token from a received message to link the reply to the conversation thread.",
             inputSchema: {
                 type: "object",
                 properties: {
                     to: { type: "string", description: "Recipient user ID / OpenId" },
                     text: { type: "string", description: "Message text to send" },
+                    context_token: {
+                        type: "string",
+                        description: "Optional: context_token from a received message, links the reply to the conversation",
+                    },
                 },
                 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",
+            name: "weixin_poll",
+            description: "Poll for new WeChat messages. Uses a persistent cursor to avoid re-delivering old messages. Returns new messages since last poll.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    since_ts: { type: "number", description: "Unix timestamp in ms (optional)" },
+                    reset_cursor: {
+                        type: "boolean",
+                        description: "If true, reset cursor and re-fetch from the beginning (useful for debugging)",
+                    },
                 },
             },
         },
         {
-            name: "weixin_get_history",
-            description: "Get chat history with a WeChat contact",
+            name: "weixin_get_config",
+            description: "Get bot config for a user — includes typing_ticket needed for sendTyping. Call before sending typing indicators.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    to: { type: "string", description: "Contact user ID / OpenId" },
-                    limit: { type: "number", description: "Number of messages (default 20)" },
+                    user_id: { type: "string", description: "Target user ID / OpenId" },
+                    context_token: { type: "string", description: "Optional context token" },
                 },
-                required: ["to"],
+                required: ["user_id"],
             },
         },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const account = loadAccount();
-    const { token, baseUrl = DEFAULT_BASE_URL } = account;
+    const { token, baseUrl = DEFAULT_BASE_URL, accountId } = account;
     const { name, arguments: args } = req.params;
     try {
         let result;
         if (name === "weixin_send") {
-            const { to, text } = (args ?? {});
+            const { to, text, context_token } = (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);
+            result = await sendTextMessage(validatedTo, validatedText, token, baseUrl, context_token);
         }
-        else if (name === "weixin_poll_messages") {
-            const { since_ts } = (args ?? {});
-            result = await pollMessages(token, baseUrl, since_ts);
+        else if (name === "weixin_poll") {
+            const { reset_cursor } = (args ?? {});
+            const cursor = reset_cursor ? "" : loadCursor(accountId);
+            const resp = await getUpdates(token, baseUrl, cursor);
+            // Persist new cursor for next poll
+            if (resp.get_updates_buf)
+                saveCursor(accountId, resp.get_updates_buf);
+            result = resp;
         }
-        else if (name === "weixin_get_history") {
-            const { to, limit = 20 } = (args ?? {});
-            result = { note: "WeChat bot API does not support fetching chat history." };
+        else if (name === "weixin_get_config") {
+            const { user_id, context_token } = (args ?? {});
+            const validatedUserId = assertNonEmptyString(user_id, "user_id");
+            result = await getConfig(validatedUserId, token, baseUrl, context_token);
         }
         else {
             throw new Error(`Unknown tool: ${name}`);

package/package.json

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

package/src/api.ts

@@ -1,11 +1,13 @@
 import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
 
 export const DEFAULT_BASE_URL = "https://ilinkai.weixin.qq.com";
-
-const AUTH_ERROR_STATUSES = new Set([401, 403]);
+const CHANNEL_VERSION = "1.0.2";
 
 export class WeixinAuthError extends Error {
-  constructor(message = "Authentication failed. Run npm run login to re-authenticate.") {
+  constructor(message = "Authentication failed. Run: npm run login") {
     super(message);
     this.name = "WeixinAuthError";
   }
@@ -18,21 +20,63 @@ export class WeixinNetworkError extends Error {
   }
 }
 
+// ── Helpers ────────────────────────────────────────────────────────────────
+
 export function generateClientId(): string {
-  return `openclaw-weixin-mcp-${crypto.randomUUID().replace(/-/g, "").slice(0, 16)}`;
+  return `weixin-mcp-${crypto.randomUUID().replace(/-/g, "").slice(0, 16)}`;
 }
 
-async function parseErrorResponse(res: Response): Promise<string> {
+/** X-WECHAT-UIN: base64-encoded random uint32, required by backend */
+function randomWechatUin(): string {
+  const buf = crypto.randomBytes(4);
+  return buf.toString("base64");
+}
+
+function buildHeaders(token: string, bodyStr: string): Record<string, string> {
+  return {
+    "Content-Type": "application/json",
+    "Content-Length": String(Buffer.byteLength(bodyStr, "utf-8")),
+    "AuthorizationType": "ilink_bot_token",
+    "Authorization": `Bearer ${token}`,
+    "X-WECHAT-UIN": randomWechatUin(),
+  };
+}
+
+// ── Cursor persistence ─────────────────────────────────────────────────────
+
+const STATE_DIR =
+  process.env.OPENCLAW_STATE_DIR?.trim() ||
+  path.join(os.homedir(), ".openclaw");
+
+function cursorPath(accountId: string): string {
+  return path.join(STATE_DIR, "openclaw-weixin", "accounts", `${accountId}.cursor.json`);
+}
+
+export function loadCursor(accountId: string): string {
   try {
-    const text = await res.text();
-    return text.trim() || `HTTP ${res.status}`;
+    const data = JSON.parse(fs.readFileSync(cursorPath(accountId), "utf-8")) as { cursor?: string };
+    return data.cursor ?? "";
   } catch {
-    return `HTTP ${res.status}`;
+    return "";
   }
 }
 
-function isTransientNetworkError(error: unknown): boolean {
-  return error instanceof TypeError || error instanceof WeixinNetworkError;
+export function saveCursor(accountId: string, cursor: string): void {
+  try {
+    fs.writeFileSync(cursorPath(accountId), JSON.stringify({ cursor }));
+  } catch {
+    // non-fatal
+  }
+}
+
+// ── Core request ───────────────────────────────────────────────────────────
+
+async function parseErrorResponse(res: Response): Promise<string> {
+  try {
+    return (await res.text()).trim() || `HTTP ${res.status}`;
+  } catch {
+    return `HTTP ${res.status}`;
+  }
 }
 
 export async function weixinRequest(
@@ -50,49 +94,39 @@ export async function weixinRequest(
     try {
       const res = await fetch(url, {
         method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "Content-Length": String(Buffer.byteLength(bodyStr, "utf-8")),
-          "AuthorizationType": "ilink_bot_token",
-          "Authorization": `Bearer ${token}`,
-        },
+        headers: buildHeaders(token, bodyStr),
         body: bodyStr,
       });
 
-      if (AUTH_ERROR_STATUSES.has(res.status)) {
-        throw new WeixinAuthError();
-      }
-
+      if (res.status === 401 || res.status === 403) throw new WeixinAuthError();
       if (!res.ok) {
-        const message = await parseErrorResponse(res);
-        throw new Error(`Weixin API error ${res.status}: ${message}`);
+        const msg = await parseErrorResponse(res);
+        throw new Error(`Weixin API error ${res.status}: ${msg}`);
       }
-
       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;
+    } catch (err) {
+      if (err instanceof WeixinAuthError) throw err;
+      if (err instanceof TypeError && attempt < retries) continue; // network retry
+      if (err instanceof TypeError) throw new WeixinNetworkError(String(err));
+      throw err;
     }
   }
-
-  throw new WeixinNetworkError("Network request failed");
+  throw new WeixinNetworkError("Network request failed after retries");
 }
 
-/** Send a text message. Uses real endpoint: ilink/bot/sendmessage */
-export async function sendTextMessage(to: string, text: string, token: string, baseUrl: string) {
+// ── API functions ──────────────────────────────────────────────────────────
+
+/**
+ * Send a text message.
+ * Pass contextToken from the received message to link the reply to the conversation.
+ */
+export async function sendTextMessage(
+  to: string,
+  text: string,
+  token: string,
+  baseUrl: string,
+  contextToken?: string,
+) {
   return weixinRequest(
     "ilink/bot/sendmessage",
     {
@@ -100,46 +134,74 @@ export async function sendTextMessage(to: string, text: string, token: string, b
         from_user_id: "",
         to_user_id: to,
         client_id: generateClientId(),
-        message_type: 2,   // BOT
-        message_state: 2,  // FINISH
+        message_type: 2,  // BOT
+        message_state: 2, // FINISH
         item_list: [{ type: 1, text_item: { text } }],
+        ...(contextToken ? { context_token: contextToken } : {}),
       },
-      base_info: { channel_version: "1.0.1" },
+      base_info: { channel_version: CHANNEL_VERSION },
     },
     token,
     baseUrl,
   );
 }
 
-/** Long-poll for new messages. Uses real endpoint: ilink/bot/getupdates */
-export async function pollMessages(token: string, baseUrl: string, timeoutMs = 5000) {
+/**
+ * Long-poll for new messages.
+ * Pass the cursor from the previous response to avoid re-receiving old messages.
+ */
+export async function getUpdates(
+  token: string,
+  baseUrl: string,
+  cursor = "",
+): Promise<{ msgs?: unknown[]; get_updates_buf?: string; ret?: number; errcode?: number }> {
   return weixinRequest(
     "ilink/bot/getupdates",
     {
-      timeout_ms: timeoutMs,
-      base_info: { channel_version: "1.0.1" },
+      get_updates_buf: cursor,
+      base_info: { channel_version: CHANNEL_VERSION },
     },
     token,
     baseUrl,
-  );
+  ) as Promise<{ msgs?: unknown[]; get_updates_buf?: string; ret?: number; errcode?: number }>;
 }
 
-/** Get bot config for a user (includes context_token for replies). */
-export async function getConfig(ilinkUserId: string, token: string, baseUrl: string) {
+/**
+ * Get bot config for a user (includes typing_ticket and context_token).
+ */
+export async function getConfig(ilinkUserId: string, token: string, baseUrl: string, contextToken?: string) {
   return weixinRequest(
     "ilink/bot/getconfig",
     {
       ilink_user_id: ilinkUserId,
-      base_info: { channel_version: "1.0.1" },
+      ...(contextToken ? { context_token: contextToken } : {}),
+      base_info: { channel_version: CHANNEL_VERSION },
     },
     token,
     baseUrl,
   );
 }
 
-// Note: WeChat bot API does not have a standalone contacts/history endpoint.
-// Contacts are tracked from incoming messages (getupdates).
-// Keeping a stub for MCP compatibility:
-export async function getContacts(_token: string, _baseUrl: string) {
-  return { note: "WeChat bot API does not support listing contacts. Use weixin_poll_messages to receive incoming messages and track senders." };
+/**
+ * Send typing indicator.
+ * status: 1 = typing, 2 = cancel
+ */
+export async function sendTyping(
+  ilinkUserId: string,
+  typingTicket: string,
+  status: 1 | 2,
+  token: string,
+  baseUrl: string,
+) {
+  return weixinRequest(
+    "ilink/bot/sendtyping",
+    {
+      ilink_user_id: ilinkUserId,
+      typing_ticket: typingTicket,
+      status,
+      base_info: { channel_version: CHANNEL_VERSION },
+    },
+    token,
+    baseUrl,
+  );
 }

package/src/index.ts

@@ -15,10 +15,11 @@ import path from "node:path";
 import os from "node:os";
 import {
   DEFAULT_BASE_URL,
-  
-  getContacts,
-  pollMessages,
+  getUpdates,
+  getConfig,
   sendTextMessage,
+  loadCursor,
+  saveCursor,
   WeixinAuthError,
   WeixinNetworkError,
 } from "./api.js";
@@ -40,18 +41,22 @@ interface AccountData {
 }
 
 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 files = fs
+    .readdirSync(WEIXIN_DIR)
+    .filter((f) => f.endsWith(".json") && !f.endsWith(".sync.json") && !f.endsWith(".cursor.json"));
+  if (files.length === 0)
+    throw new Error("No WeChat account found. Run: npm run login");
+
+  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.`);
+  if (!data.token)
+    throw new Error(`No token for account ${accountId}. Re-run: npm run login`);
   return { ...data, accountId };
 }
 
-// ── Weixin API ─────────────────────────────────────────────────────────────
+// ── Helpers ────────────────────────────────────────────────────────────────
 
 function assertNonEmptyString(value: unknown, field: string): string {
   if (typeof value !== "string" || value.trim() === "") {
@@ -61,25 +66,17 @@ function assertNonEmptyString(value: unknown, field: string): string {
 }
 
 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;
-  }
-
+  if (error instanceof WeixinAuthError) return error.message;
+  if (error instanceof WeixinNetworkError)
+    return `Network error: ${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" },
+  { name: "weixin-mcp", version: "1.0.2" },
   { capabilities: { tools: {} } },
 );
 
@@ -87,41 +84,48 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     {
       name: "weixin_send",
-      description: "Send a WeChat message to a user (by user ID or OpenId)",
+      description:
+        "Send a WeChat text message to a user. Pass context_token from a received message to link the reply to the conversation thread.",
       inputSchema: {
         type: "object",
         properties: {
           to: { type: "string", description: "Recipient user ID / OpenId" },
           text: { type: "string", description: "Message text to send" },
+          context_token: {
+            type: "string",
+            description:
+              "Optional: context_token from a received message, links the reply to the conversation",
+          },
         },
         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",
+      name: "weixin_poll",
+      description:
+        "Poll for new WeChat messages. Uses a persistent cursor to avoid re-delivering old messages. Returns new messages since last poll.",
       inputSchema: {
         type: "object",
         properties: {
-          since_ts: { type: "number", description: "Unix timestamp in ms (optional)" },
+          reset_cursor: {
+            type: "boolean",
+            description:
+              "If true, reset cursor and re-fetch from the beginning (useful for debugging)",
+          },
         },
       },
     },
     {
-      name: "weixin_get_history",
-      description: "Get chat history with a WeChat contact",
+      name: "weixin_get_config",
+      description:
+        "Get bot config for a user — includes typing_ticket needed for sendTyping. Call before sending typing indicators.",
       inputSchema: {
         type: "object",
         properties: {
-          to: { type: "string", description: "Contact user ID / OpenId" },
-          limit: { type: "number", description: "Number of messages (default 20)" },
+          user_id: { type: "string", description: "Target user ID / OpenId" },
+          context_token: { type: "string", description: "Optional context token" },
         },
-        required: ["to"],
+        required: ["user_id"],
       },
     },
   ],
@@ -129,7 +133,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 
 server.setRequestHandler(CallToolRequestSchema, async (req) => {
   const account = loadAccount();
-  const { token, baseUrl = DEFAULT_BASE_URL } = account;
+  const { token, baseUrl = DEFAULT_BASE_URL, accountId } = account;
 
   const { name, arguments: args } = req.params;
 
@@ -137,18 +141,34 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     let result: unknown;
 
     if (name === "weixin_send") {
-      const { to, text } = (args ?? {}) as { to?: string; text?: string };
+      const { to, text, context_token } = (args ?? {}) as {
+        to?: string;
+        text?: string;
+        context_token?: 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 };
-      result = { note: "WeChat bot API does not support fetching chat history." };
+      result = await sendTextMessage(
+        validatedTo,
+        validatedText,
+        token!,
+        baseUrl,
+        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);
+      // Persist new cursor for next poll
+      if (resp.get_updates_buf) saveCursor(accountId, resp.get_updates_buf);
+      result = resp;
+    } else if (name === "weixin_get_config") {
+      const { user_id, context_token } = (args ?? {}) as {
+        user_id?: string;
+        context_token?: string;
+      };
+      const validatedUserId = assertNonEmptyString(user_id, "user_id");
+      result = await getConfig(validatedUserId, token!, baseUrl, context_token);
     } else {
       throw new Error(`Unknown tool: ${name}`);
     }

package/test-poll.mjs

@@ -1,16 +1,31 @@
-import { pollMessages } from './dist/api.js'
+import { getUpdates, loadCursor, saveCursor } from './dist/api.js'
 import fs from 'node:fs'
 import path from 'node:path'
 import os from 'node:os'
 
 const dir = path.join(os.homedir(), '.openclaw', 'openclaw-weixin', 'accounts')
-const files = fs.readdirSync(dir).filter(f => !f.endsWith('.sync.json'))
+const files = fs.readdirSync(dir).filter(f => f.endsWith('.json') && !f.endsWith('.sync.json') && !f.endsWith('.cursor.json'))
+const accountId = files[0].replace('.json', '')
 const data = JSON.parse(fs.readFileSync(path.join(dir, files[0]), 'utf8'))
 
-console.log('Testing pollMessages...')
-try {
-  const result = await pollMessages(data.token, data.baseUrl, 3000)
-  console.log('✅ Response:', JSON.stringify(result, null, 2).slice(0, 500))
-} catch (e) {
-  console.error('❌ Error:', e.message)
+console.log('Account:', accountId)
+const cursor = loadCursor(accountId)
+console.log('Cursor:', cursor ? cursor.slice(0, 20) + '...' : '(empty — first poll)')
+
+const resp = await getUpdates(data.token, data.baseUrl, cursor)
+console.log('ret:', resp.ret, '| msgs count:', resp.msgs?.length ?? 0)
+
+if (resp.get_updates_buf) {
+  saveCursor(accountId, resp.get_updates_buf)
+  console.log('✅ Cursor saved')
+}
+
+if (resp.msgs?.length > 0) {
+  const m = resp.msgs[0]
+  console.log('\nFirst message:')
+  console.log('  from:', m.from_user_id)
+  console.log('  type:', m.message_type, '| state:', m.message_state)
+  const text = m.item_list?.find(i => i.type === 1)?.text_item?.text
+  if (text) console.log('  text:', text.slice(0, 100))
+  console.log('  context_token:', m.context_token ? m.context_token.slice(0, 30) + '...' : '(none)')
 }