McpMailBridge Agent Notes

Project Shape

This repository is a Rust MCP server and local configuration manager for mail accounts.
MCP transport is stdio only until a human explicitly asks for another transport.
Account data lives in a SQLite database named `mmb.db` next to the executable by default.
The CLI may accept `--database <path>` for tests, local development, and recovery flows.
Do not store credentials in tracked files, examples, tests, chat output, or logs.

Keep binary entrypoint code in `src/main.rs`.
Keep command parsing and non-interactive config commands in `src/cli.rs`.
Keep account schema, validation, database path resolution, and SQLite persistence in `src/config.rs`.
Keep permission checks in `src/permissions.rs`.
Keep MCP tool registration and stdio serving in `src/mcp.rs`.
Keep terminal UI code in `src/tui.rs`.
Keep mail-provider code behind a small boundary before adding provider-specific IMAP, SMTP, OAuth, or SSO behavior.

`cargo build` builds the project.
`cargo test` runs tests.
`cargo fmt --check` verifies Rust formatting.
`cargo clippy --all-targets --all-features -- -D warnings` runs lint checks.
`cargo run -- serve` starts the MCP stdio server.
`cargo run -- config list` lists configured accounts.
`cargo run -- --database ./mmb.db config list` lists accounts from a specific SQLite database.
`cargo run -- tui` opens the terminal UI for account management.

Prefer small modules and explicit public contracts over broad catch-all files.
Prefer typed enums for closed value sets such as permissions, auth kinds, and providers.
Validate account data at process boundaries before using it.
Keep exported APIs explicit and boring; avoid framework-like abstractions until repetition proves the need.
Prefer early returns for invalid input and permission failures.
Keep errors actionable while redacting secrets.
Add unit tests for database persistence, validation, and permission behavior when those areas change.

Install dependencies through `cargo add` with exact package requirements, for example `cargo add crate@=x.y.z`.
Do not manually edit dependency versions unless cargo tooling cannot express the required change.
Keep dependency choices conservative and aligned with a modern Rust stack.

`avoid-ai-writing` - use when drafting human-facing updates, summaries, README prose, or project notes.
`humanizer` - use when prose sounds robotic or over-structured.
`professional-communication` - use for decision notes, status updates, and implementation summaries.
`writing-clearly-and-concisely` - use for documentation, error text, and concise project communication.

`rust-pro` - main coding skill for this project.
`code-simplification` - use when refactoring or reducing complexity.
`commit-work` - use when the human asks to stage or commit.
`diagnose` - use for defects, failing checks, and unexpected runtime behavior.
`doubt-driven-development` - use when changes span several modules or affect security-sensitive flows.
`incremental-implementation` - use for multi-file implementation work.
`karpathy-guidelines` - use for pragmatic Rust implementation and review.
`systematic-debugging` - use before fixing confirmed bugs or failing tests.

Do not paste secrets, tokens, passwords, or private OAuth URLs into chat, git, docs, or logs.
Redact secrets in errors and test fixtures.

Remove local screenshots, logs, traces, one-off scripts, and generated scratch files after verification unless they are explicitly needed.
Stop local servers, terminal UIs, browser sessions, or other helper processes when they are no longer needed.

Do not create branches, commits, pushes, or pull requests unless the human explicitly asks.
Use English Conventional Commits without scopes: `feat:`, `fix:`, or `chore:`.
Before committing, inspect `git status --short --branch --untracked-files=all`.
Stage only intended source, docs, and configuration changes.
Remove local screenshots, logs, traces, one-off scripts, and generated scratch outputs after verification unless a human asks to keep them.

Use `.local/` for machine-local notes, scratch plans, local credentials, and local operating context.
Keep `.local/` excluded through `.git/info/exclude`.
Do not commit `.local/` content unless a human explicitly asks for a tracked artifact.