mail-mcp: Instructions file for Codex

AGENTS.md

Guidance for coding agents working in mail-mcp.

Project Snapshot

• Language: Rust (edition 2024)
• Runtime: tokio
• Protocol framework: rmcp
• Domain: IMAP-backed MCP server over stdio
• Entry point: src/main.rs
• Main server implementation: src/server.rs

Cursor/Copilot Rules

No repository-specific Cursor or Copilot instruction files were found:

• .cursorrules: not present
• .cursor/rules/: not present
• .github/copilot-instructions.md: not present

If these are added later, treat them as higher-priority local policy and merge them into this file.

Build, Lint, and Test Commands

Run commands from repo root.

Build

• Debug build: cargo build
• Release build: cargo build --release

Format

• Check formatting: cargo fmt -- --check
• Apply formatting: cargo fmt

Lint

• Strict clippy (all targets): cargo clippy --all-targets -- -D warnings

Test

• Run all tests: cargo test
• List tests: cargo test -- --list
• GreenMail integration smoke test: scripts/test-greenmail.sh

Run a Single Test

Use a test name substring:

• cargo test parses_mailbox_with_colons
• cargo test pagination::tests::evicts_to_max_entries

Run a single test and show stdout:

• cargo test parses_mailbox_with_colons -- --exact --nocapture
• cargo test greenmail_imap_smoke_test -- --exact --ignored --nocapture

Run tests in one module/file scope:

• cargo test message_id::tests
• cargo test mime::tests
• cargo test pagination::tests

Suggested Local Validation Sequence

Before finalizing changes, run:

1. cargo fmt -- --check
2. cargo clippy --all-targets -- -D warnings
3. cargo test

Do not skip clippy or tests for code changes.

Docker

The repository includes a minimal multi-stage Dockerfile for running the MCP server.

Build and Run

• Build image: docker build -t mail-mcp .
• Run over stdio: docker run --rm -i --env-file .env mail-mcp

Docker Notes for Agents

• Keep MCP transport as stdio by default. An opt-in streamable HTTP transport exists (MAIL_MCP_TRANSPORT=http, see src/http.rs and docs/advanced-configuration.md); never make it the default or enable it implicitly in Docker.
• Keep runtime image minimal (current pattern: builder image + scratch).
• If dependencies require a non-scratch runtime, document why in the PR/commit message.
• Keep .dockerignore aligned with repo layout to avoid leaking local files and reduce context size.
• Docker publish workflow: .github/workflows/publish-docker.yml.
• Docker publish trigger: manual only (workflow_dispatch); after tagging a release, run it against the tag (e.g. gh workflow run "Publish Docker Image" --ref vX.Y.Z).
• Published image tags include latest, vX.Y.Z, and X.Y.Z on GHCR.