feat: add folder management tools by jbkjr · Pull Request #99 · ai-zerolab/mcp-email-server

jbkjr · 2026-01-15T05:09:50Z

Summary

Adds 6 new MCP tools for IMAP folder management:

list_folders - List all folders/mailboxes with IMAP flags and delimiters
move_emails - Move emails between folders (uses MOVE command with COPY+DELETE fallback)
copy_emails - Copy emails to a folder while preserving the original (standard IMAP COPY)
create_folder - Create new folders
delete_folder - Delete folders
rename_folder - Rename folders

Security

All folder management tools are disabled by default. Users must explicitly opt-in by setting:

Environment variable: MCP_EMAIL_SERVER_ENABLE_FOLDER_MANAGEMENT=true
Or TOML config: enable_folder_management = true

This addresses the concern about granting extensive permissions to LLMs by default.

Implementation Details

All operations use the existing _quote_mailbox() function for RFC 3501 compatibility
move_emails attempts RFC 6851 MOVE command first, falls back to COPY + STORE \Deleted + EXPUNGE
New response models: Folder, FolderListResponse, FolderOperationResponse, EmailMoveResponse
Abstract methods added to EmailHandler base class for extensibility
source_mailbox defaults to "INBOX" for consistency with existing tools

Test plan

All 110 existing tests pass
30 new tests added for folder management:
- Permission checks when disabled (6 tests)
- Tool functionality when enabled (6 tests)
- Handler method tests (6 tests)
- EmailClient IMAP operation tests (6 tests)
- Edge cases (3 tests)
- Config tests (3 tests)
Manual testing with IMAP server

🤖 Generated with Claude Code

codecov · 2026-01-15T05:10:41Z

Codecov Report

❌ Patch coverage is 94.32314% with 26 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
mcp_email_server/emails/classic.py	91.9%	16 Missing and 10 partials ⚠️

📢 Thoughts on this report? Let us know!

Wh1isper · 2026-01-15T05:19:17Z

Thanks for this pr!

I don't believe we should grant such extensive permissions to LLMs, at least not by default. If necessary, we can enable these features via a flag (disabled by default).

Additionally, we need some tests to ensure the behavior is generally correct.

Address maintainer feedback on PR ai-zerolab#99: - Add enable_folder_management config flag (disabled by default) - All folder management tools now require explicit opt-in - Add MCP_EMAIL_SERVER_ENABLE_FOLDER_MANAGEMENT env var support - Add comprehensive tests for folder management (30 new tests) - Update README documentation with new setting Tests cover: - Permission checks when disabled (6 tests) - Tool functionality when enabled (6 tests) - Handler method tests (6 tests) - EmailClient IMAP operation tests (6 tests) - Edge cases (3 tests) - Config tests (3 tests) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jbkjr · 2026-01-15T05:58:08Z

Thanks for the feedback! I've addressed your concerns:

Changes Made

1. Feature Flag (Disabled by Default)

Added enable_folder_management setting (defaults to false)
All 6 folder management tools now check this flag before executing
Users can enable via environment variable (MCP_EMAIL_SERVER_ENABLE_FOLDER_MANAGEMENT=true) or TOML config

2. Test Coverage

Added 30 new tests covering:

✅ Permission checks when disabled (6 tests) - verifies all tools raise PermissionError
✅ Tool functionality when enabled (6 tests) - verifies all tools work with mocked handlers
✅ Handler method tests (6 tests) - verifies ClassicEmailHandler methods
✅ EmailClient IMAP operation tests (6 tests) - verifies IMAP commands
✅ Edge cases (3 tests) - partial failures, folder failures, special characters
✅ Config tests (3 tests) - default value, env var enable/disable

All 140 tests pass (110 existing + 30 new).

Wh1isper · 2026-01-19T11:38:36Z

Can you resolve the conflict?

jbkjr · 2026-01-25T13:44:49Z

Merge conflicts resolved - rebased onto main. Ready for review.

Add 6 new MCP tools for IMAP folder operations: - list_folders: List all folders/mailboxes with flags - move_emails: Move emails between folders (MOVE or COPY+DELETE fallback) - copy_emails: Copy emails to folder (useful for labels in Proton Mail) - create_folder: Create new folders - delete_folder: Delete folders - rename_folder: Rename folders This enables full folder management through the MCP interface, with special consideration for Proton Mail Bridge compatibility. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Address maintainer feedback on PR ai-zerolab#99: - Add enable_folder_management config flag (disabled by default) - All folder management tools now require explicit opt-in - Add MCP_EMAIL_SERVER_ENABLE_FOLDER_MANAGEMENT env var support - Add comprehensive tests for folder management (30 new tests) - Update README documentation with new setting Tests cover: - Permission checks when disabled (6 tests) - Tool functionality when enabled (6 tests) - Handler method tests (6 tests) - EmailClient IMAP operation tests (6 tests) - Edge cases (3 tests) - Config tests (3 tests) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

