# mac-wechat-mcp

一个面向 macOS 个人微信的独立 MCP 项目。通过本机截图与 Apple Vision OCR，把当前指定会话的视觉上下文提供给支持 MCP 的 AI 客户端。

[English](README.en.md) · [客户端配置](docs/clients.md) · [本机校准](docs/calibration.md) · [路线图](docs/roadmap.md)

> **v0.1 是只读观察与回复草稿原型，尚不能自动发送微信。**
> 标准 MCP 握手、图片返回和观察状态已通过合成数据测试；真实微信 4.1.13 的 OCR、身份核对、发送者识别与发送回读尚未完成验证。不要将本版本用于无人值守自动回复。

## 已实现

- 标准 MCP stdio 接口，使用官方 Python SDK，不依赖任何已有微信 MCP。
- 本机 Apple Vision OCR；返回聊天区域图片与原始 OCR 块。
- 单个本地配置的联系人；目标标题不符、窗口移动/缩放、捕获失败时暂停。
- 首次捕获仅建立基线，默认观察期限 10 分钟、最小轮询间隔 15 秒。
- 前后画面对比；未处理的观察保留同一个 ID，连续变化保留最早未处理画面。
- 回复草稿预览：只返回文字，**不写入输入框、不发送消息**。
- 合成数据 demo，可在不启动微信、不授权屏幕录制的情况下测试 MCP 客户端。

## 能力边界

| 项目 | 当前状态 |
|---|---|
| MCP stdio、工具发现、图片返回 | 已用 SDK 客户端测试 |
| 基线、过期、暂停、观察确认 | 已做自动化测试 |
| 真实 Mac 窗口截图与 OCR | 已实现，待本机校准及实机验收 |
| 识别消息发送者、媒体类型、新消息 | 尚未可靠实现；OCR 一律标为 unknown |
| 语义隐私过滤 | 客户端职责，服务端尚无语义过滤器 |
| 自动发送及发送确认 | 未开放 |
| 后台定时监听 | 无；由 MCP 客户端主动轮询 |

**画面变化不等于收到新消息。** 自己发消息、时间标签、滚动、图片加载都可能改变画面。观察 ID 不是微信消息 ID，不能承诺消息级 exactly-once。

## 快速运行 demo

需要 Python 3.11+ 和 [uv](https://docs.astral.sh/uv/)。

```bash
git clone https://github.com/849860605/mac-wechat-mcp.git
cd mac-wechat-mcp
uv run mac-wechat-mcp --demo
```

这是 stdio 服务，会等待 MCP 客户端输入。终端不打印欢迎横幅是正常现象，日志写到 stderr。

通用客户端配置：

```json
{
  "mcpServers": {
    "mac-wechat": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/mac-wechat-mcp", "run", "mac-wechat-mcp", "--demo"]
    }
  }
}
```

Claude Desktop、Cursor 等客户端通常接受此类配置，但实际入口请以各客户端文档为准。客户端必须支持 **本地 stdio MCP 和图片工具结果**，才能完成视觉复核；没有宣称已逐个验证这些客户端。纯云端客户端不能直接运行你 Mac 上的 stdio 进程。

## 接入真实微信

先阅读 [校准说明](docs/calibration.md)，生成自己的本地配置。示例坐标不能直接当成已验证配置。

```bash
uv run --extra macos mac-wechat-mcp --config /absolute/path/config.local.json --doctor
uv run --extra macos mac-wechat-mcp --config /absolute/path/config.local.json
```

第一版使用 Python + PyObjC 调用 macOS 原生 API，便于安装与 MCP 集成；不需要运行 Swift 编译工具。微信须处于前台、可见、已登录，电脑须保持解锁。

## 工具

| 工具 | 行为 |
|---|---|
| `get_status` | 查看后端、到期时间及限制 |
| `start_observation` | 建立新基线；默认 600 秒、15 秒间隔 |
| `poll_changes` | 到达间隔后捕获；返回前后图片及 OCR |
| `preview_reply` | 返回未发送草稿，不操作微信 |
| `acknowledge_observation` | 确认观察结果；uncertain 会暂停 |
| `pause_observation` | 暂停并使待处理草稿失效 |
| `demo_advance` | 仅 demo：改变合成画面 |

AI 客户端负责生成回复；项目不内置模型、不要求模型 API Key，也不自动调用外部模型服务。

## 数据与权限

- 本机 OCR 不需要网络请求。MCP 返回的图片、文字会交给接入的 AI 客户端，可能进一步发往该客户端的模型服务商。
- 仅返回校准的消息区域，标题用于本机核对。捕获时临时生成完整微信窗口 PNG，正常结束后删除；异常终止时操作系统临时目录中可能留下文件。
- 不读取微信数据库，不上传联系人清单，不提供任意文件读取、Shell、浏览器或跨会话操作工具。
- 不持久化聊天内容；当前会话的少量前后图片保留在进程内存中。
- 备注名不能证明唯一身份。启用前须由使用者核对联系人资料；本版本不声称能自动解决同名联系人。
- 不在仓库提交真实截图、聊天内容、本地配置、密钥、运行日志。

## 开发与验证

```bash
uv sync --extra macos  # 非 macOS 可省略 --extra macos
PYTHONPATH=src uv run python -m unittest discover -s tests -v
```

本机已通过 21 项状态/协议测试，以及 1 项 Apple Vision 合成图片 OCR 测试；wheel 和源码包构建成功。原生 OCR 测试需允许系统 Vision 运行，受限沙箱中可能失败。

测试包含真实 stdio 子进程握手、工具调用与 PNG 返回，但微信画面由 demo 合成，**不是微信实机收发测试**。

架构：`server.py` 定义 MCP 接口；`core.py` 管理观察生命周期；`macos.py` 负责窗口截图与 OCR；`demo.py` 提供无微信测试后端。

## License

MIT。独立第三方项目，与腾讯/微信无隶属关系。