imap-mcp 0.1.0__tar.gz

imap_mcp-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.agents/worktrees/
+.venv/
+__pycache__/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage

imap_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-01
+
+### Added
+
+- MCP server over stdio with six tools: `search_mail`, `get_message`, `list_folders`, `sync_now`, `download_attachment` and `create_draft`.
+- Local SQLite index with ranked FTS5 keyword search. Search skips Junk and Trash unless the agent names the folder.
+- Sync on a tool call when the data is more than 15 minutes old, with a 20 second time limit, and `sync_now` to force one. Every result reports how old the data is.
+- Incremental sync: `STATUS` checks, `CONDSTORE` flag updates, moves linked without a download, and `UIDVALIDITY` relinks that resume after an interruption.
+- A cross-process sync lock, so several agent sessions can share one index.
+- An IMAP command allowlist that refuses every write except `APPEND` to the Drafts folder.
+- Prompt-injection defences: sender text kept apart from server data, nonce-tagged message text, hidden HTML and invisible Unicode removed, and sender authentication results.
+- Markdown drafts with raw HTML off and images rendered as links.
+- Attachment download that never overwrites a file and sets the macOS quarantine attribute.
+- The macOS Keychain as the password store.
+- CLI commands: `serve`, `set-password`, `probe`, `sync`, `status`, `vacuum` and `purge`.
+- The `auth_servers` setting names the domains whose `Authentication-Results` headers count.
+
+### Security
+
+- Authentication verdicts come only from the top headers whose authserv-id is in `auth_servers`, and only from the `method=result` token at the start of each clause. Sender text in a comment or in `smtp.mailfrom` can no longer add a pass verdict.
+- The message identity includes the RFC822 size, so a forged copy with a real message's `Message-ID`, `Date` and `From` no longer merges into it. Schema v3 clears the index, and the next sync downloads all mail again.
+- A message the client cannot parse, such as one nested hundreds of MIME levels deep, is skipped and the sync reports `partial`. It no longer stops the sync or makes every read tool fail.
+- IMAP error messages no longer contain library error text, which could quote headers into logs and the `sync.error` field.
+- `attachments[].type` shows only known media types.
+- `create_draft` and `download_attachment` carry `openWorldHint: true`.
+- Draft headers hold the parsed address that `new_recipients` reports. A non-ASCII address is refused as invalid.
+- Attachment names are capped at 255 UTF-8 bytes.
+- CI actions are pinned to commit SHAs, and uv and hatchling to exact versions.
+
+[unreleased]: https://github.com/bcrisp4/imap-mcp/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/bcrisp4/imap-mcp/releases/tag/v0.1.0

imap_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Crisp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

