IMAP MCP Server Development Guide

# IMAP MCP Server Development Guide

## Environment Setup and Build Commands with `uv`
- Create virtual environment: `uv venv`
- Activate virtual environment: `source .venv/bin/activate` (Unix/macOS) or `.venv\Scripts\activate` (Windows)
- Install dependencies: `uv pip install -e ".[dev]"`
- Install specific packages: `uv add package_name`
- Run commands within the environment: `uv run command [args]`

## Build and Test Commands
- Install dependencies: `uv pip install -e ".[dev]"`
- Run all tests: `uv run pytest`
- Run single test: `uv run pytest tests/test_file.py::TestClass::test_function -v`
- Run with coverage: `uv run pytest --cov=imap_mcp`
- Run server: `uv run python -m imap_mcp.server --config /path/to/config.yaml`
- Development mode: `uv run python -m imap_mcp.server --dev`
- One-line execution with dependencies: `uvx run -m imap_mcp.server --config /path/to/config.yaml`

## Code Style Guidelines
- Use Black with 88 character line length
- Imports: Use isort with Black profile
- Types: All functions must have type hints (mypy enforces this)
- Naming: snake_case for variables/functions, PascalCase for classes
- Error handling: Use specific exceptions and provide helpful messages
- Documentation: Write docstrings for all classes and methods
- Testing: Follow TDD pattern (write tests before implementation)
- Project structure follows the standard Python package layout

## Task Workflow
When working on tasks from GitHub Issues, follow this workflow:

1. **Task Analysis**:
   - Read and understand the issue requirements
   - Assess if the issue needs to be broken down into smaller subtasks
   - If needed, create separate issues for subtasks and link them to the parent issue
   - Analyze existing labels and make sure the issue has the correct priority and status labels

2. **Starting Work on an Issue**:
   - Create a branch that references the issue number: `git checkout -b feature/issue-[NUMBER]-[SHORT_DESCRIPTION]`
   - Make an initial commit that references the issue: `git commit -m "refs #[NUMBER]: Start implementing [FEATURE]"`
   - The automated status tracking system will detect this commit and change the issue status to "in-progress"

3. **Test-Driven Development**:
   - Write tests first that verify the desired functionality
   - Implement the feature until all tests pass
   - Refactor code while maintaining test coverage
   - Run full test suite to check for regressions: `uv run pytest --cov=imap_mcp`

4. **Completing an Issue**:
   - Create a pull request that references the issue: `gh pr create --title "[TITLE]" --body "Closes #[NUMBER]"`
   - The body should include "Closes #[NUMBER]" or "Fixes #[NUMBER]" to automatically close the issue when merged
   - The automated status tracking system will update the issue status to "completed" when the PR is merged
   - It will also automatically adjust priorities of remaining tasks

5. **GitHub Issue Management Commands**:
   - View all issues: `gh issue list`
   - View specific issue: `gh issue view [NUMBER]`
   - Filter issues by label: `gh issue list --label "priority:1"`
   - Create new issue: `gh issue create` (interactive) or:
     `gh issue create --title "Title" --body "Description" --label "priority:X" --label "status:prioritized"`
   - Edit issue: `gh issue edit [NUMBER] --add-label "priority:1" --remove-label "priority:2"`

6. **Documentation**:
   - Update docstrings in implementation
   - Update README.md or other docs if needed
   - Add new commands or processes to this CLAUDE.md file if relevant

7. **Commit Conventions**:
   - Use these prefixes in commit messages to trigger automatic status changes:
     - `refs #X`: References the issue without changing status
     - `implements #X`: Indicates implementation progress
     - `fixes #X`: Indicates the issue is fixed (used in final commits)
     - `closes #X`: Same as fixes, will close the issue when merged
   - Always include the issue number with the # prefix
   - Add descriptive message after the issue reference

## Issue Status Definitions

GitHub Issues have the following status labels:

- **status:prioritized**: Task has been assigned a priority, not yet started
- **status:in-progress**: Work on the task has begun (automatic when commits reference issue)
- **status:completed**: Implementation is finished (automatic when PR with "fixes/closes" is merged)
- **status:reviewed**: Task has been reviewed (currently manual update)
- **status:archived**: Task has been archived (currently manual update)

Priority labels follow the format `priority:X` where X is a number starting from 1 (highest priority).

# General
## continuous_improvement
- Self-reflection: After each significant development task:
  1. Evaluate the solution against requirements and best practices
  2. Identify at least one aspect that could be improved in future iterations
  3. Suggest concrete improvements with measurable benefits
- Pattern recognition: Identify recurring patterns in code and suggest abstractions
- Knowledge accumulation: Build on previous solutions when solving similar problems
- Metrics tracking: Monitor improvements in code quality, test coverage, and development efficiency


## communication_preferences
- Provide concise explanations focused on practical implementation
- Present multiple solution options when appropriate, with clear trade-offs
- Use code examples to illustrate concepts
- Focus on actionable advice rather than theoretical discussions

## rules_evolution
- Periodically review these rules and suggest improvements based on observed patterns
- Identify rules that may be overly restrictive or no longer relevant
- Suggest new rules that would improve development efficiency or code quality
- For each rule change, provide clear reasoning and expected benefits