@paean-ai/wechat-mcp 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,195 @@
+interface AccountData {
+    token: string;
+    baseUrl: string;
+    accountId: string;
+    userId?: string;
+    savedAt: string;
+}
+interface QRCodeResponse {
+    qrcode: string;
+    qrcode_img_content: string;
+}
+interface QRStatusResponse {
+    status: "wait" | "scaned" | "confirmed" | "expired";
+    bot_token?: string;
+    ilink_bot_id?: string;
+    baseurl?: string;
+    ilink_user_id?: string;
+}
+interface TextItem {
+    text?: string;
+}
+interface RefMessage {
+    message_item?: MessageItem;
+    title?: string;
+}
+interface MessageItem {
+    type?: number;
+    text_item?: TextItem;
+    voice_item?: {
+        text?: string;
+    };
+    ref_msg?: RefMessage;
+}
+interface WeixinMessage {
+    from_user_id?: string;
+    to_user_id?: string;
+    client_id?: string;
+    session_id?: string;
+    message_type?: number;
+    message_state?: number;
+    item_list?: MessageItem[];
+    context_token?: string;
+    create_time_ms?: number;
+}
+interface GetUpdatesResp {
+    ret?: number;
+    errcode?: number;
+    errmsg?: string;
+    msgs?: WeixinMessage[];
+    get_updates_buf?: string;
+    longpolling_timeout_ms?: number;
+}
+interface AgentRegistration {
+    agentId: string;
+    name: string;
+    registeredAt: string;
+}
+interface RoutedMessage {
+    id: string;
+    senderId: string;
+    senderName: string;
+    text: string;
+    rawText: string;
+    contextToken: string;
+    targetAgent: string | null;
+    timestamp: number;
+}
+interface WechatContact {
+    userId: string;
+    contextToken: string;
+    lastSeen: string;
+    displayName?: string;
+}
+interface DaemonInfo {
+    pid: number;
+    port: number;
+    startedAt: string;
+}
+interface DaemonStatus {
+    running: boolean;
+    wechatConnected: boolean;
+    accountId?: string;
+    agents: AgentRegistration[];
+    uptime: number;
+}
+interface SendMessageRequest {
+    to: string;
+    text: string;
+    agentId: string;
+}
+interface SendMessageResponse {
+    success: boolean;
+    error?: string;
+}
+interface PollMessagesResponse {
+    messages: RoutedMessage[];
+}
+
+/**
+ * Unified WeChat iLink API Client
+ *
+ * Handles all communication with the WeChat iLink bot API:
+ * QR login, long-polling for messages, and sending replies.
+ */
+
+declare function fetchQRCode(baseUrl: string): Promise<QRCodeResponse>;
+declare function pollQRStatus(baseUrl: string, qrcode: string): Promise<QRStatusResponse>;
+declare function getUpdates(baseUrl: string, token: string, getUpdatesBuf: string): Promise<GetUpdatesResp>;
+declare function sendTextMessage(baseUrl: string, token: string, to: string, text: string, contextToken: string): Promise<string>;
+declare function extractTextFromMessage(msg: WeixinMessage): string;
+
+/**
+ * Credential & Contact Storage
+ *
+ * All state is stored under ~/.wechat-mcp/ with restrictive permissions.
+ */
+
+declare function loadCredentials(): AccountData | null;
+declare function saveCredentials(data: AccountData): void;
+declare function removeCredentials(): void;
+declare function loadContacts(): WechatContact[];
+declare function saveContact(userId: string, contextToken: string): void;
+declare function getContactToken(userId: string): string | null;
+
+/**
+ * Daemon Lifecycle Management
+ *
+ * Handles auto-starting, health checking, and stopping the daemon process.
+ * MCP server processes call ensureDaemon() to auto-start if needed.
+ */
+
+/**
+ * Check if the daemon is currently running and healthy.
+ * Returns the daemon info if healthy, null otherwise.
+ */
+declare function checkDaemon(): Promise<DaemonInfo | null>;
+/**
+ * Ensure the daemon is running. Auto-starts if needed.
+ * Returns the daemon info (port, pid).
+ */
+declare function ensureDaemon(): Promise<DaemonInfo>;
+/**
+ * Stop the running daemon.
+ */
+declare function stopDaemon(): Promise<boolean>;
+
+/**
+ * Daemon HTTP Client
+ *
+ * Thin client used by MCP server processes to communicate with the daemon
+ * over its local HTTP API.
+ */
+
+declare class DaemonClient {
+    private baseUrl;
+    constructor(port: number);
+    private request;
+    health(): Promise<boolean>;
+    status(): Promise<DaemonStatus>;
+    registerAgent(agentId: string, name?: string): Promise<AgentRegistration>;
+    unregisterAgent(agentId: string): Promise<{
+        removed: boolean;
+    }>;
+    /**
+     * Long-poll for messages intended for this agent.
+     * Will block up to ~30s on the daemon side.
+     */
+    pollMessages(agentId: string): Promise<RoutedMessage[]>;
+    send(to: string, text: string, agentId: string): Promise<SendMessageResponse>;
+    getContacts(): Promise<WechatContact[]>;
+}
+
+/**
+ * Message Router
+ *
+ * Parses incoming WeChat messages for @agent_name mentions and routes
+ * them to the appropriate agent. Messages without a mention go to the
+ * default agent.
+ */
+
+/**
+ * Parse @mention from the beginning of a message.
+ * Supports: @claude, @openclaw, @paean, etc.
+ * The mention must appear at the start (possibly after whitespace).
+ */
+declare function parseMention(text: string): {
+    agent: string | null;
+    rest: string;
+};
+
+declare const PACKAGE_VERSION = "0.1.0";
+declare const DEFAULT_BASE_URL = "https://ilinkai.weixin.qq.com";
+declare const CONFIG_DIR: string;
+
+export { type AccountData, type AgentRegistration, CONFIG_DIR, DEFAULT_BASE_URL, DaemonClient, type DaemonInfo, type DaemonStatus, type GetUpdatesResp, PACKAGE_VERSION, type PollMessagesResponse, type QRCodeResponse, type QRStatusResponse, type RoutedMessage, type SendMessageRequest, type SendMessageResponse, type WechatContact, type WeixinMessage, checkDaemon, ensureDaemon, extractTextFromMessage, fetchQRCode, getContactToken, getUpdates, loadContacts, loadCredentials, parseMention, pollQRStatus, removeCredentials, saveContact, saveCredentials, sendTextMessage, stopDaemon };

