# FudanMailBox MCP

A small, privacy-conscious MCP server for **Fudan Cloud Mail (`@m.fudan.edu.cn`)** and compatible Tencent Enterprise Mail accounts.

It uses standard **IMAP over SSL** for mailbox operations and **SMTP over SSL** for sending. Credentials are read from operating-system environment variables and are never stored in this repository.

> Community project. Not an official Fudan University or Tencent project.

## Features

### Mailbox
- List folders and special-use folders (Inbox, Drafts, Sent, Trash, Junk when advertised)
- Folder total/unread counts
- List newest mail without marking it read
- Search by text, sender, recipient, subject, date range, unread/starred
- Read plain-text content, optional HTML, headers, attachment inventory
- Download attachments
- Mark read/unread and starred/unstarred
- Move, archive, trash, or permanently delete messages
- Create, rename, and delete folders

### Drafts
- Save server-side drafts through IMAP
- Replace/update an existing draft
- Drafts support To/Cc/Bcc, plain text, optional HTML, and attachments

### Sending
- Send To/Cc/Bcc mail
- Plain-text and optional HTML body
- File attachments
- Reply / reply-all
- Forward, optionally including original attachments
- Configurable approved sender aliases
- `dry_run=true` by default for send/reply/forward so an agent can show a preview first
- Optional copy to the server Sent folder

### Contacts
The public v0.1 implementation deliberately does **not** reverse-engineer Tencent Webmail contacts.

Instead it provides a **local private contact book**, stored outside this Git repository:
- list/search contacts
- add/update/delete contacts
- import recent correspondents from message headers

Native Tencent/Fudan contact and calendar sync is intentionally left for a future Exchange-compatible module.

## Not implemented in v0.1

These are not standard IMAP/SMTP features:
- Native Tencent/Fudan webmail contact synchronization
- Exchange calendar synchronization / meeting invitations
- Webmail-only mail recall
- Delivery-status query
- 2 GB webmail large-attachment transfer
- Webmail notes, to-do, microdisk/docs/file-transfer features

## Requirements

- Python 3.11+
- Fudan Cloud Mail account
- Client protocol enabled in webmail settings
- Client-specific password if secure login is enabled

Default servers:
- IMAP: `imap.exmail.qq.com:993` with SSL
- SMTP: `smtp.exmail.qq.com:465` with SSL

## Installation

```powershell
git clone https://github.com/BuddyKang/FudanMailBox_MCP.git
cd FudanMailBox_MCP

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
```

Run directly:

```powershell
.\.venv\Scripts\python.exe -m fudanmailbox_mcp
```

## Windows credential setup

Do **not** paste the client-specific password into `config.json`, `README.md`, `.env`, source code, Git, or an issue.

Set Windows **user environment variables**:

```powershell
[Environment]::SetEnvironmentVariable(
  "FUDAN_MAIL_USER",
  "YOUR_STUDENT_ID@m.fudan.edu.cn",
  "User"
)

[Environment]::SetEnvironmentVariable(
  "FUDAN_MAIL_APP_PASSWORD",
  "YOUR_CLIENT_SPECIFIC_PASSWORD",
  "User"
)
```

Optional approved From aliases:

```powershell
[Environment]::SetEnvironmentVariable(
  "FUDAN_MAIL_FROM_ALIASES",
  "alias1@m.fudan.edu.cn,alias2@m.fudan.edu.cn",
  "User"
)
```

After changing environment variables, **fully restart DSH / Super-MCP** so the child MCP process inherits them.

Windows GUI path:

`Search "Edit environment variables for your account" -> Environment Variables -> User variables`

Create:
- `FUDAN_MAIL_USER`
- `FUDAN_MAIL_APP_PASSWORD`

## Super-MCP example

```json
{
  "mcpServers": {
    "fudanmailbox": {
      "command": "C:\\path\\to\\FudanMailBox_MCP\\.venv\\Scripts\\python.exe",
      "args": ["-m", "fudanmailbox_mcp"]
    }
  }
}
```

No credentials are written into this config. The process inherits Windows user environment variables.

## Recommended agent policy

Read-only operations can usually be allowed.

Treat these as consequential:
- `send_message` / `reply_message` / `forward_message`: preview first, then send
- `delete_message(permanent=true)`: require explicit confirmation
- `delete_folder`: require explicit confirmation
- `update_draft`: require confirmation before replacing the old draft
- `delete_contact`: require explicit confirmation

The server also has conservative defaults such as `dry_run=true` for outbound mail and confirmation gates for destructive actions.

## Main MCP tools

- `capabilities`
- `account_status`
- `test_connection`
- `list_folders`
- `folder_status`
- `list_messages`
- `search_messages`
- `get_message`
- `download_attachment`
- `set_message_flags`
- `move_message`
- `archive_message`
- `delete_message`
- `create_folder`
- `rename_folder`
- `delete_folder`
- `save_draft`
- `update_draft`
- `send_message`
- `reply_message`
- `forward_message`
- `list_sender_aliases`
- `list_contacts`
- `search_contacts`
- `upsert_contact`
- `delete_contact`
- `import_correspondents`

## Environment variables

| Variable | Default | Purpose |
|---|---|---|
| `FUDAN_MAIL_USER` | required | Full mailbox address |
| `FUDAN_MAIL_APP_PASSWORD` | required | Client-specific password |
| `FUDAN_MAIL_IMAP_HOST` | `imap.exmail.qq.com` | IMAP host |
| `FUDAN_MAIL_IMAP_PORT` | `993` | IMAP SSL port |
| `FUDAN_MAIL_SMTP_HOST` | `smtp.exmail.qq.com` | SMTP host |
| `FUDAN_MAIL_SMTP_PORT` | `465` | SMTP SSL port |
| `FUDAN_MAIL_FROM_ALIASES` | empty | Comma-separated approved From aliases |
| `FUDAN_MAIL_SAVE_SENT_COPY` | `true` | Append a copy to Sent after SMTP delivery |
| `FUDAN_MAIL_MAX_ATTACHMENT_MB` | `50` | Attachment cap enforced by MCP |
| `FUDAN_MAIL_CONTACTS_PATH` | `%APPDATA%\FudanMailBox_MCP\contacts.json` | Local contact store |
| `FUDAN_MAIL_DOWNLOAD_DIR` | `~/Downloads/FudanMailBox_MCP` | Attachment download folder |
| `FUDAN_MAIL_ARCHIVE_FOLDER` | unset | Explicit archive folder if server advertises none |

## Security

See [SECURITY.md](SECURITY.md). Never commit credentials, exported session cookies, saved webmail HTML containing live session identifiers, private contact databases, or downloaded mail/attachments.

## License

MIT