weixin-mcp 1.4.2 → 1.5.0

package/README.en.md

@@ -1,28 +1,54 @@
 # weixin-mcp
 
-Standalone MCP server for WeChat — expose WeChat messaging as MCP tools for Claude Desktop and other MCP clients.
+MCP server for WeChat messaging — expose WeChat capabilities as MCP tools for Claude Desktop, Cursor, and other MCP clients.
 
-Reuses the token from [OpenClaw weixin plugin](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin) if already installed, or supports independent QR login.
+[中文](./README.md)
 
 ## Quick Start
 
-### Step 1 — Login (first time only)
-
 ```bash
-npx weixin-login
-```
+# 1. Login (scan QR code)
+npx weixin-mcp login
+
+# 2. Check status
+npx weixin-mcp status
 
-A QR code will appear in your terminal. Scan it with WeChat and confirm. Token is saved locally.
+# 3. Start MCP server (stdio mode for Claude Desktop)
+npx weixin-mcp
+```
 
-### Step 2 — Start the MCP server
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx weixin-mcp login` | QR code login |
+| `npx weixin-mcp status` | Show account and daemon status |
+| `npx weixin-mcp` | Start stdio MCP server (Claude Desktop) |
+| `npx weixin-mcp start [--port n]` | Start HTTP daemon (background, default 3001) |
+| `npx weixin-mcp stop` | Stop daemon |
+| `npx weixin-mcp restart` | Restart daemon |
+| `npx weixin-mcp logs [-f]` | View daemon logs (-f for follow) |
+| `npx weixin-mcp send <userId> <text>` | Send message (supports short ID prefix) |
+| `npx weixin-mcp poll [--watch] [--reset]` | Poll messages (--watch for continuous) |
+| `npx weixin-mcp contacts` | List contacts (users who messaged the bot) |
+| `npx weixin-mcp accounts [list]` | List all accounts |
+| `npx weixin-mcp accounts remove <id>` | Remove an account |
+| `npx weixin-mcp accounts clean` | Remove duplicates (keep newest per userId) |
+| `npx weixin-mcp update` | Check and install latest version |
+| `npx weixin-mcp --version` | Print version |
+
+### Short ID Matching
+
+When sending messages, you can use a prefix of the user ID if it uniquely matches a contact:
 
 ```bash
-npx weixin-mcp
+npx weixin-mcp send o9cq8 "hello"
+# Resolved "o9cq8" → o9cq80x8ou646cs3Tt5EQgfsZRtI@im.wechat
 ```
 
 ## Claude Desktop Integration
 
-Add to your `claude_desktop_config.json`:
+Add to `claude_desktop_config.json`:
 
 ```json
 {
@@ -35,34 +61,46 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
-Restart Claude Desktop. You can now ask Claude to send WeChat messages or poll for new ones.
+## HTTP Daemon Mode
 
-## Tools
+Start an HTTP daemon for multi-client connections:
 
-| Tool | Description | Parameters |
-|------|-------------|------------|
-| `weixin_send` | Send a text message | `to` (user ID), `text`, `context_token` (optional — link reply to a conversation) |
-| `weixin_poll` | Poll for new messages (cursor-based, no duplicates) | `reset_cursor` (optional boolean) |
-| `weixin_get_config` | Get user config (typing ticket, etc.) | `user_id`, `context_token` (optional) |
+```bash
+npx weixin-mcp start --port 3001
+```
 
-## Already using OpenClaw weixin plugin?
+- MCP endpoint: `http://localhost:3001/mcp` (StreamableHTTP)
+- Health check: `http://localhost:3001/health`
 
-If you've already logged in via OpenClaw, no login needed — `npx weixin-mcp` will pick up the existing token automatically.
+## MCP Tools
 
-## Environment Variables
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `weixin_send` | Send text message | `to`, `text`, `context_token` (optional) |
+| `weixin_poll` | Poll new messages | `reset_cursor` (optional) |
+| `weixin_contacts` | List contacts | none |
+| `weixin_get_config` | Get user config | `user_id`, `context_token` (optional) |
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `OPENCLAW_STATE_DIR` | `~/.openclaw` | State directory; accounts are read from `$OPENCLAW_STATE_DIR/openclaw-weixin/accounts/` |
-| `WEIXIN_ACCOUNT_ID` | first account found | Specify which account to use (filename without `.json`) |
+## Data Storage
 