for more information, see https://pre-commit.ci

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add 6 new MCP tools for managing ProtonMail labels: - list_labels: List all labels (filters Labels/ prefix folders) - apply_label: Apply label to emails (copy to Labels/X) - remove_label: Remove label from emails (delete from Labels/X) - get_email_labels: Get all labels for an email - create_label: Create new label - delete_label: Delete label Labels in ProtonMail Bridge are exposed as IMAP folders under the Labels/ prefix. These tools provide semantic operations for label management while using the underlying folder operations. Includes comprehensive tests (26 new tests, all passing). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add clearer documentation for the mailbox parameter across all tools, explaining standard IMAP folders and provider-specific paths for Gmail ([Gmail]/...) and ProtonMail Bridge (Folders/<name>, Labels/<name>). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add functionality to mark emails as read or unread using IMAP \Seen flag: - EmailMarkResponse model for operation results - mark_emails abstract method in EmailHandler - Implementation in EmailClient and ClassicEmailHandler - MCP tool exposed via app.py Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Clarify that move_emails removes from source folder and apply_label only tags without removing from INBOX. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Cherry-picked test improvements from feature/folder-management: - Comprehensive tests for folder management edge cases - Tests for _parse_list_response exception handling - Tests for EmailClient.delete_emails coverage - Ruff RUF059 fixes for unused variables Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Cherry-picked test improvements from pr/mark-read-unread: - Comprehensive tests for mark_emails functionality - Logout error test for mark_emails coverage Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

for more information, see https://pre-commit.ci

Remove TestParseHeaderToMetadata (uses non-existent _parse_header_to_metadata) and TestGetEmailsStreamWithSort (tests SORT capability from PR ai-zerolab#107) that were accidentally included during rebase. These test upstream's batch fetch implementation, not the folder management feature. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jbkjr closed this Jan 15, 2026

jbkjr deleted the feature/folder-management branch January 15, 2026 08:35

jbkjr restored the feature/folder-management branch January 15, 2026 09:21

jbkjr reopened this Jan 15, 2026

Wh1isper self-assigned this Jan 19, 2026

jbkjr force-pushed the feature/folder-management branch from d36ffe7 to 4270249 Compare January 25, 2026 13:34

Jack Koch and others added 12 commits January 26, 2026 01:09

[pre-commit.ci] auto fixes from pre-commit.com hooks

fb1d85e

for more information, see https://pre-commit.ci

fix: unused variables in tests (ruff RUF059)

f7d2462

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Improve move_emails and apply_label tool descriptions

bb62d03

Clarify that move_emails removes from source folder and apply_label only tags without removing from INBOX. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

test: Add mark_emails test coverage from pr/mark-read-unread

ce051d2

Cherry-picked test improvements from pr/mark-read-unread: - Comprehensive tests for mark_emails functionality - Logout error test for mark_emails coverage Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

[pre-commit.ci] auto fixes from pre-commit.com hooks

15a0ecc

for more information, see https://pre-commit.ci

chore: retrigger CI for codecov

d3c7b97

jbkjr force-pushed the feature/folder-management branch from 4270249 to d3c7b97 Compare January 26, 2026 06:16

pre-commit-ci bot and others added 2 commits January 26, 2026 06:16

[pre-commit.ci] auto fixes from pre-commit.com hooks

da13bff

for more information, see https://pre-commit.ci

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add folder management tools#99

feat: add folder management tools#99
jbkjr wants to merge 14 commits intoai-zerolab:mainfrom
jbkjr:feature/folder-management

jbkjr commented Jan 15, 2026 •

edited

Loading

Uh oh!

codecov bot commented Jan 15, 2026 •

edited

Loading

Uh oh!

Wh1isper commented Jan 15, 2026

Uh oh!

jbkjr commented Jan 15, 2026

Uh oh!

Wh1isper commented Jan 19, 2026

Uh oh!

jbkjr commented Jan 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jbkjr commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Security

Implementation Details

Test plan

Uh oh!

codecov bot commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Wh1isper commented Jan 15, 2026

Uh oh!

jbkjr commented Jan 15, 2026

Changes Made

1. Feature Flag (Disabled by Default)

2. Test Coverage

Uh oh!

Wh1isper commented Jan 19, 2026

Uh oh!

jbkjr commented Jan 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jbkjr commented Jan 15, 2026 •

edited

Loading

codecov bot commented Jan 15, 2026 •

edited

Loading