# Thunderbird MCP Server v0.2.0

Centralizes Thunderbird email operations as MCP tools: read, send, draft, search, attachments.

## Status

| Aspect | State |
|--------|-------|
| Core development | Complete |
| Unit tests | 5/5 PASS |
| Deployment | Active (opencode MCP) |
| Agent integration | `communication-drafter` (draft-only) |

## Tools

| Tool | Description | Agent access |
|------|-------------|-------------|
| `tb_list_folders` | List available Thunderbird mail folders | ✅ read |
| `tb_read_messages` | Read messages from a folder with pagination | ✅ read |
| `tb_search_messages` | Search messages by keyword | ✅ read |
| `tb_download_attachments` | Download attachments from a message | ✅ read |
| `tb_draft_message` | Create a draft email in Thunderbird | ✅ write |
| `tb_send_message` | Send email via Thunderbird compose command | ❌ forbidden |

## Configuration

Environment variables:
- `THUNDERBIRD_PROFILE_DIR` — Thunderbird profile directory (default: ~/.thunderbird)
- `THUNDERBIRD_MAIL_DIR` — Local mail data directory (default: ~/Downloads/thunderbird.tmp)
- `THUNDERBIRD_SEND_COMMAND` — Command to invoke Thunderbird (default: thunderbird)
- `THUNDERBIRD_DEFAULT_ACCOUNT` — Default account identifier (optional)
- `THUNDERBIRD_DRAFT_FOLDER` — Drafts folder name (default: Drafts)

## Installation

Due to PEP 668 restrictions, use PYTHONPATH approach:
```bash
export PYTHONPATH=src
python3 -m thunderbird_mcp_server
```
Or use the provided wrapper:
```bash
bash run.sh
```

Development:
```bash
.venv/bin/pip install -e ".[dev]"
```

## Running

```bash
bash run.sh
# or directly with PYTHONPATH:
PYTHONPATH=src python3 -m thunderbird_mcp_server
```

## Testing

```bash
PYTHONPATH=src .venv/bin/pytest tests/ -v
```

Test coverage:
- `test_list_folders` — discovers mbox folders from temp mail dir
- `test_read_messages` — parses mbox with verified subject/body extraction
- `test_search_messages` — keyword search across folders
- `test_list_folders_uses_unique_relative_names` — multi-account path dedup
- `test_modified_utf7_folder_name_decoding` — IMAP modified UTF-7 decoding (e.g. Chinese folder names)

## Integration with opencode

Registered in `.opencode/opencode.json`:

```json
{
  "mcp": {
    "thunderbird-mcp-server": {
      "type": "local",
      "command": ["bash", "/home/gw/opt/thunderbird-mcp-server/run.sh"],
      "enabled": true,
      "environment": {
        "THUNDERBIRD_PROFILE_DIR": "/home/gw/snap/thunderbird/common/.thunderbird/34p30y9x.default",
        "THUNDERBIRD_MAIL_DIR": "/home/gw/snap/thunderbird/common/.thunderbird/34p30y9x.default/ImapMail",
        "THUNDERBIRD_SEND_COMMAND": "/snap/bin/thunderbird"
      }
    }
  }
}
```

**Agent integration**: `communication-drafter` is the sole authorized agent, granted read/search/draft tools only. `tb_send_message` is forbidden at the static check level (`scripts/check_agent_tool_budget.py`). Sending remains a manual user action.

## Architecture

- `config.py` — ThunderbirdConfig dataclass, reads from env vars
- `client.py` — ThunderbirdClient: reads mbox folders, parses messages, sends via CLI
- `server.py` — MCP Server with 6 tool definitions and stdio transport
- `tools/` — Shared tool parameter schemas

## Limitations

- **Large mbox timeout**: Folders with thousands of messages (e.g. INBOX) may exceed MCP timeouts during read/search. Mitigation: use `limit` and `offset` for pagination, or target smaller subfolders.
- **Local mbox dependency**: Read operations require Thunderbird to have downloaded mail locally (offline storage enabled). Folders with only `.msf` indexes return placeholder messages.
- **Send is interactive**: `tb_send_message` opens the Thunderbird compose window; it is not fully automated. This tool is explicitly denied to all agents — sending is a manual user action.
- **MSF-only folders**: Return `[MSF index only — no message data]` placeholder.
- **PEP 668**: `pip install -e .` is blocked; use `PYTHONPATH=src` approach.
- **`tb_send_message` denied**: Static check in `scripts/check_agent_tool_budget.py` prevents any agent from being granted this tool.