下载文件夹管理工具

src/
├── server.py               # MCP entry point — exposes 7 tools, wires DI in main()
├── interfaces.py           # IDownloadsService — abstract interface
├── exceptions.py           # Custom exceptions hierarchy
├── services/
│   └── downloads_service.py  # Business logic — implements IDownloadsService
├── models/
│   ├── file_info.py          # FileInfo dataclass
│   ├── scan_result.py        # ScanResult, CategoryStats dataclasses
│   └── operation_result.py   # OperationResult, LargeFilesResult dataclasses
└── utils/
    └── file_utils.py         # get_file_category, calculate_file_hash, get_file_size_mb

tests/
├── test_downloads_service.py  # Unit tests for DownloadsService
├── test_server.py             # Unit tests for MCP tools (mock injection via DI)
└── test_utils.py              # Unit tests for utility functions

# Install dependencies
pip install -r requirements.txt

# Run server
python src/server.py

docker build -t downloads-warden .
docker run --rm -v ~/Downloads:/root/Downloads downloads-warden

# Run all tests
pytest tests/ -v

# With coverage
pytest tests/ --cov=src --cov-report=term-missing

# Lint
ruff check src/

# Type check
mypy src/

def main() -> None:
    service = DownloadsService(get_downloads_path())
    create_server(service=service)
    mcp.run(transport="stdio")

mock_service = MagicMock(spec=IDownloadsService)
create_server(service=mock_service)

DownloadsWardenError
├── PathNotFoundError
├── FileMoveError
├── HashCalculationError
├── ExtractionError
├── InstallerCleanupError
└── FolderDeletionError

{
  "mcpServers": {
    "downloads-warden": {
      "command": "python",
      "args": ["C:/path/to/src/server.py"]
    }
  }
}