内容
<p align="center">
<img src="./app-icon-512-transparent.png" alt="邮箱 MCP" width="116" />
</p>
<h1 align="center">邮箱 MCP</h1>
<p align="center">
为 Codex 提供本地桌面邮箱工具，由 Go MCP 边车和 Tauri 设置应用支持。
</p>
<p align="center">
<a href="#概述">概述</a> ·
<a href="#架构">架构</a> ·
<a href="#关键功能">关键功能</a> ·
<a href="#快速入门">快速入门</a> ·
<a href="#MCP 工具">MCP 工具</a> ·
<a href="#开发">开发</a>
</p>
<p align="center">
<img alt="Go" src="https://img.shields.io/badge/Go-1.25-00ADD8?logo=go&logoColor=white" />
<img alt="Tauri" src="https://img.shields.io/badge/Tauri-2.x-24C8DB?logo=tauri&logoColor=white" />
<img alt="React" src="https://img.shields.io/badge/React-18-61DAFB?logo=react&logoColor=111111" />
<img alt="SQLite" src="https://img.shields.io/badge/SQLite-FTS5-003B57?logo=sqlite&logoColor=white" />
<img alt="MCP" src="https://img.shields.io/badge/MCP-stdio-6E56CF" />
<img alt="平台" src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS-4B5563" />
<img alt="版本" src="https://img.shields.io/badge/version-0.1.0-blue" />
</p>
---
## 概述
邮箱 MCP 是为 Codex 提供本地桌面邮箱 MCP 服务器。它允许 Codex 通过用户拥有的本地边车读取、搜索、组织和发送电子邮件，而不是通过远程服务。
桌面应用程序是一个配置中心。Codex 直接通过 stdio 与本地 Go 边车通信，因此当 GUI 关闭时，MCP 工具仍可工作。
邮箱 MCP 的设计围绕着一个狭窄的信任边界：
- 没有远程 HTTP 服务。
- 没有共享令牌存储。
- 没有注册流程。
- 没有管理员审批页面。
- 应用程序日志或 JSON 配置中没有邮箱授权码。
## 架构
```mermaid
flowchart LR
Codex["Codex"] -->|"MCP stdio"| 边车["Go 边车"]
桌面["Tauri 桌面应用"] -->|"配置 CLI"| 边车
边车 -->|"IMAP"| 邮箱["用户邮箱"]
边车 -->|"SMTP"| SMTP["SMTP 服务器"]
边车 -->|"SQLite FTS5"| 索引["本地邮件索引"]
边车 -->|"操作系统凭证存储"| 机密["SMTP/IMAP 授权码"]
```
核心组件：
| 组件 | 目的 |
| --- | --- |
| Go 边车 | `email-mcp mcp` 为 Codex 公开 stdio MCP 服务器。 |
| 配置 CLI | `email-mcp config ...` 管理非机密配置和操作系统凭证存储机密。 |
| 医生 CLI | `email-mcp doctor --json` 报告本地准备情况。 |
| 索引 CLI | `email-mcp index ...` 管理本地 SQLite/FTS 邮箱索引。 |
| 桌面 GUI | `apps/desktop` 提供 Tauri + React 设置中心。 |
## 关键功能
- 为 Codex 集成提供本地 MCP 服务器。
- IMAP 邮件列表、文件夹发现、搜索和完整消息检索。
- 使用本地附件允许列表发送 SMTP。
- SQLite/FTS5 邮箱索引，用于快速本地搜索。
- 附件下载仅限于配置的目录。
- 批量邮箱操作，默认为 dry-run。
- 桌面设置流程，用于邮箱设置、权限、诊断和 Codex 配置安装。
- 通过 Tauri 和 GitHub Actions 支持 Windows 和 macOS 打包。
## 快速入门
### 1. 配置邮箱 MCP
安装桌面应用程序后：
1. 打开邮箱 MCP。
2. 配置邮箱主机、端口、账户、SMTP 授权码和 IMAP 授权码。
3. 配置附件下载和允许发送附件的目录。
4. 启用所需的权限。
5. 打开 **Codex** 页面并安装 MCP 配置。
桌面应用程序将此块写入 Codex 配置并创建备份：
```toml
[mcp_servers.email]
command = "<安装的 email-mcp 路径>"
args = ["mcp"]
```
### 2. 运行诊断
使用 GUI **状态** 页面，或运行：
```powershell
.\email-mcp-service.exe doctor --json
```
### 3. 构建邮件索引
```powershell
.\email-mcp-service.exe index status
.\email-mcp-service.exe index sync --limit-per-folder 1000
```
在本地索引中搜索：
```powershell
@'
{"keyword":"invoice","limit":20}
'@ | .\email-mcp-service.exe index search
```
## MCP 工具
邮箱 MCP 公开原始、可审计的邮箱操作。诸如发票过滤、附件审查、金额提取、报告编写和邮箱清理等更高级别的任务由 Codex 使用这些工具处理。
| 区域 | 工具 |
| --- | --- |
| 读取 | `listEmails`、`listEmailsV2`、`listFolders`、`searchAllFolders`、`getEmail` |
| 本地索引 | `searchEmails` |
| 附件 | `downloadEmailAttachments` |
| 发送 | `sendEmail` |
| 文件夹 | `createFolder`、`resolveSpecialFolders` |
| 消息状态 | `setEmailReadStatus`、`moveEmail`、`deleteEmail` |
| 批量操作 | `bulkMoveEmails`、`bulkDeleteEmails`、`bulkSetEmailReadStatus`、`archiveEmails` |
| 组织工作流 | `previewOrganizePlan`、`applyOrganizePlan` |
在执行邮箱组织之前，应先使用 `previewOrganizePlan` 或批量工具的默认 dry-run 行为进行预览。
## 桌面安装
### Windows
在 Windows 上构建安装程序：
```powershell
cd apps/desktop
npm install
npm run tauri:build
```
安装程序写入：
```text
apps/desktop/src-tauri/target/release/bundle/nsis/
```
### macOS
macOS `.dmg` 和 `.app` 包必须在 macOS 上构建。
推荐路径：使用 GitHub Actions。
1. 将此存储库推送到 GitHub。
2. 打开 **Actions**。
3. 运行 **Build macOS package**。
4. 下载 `email-mcp-macos` 工件。
5. 打开 `.dmg` 并将 `Email MCP.app` 拖入 `/Applications`。
本地构建路径从 Mac：
```bash
xcode-select --install
brew install node go rust
cargo install tauri-cli --version "^2" --locked
cd apps/desktop
npm ci
npm run tauri:build
```
输出写入以下路径：
```text
apps/desktop/src-tauri/target/release/bundle/dmg/
apps/desktop/src-tauri/target/release/bundle/macos/
```
对于未经签名的内部构建，macOS 可能会阻止第一次启动。使用 Control-click -> **Open**，或从 **System Settings -> Privacy & Security** 中批准。
## 配置和机密
| 项目 | 位置 |
| --- | --- |
| Windows 配置 | `%APPDATA%\EmailMCP\config.json` |
| macOS 配置 | `~/Library/Application Support/EmailMCP/config.json` |
| SMTP/IMAP 授权码 | 操作系统凭证存储 |
| 本地邮箱索引 | `EmailMCP/mail-index.db` 下的操作系统缓存目录，除非配置了自定义路径 |
| 开发备用 | 边车旁边的 `.env` 或工作目录中的 `.env` |
GUI 不显示或记录 SMTP/IMAP 授权码。
## 安全边界
- 此版本不启动 HTTP 监听器。
- 不使用 Bearer 令牌；本地操作系统用户是权限边界。
- 附件下载仅写入配置的下载目录。
- 发送附件时只能读取配置的白名单目录。
- `deleteEmail` 将消息移动到垃圾箱；不公开硬删除。
- 批量移动/删除/存档工具默认为 dry-run 模式。
- 在执行之前应始终预览邮箱组织。
## 开发
Go 边车：
```powershell
go test -count=1 ./...
go build -buildvcs=false -o email-mcp-service.exe .
.\email-mcp-service.exe mcp
.\email-mcp-service.exe config path
.\email-mcp-service.exe doctor --json
.\email-mcp-service.exe index status
.\email-mcp-service.exe index sync --limit-per-folder 200
```
桌面应用程序：
```powershell
cd apps/desktop
npm install
npm run tauri:dev
npm run tauri:build
```
桌面构建需要 Node.js、Go 和 Rust/Cargo。Tauri 构建脚本编译 Go 边车到：
```text
apps/desktop/src-tauri/binaries/email-mcp-<target-triple>
```
## 发布版本
此存储库包括手动 GitHub Actions 发布工作流：
```text
.github/workflows/build-macos.yml
.github/workflows/release.yml
```
要发布桌面软件包：
1. 打开 GitHub 存储库。
2. 进入 **Actions**。
3. 运行 **Release desktop packages**。
4. 输入版本号，例如 `0.1.0`。
5. 对于未经签名的内部构建，请保持 `prerelease=true`。
6. 等待 Windows 和 macOS 作业完成。
7. 打开 **Releases** 并下载生成的安装程序文件。
发布工作流构建：
- Windows NSIS 安装程序。
- macOS dmg。
- macOS 压缩的 `.app`。
发布工作流在 CI 期间临时将输入版本号应用于桌面软件包元数据。存储库中的源文件不会被工作流修改。
## 存储库卫生
请勿提交本地机密、本地邮箱数据、生成的二进制文件、安装程序输出、日志或私有邮箱报告。
存储库故意忽略：
- `.env`
- `*.db`、`*.db-shm`、`*.db-wal`
- `*.exe`、`*.exe~`
- `logs/`
- `docs/`
- `.agents/`、`.codegraph/`、`.uploads/`、`.superpowers/`
- `apps/desktop/node_modules/`
- `apps/desktop/dist/`
- `apps/desktop/src-tauri/target/`
- `apps/desktop/src-tauri/binaries/email-mcp-*`
在推送之前，运行：
```powershell
git status --short
git diff --cached --name-only
```
仅应提交源代码、配置文件模板、图标、锁定文件、测试和 GitHub 工作流文件。
