netease-mail-connector 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- netease_mail_connector-0.3.0/.gitattributes +3 -0
- netease_mail_connector-0.3.0/.gitignore +7 -0
- netease_mail_connector-0.3.0/CHANGELOG.md +70 -0
- netease_mail_connector-0.3.0/PKG-INFO +6 -0
- netease_mail_connector-0.3.0/README.md +168 -0
- netease_mail_connector-0.3.0/connector/cli.json +43 -0
- netease_mail_connector-0.3.0/connector/connector-meta.json +22 -0
- netease_mail_connector-0.3.0/connector/icon.svg +5 -0
- netease_mail_connector-0.3.0/connector/skills/netease-mail/SKILL.md +68 -0
- netease_mail_connector-0.3.0/connector-mcp/connector-meta.json +23 -0
- netease_mail_connector-0.3.0/connector-mcp/icon.svg +5 -0
- netease_mail_connector-0.3.0/connector-mcp/mcp.dev.json +10 -0
- netease_mail_connector-0.3.0/connector-mcp/mcp.json +16 -0
- netease_mail_connector-0.3.0/connector-mcp/skills/netease-mail/SKILL.md +74 -0
- netease_mail_connector-0.3.0/connector-mcp/token-schema.json +46 -0
- netease_mail_connector-0.3.0/docs/connector.md +115 -0
- netease_mail_connector-0.3.0/docs/development.md +106 -0
- netease_mail_connector-0.3.0/docs/troubleshooting.md +87 -0
- netease_mail_connector-0.3.0/pyproject.toml +23 -0
- netease_mail_connector-0.3.0/scripts/check_build.py +107 -0
- netease_mail_connector-0.3.0/scripts/smoke_cli.py +123 -0
- netease_mail_connector-0.3.0/scripts/smoke_mcp.py +59 -0
- netease_mail_connector-0.3.0/src/netease_mail_connector/__init__.py +1 -0
- netease_mail_connector-0.3.0/src/netease_mail_connector/__main__.py +28 -0
- netease_mail_connector-0.3.0/src/netease_mail_connector/auth_web.py +211 -0
- netease_mail_connector-0.3.0/src/netease_mail_connector/cli.py +243 -0
- netease_mail_connector-0.3.0/src/netease_mail_connector/config.py +109 -0
- netease_mail_connector-0.3.0/src/netease_mail_connector/errors.py +2 -0
- netease_mail_connector-0.3.0/src/netease_mail_connector/mailer.py +308 -0
- netease_mail_connector-0.3.0/src/netease_mail_connector/mime_utils.py +132 -0
- netease_mail_connector-0.3.0/src/netease_mail_connector/server.py +117 -0
- netease_mail_connector-0.3.0/tests/test_auth_web.py +117 -0
- netease_mail_connector-0.3.0/tests/test_cli.py +111 -0
- netease_mail_connector-0.3.0/tests/test_connector_package.py +121 -0
- netease_mail_connector-0.3.0/tests/test_docs.py +31 -0
- netease_mail_connector-0.3.0/tests/test_folders.py +87 -0
- netease_mail_connector-0.3.0/tests/test_mailer.py +46 -0
- netease_mail_connector-0.3.0/tests/test_mime_utils.py +88 -0
- netease_mail_connector-0.3.0/tests/test_security.py +208 -0
- netease_mail_connector-0.3.0/uv.lock +1231 -0
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# 变更记录
|
|
2
|
+
|
|
3
|
+
格式参考 Keep a Changelog,版本号遵循语义化版本。
|
|
4
|
+
|
|
5
|
+
## [0.3.0] - 2026-11-20
|
|
6
|
+
|
|
7
|
+
本版本针对上架评审的 P0/P1/P2 逐项修复。
|
|
8
|
+
|
|
9
|
+
### 变更(破坏性)
|
|
10
|
+
|
|
11
|
+
- **分发包与导入包重命名**:`netease-mail-mcp` → `netease-mail-connector`,`netease_mail_mcp` → `netease_mail_connector`。原名称在 PyPI 已被微核智算 1.0.3 占用,且导入名会互相覆盖。命令入口名(`netease-mail`、`netease-mail-mcp`)保持不变。
|
|
12
|
+
- **发信结果结构**:`sent` 仅在全部收件人都被接受时为 `true`;新增 `accepted`、`refused`、`partial` 字段,部分退信不再报告整批成功。
|
|
13
|
+
|
|
14
|
+
### 安全
|
|
15
|
+
|
|
16
|
+
- IMAP 与 SMTP 连接改用 `ssl.create_default_context()`,默认校验证书链与主机名;仅在显式设置 `MAIL_INSECURE_TLS=1` 时才放宽。
|
|
17
|
+
- 自检入口复用同一套 TLS 与账号规则,不再单独建连。
|
|
18
|
+
|
|
19
|
+
### 修复
|
|
20
|
+
|
|
21
|
+
- **搜索在 163 上恒为空**:实测 163 的 IMAP 不支持 `SUBJECT`/`FROM`/`BODY`/`HEADER` 文本检索(返回 OK 但无结果,literal 语法同样)。现在服务端无命中时自动回退为本地扫描最近 `scan` 封邮件头再匹配,返回 `search_mode`、`scanned`、`scan_truncated`;CLI 与 MCP 均新增 `scan` 参数(默认 200)。
|
|
22
|
+
- 中文与含空格的搜索值会因 ASCII 编码或未加引号而失败:命令参数现在按 IMAP 规则加引号,会话编码设为 UTF-8。
|
|
23
|
+
- 含空格的文件夹名无法打开:`SELECT` 前对文件夹名加引号。
|
|
24
|
+
- FETCH 响应中 UID 出现在字面量之后时整封邮件被丢弃:改为按响应分段合并元数据,`returned` 按实际解析条数统计。
|
|
25
|
+
- 账号显示与实际使用不一致:状态查询改用与收发相同的凭证选择规则,并返回 `source`;环境变量与本地文件账号不同时给出 `account_mismatch` 与 `saved_user`。
|
|
26
|
+
- 管道环境下中文 Windows 输出含 emoji 的主题会抛 `UnicodeEncodeError`:CLI 启动时把 stdout/stderr 重设为 UTF-8。
|
|
27
|
+
- 带 `.eml` 附件的邮件会把附件内部正文当成外层正文:MIME 解析遇到附件即停止下探,并正确记录附件名。
|
|
28
|
+
- 本地 MCP 模板中的 `${MAIL_IMAP_HOST}` 等占位符未被替换导致连接失败:开发模板移除 `env`,直接读取本机凭证文件。
|
|
29
|
+
- MCP 冒烟脚本在已登录的开发机上会读到真实邮箱:改为强制使用临时凭证目录。
|
|
30
|
+
|
|
31
|
+
### 新增
|
|
32
|
+
|
|
33
|
+
- `scripts/smoke_cli.py` 增加 `auth --web` 表单可访问性验证,覆盖真实清单里的认证命令。
|
|
34
|
+
|
|
35
|
+
## [0.2.0] - 2026-11-20(未发布)
|
|
36
|
+
|
|
37
|
+
### 新增
|
|
38
|
+
|
|
39
|
+
- **CLI 形态**:`netease-mail` 命令,覆盖 `auth login/status/logout` 与 `folders/list/search/read/send`,统一 JSON 输出。
|
|
40
|
+
- **CLI + Skill 连接器包**:`connector/`,含 `connector-meta.json`(`type: cli`、`minWorkbuddyVersion: 5.0.0`)、`cli.json`(Python 运行时托管)、`SKILL.md`。
|
|
41
|
+
- **本地网页表单登录**:`auth login --web`,仅监听 `127.0.0.1`,URL 带一次性 token,填完即验证 IMAP 并保存凭证;`cli.json` 配 `authWaitForExit: true`。
|
|
42
|
+
- 隔离测试目录支持:环境变量 `NETEASE_MAIL_HOME`。
|
|
43
|
+
- 冒烟脚本:`scripts/smoke_cli.py`(模拟 WorkBuddy 调度时序)、`scripts/smoke_mcp.py`(stdio 握手)。
|
|
44
|
+
- 文档:`README.md`、`docs/connector.md`、`docs/troubleshooting.md`、`docs/development.md`。
|
|
45
|
+
- `tests/test_docs.py`:校验文档存在、README 相对链接可解析、文档不含真实账号与本机路径。
|
|
46
|
+
|
|
47
|
+
### 变更
|
|
48
|
+
|
|
49
|
+
- 凭证来源改为「环境变量优先,其次 `~/.netease-mail/config.json`」,CLI 自行持久化。
|
|
50
|
+
- 正文输出统一 `\r\n → \n`,连续空行压到最多一个空行。
|
|
51
|
+
- MCP 依赖升级到 `mcp>=2.3.0,<3`,使用 `MCPServer`(`FastMCP` 已更名)。
|
|
52
|
+
- MCP 工具错误统一转为 `ToolError`,AI 能读到中文原因而非 `Error executing tool`。
|
|
53
|
+
|
|
54
|
+
### 修复
|
|
55
|
+
|
|
56
|
+
- `imap.select()` 现在会把文件夹名编码为 modified UTF-7,修复中文自定义文件夹无法打开的问题。
|
|
57
|
+
- 修复本地表单登录在打印 URL 阶段出错时 `server.shutdown()` 永久阻塞的问题(先启动服务线程再打印)。
|
|
58
|
+
|
|
59
|
+
### 实测
|
|
60
|
+
|
|
61
|
+
- 真实 163 账号:文件夹列表(含中文与自建文件夹)、搜索、读正文与附件名、发信、网页表单登录全部通过;读取后邮件保持未读。
|
|
62
|
+
|
|
63
|
+
## [0.1.0] - 2026-11-11
|
|
64
|
+
|
|
65
|
+
### 新增
|
|
66
|
+
|
|
67
|
+
- 初始版本:MCP stdio Server(`mail_list_folders`、`mail_list_messages`、`mail_search_messages`、`mail_read_message`、`mail_send_message`)。
|
|
68
|
+
- 163 `ID` 扩展支持(规避 `Unsafe Login`)。
|
|
69
|
+
- MCP + token 连接器包:`connector-mcp/`,含 `mcp.json`、`mcp.dev.json`、`token-schema.json`、`SKILL.md`。
|
|
70
|
+
- `python -m netease_mail_connector --check` 登录自检。
|
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
# netease-mail-connector
|
|
2
|
+
|
|
3
|
+
(仓库目录名仍为 `netease-mail-mcp`,PyPI 分发名为 `netease-mail-connector`——原名称已被其他厂商占用,不可复用。)
|
|
4
|
+
|
|
5
|
+
163 邮箱(及其他 IMAP/SMTP 邮箱)的本地接入工具:**一个 Python 包,同时提供 CLI 和 MCP Server 两种形态**,供 WorkBuddy 等 AI 客户端通过自然语言搜索、读取、发送邮件。
|
|
6
|
+
|
|
7
|
+
- 版本:0.3.0
|
|
8
|
+
- 语言/依赖:Python ≥ 3.10,`mcp>=2.3.0,<3`(仅 MCP 形态需要)
|
|
9
|
+
- 凭证:163 客户端授权码,只保存在本机,不上传任何第三方服务器
|
|
10
|
+
- 传输安全:IMAP/SMTP 默认校验证书链与主机名(`MAIL_INSECURE_TLS=1` 可显式放开,仅供企业代理环境临时排查)
|
|
11
|
+
|
|
12
|
+
## 文档
|
|
13
|
+
|
|
14
|
+
| 文档 | 内容 |
|
|
15
|
+
| --- | --- |
|
|
16
|
+
| 本页 | 功能、安装、CLI/MCP 快速开始、测试、协议范围 |
|
|
17
|
+
| [docs/connector.md](docs/connector.md) | WorkBuddy 接入与上架:两方案对比、包结构、字段要求、连接时序、提交清单 |
|
|
18
|
+
| [docs/troubleshooting.md](docs/troubleshooting.md) | 排错手册:认证/文件夹/读信/MCP/连接器/环境六类问题 |
|
|
19
|
+
| [docs/development.md](docs/development.md) | 代码结构、测试分层、如何新增命令或工具、约定与技术债 |
|
|
20
|
+
| [CHANGELOG.md](CHANGELOG.md) | 版本变更记录 |
|
|
21
|
+
|
|
22
|
+
## 功能
|
|
23
|
+
|
|
24
|
+
| 能力 | CLI 命令 | MCP 工具 |
|
|
25
|
+
| --- | --- | --- |
|
|
26
|
+
| 列出全部文件夹(含自定义、中文名、嵌套) | `netease-mail folders` | `mail_list_folders` |
|
|
27
|
+
| 列出最新邮件头 | `netease-mail list` | `mail_list_messages` |
|
|
28
|
+
| 条件搜索(发件人/主题/关键词/时间段/未读) | `netease-mail search` | `mail_search_messages` |
|
|
29
|
+
|
|
30
|
+
163 的 IMAP **不支持服务端文本检索**(`SUBJECT`/`FROM`/`BODY` 实测恒为空)。因此文本条件会自动回退为「本地扫描最近 N 封邮件头再匹配」,N 由 `--scan` 控制(默认 200),返回值会标明 `search_mode: "local_scan"` 与 `scanned` 数量。
|
|
31
|
+
| 读取正文与附件名(不标已读) | `netease-mail read` | `mail_read_message` |
|
|
32
|
+
| 发送纯文本邮件(需显式确认) | `netease-mail send --yes` | `mail_send_message` |
|
|
33
|
+
|
|
34
|
+
发信结果包含 `accepted`(服务器已接受)、`refused`(被拒地址与错误码)与 `partial`;`sent: true` 仅代表全部收件人都被接受。
|
|
35
|
+
|
|
36
|
+
刻意不做:删除、移动、标记已读、附件下载、HTML 邮件、草稿写入。写操作只保留「发信」一个口,降低 AI 误操作风险。
|
|
37
|
+
|
|
38
|
+
## 目录结构
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
netease-mail-mcp/
|
|
42
|
+
├── pyproject.toml # 包定义与两个命令行入口
|
|
43
|
+
├── src/netease_mail_connector/
|
|
44
|
+
│ ├── cli.py # netease-mail:CLI(argparse,JSON 输出)
|
|
45
|
+
│ ├── auth_web.py # 本地网页表单登录(127.0.0.1,一次性 token)
|
|
46
|
+
│ ├── server.py # netease-mail-mcp:MCP Server(mcp 2.x MCPServer)
|
|
47
|
+
│ ├── mailer.py # IMAP/SMTP 核心实现
|
|
48
|
+
│ ├── mime_utils.py # 中文头/正文/附件名/modified UTF-7 编解码
|
|
49
|
+
│ ├── config.py # 凭证加载:环境变量优先,其次 CLI 持久化文件
|
|
50
|
+
│ ├── errors.py # MailError,可读中文错误
|
|
51
|
+
│ └── __main__.py # python -m netease_mail_connector --check 自检
|
|
52
|
+
├── connector/ # WorkBuddy 上架包:CLI + Skill 方案
|
|
53
|
+
│ ├── connector-meta.json # type=cli,minWorkbuddyVersion 5.0.0
|
|
54
|
+
│ ├── cli.json # runtime python、init/auth/status/unAuth、versionCheck
|
|
55
|
+
│ └── skills/netease-mail/SKILL.md
|
|
56
|
+
├── connector-mcp/ # WorkBuddy 上架包:MCP + token 方案(备选)
|
|
57
|
+
│ ├── connector-meta.json # auth_mode=token,minWorkbuddyVersion 4.23.0
|
|
58
|
+
│ ├── mcp.json # 上架用(uvx,需先发布 PyPI)
|
|
59
|
+
│ ├── mcp.dev.json # 本地开发用(uv run --project 指向本目录)
|
|
60
|
+
│ └── token-schema.json # 授权码表单(password 类型)
|
|
61
|
+
├── scripts/
|
|
62
|
+
│ ├── smoke_cli.py # 模拟 WorkBuddy 调度:init→auth→status→unAuth
|
|
63
|
+
│ └── smoke_mcp.py # MCP stdio 冒烟测试
|
|
64
|
+
├── docs/ # 接入指南、排错手册、开发指南
|
|
65
|
+
├── CHANGELOG.md
|
|
66
|
+
└── tests/ # 67 个测试(含文档与链接校验)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## 安装
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
cd D:\workbuddy\netease-mail-mcp
|
|
73
|
+
uv sync # 安装依赖并生成 .venv
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
所有命令均通过 `uv run` 执行,无需激活虚拟环境。
|
|
77
|
+
|
|
78
|
+
## 快速开始(CLI)
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
# 1) 163 网页版「设置 → POP3/SMTP/IMAP」开启 IMAP/SMTP 服务,获取客户端授权码
|
|
82
|
+
# 2) 录入凭证(三种方式任选)
|
|
83
|
+
# a. 本地网页表单(推荐,WorkBuddy 点「连接」时也走这条)
|
|
84
|
+
uv run netease-mail auth login --web
|
|
85
|
+
# b. 终端交互录入(授权码输入不回显)
|
|
86
|
+
uv run netease-mail auth login
|
|
87
|
+
# c. 非交互
|
|
88
|
+
uv run netease-mail auth login --user a@163.com --auth-code 授权码
|
|
89
|
+
|
|
90
|
+
# 3) 使用
|
|
91
|
+
uv run netease-mail auth status # {"logged_in": true, ...}
|
|
92
|
+
uv run netease-mail folders
|
|
93
|
+
uv run netease-mail search --sender hr@company.com --days 14
|
|
94
|
+
uv run netease-mail read --uid 12345 --folder INBOX
|
|
95
|
+
uv run netease-mail send --to a@b.com --subject "主题" --body "正文" --yes
|
|
96
|
+
|
|
97
|
+
# 4) 登出(删除本机凭证,幂等)
|
|
98
|
+
uv run netease-mail auth logout
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
- 凭证文件:`~/.netease-mail/config.json`(权限 600);环境变量 `NETEASE_MAIL_HOME` 可改变存储目录。
|
|
102
|
+
- 非交互登录:`netease-mail auth login --user a@163.com --auth-code 授权码`。
|
|
103
|
+
- 其他网易系邮箱:`--imap-host imap.126.com --smtp-host smtp.126.com`。
|
|
104
|
+
- 退出码:`0` 成功;`1` 一般错误;`2` 未登录。
|
|
105
|
+
|
|
106
|
+
WorkBuddy 点「连接」时的实际交互:后台 `pip install` → 启动 `auth login --web`(`cli.json` 配了 `authWaitForExit: true`,进程不被提前终止)→ 浏览器打开本地表单 → 填邮箱与授权码,IMAP 验证通过即保存并提示可关闭页面 → `status` 轮询到 `logged_in: true`,卡片变已连接。表单只监听 `127.0.0.1`,URL 带一次性 token,授权码不会回显在页面上。
|
|
107
|
+
|
|
108
|
+
## 快速开始(MCP)
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
set MAIL_USER=yourname@163.com
|
|
112
|
+
set MAIL_AUTH_CODE=你的授权码
|
|
113
|
+
uv run python -m netease_mail_connector --check # 自检:IMAP + SMTP 登录,不读不发邮件
|
|
114
|
+
uv run netease-mail-mcp # 启动 stdio MCP Server
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
环境变量:`MAIL_USER`、`MAIL_AUTH_CODE`(必填),`MAIL_IMAP_HOST`、`MAIL_SMTP_HOST`、`MAIL_IMAP_PORT`、`MAIL_SMTP_PORT`、`MAIL_TIMEOUT`(可选)。环境变量优先于 CLI 保存的凭证。
|
|
118
|
+
|
|
119
|
+
WorkBuddy 本地接入:连接器管理 → 自定义连接器,粘贴 `connector-mcp/mcp.dev.json` 内容即可。该模板不带 `env`,服务启动时会读取本机 `~/.netease-mail/config.json`(先跑 `auth login --web` 或用 `auth login --user --auth-code` 写一次)。上架包 `mcp.json` 才使用 `${MAIL_USER}` 表单占位符,普通 `mcp.json` 不做变量替换。
|
|
120
|
+
|
|
121
|
+
## 测试
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
uv run pytest -q # 第 1 层:67 个测试,无网络无凭证
|
|
125
|
+
uv run python scripts/smoke_cli.py # 第 2 层:模拟 WorkBuddy 调度 init/auth/status/unAuth 全生命周期
|
|
126
|
+
uv run python scripts/smoke_mcp.py # 第 2 层:真实 stdio 握手;有 MAIL_* 环境变量时做真实搜索
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
两个冒烟脚本在设置了 `MAIL_USER` / `MAIL_AUTH_CODE` 环境变量后会自动加跑真实账号分支;`smoke_cli.py` 使用临时目录隔离凭证,不会读写真实的 `~/.netease-mail`。
|
|
130
|
+
|
|
131
|
+
第 3 层真实账号联调:`auth login` 后依次跑 `folders` / `search` / `read` / `send`(发信发给自己)。
|
|
132
|
+
第 4 层 WorkBuddy 验收:自然语言「列出所有文件夹」「找最近两周某发件人的邮件」「读出最新一封」,并确认 AI 发信前会复述并等待确认、读取后邮件仍保持未读。
|
|
133
|
+
|
|
134
|
+
## 协议与适用范围
|
|
135
|
+
|
|
136
|
+
- 支持:**IMAP4 over SSL(993)读取 + SMTP over SSL(465)发送**;IMAP `ID` 扩展(163 强制)、`UID SEARCH`(UTF-8 中文搜索)、`BODY.PEEK`、modified UTF-7 文件夹名。
|
|
137
|
+
- 不支持:POP3、STARTTLS(143/587)、OAuth2/XOAUTH2、Exchange/EWS、Gmail/Outlook 专有 API。
|
|
138
|
+
- 可用:163、126、yeah.net 等网易系;其他「IMAP/SMTP + 授权码 + SSL」邮箱理论可连(未实测)。
|
|
139
|
+
- 不可用:Gmail、Outlook.com、纯 Exchange 内网邮箱。
|
|
140
|
+
|
|
141
|
+
## 实测记录
|
|
142
|
+
|
|
143
|
+
2026-11-20,真实 163 账号执行 `scripts/smoke_mcp.py`:
|
|
144
|
+
|
|
145
|
+
- stdio 握手与 5 个工具注册正常;
|
|
146
|
+
- 返回 10 个文件夹,含中文系统文件夹(草稿箱、已发送、已删除、垃圾邮件、病毒文件夹、广告邮件、订阅邮件)与用户自建文件夹(`code-project`、`阿里云`),modified UTF-7 解码正确;
|
|
147
|
+
- 163 的自定义文件夹为**顶层**结构,不带 `INBOX.` 前缀或层级分隔符,`--folder 阿里云` 可直接使用;
|
|
148
|
+
- 近 7 天命中 21 封邮件,中文主题与发件人显示正常,UID 为 10 位数字(按字符串处理);
|
|
149
|
+
- 读取 `uid 1409749410`(185 KB 账单邮件):纯文本正文提取正常,附件名 `Invoice-24641544.pdf` 解析正确,读取后网页版**仍为未读**(`BODY.PEEK` 生效);
|
|
150
|
+
- 真实发信验证通过:收件箱收到、已发送有记录、正文无乱码;
|
|
151
|
+
- 网页表单登录(`auth login --web`)实测通过:浏览器填写邮箱与授权码 → 页面显示「已连接」→ `auth status` 返回 `logged_in: true`,凭证写入 `~/.netease-mail/config.json`;
|
|
152
|
+
- 授权码失效场景:`auth status --verify` 返回可读的中文错误(`IMAP 登录失败:LOGIN Login error or password error`),未抛出堆栈;
|
|
153
|
+
- 搜索:确认 163 服务端文本检索不可用(`SUBJECT`/`FROM`/`BODY`/`HEADER` 全空),本地回退生效——中文主题「世界儿童日」命中 1 封,发件人 `bandwagonhost.com` 命中 7 封,`scanned=49`。
|
|
154
|
+
|
|
155
|
+
未实测:真实环境下的部分退信(已用模拟 SMTP 响应覆盖单测)。附件只解析文件名,不支持下载内容。
|
|
156
|
+
|
|
157
|
+
## 上架 WorkBuddy 市场前的待办
|
|
158
|
+
|
|
159
|
+
1. `uv build` 并发布到 PyPI——`cli.json` 的 `pip install netease-mail-connector` 与 `mcp.json` 的 `uvx --from` 都依赖已发布的包。**注意原名称 `netease-mail-mcp` 已被其他厂商占用,不可复用。**
|
|
160
|
+
2. 在**空环境**(干净 venv 或容器)里按 `cli.json` 与 `mcp.json` 各安装/启动一次,确认拿到的是本项目的命令与工具,而不是同名包。
|
|
161
|
+
2. 向 WorkBuddy 团队确认 `runtime.python.version` 的写法(当前按 Node 风格填 `>=3.10`)。
|
|
162
|
+
3. 两种接入方案二选一提交(一个 Connector 不能混用),递增 `version`。
|
|
163
|
+
|
|
164
|
+
## 实现备注(踩过的坑)
|
|
165
|
+
|
|
166
|
+
- **163 `Unsafe Login`**:IMAP 登录前必须 `xatom("ID", ...)` 上报客户端身份,已在 `mailer.py` 内置。
|
|
167
|
+
- **mcp Python SDK 2.x**:`FastMCP` 已改名 `MCPServer`;业务错误必须抛 `ToolError`,否则 AI 只能看到笼统的 `Error executing tool`。
|
|
168
|
+
- **中文自定义文件夹**:`LIST` 返回 modified UTF-7 需解码展示,`SELECT` 前必须编码回去,否则中文名文件夹打不开。
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
{
|
|
2
|
+
"runtime": { "type": "python", "version": ">=3.10" },
|
|
3
|
+
"init": {
|
|
4
|
+
"darwin": "python -m pip install netease-mail-connector",
|
|
5
|
+
"linux": "python -m pip install netease-mail-connector",
|
|
6
|
+
"win32": "python -m pip install netease-mail-connector"
|
|
7
|
+
},
|
|
8
|
+
"auth": [
|
|
9
|
+
{
|
|
10
|
+
"command": {
|
|
11
|
+
"darwin": "netease-mail auth login --web",
|
|
12
|
+
"linux": "netease-mail auth login --web",
|
|
13
|
+
"win32": "netease-mail auth login --web"
|
|
14
|
+
},
|
|
15
|
+
"skipIf": {
|
|
16
|
+
"darwin": "netease-mail auth status",
|
|
17
|
+
"linux": "netease-mail auth status",
|
|
18
|
+
"win32": "netease-mail auth status"
|
|
19
|
+
},
|
|
20
|
+
"authWaitForExit": true
|
|
21
|
+
}
|
|
22
|
+
],
|
|
23
|
+
"status": {
|
|
24
|
+
"darwin": "netease-mail auth status",
|
|
25
|
+
"linux": "netease-mail auth status",
|
|
26
|
+
"win32": "netease-mail auth status"
|
|
27
|
+
},
|
|
28
|
+
"statusMatchJson": { "logged_in": true },
|
|
29
|
+
"unAuth": {
|
|
30
|
+
"darwin": "netease-mail auth logout",
|
|
31
|
+
"linux": "netease-mail auth logout",
|
|
32
|
+
"win32": "netease-mail auth logout"
|
|
33
|
+
},
|
|
34
|
+
"versionCheck": {
|
|
35
|
+
"command": {
|
|
36
|
+
"darwin": "netease-mail --version",
|
|
37
|
+
"linux": "netease-mail --version",
|
|
38
|
+
"win32": "netease-mail --version"
|
|
39
|
+
},
|
|
40
|
+
"minVersion": "0.3.0",
|
|
41
|
+
"versionPattern": "(\\d+\\.\\d+\\.\\d+)"
|
|
42
|
+
}
|
|
43
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "163邮箱",
|
|
3
|
+
"name_zh": "163邮箱",
|
|
4
|
+
"name_en": "NetEase Mail",
|
|
5
|
+
"description": "Search, read and send 163 mail from a local CLI over IMAP/SMTP.",
|
|
6
|
+
"description_zh": "通过本机 CLI 直连 163 邮箱:搜索邮件、读取正文、发送邮件,授权码由 CLI 保存在本机。",
|
|
7
|
+
"description_en": "Connect to 163 Mail from a local CLI over IMAP/SMTP: search, read and send messages. Credentials are stored locally by the CLI.",
|
|
8
|
+
"source": "netease-mail",
|
|
9
|
+
"type": "cli",
|
|
10
|
+
"version": "0.3.0",
|
|
11
|
+
"minWorkbuddyVersion": "5.0.0",
|
|
12
|
+
"examples_zh": [
|
|
13
|
+
"找出最近两周来自 hr@company.com 的所有邮件",
|
|
14
|
+
"搜索主题里带发票的未读邮件并读出最新一封的内容",
|
|
15
|
+
"帮我给 zhangsan@example.com 发一封项目进度同步邮件"
|
|
16
|
+
],
|
|
17
|
+
"examples_en": [
|
|
18
|
+
"Find all emails from hr@company.com in the last two weeks",
|
|
19
|
+
"Search unread emails with invoice in the subject and read the latest one",
|
|
20
|
+
"Send a project status update to zhangsan@example.com"
|
|
21
|
+
]
|
|
22
|
+
}
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
|
|
2
|
+
<rect x="4" y="12" width="56" height="40" rx="8" fill="#D43D2A"/>
|
|
3
|
+
<path d="M8 18 L32 38 L56 18" fill="none" stroke="#FFFFFF" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
|
|
4
|
+
<rect x="8" y="20" width="48" height="28" rx="4" fill="none" stroke="#FFFFFF" stroke-width="2" opacity="0.5"/>
|
|
5
|
+
</svg>
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: netease-mail
|
|
3
|
+
description: 163 邮箱(网易系及通用 IMAP/SMTP 邮箱)命令行技能 - 用 netease-mail CLI 搜索邮件、读取正文、发送邮件
|
|
4
|
+
version: 0.2.0
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 163 邮箱 CLI Skill
|
|
8
|
+
|
|
9
|
+
所有操作通过 `netease-mail` 命令完成,**输出统一为 JSON**,直接解析即可。Windows / macOS / Linux 命令相同。
|
|
10
|
+
|
|
11
|
+
## 登录态
|
|
12
|
+
|
|
13
|
+
| 命令 | 作用 | 退出码 |
|
|
14
|
+
| --- | --- | --- |
|
|
15
|
+
| `netease-mail auth status` | 检查登录态,输出 `{"logged_in": true, "user": "..."}` | 已登录 0,未登录 2 |
|
|
16
|
+
| `netease-mail auth login` | 交互式录入授权码并验证 IMAP(**只能在用户终端执行**) | 0 成功 |
|
|
17
|
+
| `netease-mail auth login --web` | 启动本地网页表单(127.0.0.1 随机端口),在浏览器填邮箱与授权码;WorkBuddy 点连接时走这条 | 0 成功 |
|
|
18
|
+
| `netease-mail auth login --guide` | 打印授权码获取指引,不交互 | 2 |
|
|
19
|
+
| `netease-mail auth logout` | 删除本机凭证,幂等 | 0 |
|
|
20
|
+
|
|
21
|
+
- 任何邮件命令报「尚未登录」时,不要反复重试,引导用户在终端执行 `netease-mail auth login --web`。
|
|
22
|
+
- 凭证文件在 `~/.netease-mail/config.json`,**不要读取、打印或外传其中的 auth_code**。
|
|
23
|
+
|
|
24
|
+
## 读邮件
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
netease-mail folders # 列出文件夹
|
|
28
|
+
netease-mail list --folder INBOX --limit 20 # 最新邮件头
|
|
29
|
+
netease-mail search --sender hr@company.com --days 14 # 条件搜索
|
|
30
|
+
netease-mail search --subject 发票 --unread # 未读 + 主题
|
|
31
|
+
netease-mail search --keyword 合同 --days 0 # 关键词匹配主题或发件人,不限时间
|
|
32
|
+
netease-mail read --uid 12345 --folder INBOX # 读正文与附件名
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
搜索参数:`--folder`(默认 INBOX)、`--sender`、`--subject`、`--keyword`、`--days`(默认 30,0 为不限)、`--unread`、`--limit`(默认 20)、`--scan`(文本过滤时最多扫描多少封,默认 200)。
|
|
36
|
+
搜索返回 `total_matched` 与 `messages[]`(含 `uid`、`subject`、`from`、`date`、`size`),**不含正文**。
|
|
37
|
+
|
|
38
|
+
**163 的服务端不支持文本检索**,带 `--sender`/`--subject`/`--keyword` 时会返回 `search_mode: "local_scan"`,即扫描最近 `--scan` 封再本地匹配。若 `scan_truncated: true`,说明还有更早邮件未覆盖——结果偏少时调大 `--scan` 或用 `--days` 收窄范围,并如实告知用户「只搜索了最近 N 封」。
|
|
39
|
+
|
|
40
|
+
## 发邮件
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
netease-mail send --to zhangsan@example.com --cc lisi@example.com \
|
|
44
|
+
--subject "项目进度同步" --body "正文内容" --yes
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
**发信纪律**:
|
|
48
|
+
1. 先向用户复述收件人、主题、正文要点,得到确认后才执行。
|
|
49
|
+
2. `--yes` 是必填的显式确认开关,缺了命令会拒绝执行。
|
|
50
|
+
3. 只支持纯文本,不支持附件与 HTML;不代用户群发,不编造收件人。
|
|
51
|
+
4. 返回 `sent: true` 表示全部收件人都被接受。若 `sent: false`,先看 `refused` 里的地址和错误码,**不要整批重发**——`accepted` 里的人会收到两次;应只对 `refused` 里的地址重试或告知用户。
|
|
52
|
+
|
|
53
|
+
## 使用要点
|
|
54
|
+
|
|
55
|
+
1. **先搜后读**:用 `uid` 读正文,且 `--folder` 必须与搜索时一致。
|
|
56
|
+
2. **不确定文件夹名**先跑 `folders`(已发送、垃圾邮件等名称以实际返回为准)。
|
|
57
|
+
3. **加时间范围**:用户没指定时间就用默认 30 天,避免全量扫描邮箱。
|
|
58
|
+
4. `read` 使用 BODY.PEEK,**不会把邮件标为已读**;本工具不做删除、移动、标记等写操作。
|
|
59
|
+
5. 正文默认截断 8000 字符,需要更多时用 `--max-chars` 调大,并注意 `body_truncated` 标记。
|
|
60
|
+
|
|
61
|
+
## 常见错误
|
|
62
|
+
|
|
63
|
+
| 报错 | 处理 |
|
|
64
|
+
| --- | --- |
|
|
65
|
+
| `尚未登录` | 引导用户在终端执行 `netease-mail auth login` |
|
|
66
|
+
| `IMAP 登录失败` | 检查是否开启 IMAP/SMTP 服务、填的是授权码而非登录密码 |
|
|
67
|
+
| `无法打开文件夹` | 先 `folders` 拿准确名称 |
|
|
68
|
+
| SMTP 被拒 / 频繁发信失败 | 163 有发信频率限制,提示稍后再试 |
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "163邮箱",
|
|
3
|
+
"name_zh": "163邮箱",
|
|
4
|
+
"name_en": "NetEase Mail",
|
|
5
|
+
"description": "Search, read and send 163 mail via local IMAP/SMTP MCP.",
|
|
6
|
+
"description_zh": "在本机直连 163 邮箱:搜索邮件、读取正文、发送邮件,授权码仅保存在本机。",
|
|
7
|
+
"description_en": "Connect to 163 Mail locally over IMAP/SMTP: search, read and send messages. Credentials stay on your machine.",
|
|
8
|
+
"source": "netease-mail",
|
|
9
|
+
"type": "mcp",
|
|
10
|
+
"version": "0.3.0",
|
|
11
|
+
"auth_mode": "token",
|
|
12
|
+
"minWorkbuddyVersion": "4.23.0",
|
|
13
|
+
"examples_zh": [
|
|
14
|
+
"找出最近两周来自 hr@company.com 的所有邮件",
|
|
15
|
+
"搜索主题里带发票的未读邮件并读出最新一封的内容",
|
|
16
|
+
"帮我给 zhangsan@example.com 发一封项目进度同步邮件"
|
|
17
|
+
],
|
|
18
|
+
"examples_en": [
|
|
19
|
+
"Find all emails from hr@company.com in the last two weeks",
|
|
20
|
+
"Search unread emails with invoice in the subject and read the latest one",
|
|
21
|
+
"Send a project status update to zhangsan@example.com"
|
|
22
|
+
]
|
|
23
|
+
}
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
|
|
2
|
+
<rect x="4" y="12" width="56" height="40" rx="8" fill="#D43D2A"/>
|
|
3
|
+
<path d="M8 18 L32 38 L56 18" fill="none" stroke="#FFFFFF" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
|
|
4
|
+
<rect x="8" y="20" width="48" height="28" rx="4" fill="none" stroke="#FFFFFF" stroke-width="2" opacity="0.5"/>
|
|
5
|
+
</svg>
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
{
|
|
2
|
+
"mcpServers": {
|
|
3
|
+
"netease-mail": {
|
|
4
|
+
"type": "stdio",
|
|
5
|
+
"command": "uvx",
|
|
6
|
+
"args": ["--from", "netease-mail-connector", "netease-mail-mcp"],
|
|
7
|
+
"env": {
|
|
8
|
+
"MAIL_USER": "${MAIL_USER}",
|
|
9
|
+
"MAIL_AUTH_CODE": "${MAIL_AUTH_CODE}",
|
|
10
|
+
"MAIL_IMAP_HOST": "${MAIL_IMAP_HOST}",
|
|
11
|
+
"MAIL_SMTP_HOST": "${MAIL_SMTP_HOST}"
|
|
12
|
+
},
|
|
13
|
+
"timeout": 60000
|
|
14
|
+
}
|
|
15
|
+
}
|
|
16
|
+
}
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: netease-mail
|
|
3
|
+
description: 163 邮箱(网易系及通用 IMAP/SMTP 邮箱)操作技能 - 搜索邮件、读取正文、发送邮件
|
|
4
|
+
version: 0.1.0
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# 163 邮箱 Skill
|
|
8
|
+
|
|
9
|
+
通过本地 MCP Server 直连 IMAP/SMTP,处理用户的邮件任务。授权码只保存在用户本机。
|
|
10
|
+
|
|
11
|
+
## 可用工具
|
|
12
|
+
|
|
13
|
+
### mail_list_folders - 列出邮箱文件夹
|
|
14
|
+
无参数。返回 `folders` 数组,含 INBOX、已发送、草稿、垃圾邮件等。
|
|
15
|
+
|
|
16
|
+
### mail_list_messages - 列出最新邮件
|
|
17
|
+
| 参数 | 类型 | 必填 | 说明 |
|
|
18
|
+
| --- | --- | :--: | --- |
|
|
19
|
+
| folder | string | 否 | 文件夹名,默认 `INBOX` |
|
|
20
|
+
| limit | number | 否 | 数量上限,默认 20,建议不超过 50 |
|
|
21
|
+
|
|
22
|
+
### mail_search_messages - 搜索邮件
|
|
23
|
+
| 参数 | 类型 | 必填 | 说明 |
|
|
24
|
+
| --- | --- | :--: | --- |
|
|
25
|
+
| folder | string | 否 | 默认 `INBOX` |
|
|
26
|
+
| sender | string | 否 | 发件人地址或名字片段,如 `hr@company.com` |
|
|
27
|
+
| subject | string | 否 | 主题包含的文字 |
|
|
28
|
+
| keyword | string | 否 | 同时匹配主题或发件人的关键词 |
|
|
29
|
+
| days | number | 否 | 最近 N 天,默认 30;`0` 表示不限时间 |
|
|
30
|
+
| unread_only | boolean | 否 | 只看未读 |
|
|
31
|
+
| limit | number | 否 | 默认 20 |
|
|
32
|
+
| scan | number | 否 | 文本过滤时最多扫描的邮件数,默认 200 |
|
|
33
|
+
|
|
34
|
+
返回 `total_matched`(命中总数)、`returned`、`messages[]`(含 `uid`、`subject`、`from`、`date`、`size`)。
|
|
35
|
+
|
|
36
|
+
**163 不支持服务端文本检索**:带 `sender`/`subject`/`keyword` 时返回 `search_mode: "local_scan"`,即扫描最近 `scan` 封再本地匹配。`scan_truncated: true` 表示还有更早邮件未覆盖,结果偏少时调大 `scan` 或缩小 `days`,并如实告知用户搜索范围。
|
|
37
|
+
|
|
38
|
+
### mail_read_message - 读取正文
|
|
39
|
+
| 参数 | 类型 | 必填 | 说明 |
|
|
40
|
+
| --- | --- | :--: | --- |
|
|
41
|
+
| uid | string | 是 | 来自列表/搜索结果 |
|
|
42
|
+
| folder | string | 否 | 必须与搜索时用的文件夹一致 |
|
|
43
|
+
| max_chars | number | 否 | 正文截断长度,默认 8000 |
|
|
44
|
+
|
|
45
|
+
返回 `body`、`body_truncated`、`attachments`。**使用 BODY.PEEK,不会把邮件标为已读。**
|
|
46
|
+
|
|
47
|
+
### mail_send_message - 发送邮件
|
|
48
|
+
| 参数 | 类型 | 必填 | 说明 |
|
|
49
|
+
| --- | --- | :--: | --- |
|
|
50
|
+
| to | string | 是 | 收件人,多个用英文逗号分隔 |
|
|
51
|
+
| subject | string | 是 | 主题 |
|
|
52
|
+
| body | string | 是 | 纯文本正文 |
|
|
53
|
+
| cc | string | 否 | 抄送 |
|
|
54
|
+
|
|
55
|
+
## 工作方式
|
|
56
|
+
|
|
57
|
+
1. **先搜后读**:搜索/列表只返回邮件头,要正文必须再用 `uid` 调 `mail_read_message`。读多封时逐封读取,不要一次拉大 limit。
|
|
58
|
+
2. **文件夹要对应**:跨文件夹的邮件(如已发送、垃圾邮件)必须先 `mail_list_folders` 确认名称,读取时带上同一个 `folder`。
|
|
59
|
+
3. **时间条件**:用户说「最近两周」→ `days: 14`;没说时间就保持默认 30 天,避免全量扫描邮箱。
|
|
60
|
+
4. **中文搜索**已处理 UTF-8 编码,直接传中文关键词即可。
|
|
61
|
+
|
|
62
|
+
## 发信纪律(重要)
|
|
63
|
+
|
|
64
|
+
- 发信前必须向用户复述收件人、主题、正文要点并获得确认。
|
|
65
|
+
- 不代用户群发、不编造收件人地址、不在正文里写入用户没提供的承诺或数据。
|
|
66
|
+
- 只支持纯文本;不支持附件与 HTML 排版,需要时说明并让用户在网页版完成。
|
|
67
|
+
- 返回 `sent: true` 表示全部收件人都被接受。`sent: false` 时看 `refused` 的地址与错误码,**不要整批重发**(`accepted` 里的人会重复收到),只对 `refused` 重试或告知用户。
|
|
68
|
+
|
|
69
|
+
## 错误与边界
|
|
70
|
+
|
|
71
|
+
- 报「IMAP/SMTP 登录失败」→ 引导用户检查:① 是否开启 IMAP/SMTP 服务;② 填的是**授权码**而非登录密码;③ 授权码是否被重置。
|
|
72
|
+
- 报「无法打开文件夹」→ 先列文件夹再用准确名称。
|
|
73
|
+
- 本连接器**不做**删除、移动、标记已读等写操作,用户要求时说明当前只读 + 发信。
|
|
74
|
+
- 163 有发信频率限制,短时间大量发送会被拒,遇到时提示稍后再试。
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
{
|
|
2
|
+
"title": "163 邮箱连接配置",
|
|
3
|
+
"title_en": "NetEase Mail Configuration",
|
|
4
|
+
"description": "填写邮箱地址与客户端授权码。凭证仅存储在本机 ~/.workbuddy 目录下,不会上传到任何第三方服务器。",
|
|
5
|
+
"description_en": "Enter your email address and client authorization code. Credentials are stored locally in ~/.workbuddy only.",
|
|
6
|
+
"docUrl": "https://help.mail.163.com/",
|
|
7
|
+
"docLabel": "如何开启 IMAP/SMTP 并获取授权码?",
|
|
8
|
+
"fields": [
|
|
9
|
+
{
|
|
10
|
+
"key": "MAIL_USER",
|
|
11
|
+
"label": "邮箱地址",
|
|
12
|
+
"label_en": "Email address",
|
|
13
|
+
"type": "text",
|
|
14
|
+
"required": true,
|
|
15
|
+
"placeholder": "yourname@163.com",
|
|
16
|
+
"description": "完整的 163 邮箱地址,也支持 126、yeah.net 等网易系邮箱。"
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
"key": "MAIL_AUTH_CODE",
|
|
20
|
+
"label": "客户端授权码",
|
|
21
|
+
"label_en": "Authorization code",
|
|
22
|
+
"type": "password",
|
|
23
|
+
"required": true,
|
|
24
|
+
"placeholder": "不是邮箱登录密码",
|
|
25
|
+
"description": "在 163 网页版「设置 → POP3/SMTP/IMAP」开启 IMAP/SMTP 服务后生成的授权码。"
|
|
26
|
+
},
|
|
27
|
+
{
|
|
28
|
+
"key": "MAIL_IMAP_HOST",
|
|
29
|
+
"label": "IMAP 服务器",
|
|
30
|
+
"label_en": "IMAP host",
|
|
31
|
+
"type": "text",
|
|
32
|
+
"required": false,
|
|
33
|
+
"defaultValue": "imap.163.com",
|
|
34
|
+
"description": "读取邮件使用,SSL 端口 993。126 邮箱填 imap.126.com,企业邮箱按服务商说明填写。"
|
|
35
|
+
},
|
|
36
|
+
{
|
|
37
|
+
"key": "MAIL_SMTP_HOST",
|
|
38
|
+
"label": "SMTP 服务器",
|
|
39
|
+
"label_en": "SMTP host",
|
|
40
|
+
"type": "text",
|
|
41
|
+
"required": false,
|
|
42
|
+
"defaultValue": "smtp.163.com",
|
|
43
|
+
"description": "发送邮件使用,SSL 端口 465。126 邮箱填 smtp.126.com。"
|
|
44
|
+
}
|
|
45
|
+
]
|
|
46
|
+
}
|