package/dist/index.js

@@ -0,0 +1,443 @@
+// src/wechat-api.ts
+import crypto from "crypto";
+
+// src/constants.ts
+import path from "path";
+import os from "os";
+var PACKAGE_VERSION = "0.1.0";
+var DEFAULT_BASE_URL = "https://ilinkai.weixin.qq.com";
+var BOT_TYPE = "3";
+var CHANNEL_VERSION = "0.1.0";
+var MSG_TYPE_BOT = 2;
+var MSG_STATE_FINISH = 2;
+var MSG_ITEM_TEXT = 1;
+var MSG_ITEM_VOICE = 3;
+var LONG_POLL_TIMEOUT_MS = 35e3;
+var QR_POLL_TIMEOUT_MS = 35e3;
+var SEND_TIMEOUT_MS = 15e3;
+var DAEMON_HOST = "127.0.0.1";
+var CONFIG_DIR = path.join(os.homedir(), ".wechat-mcp");
+var CREDENTIALS_FILE = path.join(CONFIG_DIR, "credentials.json");
+var SYNC_BUF_FILE = path.join(CONFIG_DIR, "sync_buf.txt");
+var CONTACTS_FILE = path.join(CONFIG_DIR, "contacts.json");
+var DAEMON_PID_FILE = path.join(CONFIG_DIR, "daemon.pid");
+var DAEMON_INFO_FILE = path.join(CONFIG_DIR, "daemon.json");
+
+// src/wechat-api.ts
+function randomWechatUin() {
+  const uint32 = crypto.randomBytes(4).readUInt32BE(0);
+  return Buffer.from(String(uint32), "utf-8").toString("base64");
+}
+function buildHeaders(token, body) {
+  const headers = {
+    "Content-Type": "application/json",
+    AuthorizationType: "ilink_bot_token",
+    "X-WECHAT-UIN": randomWechatUin()
+  };
+  if (body) {
+    headers["Content-Length"] = String(Buffer.byteLength(body, "utf-8"));
+  }
+  if (token?.trim()) {
+    headers.Authorization = `Bearer ${token.trim()}`;
+  }
+  return headers;
+}
+function normalizeBaseUrl(baseUrl) {
+  return baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+}
+async function apiFetch(baseUrl, endpoint, body, token, timeoutMs = 15e3) {
+  const url = new URL(endpoint, normalizeBaseUrl(baseUrl)).toString();
+  const headers = buildHeaders(token, body);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers,
+      body,
+      signal: controller.signal
+    });
+    clearTimeout(timer);
+    const text = await res.text();
+    if (!res.ok) throw new Error(`HTTP ${res.status}: ${text}`);
+    return text;
+  } catch (err) {
+    clearTimeout(timer);
+    throw err;
+  }
+}
+async function fetchQRCode(baseUrl) {
+  const url = new URL(
+    `ilink/bot/get_bot_qrcode?bot_type=${encodeURIComponent(BOT_TYPE)}`,
+    normalizeBaseUrl(baseUrl)
+  );
+  const res = await fetch(url.toString());
+  if (!res.ok) throw new Error(`QR fetch failed: ${res.status}`);
+  return await res.json();
+}
+async function pollQRStatus(baseUrl, qrcode) {
+  const url = new URL(
+    `ilink/bot/get_qrcode_status?qrcode=${encodeURIComponent(qrcode)}`,
+    normalizeBaseUrl(baseUrl)
+  );
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), QR_POLL_TIMEOUT_MS);
+  try {
+    const res = await fetch(url.toString(), {
+      headers: { "iLink-App-ClientVersion": "1" },
+      signal: controller.signal
+    });
+    clearTimeout(timer);
+    if (!res.ok) throw new Error(`QR status failed: ${res.status}`);
+    return await res.json();
+  } catch (err) {
+    clearTimeout(timer);
+    if (err instanceof Error && err.name === "AbortError") {
+      return { status: "wait" };
+    }
+    throw err;
+  }
+}
+async function getUpdates(baseUrl, token, getUpdatesBuf) {
+  try {
+    const raw = await apiFetch(
+      baseUrl,
+      "ilink/bot/getupdates",
+      JSON.stringify({
+        get_updates_buf: getUpdatesBuf,
+        base_info: { channel_version: CHANNEL_VERSION }
+      }),
+      token,
+      LONG_POLL_TIMEOUT_MS
+    );
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      return { ret: 0, msgs: [], get_updates_buf: getUpdatesBuf };
+    }
+    throw err;
+  }
+}
+function generateClientId() {
+  return `wechat-mcp:${Date.now()}-${crypto.randomBytes(4).toString("hex")}`;
+}
+async function sendTextMessage(baseUrl, token, to, text, contextToken) {
+  const clientId = generateClientId();
+  await apiFetch(
+    baseUrl,
+    "ilink/bot/sendmessage",
+    JSON.stringify({
+      msg: {
+        from_user_id: "",
+        to_user_id: to,
+        client_id: clientId,
+        message_type: MSG_TYPE_BOT,
+        message_state: MSG_STATE_FINISH,
+        item_list: [{ type: MSG_ITEM_TEXT, text_item: { text } }],
+        context_token: contextToken
+      },
+      base_info: { channel_version: CHANNEL_VERSION }
+    }),
+    token,
+    SEND_TIMEOUT_MS
+  );
+  return clientId;
+}
+function extractTextFromMessage(msg) {
+  if (!msg.item_list?.length) return "";
+  for (const item of msg.item_list) {
+    if (item.type === MSG_ITEM_TEXT && item.text_item?.text) {
+      const text = item.text_item.text;
+      const ref = item.ref_msg;
+      if (!ref) return text;
+      const parts = [];
+      if (ref.title) parts.push(ref.title);
+      if (!parts.length) return text;
+      return `[Quote: ${parts.join(" | ")}]
+${text}`;
+    }
+    if (item.type === MSG_ITEM_VOICE && item.voice_item?.text) {
+      return item.voice_item.text;
+    }
+  }
+  return "";
+}
+
+// src/credentials.ts
+import fs from "fs";
+function ensureDir() {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+}
+function loadCredentials() {
+  try {
+    if (!fs.existsSync(CREDENTIALS_FILE)) return null;
+    return JSON.parse(fs.readFileSync(CREDENTIALS_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function saveCredentials(data) {
+  ensureDir();
+  fs.writeFileSync(CREDENTIALS_FILE, JSON.stringify(data, null, 2), "utf-8");
+  try {
+    fs.chmodSync(CREDENTIALS_FILE, 384);
+  } catch {
+  }
+}
+function removeCredentials() {
+  for (const file of [CREDENTIALS_FILE, SYNC_BUF_FILE, CONTACTS_FILE]) {
+    try {
+      if (fs.existsSync(file)) fs.unlinkSync(file);
+    } catch {
+    }
+  }
+}
+function loadContacts() {
+  try {
+    if (!fs.existsSync(CONTACTS_FILE)) return [];
+    return JSON.parse(fs.readFileSync(CONTACTS_FILE, "utf-8"));
+  } catch {
+    return [];
+  }
+}
+function saveContact(userId, contextToken) {
+  const contacts = loadContacts();
+  const displayName = userId.split("@")[0] || userId;
+  const idx = contacts.findIndex((c) => c.userId === userId);
+  const entry = {
+    userId,
+    contextToken,
+    lastSeen: (/* @__PURE__ */ new Date()).toISOString(),
+    displayName
+  };
+  if (idx >= 0) contacts[idx] = entry;
+  else contacts.push(entry);
+  try {
+    ensureDir();
+    fs.writeFileSync(CONTACTS_FILE, JSON.stringify(contacts, null, 2), "utf-8");
+  } catch {
+  }
+}
+function getContactToken(userId) {
+  const contacts = loadContacts();
+  const match = contacts.find(
+    (c) => c.userId === userId || c.displayName === userId
+  );
+  return match?.contextToken ?? null;
+}
+function loadDaemonInfo() {
+  try {
+    if (!fs.existsSync(DAEMON_INFO_FILE)) return null;
+    return JSON.parse(fs.readFileSync(DAEMON_INFO_FILE, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function removeDaemonInfo() {
+  for (const file of [DAEMON_INFO_FILE, DAEMON_PID_FILE]) {
+    try {
+      if (fs.existsSync(file)) fs.unlinkSync(file);
+    } catch {
+    }
+  }
+}
+function loadDaemonPid() {
+  try {
+    if (!fs.existsSync(DAEMON_PID_FILE)) return null;
+    const raw = fs.readFileSync(DAEMON_PID_FILE, "utf-8").trim();
+    const pid = parseInt(raw, 10);
+    return isNaN(pid) ? null : pid;
+  } catch {
+    return null;
+  }
+}
+
+// src/daemon/lifecycle.ts
+import { spawn } from "child_process";
+import path2 from "path";
+import { fileURLToPath } from "url";
+function getDaemonScript() {
+  const thisFile = typeof __filename !== "undefined" ? __filename : fileURLToPath(import.meta.url);
+  return path2.resolve(path2.dirname(thisFile), "..", "daemon", "server.js");
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function healthCheck(port) {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 3e3);
+    const res = await fetch(`http://${DAEMON_HOST}:${port}/health`, {
+      signal: controller.signal
+    });
+    clearTimeout(timer);
+    if (!res.ok) return false;
+    const data = await res.json();
+    return data.ok === true;
+  } catch {
+    return false;
+  }
+}
+async function checkDaemon() {
+  const info = loadDaemonInfo();
+  if (!info) return null;
+  if (!isProcessAlive(info.pid)) {
+    removeDaemonInfo();
+    return null;
+  }
+  const healthy = await healthCheck(info.port);
+  if (!healthy) {
+    removeDaemonInfo();
+    return null;
+  }
+  return info;
+}
+async function startDaemonProcess() {
+  const script = getDaemonScript();
+  const child = spawn(process.execPath, [script], {
+    detached: true,
+    stdio: "ignore",
+    env: { ...process.env }
+  });
+  child.unref();
+  const deadline = Date.now() + 15e3;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 500));
+    const info = loadDaemonInfo();
+    if (info && isProcessAlive(info.pid)) {
+      const healthy = await healthCheck(info.port);
+      if (healthy) return info;
+    }
+  }
+  throw new Error("Daemon failed to start within 15 seconds");
+}
+async function ensureDaemon() {
+  const existing = await checkDaemon();
+  if (existing) return existing;
+  return startDaemonProcess();
+}
+async function stopDaemon() {
+  const pid = loadDaemonPid();
+  if (!pid) return false;
+  if (!isProcessAlive(pid)) {
+    removeDaemonInfo();
+    return false;
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+    const deadline = Date.now() + 5e3;
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 200));
+      if (!isProcessAlive(pid)) break;
+    }
+    removeDaemonInfo();
+    return true;
+  } catch {
+    removeDaemonInfo();
+    return false;
+  }
+}
+
+// src/client/index.ts
+var DaemonClient = class {
+  baseUrl;
+  constructor(port) {
+    this.baseUrl = `http://${DAEMON_HOST}:${port}`;
+  }
+  async request(method, path3, body, timeoutMs = 5e3) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      const res = await fetch(`${this.baseUrl}${path3}`, {
+        method,
+        headers: body ? { "Content-Type": "application/json" } : void 0,
+        body: body ? JSON.stringify(body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timer);
+      const data = await res.json();
+      if (!res.ok) {
+        const errMsg = data.error || `HTTP ${res.status}`;
+        throw new Error(errMsg);
+      }
+      return data;
+    } catch (err) {
+      clearTimeout(timer);
+      throw err;
+    }
+  }
+  async health() {
+    try {
+      const data = await this.request("GET", "/health");
+      return data.ok === true;
+    } catch {
+      return false;
+    }
+  }
+  async status() {
+    return this.request("GET", "/status");
+  }
+  async registerAgent(agentId, name) {
+    return this.request("POST", "/agents", { agentId, name });
+  }
+  async unregisterAgent(agentId) {
+    return this.request("DELETE", `/agents/${encodeURIComponent(agentId)}`);
+  }
+  /**
+   * Long-poll for messages intended for this agent.
+   * Will block up to ~30s on the daemon side.
+   */
+  async pollMessages(agentId) {
+    const resp = await this.request(
+      "GET",
+      `/messages/${encodeURIComponent(agentId)}`,
+      void 0,
+      35e3
+    );
+    return resp.messages;
+  }
+  async send(to, text, agentId) {
+    return this.request("POST", "/send", { to, text, agentId });
+  }
+  async getContacts() {
+    const data = await this.request("GET", "/contacts");
+    return data.contacts;
+  }
+};
+
+// src/daemon/router.ts
+import crypto2 from "crypto";
+function parseMention(text) {
+  const trimmed = text.trimStart();
+  const match = trimmed.match(/^@(\S+)\s*([\s\S]*)$/);
+  if (!match) {
+    return { agent: null, rest: text };
+  }
+  return { agent: match[1].toLowerCase(), rest: match[2] || "" };
+}
+export {
+  CONFIG_DIR,
+  DEFAULT_BASE_URL,
+  DaemonClient,
+  PACKAGE_VERSION,
+  checkDaemon,
+  ensureDaemon,
+  extractTextFromMessage,
+  fetchQRCode,
+  getContactToken,
+  getUpdates,
+  loadContacts,
+  loadCredentials,
+  parseMention,
+  pollQRStatus,
+  removeCredentials,
+  saveContact,
+  saveCredentials,
+  sendTextMessage,
+  stopDaemon
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@paean-ai/wechat-mcp",
+  "version": "0.1.0",
+  "description": "WeChat MCP middleware — shared WeChat connection for multiple AI agents with @mention routing",
+  "type": "module",
+  "bin": {
+    "wechat-mcp": "dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "commander": "^13.0.0",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "wechat",
+    "mcp",
+    "multi-agent",
+    "middleware",
+    "weixin",
+    "chatbot",
+    "ai",
+    "claude",
+    "openclaw",
+    "ilink"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paean-ai/wechat-mcp.git"
+  },
+  "homepage": "https://github.com/paean-ai/wechat-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/paean-ai/wechat-mcp/issues"
+  },
+  "author": "Paean AI",
+  "license": "MIT"
+}