# WeFlow MCP Server

把 [WeFlow](https://github.com/rfdiosuao/WeFlow) 的本地 HTTP API 包装成
[MCP](https://modelcontextprotocol.io) 工具，让你的 AI 助手直接读取本机微信聊天记录、
会话、联系人和群成员。

**数据完全在本地流转**：MCP 只与 `127.0.0.1:5031` 通信，不经过任何外部服务器。

## 提供的工具

| 工具 | 说明 |
|---|---|
| `weflow_health` | 检查 API 服务与 Token 是否可用 |
| `weflow_list_sessions` | 列出/搜索会话，获取 `sessionId` |
| `weflow_get_messages` | **读取聊天记录**（支持时间范围、关键词、分页、ChatLab 格式、媒体导出） |
| `weflow_search_contacts` | 搜索联系人，把名字解析成 `wxid` |
| `weflow_get_group_members` | 获取群成员及发言统计 |

## 前置条件

1. **WeFlow 正在运行**
2. **启用 API 服务**：WeFlow →「设置 → API 服务」→ 打开开关
3. **拿到 Access Token**：同一设置页面里显示，复制备用

默认监听 `127.0.0.1:5031`。若你改过端口，用 `WEFLOW_PORT` 指定。

## 安装

```bash
git clone https://github.com/rfdiosuao/WeFlow-MCP.git
cd WeFlow-MCP
npm install
```

## 配置

在 MCP 客户端中注册本服务。所有客户端都是同一套配置：

```json
{
  "mcpServers": {
    "weflow": {
      "command": "node",
      "args": ["<绝对路径>/weflow-mcp/src/index.js"],
      "env": {
        "WEFLOW_TOKEN": "你的 Access Token"
      }
    }
  }
}
```

### 各客户端配置位置

- **WorkBuddy**：`~/.workbuddy/mcp.json`
- **Claude Desktop**：`claude_desktop_config.json`
- **Cursor**：`.cursor/mcp.json`（项目级）或全局配置

> 不要把真实 Token 提交到 Git 仓库。建议用环境变量或在本地配置文件中引用。

## 环境变量

| 变量 | 必填 | 默认值 | 说明 |
|---|---|---|---|
| `WEFLOW_TOKEN` | ✅ | — | WeFlow「设置 → API 服务」中的 Access Token |
| `WEFLOW_HOST` | | `127.0.0.1` | API 主机 |
| `WEFLOW_PORT` | | `5031` | API 端口 |
| `WEFLOW_TIMEOUT` | | `30000` | 请求超时（毫秒） |

## 使用示例

配好之后，直接用自然语言提问即可：

- 「我和张三最近聊了什么？帮我总结一下」
- 「在项目群里搜一下提到『上线时间』的消息」
- 「这个月群里谁发言最多？」
- 「把上周和客户的对话整理成纪要」

AI 会自动按 `搜索联系人 → 取 wxid → 读消息` 的顺序调用工具。

## 工作原理

```
AI 助手  ──MCP(stdio)──▶  weflow-mcp  ──HTTP──▶  WeFlow 本地 API (127.0.0.1:5031)
                                                          │
                                                          ▼
                                                    本地微信数据库
```

## 常见问题

**返回 401 Unauthorized**
Token 不对。回到 WeFlow 设置页重新复制，注意别带上多余空格。

**无法连接 / ECONNREFUSED**
WeFlow 没启动，或 API 服务开关没打开。先用 `weflow_health` 确认。

**调用超时**
大群或大时间跨度查询较慢。缩小时间范围，或调大 `WEFLOW_TIMEOUT`。

**找不到某个群**
群聊不在联系人列表里。用 `weflow_list_sessions` 按群名搜索。

## 相关文档

- WeFlow HTTP API 完整文档：`docs/HTTP-API.md`
- MCP 协议：https://modelcontextprotocol.io

## License

MIT