yach-mail-tool 0.1.0__tar.gz

yach_mail_tool-0.1.0/.cursor/mcp.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "netease-mail": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/Users/tal/Desktop/好未来/MailTool",
+        "python",
+        "-m",
+        "mailtool"
+      ]
+    }
+  }
+}

yach_mail_tool-0.1.0/.env.example

@@ -0,0 +1,7 @@
+# 完整邮箱地址
+MAIL_USER=
+# 网页邮箱「设置 → 账户与安全 → 客户端设置」生成的授权码，不是登录密码
+MAIL_AUTH_CODE=
+# tal.com 的 MX 在网易杭州机房
+MAIL_IMAP_HOST=imap.163.com
+MAIL_IMAP_PORT=993

yach_mail_tool-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+.env
+__pycache__/
+.pytest_cache/
+*.pyc
+dist/
+build/
+*.egg-info/

yach_mail_tool-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.5
+Name: yach-mail-tool
+Version: 0.1.0
+Summary: 只读查询网易邮箱的 MCP 服务
+Requires-Python: >=3.10
+Requires-Dist: imapclient>=3.0.1
+Requires-Dist: keyring>=25
+Requires-Dist: mcp>=2
+Provides-Extra: bundle
+Requires-Dist: pyinstaller>=6; extra == 'bundle'
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'

yach_mail_tool-0.1.0/README.md

@@ -0,0 +1,84 @@
+# 网易邮箱 MCP
+
+本地只读查询网易邮箱。发给别人的是编好的 `yach-mail-tool` 程序，不是这份源码。Cursor、Claude Desktop、Claude Code、VS Code 以及其他能配置 MCP 的客户端都可以用。
+
+程序通过标准输入输出提供 MCP 工具。邮箱和客户端授权码在本机浏览器页面里填写，优先写入系统钥匙串。Linux 上如果没有钥匙串服务，则写到 `~/.config/netease-mail-mcp/mailbox.json`，权限为仅本人可读。授权码不会出现在工具参数或对话里。
+
+`@163.com`、`@126.com`、`@yeah.net` 使用对应的个人邮箱服务器，其他域名使用企业邮杭州机房 `imaphz.qiye.163.com`。
+
+## 打包
+
+在目标系统上打包。macOS 打出来的程序只能在 macOS 使用，Linux 同理。
+
+```bash
+uv sync --extra bundle
+uv run pyinstaller netease-mail-mcp.spec
+```
+
+产物是 `dist/yach-mail-tool`。把这个文件交给用户即可。
+
+## 发给 Agent 的安装话术
+
+把程序放到本机后，把下面这段原样发给要安装的 Agent。它会找自己的 MCP 配置并写入，不依赖 Cursor、Claude 或 VS Code 的固定路径。
+
+```text
+请在你自己的 MCP 配置里安装本地服务 netease-mail，保留已有的其他服务。
+
+1. 在本机找到可执行文件 yach-mail-tool 的绝对路径。找不到就停下来告诉我，不要改用别的邮箱工具。
+2. 找到你这个客户端实际读取的 MCP 配置文件并合并进去，不要覆盖整个文件。配置为：
+   名称：netease-mail
+   command：上一步得到的绝对路径
+   不需要 args，不需要 env。
+3. 如果配置分成「命令」和「参数」两栏，命令填绝对路径，参数留空。
+4. 写完后重载 MCP，确认 netease-mail 已出现。
+5. 不要向我索要邮箱或授权码，也不要在命令参数里填写它们。第一次查信时，程序会打开本机浏览器让我填写。
+```
+
+## 用户安装
+
+```bash
+chmod +x yach-mail-tool
+mv yach-mail-tool /usr/local/bin/
+yach-mail-tool install
+```
+
+`install` 会写入：
+
+| 系统 | 客户端 | 配置文件 |
+|---|---|---|
+| macOS / Linux | Cursor | `~/.cursor/mcp.json` |
+| macOS | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Linux | Claude Desktop | `~/.config/Claude/claude_desktop_config.json` |
+| macOS / Linux | Claude Code | `~/.claude.json` |
+| macOS | VS Code | `~/Library/Application Support/Code/User/mcp.json` |
+| Linux | VS Code | `~/.config/Code/User/mcp.json` |
+
+已有的其他 MCP 配置会保留。某个文件不是合法 JSON 时会跳过，避免把原文件盖坏。
+
+其他客户端执行 `yach-mail-tool config`，把打印出的配置贴进自己的 MCP 设置。命令必须是程序的绝对路径。
+
+写好后重载该客户端的 MCP。
+
+## 第一次查信
+
+对话里直接说「看看最近的邮件」。如果这台电脑还没配置过，程序会打开浏览器。页面只监听 `127.0.0.1`，链接带一次性口令。
+
+用户填写：
+
+- 邮箱地址
+- 网页邮箱「设置 → 账户与安全 → 客户端设置」生成的授权码
+
+授权码不是登录密码。保存后关掉页面，回到对话即可。更换授权码时说「重新配置邮箱」，Agent 会调用 `configure_mailbox` 再次打开页面。
+
+## 工具
+
+| 工具 | 作用 |
+|---|---|
+| `mailbox_status` | 是否已配置，只返回邮箱地址 |
+| `configure_mailbox` | 打开本机浏览器填写授权码 |
+| `list_mail_folders` | 列出文件夹 |
+| `list_messages` | 最近邮件 |
+| `search_messages` | 按发件人、收件人、主题、日期搜索信头 |
+| `get_mail_message` | 按 uid 读纯文本正文和附件名 |
+
+读信不会把邮件标成已读，也不能发信、删除或改状态。

