# 统一邮件与附件读取工具

独立运行的 Python 工具，提供命令行与本地 stdio MCP 接口。支持多账号绑定、分页列收件箱、读取正文、下载附件和整封邮件导出。

## 验证状态

| 邮箱 | 适配器实现 | 模拟测试 | 真实邮箱验证 |
|---|---|---|---|
| Outlook 个人邮箱 | 已完成 | 已通过 | 已通过：正文、附件和文件一致性 |
| Gmail | 已完成 | 已通过 | 未完成：缺少 Google OAuth 客户端配置及用户授权 |
| QQ | 已完成 | 已通过 | 未完成：缺少用户 IMAP 授权 |
| 其他 IMAP | 通用适配已实现 | 已通过 | 未逐厂商验证 |

模拟测试不代表真实服务接入已验证。当前是本机单用户工具，不是公开部署的多租户服务。

## 快速开始

```bash
uv sync --locked
uv run python -m mail_tool accounts
uv run python -m mail_tool list --account outlook-main --limit 5
uv run python -m mail_tool get --account outlook-main --message '邮件ID'
uv run python -m mail_tool export --account outlook-main --message '邮件ID'
```

本机已有账号 outlook-main 可直接使用。新邮箱先绑定：

```bash
uv run python -m mail_tool bind outlook --account outlook-main --client-id '微软应用ClientID'
uv run python -m mail_tool bind gmail --account gmail-main --credentials .state/google-client.json
uv run python -m mail_tool bind qq --account qq-main --email '你的邮箱@qq.com'
```

Gmail 使用 Desktop OAuth JSON 和浏览器授权；QQ 在终端隐藏输入客户端授权码。不要将凭据写入聊天或提交到 Git。

config.example.json 仍可复制为 config.json 保存 Microsoft Client ID。原授权缓存和历史下载文件保留，旧代码已迁入 mail_tool；不再使用旧模块入口。

## MCP 和测试

```bash
uv run python -m mail_tool serve
uv run python -m unittest discover -v
```

MCP 提供 mail_list_accounts、mail_list_messages、mail_get_message、mail_download_attachment、mail_export_message。

完整绑定步骤、MCP客户端配置、Provider扩展方法和当前边界见 [邮件工具使用说明](邮件工具使用说明.md)。

## 代码结构

- mail_tool/outlook_auth.py：微软授权与令牌缓存。
- mail_tool/providers.py：Provider协议和三类邮箱适配器。
- mail_tool/common.py：MIME解析、文件名处理、游标及文件保存。
- mail_tool/service.py：统一账号、邮件和附件服务。
- mail_tool/__main__.py：命令行入口。
- mail_tool/mcp_server.py：MCP接口。

下一步分别绑定 Gmail、QQ，用含正文和附件的测试邮件执行 list → get → export，核对正文和原附件哈希。验证前不将两家标记为已接通。