mailbox-mcp-server: Instructions file for Claude Code

CLAUDE.md

ALWAYS verify your changes by running the tests with bun run test!

Project Overview

This is a Model Context Protocol (MCP) server for mailbox.org integration, providing:

• IMAP email access and management
• SMTP email sending
• CalDAV calendar operations
• Sieve email filter management

Built with TypeScript and Bun runtime, designed to be used with Claude Desktop.

Architecture

Core Services

• ImapService (src/services/ImapService.ts) - Email fetching, searching, folder management
• SmtpService (src/services/SmtpService.ts) - Email sending with attachments
• CalendarService (src/services/CalendarService.ts) - CalDAV operations for events
• SieveService (src/services/SieveService.ts) - Email filter script management

Connection Management

• ConnectionPool (src/services/ConnectionPool.ts) - Manages persistent IMAP connections
• Implements connection reuse, health checks, and automatic cleanup
• Configurable pool size and connection timeouts
• Graceful degradation on connection failures

Security

• Credentials stored in environment variables (.env file)
• Never log sensitive data (passwords, tokens, email content)
• App passwords recommended for mailbox.org (see APP_PASSWORDS.md)
• Password validation: 10+ chars for standard, 6+ for app passwords

Code Style

Language Features

• ES modules with destructured imports
• Double quotes, 2 spaces indentation, semicolons
• Arrow functions preferred
• async/await over promises
• Object/array destructuring where appropriate

Patterns

• Dependency injection for services (constructor parameters)
• Error handling with try-catch and custom error messages
• Logging via Logger utility (see src/utils/logger.ts)
• Type-safe interfaces for all data structures

Naming Conventions

• PascalCase for classes and interfaces
• camelCase for variables, functions, and methods
• SCREAMING_SNAKE_CASE for constants
• Descriptive names over abbreviations