# WeChat MCP Plugin

**让 Codex 接管微信** — 通过 MCP 协议将微信能力暴露为 AI 可调用的工具。

## 概览

```
┌─────────────────────────────────────────────┐
│                 Codex                        │
│       ┌──────────────────────────────┐      │
│       │   WeChat MCP Server          │      │
│       │   (暴露 10+ 个工具给 Codex)   │      │
│       └───────┬──────────────────────┘      │
│               │ stdio / JSON-RPC            │
│       ┌───────▼──────────────────────┐      │
│       │   Wechaty + Puppet           │      │
│       │   (微信协议桥接层)             │      │
│       └───────┬──────────────────────┘      │
│               │ 注入/协议                  │
│       ┌───────▼──────────────────────┐      │
│       │  微信 (桌面版 / iPad 协议)     │      │
│       └──────────────────────────────┘      │
└─────────────────────────────────────────────┘
```

## 快速开始

```bash
# 1. 安装依赖
bash scripts/setup.sh

# 2. 启动（扫码登录微信）
npm start

# 3. 注册到 Codex
codex plugin add wechat-mcp@personal

# 4. 在 Codex 中即可使用 WeChat 工具
```

## 工具列表

| 工具 | 描述 |
|------|------|
| `wechat_status` | 获取登录状态和 Bot 信息 |
| `wechat_send_text` | 发送文本消息 |
| `wechat_send_file` | 发送文件/图片 |
| `wechat_get_contacts` | 获取联系人列表（支持搜索） |
| `wechat_get_rooms` | 获取群聊列表 |
| `wechat_get_messages` | 获取最近消息 |
| `wechat_search_messages` | 搜索历史消息 |
| `wechat_contact_info` | 获取联系人详情 |
| `wechat_self_info` | 获取自身信息 |
| `wechat_setup_guide` | 搭建指南和故障排查 |

## 技术选型

- **协议**: MCP (Model Context Protocol) over stdio
- **微信桥接**: Wechaty + wechaty-puppet-wechat (UOS)
- **运行时**: Node.js 18+
- **通信**: JSON-RPC 2.0

## 目录结构

```
wechat-mcp/
├── .codex-plugin/
│   └── plugin.json        # 插件清单
├── .mcp.json              # MCP Server 配置
├── mcp/
│   ├── index.mjs          # MCP Server 入口
│   └── wechaty-bridge.mjs # Wechaty 桥接封装
├── scripts/
│   └── setup.sh           # 一键安装/检查脚本
├── skills/
│   └── SKILL.md            # Codex 技能定义
├── package.json           # Node.js 依赖
└── README.md
```

## 许可证

MIT