yach_mail_tool-0.1.0/mailtool/__init__.py

@@ -0,0 +1 @@
+"""网易企业邮箱只读 MCP。"""

yach_mail_tool-0.1.0/mailtool/__main__.py

@@ -0,0 +1,4 @@
+from mailtool.cli import main
+
+if __name__ == "__main__":
+    main()

yach_mail_tool-0.1.0/mailtool/cli.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import json
+import sys
+
+from mailtool.install_mcp import install_clients, mcp_entry
+
+
+def main() -> None:
+    action = sys.argv[1] if len(sys.argv) > 1 else ""
+    if action in {"", "serve"}:
+        from mailtool.server import main as serve
+
+        serve()
+        return
+    if action == "setup":
+        from mailtool.setup_server import run_browser_setup
+
+        settings = run_browser_setup()
+        print(f"已保存 {settings.user}，服务器 {settings.host}")
+        return
+    if action == "install":
+        paths, skipped = install_clients()
+        print("已写入这些 MCP 配置，重载对应客户端后即可使用：")
+        for path in paths:
+            print(path)
+        for message in skipped:
+            print(message, file=sys.stderr)
+        return
+    if action == "config":
+        print(json.dumps({"mcpServers": {"netease-mail": mcp_entry()}}, ensure_ascii=False, indent=2))
+        return
+    print("用法: yach-mail-tool [serve|setup|install|config]", file=sys.stderr)
+    raise SystemExit(2)
+
+
+if __name__ == "__main__":
+    main()