-## Re-login
+Priority:
+1. `WEIXIN_MCP_DIR` environment variable
+2. `~/.openclaw/openclaw-weixin/` (if OpenClaw installed)
+3. `~/.weixin-mcp/` (default)
 
-If your token expires:
+Files:
+- `accounts/<accountId>.json` — account token
+- `accounts/<accountId>.cursor.json` — message cursor
+- `contacts.json` — contact book
+- `daemon.json` — daemon PID (HTTP mode only)
+- `daemon.log` — daemon logs
 
-```bash
-npx weixin-login
-```
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `WEIXIN_MCP_DIR` | Custom data directory |
+| `WEIXIN_ACCOUNT_ID` | Specify which account to use |
 
 ## License
 

package/README.md

@@ -1,6 +1,6 @@
 # weixin-mcp
 
-基于 MCP 协议的微信消息服务端——将微信能力暴露为 MCP 工具，供 Claude Desktop 及其他 MCP 客户端使用。
+基于 MCP 协议的微信消息服务端——将微信能力暴露为 MCP 工具，供 Claude Desktop、Cursor 及其他 MCP 客户端使用。
 
 支持复用 [OpenClaw weixin 插件](https://www.npmjs.com/package/@tencent-weixin/openclaw-weixin) 的已有登录态，或独立扫码登录。
 
@@ -8,18 +8,44 @@
 
 ## 快速开始
 
-### 第一步 — 登录（首次使用）
-
 ```bash
-npx weixin-login
-```
+# 1. 登录（首次使用，扫码）
+npx weixin-mcp login
+
+# 2. 查看状态
+npx weixin-mcp status
 
-终端会显示二维码，微信扫码确认后 token 自动保存到本地。
+# 3. 启动 MCP server（Claude Desktop 模式）
+npx weixin-mcp
+```
 
-### 第二步 — 启动 MCP 服务
+## CLI 命令一览
+
+| 命令 | 说明 |
+|------|------|
+| `npx weixin-mcp login` | 扫码登录微信 |
+| `npx weixin-mcp status` | 查看账号和 daemon 状态 |
+| `npx weixin-mcp` | 启动 stdio MCP server（Claude Desktop） |
+| `npx weixin-mcp start [--port n]` | 启动 HTTP daemon（后台，默认端口 3001） |
+| `npx weixin-mcp stop` | 停止 daemon |
+| `npx weixin-mcp restart` | 重启 daemon |
+| `npx weixin-mcp logs [-f]` | 查看 daemon 日志（-f 实时跟踪） |
+| `npx weixin-mcp send <userId> <text>` | 发送消息（支持短 ID 前缀匹配） |
+| `npx weixin-mcp poll [--watch] [--reset]` | 拉取消息（--watch 持续监听） |
+| `npx weixin-mcp contacts` | 查看联系人（给 bot 发过消息的用户） |
+| `npx weixin-mcp accounts [list]` | 列出所有账号 |
+| `npx weixin-mcp accounts remove <id>` | 删除账号 |
+| `npx weixin-mcp accounts clean` | 清理重复账号（同 userId 保留最新） |
+| `npx weixin-mcp update` | 检查并更新到最新版 |
+| `npx weixin-mcp --version` | 查看版本 |
+
+### 短 ID 匹配
+
+发送消息时可以用用户 ID 的前缀，只要在联系人中唯一匹配即可：
 
 ```bash
-npx weixin-mcp
+npx weixin-mcp send o9cq8 "hello"
+# Resolved "o9cq8" → o9cq80x8ou646cs3Tt5EQgfsZRtI@im.wechat
 ```
 
 ## Claude Desktop 集成
@@ -37,32 +63,48 @@ npx weixin-mcp
 }
 ```
 
-重启 Claude Desktop 后，即可让 Claude 直接发送微信消息或拉取新消息。
+重启 Claude Desktop 后即可使用。
+
+## HTTP Daemon 模式
 
-## 工具列表
+除了 stdio 模式，也可以启动 HTTP daemon 供多客户端连接：
+
+```bash
+npx weixin-mcp start --port 3001
+```
+
+MCP 端点：`http://localhost:3001/mcp`（StreamableHTTP）
+健康检查：`http://localhost:3001/health`
+
+## MCP 工具列表
 
 | 工具名 | 说明 | 参数 |
 |--------|------|------|
-| `weixin_send` | 发送文本消息 | `to`（用户 ID）、`text`、`context_token`（可选，关联会话） |
-| `weixin_poll` | 拉取新消息（基于游标，不重复） | `reset_cursor`（可选布尔值） |
-| `weixin_get_config` | 获取用户配置（typing ticket 等） | `user_id`、`context_token`（可选） |
-
-## 已有 OpenClaw weixin 插件？
+| `weixin_send` | 发送文本消息 | `to`、`text`、`context_token`（可选） |
+| `weixin_poll` | 拉取新消息 | `reset_cursor`（可选） |
+| `weixin_contacts` | 列出联系人 | 无 |
+| `weixin_get_config` | 获取用户配置 | `user_id`、`context_token`（可选） |
 
-如果已通过 OpenClaw 完成微信登录，无需重新登录——`npx weixin-mcp` 会自动复用已有 token。
+## 数据存储路径
 
-## 环境变量
+优先级：
+1. `WEIXIN_MCP_DIR` 环境变量
+2. `~/.openclaw/openclaw-weixin/`（已装 OpenClaw）
+3. `~/.weixin-mcp/`（默认）
 
-| 变量名 | 默认值 | 说明 |
-|--------|--------|------|
-| `OPENCLAW_STATE_DIR` | `~/.openclaw` | 状态目录，账号文件读取路径为 `$OPENCLAW_STATE_DIR/openclaw-weixin/accounts/` |
-| `WEIXIN_ACCOUNT_ID` | 目录中第一个账号 | 指定使用哪个账号（对应文件名去掉 `.json`） |
+文件：
+- `accounts/<accountId>.json` — 账号 token
+- `accounts/<accountId>.cursor.json` — 消息游标
+- `contacts.json` — 联系人
+- `daemon.json` — daemon PID（仅 HTTP 模式）
+- `daemon.log` — daemon 日志
 
-## Token 过期重新登录
+## 环境变量
 
-```bash
-npx weixin-login
-```
+| 变量名 | 说明 |
+|--------|------|
+| `WEIXIN_MCP_DIR` | 自定义数据目录 |
+| `WEIXIN_ACCOUNT_ID` | 指定使用哪个账号 |
 
 ## License
 

package/dist/index.js

@@ -11,6 +11,16 @@ import path from "node:path";
 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";
+/** Resolve short userId prefix to full ID from contacts. */
+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; // ambiguous or not found — use as-is
+}
 // ── Auth / config ──────────────────────────────────────────────────────────
 const WEIXIN_DIR = ACCOUNTS_DIR;
 function loadAccount() {
@@ -52,7 +62,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             inputSchema: {
                 type: "object",
                 properties: {
-                    to: { type: "string", description: "Recipient user ID / OpenId" },
+                    to: { type: "string", description: "Recipient user ID (full or short prefix if unique in contacts)" },
                     text: { type: "string", description: "Message text to send" },
                     context_token: {
                         type: "string",
@@ -103,8 +113,9 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         if (name === "weixin_send") {
             const { to, text, context_token } = (args ?? {});
             const validatedTo = assertNonEmptyString(to, "to");
+            const resolvedTo = resolveUserId(validatedTo, loadContacts());
             const validatedText = assertNonEmptyString(text, "text");
-            result = await sendTextMessage(validatedTo, validatedText, token, baseUrl, context_token);
+            result = await sendTextMessage(resolvedTo, validatedText, token, baseUrl, context_token);
         }
         else if (name === "weixin_poll") {
             const { reset_cursor } = (args ?? {});

package/dist/messaging.js

@@ -7,7 +7,25 @@ import fs from "node:fs";
 import path from "node:path";
 import { ACCOUNTS_DIR } from "./paths.js";
 import { DEFAULT_BASE_URL, sendTextMessage, getUpdates, loadCursor, saveCursor, } from "./api.js";
-import { updateContactsFromMsgs } from "./contacts.js";
+import { updateContactsFromMsgs, loadContacts } from "./contacts.js";
+/** Resolve a short/partial userId to a full one from contacts. */
+function resolveUserId(input) {
+    if (!input)
+        return input;
+    // Already looks like a full id? return as-is
+    if (input.includes("@"))
+        return input;
+    const contacts = Object.keys(loadContacts());
+    const matches = contacts.filter((id) => id.startsWith(input) || id.includes(input));
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1) {
+        console.error(`Ambiguous user "${input}", matches:\n${matches.map((m) => `  ${m}`).join("\n")}`);
+        process.exit(1);
+    }
+    // Not found in contacts — treat as literal
+    return input;
+}
 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)
@@ -41,9 +59,12 @@ export async function cliSend(args) {
         process.exit(1);
     }
     const text = textParts.join(" ");
+    const resolvedTo = resolveUserId(to);
+    if (resolvedTo !== to)
+        console.log(`Resolved "${to}" → ${resolvedTo}`);
     const { token, baseUrl = DEFAULT_BASE_URL } = loadAccount();
-    process.stdout.write(`Sending to ${to}... `);
-    const result = await sendTextMessage(to, text, token, baseUrl);
+    process.stdout.write(`Sending to ${resolvedTo}... `);
+    const result = await sendTextMessage(resolvedTo, text, token, baseUrl);
     const ret = result?.ret ?? result?.errcode;
     if (ret === 0 || ret === undefined) {
         console.log("✅ Sent");

package/package.json

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

package/src/index.ts

@@ -23,7 +23,16 @@ import {
   WeixinNetworkError,
 } from "./api.js";
 import { ACCOUNTS_DIR } from "./paths.js";
-import { updateContactsFromMsgs, loadContacts } from "./contacts.js";
+import { updateContactsFromMsgs, loadContacts, type ContactBook } from "./contacts.js";
+
+/** Resolve short userId prefix to full ID from contacts. */
+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; // ambiguous or not found — use as-is
+}
 
 // ── Auth / config ──────────────────────────────────────────────────────────
 
@@ -85,7 +94,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       inputSchema: {
         type: "object",
         properties: {
-          to: { type: "string", description: "Recipient user ID / OpenId" },
+          to: { type: "string", description: "Recipient user ID (full or short prefix if unique in contacts)" },
           text: { type: "string", description: "Message text to send" },
           context_token: {
             type: "string",
@@ -149,9 +158,10 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         context_token?: string;
       };
       const validatedTo = assertNonEmptyString(to, "to");
+      const resolvedTo = resolveUserId(validatedTo, loadContacts());
       const validatedText = assertNonEmptyString(text, "text");
       result = await sendTextMessage(
-        validatedTo,
+        resolvedTo,
         validatedText,
         token!,
         baseUrl,

package/src/messaging.ts

@@ -14,7 +14,23 @@ import {
   loadCursor,
   saveCursor,
 } from "./api.js";
-import { updateContactsFromMsgs } from "./contacts.js";
+import { updateContactsFromMsgs, loadContacts } from "./contacts.js";
+
+/** Resolve a short/partial userId to a full one from contacts. */
+function resolveUserId(input: string): string {
+  if (!input) return input;
+  // Already looks like a full id? return as-is
+  if (input.includes("@")) return input;
+  const contacts = Object.keys(loadContacts());
+  const matches = contacts.filter((id) => id.startsWith(input) || id.includes(input));
+  if (matches.length === 1) return matches[0];
+  if (matches.length > 1) {
+    console.error(`Ambiguous user "${input}", matches:\n${matches.map((m) => `  ${m}`).join("\n")}`);
+    process.exit(1);
+  }
+  // Not found in contacts — treat as literal
+  return input;
+}
 
 interface AccountData { token?: string; baseUrl?: string; userId?: string }
 
@@ -50,10 +66,12 @@ export async function cliSend(args: string[]) {
     process.exit(1);
   }
   const text = textParts.join(" ");
+  const resolvedTo = resolveUserId(to);
+  if (resolvedTo !== to) console.log(`Resolved "${to}" → ${resolvedTo}`);
   const { token, baseUrl = DEFAULT_BASE_URL } = loadAccount();
 
-  process.stdout.write(`Sending to ${to}... `);
-  const result = await sendTextMessage(to, text, token!, baseUrl) as Record<string, unknown>;
+  process.stdout.write(`Sending to ${resolvedTo}... `);
+  const result = await sendTextMessage(resolvedTo, text, token!, baseUrl) as Record<string, unknown>;
   const ret = result?.ret ?? result?.errcode;
   if (ret === 0 || ret === undefined) {
     console.log("✅ Sent");