imap_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.5
+Name: imap-mcp
+Version: 0.1.0
+Summary: Local, read-only MCP server with keyword search over one IMAP mailbox
+Project-URL: Homepage, https://github.com/bcrisp4/imap-mcp
+Project-URL: Source, https://github.com/bcrisp4/imap-mcp
+Project-URL: Issues, https://github.com/bcrisp4/imap-mcp/issues
+Project-URL: Design, https://github.com/bcrisp4/imap-mcp/blob/main/docs/designs/imap-mcp.md
+Project-URL: Changelog, https://github.com/bcrisp4/imap-mcp/blob/main/CHANGELOG.md
+Author-email: Ben Crisp <ben@thecrisp.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: email,icloud,imap,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Email :: Post-Office :: IMAP
+Requires-Python: >=3.14
+Requires-Dist: beautifulsoup4>=4.15
+Requires-Dist: imapclient>=4.1
+Requires-Dist: lxml>=6.1
+Requires-Dist: markdown-it-py>=4.2
+Requires-Dist: mcp>=2.3
+Requires-Dist: pydantic>=2.14
+Requires-Dist: structlog>=26.1
+Description-Content-Type: text/markdown
+
+# imap-mcp
+
+imap-mcp is a local MCP server that gives an AI agent read-only, searchable access to one IMAP mailbox. It can write drafts and can never send mail.
+
+It syncs the mailbox into a local SQLite index with ranked keyword search. It syncs again on a tool call when the data is more than 15 minutes old, and every result tells the agent how old the data is. iCloud is the main target. Any IMAP server that accepts an app password also works.
+
+Status: alpha. Tool names and parameters can change before 1.0.0. See the [changelog](https://github.com/bcrisp4/imap-mcp/blob/main/CHANGELOG.md).
+
+## What it never does
+
+- It never sends mail. The package contains no SMTP code.
+- It never deletes, moves or flags mail. A read never marks a message as read. A command allowlist checks every IMAP command before it goes on the wire.
+- It never listens on the network. It runs on stdio, started by your agent.
+
+Email is untrusted input. Results keep sender text apart from server data, remove hidden HTML and invisible Unicode, and show sender authentication results. See [Security](https://github.com/bcrisp4/imap-mcp/blob/main/docs/designs/imap-mcp.md#security) in the design doc.
+
+## Requirements
+
+- macOS. The password lives in the macOS Keychain.
+- [uv](https://docs.astral.sh/uv/). It installs Python 3.14 if you do not have it.
+- An IMAP account with an app password. For iCloud, create one at [account.apple.com](https://account.apple.com) under Sign-In and Security, App-Specific Passwords.
+
+## Set up
+
+1. Create `~/.config/imap-mcp/config.toml`. For iCloud, `username` is your Apple Account email or a custom-domain address on the account:
+
+   ```toml
+   host = "imap.mail.me.com"
+   port = 993
+   username = "you@icloud.com"
+   from_address = "you@icloud.com"
+   ```
+
+2. Store the app password in the Keychain. `security` prompts for it twice. When macOS asks for Keychain access later, choose Always Allow for `/usr/bin/security`:
+
+   ```bash
+   uvx imap-mcp set-password
+   ```
+
+3. Check the connection. This prints the server capabilities and folders, and no message content:
+
+   ```bash
+   uvx imap-mcp probe
+   ```
+
+4. Run the first full sync. A large mailbox takes a long time, because iCloud limits download speed. You can stop it and run it again later. It continues where it stopped:
+
+   ```bash
+   uvx imap-mcp sync
+   ```
+
+### Optional settings
+
+| Key | Default | Effect |
+|---|---|---|
+| `download_dir` | `~/Downloads` | Where `download_attachment` saves files |
+| `sync_interval_minutes` | `15` | How old the data can be before a tool call syncs |
+| `sync_budget_seconds` | `20` | The time limit of a sync that a tool call starts |
+| `db_path` | `~/Library/Application Support/imap-mcp/imap-mcp.db` | The index. It must be on a local disk, not in iCloud Drive. |
+| `drafts_folder` | empty | The Drafts folder name. Empty means find it by role or name. |
+| `exclude_folders` | `[]` | Folders never to sync |
+| `auth_servers` | `["icloud.com"]` | Domains of your IMAP server's `Authentication-Results` headers. Only those headers give the `spf`, `dkim` and `dmarc` verdicts. |
+
+`IMAP_MCP_CONFIG` overrides the config file path.
+
+## Connect the Claude desktop app
+
+1. Find the absolute path of `uvx`. The desktop app starts servers with a minimal `PATH`, so a bare `uvx` fails. Do not use a version-manager shim:
+
+   ```bash
+   which -a uvx
+   ```
+
+2. Open Claude, then Settings, Developer, Edit Config. This opens `~/Library/Application Support/Claude/claude_desktop_config.json`.
+
+3. Add the server, with your `uvx` path:
+
+   ```json
+   {
+     "mcpServers": {
+       "imap": {
+         "command": "/opt/homebrew/bin/uvx",
+         "args": ["imap-mcp@latest", "serve"]
+       }
+     }
+   }
+   ```
+
+   `imap-mcp@latest` checks for a new release at each start. Use a fixed version such as `imap-mcp@0.1.0` to upgrade only when you choose.
+
+4. Quit and restart Claude. The tools appear under the imap server in the tools menu.
+
+5. Keep `create_draft` on "Ask" when Claude asks for permission. Do not choose "Always allow".
+
+Server logs go to `~/Library/Logs/Claude/mcp-server-imap.log`. Logs never contain message content or addresses.
+
+## Connect Claude Code or another MCP client
+
+Any client that runs a stdio server can use the same command:
+
+```bash
+claude mcp add imap -- uvx imap-mcp@latest serve
+```
+
+## Usage
+
+Ask the agent in plain language. It picks the tools. For example:
+
+- "When does my car insurance renew?" The agent searches, reads the best match and answers with the date and the sender.
+- "What did the plumber say about Thursday? Draft a reply that accepts 9am." The agent finds the thread and writes a draft. You open Drafts in Mail, edit it and send it yourself.
+- "Save the PDF invoice from Acme." The agent saves it to `~/Downloads` and tells you the path.
+- "Check for new mail first." The agent calls `sync_now`.
+
+### Tools
+
+| Tool | Effect |
+|---|---|
+| `search_mail` | Ranked keyword search with filters (folder, sender, recipient, dates, unread, flagged, attachments). Skips Junk and Trash unless named. |
+| `get_message` | One message: headers, plain-text body, attachment list |
+| `list_folders` | Folders with message and unread counts |
+| `sync_now` | Sync now, within the time limit |
+| `download_attachment` | Save one attachment to `download_dir` |
+| `create_draft` | Write a Markdown draft to the Drafts folder. Never sends. |
+
+### Commands
+
+| Command | Effect |
+|---|---|
+| `imap-mcp serve` | Run the MCP server on stdio. Your agent runs this. |
+| `imap-mcp set-password` | Store the app password in the Keychain |
+| `imap-mcp probe` | Log in and print capabilities and folders |
+| `imap-mcp sync` | Run a full sync with no time limit |
+| `imap-mcp status` | Show sync state, folder counts and database size |
+| `imap-mcp vacuum` | Rebuild the database file |
+| `imap-mcp purge --yes` | Delete the index. The next sync rebuilds it. |
+
+## Prompt injection
+
+An email can contain text written to steer the agent. imap-mcp cannot send mail, so the worst it can do on its own is write a draft. But if the same agent also has a tool that can reach the network (web fetch, HTTP, another mail tool), a hostile email can tell the agent to leak data through that tool. In a session that reads mail, give the agent as few network tools as possible.
+
+## Development
+
+```bash
+git clone https://github.com/bcrisp4/imap-mcp
+```
+
+```bash
+cd imap-mcp && uv sync
+```
+
+```bash
+uv run ruff check && uv run ruff format --check && uv run pyright && uv run mypy && uv run pytest
+```
+
+To run your checkout instead of the release, use `uv run --directory /path/to/imap-mcp imap-mcp serve` as the server command.
+
+Tests never connect to a real mailbox. They use a TLS fake IMAP server that records every command and reproduces the iCloud quirks. Read [AGENTS.md](https://github.com/bcrisp4/imap-mcp/blob/main/AGENTS.md) before you change code, and [docs/releasing.md](https://github.com/bcrisp4/imap-mcp/blob/main/docs/releasing.md) to make a release.
+
+## Docs
+
+- [Design](https://github.com/bcrisp4/imap-mcp/blob/main/docs/designs/imap-mcp.md): goals, security model, sync design and decisions
+- [Changelog](https://github.com/bcrisp4/imap-mcp/blob/main/CHANGELOG.md)
+- API reference: run `uv run pdoc imap_mcp` in a clone
+
+## Licence
+
+MIT. See [LICENSE](https://github.com/bcrisp4/imap-mcp/blob/main/LICENSE).

imap_mcp-0.1.0/README.md

@@ -0,0 +1,167 @@
+# imap-mcp
+
+imap-mcp is a local MCP server that gives an AI agent read-only, searchable access to one IMAP mailbox. It can write drafts and can never send mail.
+
+It syncs the mailbox into a local SQLite index with ranked keyword search. It syncs again on a tool call when the data is more than 15 minutes old, and every result tells the agent how old the data is. iCloud is the main target. Any IMAP server that accepts an app password also works.
+
+Status: alpha. Tool names and parameters can change before 1.0.0. See the [changelog](https://github.com/bcrisp4/imap-mcp/blob/main/CHANGELOG.md).
+
+## What it never does
+
+- It never sends mail. The package contains no SMTP code.
+- It never deletes, moves or flags mail. A read never marks a message as read. A command allowlist checks every IMAP command before it goes on the wire.
+- It never listens on the network. It runs on stdio, started by your agent.
+
+Email is untrusted input. Results keep sender text apart from server data, remove hidden HTML and invisible Unicode, and show sender authentication results. See [Security](https://github.com/bcrisp4/imap-mcp/blob/main/docs/designs/imap-mcp.md#security) in the design doc.
+
+## Requirements
+
+- macOS. The password lives in the macOS Keychain.
+- [uv](https://docs.astral.sh/uv/). It installs Python 3.14 if you do not have it.
+- An IMAP account with an app password. For iCloud, create one at [account.apple.com](https://account.apple.com) under Sign-In and Security, App-Specific Passwords.
+
+## Set up
+
+1. Create `~/.config/imap-mcp/config.toml`. For iCloud, `username` is your Apple Account email or a custom-domain address on the account:
+
+   ```toml
+   host = "imap.mail.me.com"
+   port = 993
+   username = "you@icloud.com"
+   from_address = "you@icloud.com"
+   ```
+
+2. Store the app password in the Keychain. `security` prompts for it twice. When macOS asks for Keychain access later, choose Always Allow for `/usr/bin/security`:
+
+   ```bash
+   uvx imap-mcp set-password
+   ```
+
+3. Check the connection. This prints the server capabilities and folders, and no message content:
+
+   ```bash
+   uvx imap-mcp probe
+   ```
+
+4. Run the first full sync. A large mailbox takes a long time, because iCloud limits download speed. You can stop it and run it again later. It continues where it stopped:
+
+   ```bash
+   uvx imap-mcp sync
+   ```
+
+### Optional settings
+
+| Key | Default | Effect |
+|---|---|---|
+| `download_dir` | `~/Downloads` | Where `download_attachment` saves files |
+| `sync_interval_minutes` | `15` | How old the data can be before a tool call syncs |
+| `sync_budget_seconds` | `20` | The time limit of a sync that a tool call starts |
+| `db_path` | `~/Library/Application Support/imap-mcp/imap-mcp.db` | The index. It must be on a local disk, not in iCloud Drive. |
+| `drafts_folder` | empty | The Drafts folder name. Empty means find it by role or name. |
+| `exclude_folders` | `[]` | Folders never to sync |
+| `auth_servers` | `["icloud.com"]` | Domains of your IMAP server's `Authentication-Results` headers. Only those headers give the `spf`, `dkim` and `dmarc` verdicts. |
+
+`IMAP_MCP_CONFIG` overrides the config file path.
+
+## Connect the Claude desktop app
+
+1. Find the absolute path of `uvx`. The desktop app starts servers with a minimal `PATH`, so a bare `uvx` fails. Do not use a version-manager shim:
+
+   ```bash
+   which -a uvx
+   ```
+
+2. Open Claude, then Settings, Developer, Edit Config. This opens `~/Library/Application Support/Claude/claude_desktop_config.json`.
+
+3. Add the server, with your `uvx` path:
+
+   ```json
+   {
+     "mcpServers": {
+       "imap": {
+         "command": "/opt/homebrew/bin/uvx",
+         "args": ["imap-mcp@latest", "serve"]
+       }
+     }
+   }
+   ```
+
+   `imap-mcp@latest` checks for a new release at each start. Use a fixed version such as `imap-mcp@0.1.0` to upgrade only when you choose.
+
+4. Quit and restart Claude. The tools appear under the imap server in the tools menu.
+
+5. Keep `create_draft` on "Ask" when Claude asks for permission. Do not choose "Always allow".
+
+Server logs go to `~/Library/Logs/Claude/mcp-server-imap.log`. Logs never contain message content or addresses.
+
+## Connect Claude Code or another MCP client
+
+Any client that runs a stdio server can use the same command:
+
+```bash
+claude mcp add imap -- uvx imap-mcp@latest serve
+```
+
+## Usage
+
+Ask the agent in plain language. It picks the tools. For example:
+
+- "When does my car insurance renew?" The agent searches, reads the best match and answers with the date and the sender.
+- "What did the plumber say about Thursday? Draft a reply that accepts 9am." The agent finds the thread and writes a draft. You open Drafts in Mail, edit it and send it yourself.
+- "Save the PDF invoice from Acme." The agent saves it to `~/Downloads` and tells you the path.
+- "Check for new mail first." The agent calls `sync_now`.
+
+### Tools
+
+| Tool | Effect |
+|---|---|
+| `search_mail` | Ranked keyword search with filters (folder, sender, recipient, dates, unread, flagged, attachments). Skips Junk and Trash unless named. |
+| `get_message` | One message: headers, plain-text body, attachment list |
+| `list_folders` | Folders with message and unread counts |
+| `sync_now` | Sync now, within the time limit |
+| `download_attachment` | Save one attachment to `download_dir` |
+| `create_draft` | Write a Markdown draft to the Drafts folder. Never sends. |
+
+### Commands
+
+| Command | Effect |
+|---|---|
+| `imap-mcp serve` | Run the MCP server on stdio. Your agent runs this. |
+| `imap-mcp set-password` | Store the app password in the Keychain |
+| `imap-mcp probe` | Log in and print capabilities and folders |
+| `imap-mcp sync` | Run a full sync with no time limit |
+| `imap-mcp status` | Show sync state, folder counts and database size |
+| `imap-mcp vacuum` | Rebuild the database file |
+| `imap-mcp purge --yes` | Delete the index. The next sync rebuilds it. |
+
+## Prompt injection
+
+An email can contain text written to steer the agent. imap-mcp cannot send mail, so the worst it can do on its own is write a draft. But if the same agent also has a tool that can reach the network (web fetch, HTTP, another mail tool), a hostile email can tell the agent to leak data through that tool. In a session that reads mail, give the agent as few network tools as possible.
+
+## Development
+
+```bash
+git clone https://github.com/bcrisp4/imap-mcp
+```
+
+```bash
+cd imap-mcp && uv sync
+```
+
+```bash
+uv run ruff check && uv run ruff format --check && uv run pyright && uv run mypy && uv run pytest
+```
+
+To run your checkout instead of the release, use `uv run --directory /path/to/imap-mcp imap-mcp serve` as the server command.
+
+Tests never connect to a real mailbox. They use a TLS fake IMAP server that records every command and reproduces the iCloud quirks. Read [AGENTS.md](https://github.com/bcrisp4/imap-mcp/blob/main/AGENTS.md) before you change code, and [docs/releasing.md](https://github.com/bcrisp4/imap-mcp/blob/main/docs/releasing.md) to make a release.
+
+## Docs
+
+- [Design](https://github.com/bcrisp4/imap-mcp/blob/main/docs/designs/imap-mcp.md): goals, security model, sync design and decisions
+- [Changelog](https://github.com/bcrisp4/imap-mcp/blob/main/CHANGELOG.md)
+- API reference: run `uv run pdoc imap_mcp` in a clone
+
+## Licence
+
+MIT. See [LICENSE](https://github.com/bcrisp4/imap-mcp/blob/main/LICENSE).

imap_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,109 @@
+[project]
+name = "imap-mcp"
+version = "0.1.0"
+description = "Local, read-only MCP server with keyword search over one IMAP mailbox"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Ben Crisp", email = "ben@thecrisp.io" }]
+requires-python = ">=3.14"
+keywords = ["mcp", "imap", "email", "icloud", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Communications :: Email :: Post-Office :: IMAP",
+]
+dependencies = [
+    "beautifulsoup4>=4.15",
+    "imapclient>=4.1",
+    "lxml>=6.1",
+    "markdown-it-py>=4.2",
+    "mcp>=2.3",
+    "pydantic>=2.14",
+    "structlog>=26.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/bcrisp4/imap-mcp"
+Source = "https://github.com/bcrisp4/imap-mcp"
+Issues = "https://github.com/bcrisp4/imap-mcp/issues"
+Design = "https://github.com/bcrisp4/imap-mcp/blob/main/docs/designs/imap-mcp.md"
+Changelog = "https://github.com/bcrisp4/imap-mcp/blob/main/CHANGELOG.md"
+
+[project.scripts]
+imap-mcp = "imap_mcp.entrypoints.cli:main"
+
+[build-system]
+requires = ["hatchling==1.33.0"]
+build-backend = "hatchling.build"
+
+# The sdist holds only what a rebuild and the tests need. Agent skills, CI
+# files and generated API docs stay out.
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "src", "tests", "scripts", "README.md", "CHANGELOG.md", "LICENSE", "uv.lock",
+]
+
+[dependency-groups]
+dev = [
+    "anyio>=4.15",
+    "mypy>=2.4",
+    "pdoc>=16.0",
+    "pyright>=1.1.414",
+    "pytest>=9.2",
+    "pytest-asyncio>=1.4",
+    "pytest-cov>=7.1",
+    "ruff>=0.17",
+    "trustme>=1.2",
+]
+
+[tool.ruff]
+target-version = "py314"
+line-length = 88
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E", "F", "W", "I", "UP", "B", "SIM", "TC", "RUF", "PTH",
+    "ASYNC", "S", "T20", "ARG", "FBT", "A", "C4", "DTZ", "ISC",
+    "PIE", "RSE", "RET", "TID",
+]
+
+[tool.ruff.lint.flake8-type-checking]
+runtime-evaluated-base-classes = ["pydantic.BaseModel"]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+# imap-mcp never sends mail. See docs/designs/imap-mcp.md, Security T1.
+"smtplib".msg = "imap-mcp must never send mail (design T1)."
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "S105", "S106", "ARG", "FBT", "PLR2004"]
+
+[tool.pyright]
+include = ["src", "tests"]
+typeCheckingMode = "strict"
+pythonVersion = "3.14"
+reportMissingTypeStubs = false
+
+[tool.mypy]
+strict = true
+python_version = "3.14"
+mypy_path = "src"
+packages = ["imap_mcp"]
+
+[[tool.mypy.overrides]]
+module = ["imapclient.*", "trustme.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+addopts = ["--strict-markers", "-ra", "--import-mode=importlib"]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

imap_mcp-0.1.0/scripts/changelog_section.py

@@ -0,0 +1,63 @@
+"""Print the CHANGELOG.md section of one version, for the GitHub release notes.
+
+Usage: `python scripts/changelog_section.py 0.1.0`. It exits 1 if the section
+is missing or empty, so a release cannot go out without notes.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+_HEADING = re.compile(
+    r"^## \[(?P<version>[^\]]+)\](?: - (?P<date>\d{4}-\d{2}-\d{2}))?\s*$"
+)
+
+
+def section(text: str, version: str) -> str | None:
+    """Return the body of the `## [version] - date` section, or None.
+
+    Args:
+        text: The changelog text.
+        version: The version, without a leading "v".
+
+    Returns:
+        The section body without its heading, or None if the section is
+        missing, has no release date, or is empty.
+    """
+    lines = text.splitlines()
+    body: list[str] = []
+    found = False
+    for line in lines:
+        match = _HEADING.match(line)
+        if match:
+            if found:
+                break
+            if match["version"] == version and match["date"]:
+                found = True
+            continue
+        if found:
+            if line.startswith("[") and "]: " in line:
+                break
+            body.append(line)
+    result = "\n".join(body).strip()
+    return result or None
+
+
+def main() -> int:
+    """Print the section for `sys.argv[1]`."""
+    version = sys.argv[1].removeprefix("v")
+    text = Path("CHANGELOG.md").read_text()
+    body = section(text, version)
+    if body is None:
+        sys.stderr.write(
+            f"CHANGELOG.md has no dated, non-empty section for {version}.\n"
+        )
+        return 1
+    sys.stdout.write(body + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

imap_mcp-0.1.0/scripts/check_licenses.py

@@ -0,0 +1,35 @@
+"""Fail if an installed runtime dependency has a GPL-family licence.
+
+imap-mcp is MIT, so a GPL dependency would change the licence of the whole
+distribution. Run with `uv run --no-dev python scripts/check_licenses.py`.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from importlib.metadata import distributions
+
+# AGPL and LGPL also match. LGPL is allowed in principle, but no dependency
+# needs it today, so it fails here and gets a human decision.
+_COPYLEFT = re.compile(r"\b[AL]?GPL\b|GNU (Affero |Lesser )?General Public", re.I)
+
+
+def main() -> int:
+    """Print each offending distribution and return 1 if any exist."""
+    bad: list[str] = []
+    for dist in distributions():
+        meta = dist.metadata
+        fields = [meta.get("License-Expression") or "", meta.get("License") or ""]
+        classifiers = meta.get_all("Classifier") or []
+        fields += [c for c in classifiers if c.startswith("License")]
+        text = " ".join(fields)
+        if _COPYLEFT.search(text):
+            bad.append(f"{meta['Name']} {meta['Version']}: {text[:120]}")
+    for line in bad:
+        sys.stderr.write(line + "\n")
+    return 1 if bad else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

imap_mcp-0.1.0/src/imap_mcp/__init__.py

@@ -0,0 +1 @@
+"""imap-mcp: a local, read-only MCP server over one IMAP mailbox."""

imap_mcp-0.1.0/src/imap_mcp/adapters/__init__.py

@@ -0,0 +1 @@
+"""The adapters package of imap-mcp."""

imap_mcp-0.1.0/src/imap_mcp/adapters/clock.py

@@ -0,0 +1,18 @@
+"""The system clock."""
+
+from __future__ import annotations
+
+import time
+from datetime import UTC, datetime
+
+
+class SystemClock:
+    """Reads the real time."""
+
+    def now(self) -> datetime:
+        """Return the current time, timezone-aware UTC."""
+        return datetime.now(UTC)
+
+    def monotonic(self) -> float:
+        """Return a monotonic time in seconds."""
+        return time.monotonic()