yach_mail_tool-0.1.0/mailtool/config.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from mailtool.hosts import DEFAULT_PORT, host_for_email
+from mailtool.secrets import load_mailbox
+
+
+class MissingCredentials(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class Settings:
+    host: str
+    port: int
+    user: str
+    auth_code: str
+    timeout: float
+
+
+def load_dotenv() -> None:
+    """读取 .env，不覆盖已经存在的环境变量。设置了 MAILTOOL_ENV 时只读那一个文件。"""
+    explicit = os.environ.get("MAILTOOL_ENV", "").strip()
+    if explicit:
+        path = Path(explicit)
+        if path.is_file():
+            _apply_env_file(path)
+        return
+    for path in (Path.cwd() / ".env", Path(__file__).resolve().parents[1] / ".env"):
+        if path.is_file():
+            _apply_env_file(path)
+            return
+
+
+def load_settings() -> Settings:
+    if not getattr(sys, "frozen", False):
+        load_dotenv()
+    user = os.environ.get("MAIL_USER", "").strip()
+    auth_code = os.environ.get("MAIL_AUTH_CODE", "").strip()
+    if user and auth_code:
+        host = os.environ.get("MAIL_IMAP_HOST", "").strip() or host_for_email(user)
+        port = _parse_port(os.environ.get("MAIL_IMAP_PORT", str(DEFAULT_PORT)))
+        return Settings(host=host, port=port, user=user, auth_code=auth_code, timeout=30)
+    stored = load_mailbox()
+    if stored is None:
+        raise MissingCredentials(
+            "还没有配置邮箱。请在本机浏览器页面填写邮箱和客户端授权码，不要把授权码发到对话里。"
+        )
+    return Settings(host=stored.host, port=stored.port, user=stored.user, auth_code=stored.auth_code, timeout=30)
+
+
+def _apply_env_file(path: Path) -> None:
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in {'"', "'"}:
+            value = value[1:-1]
+        if key and key not in os.environ:
+            os.environ[key] = value
+
+
+def _parse_port(raw: str) -> int:
+    try:
+        port = int(raw)
+    except ValueError as exc:
+        raise RuntimeError("MAIL_IMAP_PORT 必须是数字") from exc
+    if not 1 <= port <= 65535:
+        raise RuntimeError("MAIL_IMAP_PORT 超出范围")
+    return port

yach_mail_tool-0.1.0/mailtool/hosts.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+DEFAULT_HOST = "imaphz.qiye.163.com"
+DEFAULT_PORT = 993
+
+_PERSONAL_HOSTS = {
+    "163.com": "imap.163.com",
+    "126.com": "imap.126.com",
+    "yeah.net": "imap.yeah.net",
+}
+
+
+def host_for_email(email: str) -> str:
+    """个人邮箱按域名选服务器，其余域名走网易企业邮杭州机房。"""
+    domain = email.strip().rsplit("@", 1)[-1].lower()
+    return _PERSONAL_HOSTS.get(domain, DEFAULT_HOST)

yach_mail_tool-0.1.0/mailtool/install_mcp.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+
+def client_config_paths(home: Path | None = None) -> dict[str, Path]:
+    root = home or Path.home()
+    if sys.platform == "darwin":
+        return {
+            "cursor": root / ".cursor" / "mcp.json",
+            "claude-desktop": root / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json",
+            "claude-code": root / ".claude.json",
+            "vscode": root / "Library" / "Application Support" / "Code" / "User" / "mcp.json",
+        }
+    return {
+        "cursor": root / ".cursor" / "mcp.json",
+        "claude-desktop": root / ".config" / "Claude" / "claude_desktop_config.json",
+        "claude-code": root / ".claude.json",
+        "vscode": root / ".config" / "Code" / "User" / "mcp.json",
+    }
+
+
+def current_command() -> list[str]:
+    if getattr(sys, "frozen", False):
+        return [sys.executable]
+    return [sys.executable, "-m", "mailtool"]
+
+
+def mcp_entry(command: list[str] | None = None) -> dict:
+    parts = command or current_command()
+    entry = {"command": parts[0]}
+    if len(parts) > 1:
+        entry["args"] = parts[1:]
+    return entry
+
+
+def merge_mcp_config(existing: dict, command: list[str] | None = None) -> dict:
+    merged = dict(existing)
+    servers = dict(merged.get("mcpServers") or {})
+    servers["netease-mail"] = mcp_entry(command)
+    merged["mcpServers"] = servers
+    return merged
+
+
+def install_clients(home: Path | None = None, command: list[str] | None = None) -> tuple[list[Path], list[str]]:
+    written: list[Path] = []
+    skipped: list[str] = []
+    for path in client_config_paths(home).values():
+        existing: dict = {}
+        if path.is_file():
+            try:
+                loaded = json.loads(path.read_text(encoding="utf-8"))
+            except json.JSONDecodeError:
+                skipped.append(f"{path} 无法解析，已跳过")
+                continue
+            if not isinstance(loaded, dict):
+                skipped.append(f"{path} 不是 JSON 对象，已跳过")
+                continue
+            existing = loaded
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps(merge_mcp_config(existing, command), ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+        written.append(path)
+    return written, skipped

yach_mail_tool-0.1.0/mailtool/mailbox.py

@@ -0,0 +1,249 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Iterator
+
+from imapclient import IMAPClient
+from imapclient.exceptions import CapabilityError, IMAPClientError
+
+from mailtool.config import Settings, load_settings
+from mailtool.parse import (
+    DEFAULT_BODY_CHARS,
+    MAX_MESSAGE_BYTES,
+    clamp_body_chars,
+    clamp_limit,
+    decode_mime_header,
+    envelope_date,
+    format_addresses,
+    parse_message,
+    to_imap_date,
+)
+
+
+class MailError(RuntimeError):
+    pass
+
+
+def friendly_imap_error(exc: Exception) -> str:
+    text = str(exc)
+    upper = text.upper()
+    if "PERMDENY" in upper:
+        return "IMAP 被拒绝。请在网页邮箱开启 IMAP，或请管理员允许这个账号使用标准协议。"
+    if "AUTHENTICATIONFAILED" in upper or "LOGIN FAIL" in upper or "INVALID" in upper:
+        return "登录失败。请确认邮箱地址和客户端授权码，授权码不是网页登录密码。"
+    return f"邮箱连接失败：{text}"
+
+
+@contextmanager
+def connect(settings: Settings | None = None) -> Iterator[IMAPClient]:
+    cfg = settings or load_settings()
+    client = IMAPClient(cfg.host, port=cfg.port, ssl=True, timeout=cfg.timeout)
+    try:
+        client.login(cfg.user, cfg.auth_code)
+        _identify(client)
+    except (IMAPClientError, OSError) as exc:
+        client.shutdown()
+        raise MailError(friendly_imap_error(exc)) from exc
+    try:
+        yield client
+    finally:
+        try:
+            client.logout()
+        except Exception:
+            client.shutdown()
+
+
+def _identify(client: IMAPClient) -> None:
+    """网易邮箱要求登录后发送 IMAP ID，否则 EXAMINE/SELECT 会返回 Unsafe Login。"""
+    params = {"name": "MailTool", "version": "0.1.0", "vendor": "MailTool"}
+    try:
+        if not client.has_capability("ID"):
+            raise CapabilityError("ID")
+        client.id_(params)
+    except CapabilityError:
+        _identify_raw(client, params)
+    except IMAPClientError as exc:
+        raise MailError(f"发送 IMAP ID 失败：{exc}") from exc
+
+
+def _identify_raw(client: IMAPClient, params: dict[str, str]) -> None:
+    import itertools
+
+    from imapclient.imapclient import _quote, seq_to_parenstr
+
+    args = seq_to_parenstr(_quote(value) for value in itertools.chain.from_iterable(params.items()))
+    typ, data = client._imap._simple_command("ID", args)
+    client._checkok("id", typ, data)
+
+
+def list_folders(client: IMAPClient) -> dict:
+    folders = []
+    for flags, _delimiter, name in client.list_folders():
+        folders.append(
+            {
+                "name": name,
+                "flags": [_as_text(flag) for flag in flags],
+            }
+        )
+    return {"folders": folders}
+
+
+def list_messages(
+    client: IMAPClient,
+    *,
+    folder: str = "INBOX",
+    from_addr: str | None = None,
+    to_addr: str | None = None,
+    subject: str | None = None,
+    since: str | None = None,
+    before: str | None = None,
+    unseen_only: bool = False,
+    limit: int = 20,
+) -> dict:
+    _select(client, folder)
+    criteria = build_criteria(
+        from_addr=from_addr,
+        to_addr=to_addr,
+        subject=subject,
+        since=since,
+        before=before,
+        unseen_only=unseen_only,
+    )
+    try:
+        uids = client.search(criteria, charset="UTF-8")
+    except (IMAPClientError, OSError) as exc:
+        raise MailError(f"搜索失败：{exc}") from exc
+    limit = clamp_limit(limit)
+    chosen = list(reversed(sorted(uids)))[:limit]
+    messages = []
+    if chosen:
+        fetched = client.fetch(chosen, ["ENVELOPE", "FLAGS", "RFC822.SIZE"])
+        for uid in chosen:
+            item = fetched.get(uid)
+            if item:
+                messages.append(_summary(uid, item))
+    return {"folder": folder, "matched": len(uids), "returned": len(messages), "messages": messages}
+
+
+def get_message(
+    client: IMAPClient,
+    *,
+    folder: str,
+    uid: str,
+    max_chars: int = DEFAULT_BODY_CHARS,
+) -> dict:
+    numeric = _parse_uid(uid)
+    _select(client, folder)
+    meta = client.fetch([numeric], ["ENVELOPE", "FLAGS", "RFC822.SIZE"])
+    item = meta.get(numeric)
+    if not item:
+        raise MailError(f"文件夹 {folder} 里没有 UID {uid} 的邮件")
+    summary = _summary(numeric, item)
+    size = int(item.get(b"RFC822.SIZE") or 0)
+    max_chars = clamp_body_chars(max_chars)
+    if size > MAX_MESSAGE_BYTES:
+        summary.update(
+            {
+                "body_text": "",
+                "truncated": True,
+                "attachments": [],
+                "note": f"邮件大小 {size} 字节，超过读取上限，只返回信头。",
+            }
+        )
+        return summary
+    fetched = client.fetch([numeric], ["BODY.PEEK[]"])
+    raw = _body_bytes(fetched.get(numeric, {}))
+    if not raw:
+        summary.update({"body_text": "", "truncated": False, "attachments": []})
+        return summary
+    parsed = parse_message(raw, max_chars)
+    summary.update(parsed)
+    return summary
+
+
+def build_criteria(
+    *,
+    from_addr: str | None,
+    to_addr: str | None,
+    subject: str | None,
+    since: str | None,
+    before: str | None,
+    unseen_only: bool,
+) -> list[str]:
+    criteria: list[str] = ["UNSEEN"] if unseen_only else ["ALL"]
+    if _clean(from_addr):
+        criteria.extend(["FROM", _clean(from_addr)])
+    if _clean(to_addr):
+        criteria.extend(["TO", _clean(to_addr)])
+    if _clean(subject):
+        criteria.extend(["SUBJECT", _clean(subject)])
+    if _clean(since):
+        criteria.extend(["SINCE", to_imap_date(_clean(since))])
+    if _clean(before):
+        criteria.extend(["BEFORE", to_imap_date(_clean(before))])
+    return criteria
+
+
+def _select(client: IMAPClient, folder: str) -> None:
+    name = folder.strip() or "INBOX"
+    if "\n" in name or "\r" in name or len(name) > 200:
+        raise MailError("文件夹名称不合法")
+    try:
+        client.select_folder(name, readonly=True)
+    except (IMAPClientError, OSError) as exc:
+        raise MailError(f"打不开文件夹 {name}：{exc}") from exc
+
+
+def _summary(uid: int, item: dict) -> dict:
+    envelope = item.get(b"ENVELOPE")
+    flags = item.get(b"FLAGS") or ()
+    flag_text = {_as_text(flag) for flag in flags}
+    subject = ""
+    from_text = ""
+    to_text = ""
+    cc_text = ""
+    date_text = ""
+    if envelope is not None:
+        subject = decode_mime_header(_as_text(getattr(envelope, "subject", "")))
+        from_text = format_addresses(getattr(envelope, "from_", None))
+        to_text = format_addresses(getattr(envelope, "to", None))
+        cc_text = format_addresses(getattr(envelope, "cc", None))
+        date_text = envelope_date(getattr(envelope, "date", None))
+    return {
+        "uid": str(uid),
+        "subject": subject,
+        "from": from_text,
+        "to": to_text,
+        "cc": cc_text,
+        "date": date_text,
+        "seen": "\\Seen" in flag_text,
+        "flagged": "\\Flagged" in flag_text,
+        "size": int(item.get(b"RFC822.SIZE") or 0),
+    }
+
+
+def _body_bytes(item: dict) -> bytes:
+    for key in (b"BODY[]", b"RFC822"):
+        value = item.get(key)
+        if isinstance(value, bytes):
+            return value
+    return b""
+
+
+def _parse_uid(uid: str) -> int:
+    text = str(uid).strip()
+    if not text.isdigit():
+        raise MailError("uid 必须是数字")
+    return int(text)
+
+
+def _clean(value: str | None) -> str:
+    return (value or "").strip()
+
+
+def _as_text(value) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+    return str(value)