@paean-ai/wechat-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paean AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# @paean-ai/wechat-mcp
+
+WeChat MCP middleware — shared WeChat connection for multiple AI agents with @mention routing.
+
+## Problem
+
+WeChat's official iLink protocol only allows **one bot per WeChat account**. If you use multiple AI agents (Claude Code, OpenClaw, Paean CLI, etc.), you're forced to choose which one gets WeChat access.
+
+**wechat-mcp** solves this by providing a shared middleware layer: one WeChat connection, many agents.
+
+## How It Works
+
+```
+                     WeChat iLink API
+                          │
+                 ┌────────┴────────┐
+                 │  wechat-mcp     │
+                 │  daemon         │
+                 │  (background)   │
+                 └───┬────┬────┬───┘
+                     │    │    │    HTTP IPC (localhost)
+              ┌──────┘    │    └──────┐
+              ▼           ▼           ▼
+         MCP Server  MCP Server  MCP Server
+         (claude)    (openclaw)  (paean)
+              ▲           ▲           ▲
+              │           │           │    stdio MCP
+         Claude Code  OpenClaw   Paean CLI
+```
+
+1. A **background daemon** manages the single WeChat connection (QR login, message polling, token cache)
+2. Each agent connects via its own **MCP stdio server** (thin client)
+3. Incoming messages are **routed by @mention**: `@claude hello` goes to Claude, `@openclaw run task` goes to OpenClaw
+4. Any agent can **send messages** through the shared connection
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install -g @paean-ai/wechat-mcp
+```
+
+### 2. Authenticate
+
+```bash
+wechat-mcp setup
+```
+
+Scan the QR code with WeChat. Credentials are saved to `~/.wechat-mcp/`.
+
+### 3. Add to Any Agent
+
+Add this to your agent's MCP configuration:
+
+**Claude Code** (`~/.claude.json` or project `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "wechat": {
+      "command": "npx",
+      "args": ["@paean-ai/wechat-mcp", "serve", "--agent", "claude"]
+    }
+  }
+}
+```
+
+**OpenClaw / Other Agents:**
+
+```json
+{
+  "mcpServers": {
+    "wechat": {
+      "command": "npx",
+      "args": ["@paean-ai/wechat-mcp", "serve", "--agent", "openclaw"]
+    }
+  }
+}
+```
+
+Each agent uses a different `--agent` name. That's it — the daemon auto-starts when any agent connects.
+
+## Message Routing
+
+| WeChat Message | Routed To | Agent Receives |
+|---|---|---|
+| `@claude hello` | agent "claude" | `hello` |
+| `@openclaw run task` | agent "openclaw" | `run task` |
+| `hello` (no @) | default agent (first registered) | `hello` |
+| `@unknown hi` | default agent | `@unknown hi` |
+
+## CLI Commands
+
+```bash
+wechat-mcp setup              # QR login
+wechat-mcp serve --agent X    # Start MCP server (used in agent config)
+wechat-mcp daemon              # Start daemon in foreground
+wechat-mcp stop                # Stop daemon
+wechat-mcp status              # Show status
+wechat-mcp contacts            # List known contacts
+wechat-mcp send --to X --text Y  # One-shot send
+wechat-mcp logout              # Remove credentials & stop daemon
+```
+
+## MCP Tools
+
+When connected as an MCP server, agents can use these tools:
+
+| Tool | Description |
+|---|---|
+| `wechat_send` | Send a text message to a WeChat user |
+| `wechat_get_contacts` | List known WeChat contacts |
+| `wechat_get_status` | Get connection status and registered agents |
+
+## Proactive Messaging
+
+Agents can send messages proactively (e.g., from cron jobs or scheduled tasks) using the shared WeChat connection:
+
+```bash
+# CLI
+wechat-mcp send --to "friend@im.wechat" --text "Task completed!"
+
+# Or via MCP tool: agents call wechat_send at any time
+```
+
+## Architecture
+
+- **Daemon** (`~/.wechat-mcp/daemon.json`): Auto-started background process that owns the WeChat connection. Listens on `127.0.0.1` only.
+- **MCP Server**: Thin stdio process spawned per-agent. Connects to daemon over local HTTP.
+- **Credentials**: Stored in `~/.wechat-mcp/credentials.json` with `0600` permissions.
+
+## Programmatic API
+
+```typescript
+import {
+  ensureDaemon,
+  DaemonClient,
+  loadCredentials,
+  parseMention,
+} from "@paean-ai/wechat-mcp";
+
+// Connect to daemon
+const daemon = await ensureDaemon();
+const client = new DaemonClient(daemon.port);
+
+// Register and poll
+await client.registerAgent("my-bot");
+const messages = await client.pollMessages("my-bot");
+
+// Send
+await client.send("user@wxid", "Hello from my bot!", "my-bot");
+```
+
+## Security
+
+- Credentials stored with `0600` file permissions
+- Daemon listens only on `127.0.0.1` (no network exposure)
+- No secrets in environment variables or logs
+- Token stored locally, never transmitted to third parties
+
+## License
+
+MIT