agentic-mail-mcp 0.1.0__tar.gz

agentic_mail_mcp-0.1.0/.env.example

@@ -0,0 +1,39 @@
+# Bring your own Google app. Easiest: point at the credentials.json you
+# downloaded from Google Cloud. (Or set the client id/secret below instead.)
+AGENTIC_MAIL_MCP_GMAIL_CLIENT_SECRETS_FILE=
+AGENTIC_MAIL_MCP_GMAIL_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
+AGENTIC_MAIL_MCP_GMAIL_OAUTH_CLIENT_SECRET=your-client-secret
+AGENTIC_MAIL_MCP_GMAIL_SCOPES=["https://www.googleapis.com/auth/gmail.modify"]
+AGENTIC_MAIL_MCP_GMAIL_TOKEN_STORAGE_PATH=token.json
+AGENTIC_MAIL_MCP_GMAIL_TOKEN_ENCRYPTION_KEY=your-encryption-key
+AGENTIC_MAIL_MCP_DATABASE_URL=sqlite:///./agentic_mail_mcp.db
+AGENTIC_MAIL_MCP_DATABASE_DRIVER=sqlite
+# Read-through email cache TTL (metadata only; bodies are never persisted).
+AGENTIC_MAIL_MCP_DATABASE_CACHE_TTL_SECONDS=900
+AGENTIC_MAIL_MCP_RAILGUARDS_ACCESS_LEVEL=read_only
+AGENTIC_MAIL_MCP_RAILGUARDS_ALLOWED_RECIPIENTS=[]
+AGENTIC_MAIL_MCP_RAILGUARDS_BLOCKED_ACTIONS=[]
+AGENTIC_MAIL_MCP_RAILGUARDS_RATE_LIMITS={}
+AGENTIC_MAIL_MCP_RAILGUARDS_ARCHIVE_FIRST_POLICY=false
+AGENTIC_MAIL_MCP_MCP_SERVER_NAME=Agentic-Mail-MCP
+AGENTIC_MAIL_MCP_MCP_TRANSPORT=stdio
+AGENTIC_MAIL_MCP_MCP_HOST=127.0.0.1
+AGENTIC_MAIL_MCP_MCP_PORT=8080
+AGENTIC_MAIL_MCP_LLM_PROVIDER=openai
+AGENTIC_MAIL_MCP_LLM_MODEL=gpt-4
+# LLM is OPTIONAL. The calling agent is itself an LLM, so per-email reasoning is
+# exposed as MCP prompts by default. An LLM key only enables the digest tools
+# (map-reduce over many emails). Leave empty to run without one.
+AGENTIC_MAIL_MCP_LLM_API_KEY=
+AGENTIC_MAIL_MCP_LLM_BASE_URL=
+AGENTIC_MAIL_MCP_LLM_MODEL_PATH=
+# Set true to ALSO expose per-email summarize/classify/reply/action-items as
+# server-side tools (adds latency + needs a configured LLM). Default: caller-first.
+AGENTIC_MAIL_MCP_LLM_INTERNAL_TOOLS=false
+AGENTIC_MAIL_MCP_SEARCH_BACKEND=sqlite_vss
+AGENTIC_MAIL_MCP_SEARCH_EMBEDDING_MODEL=BAAI/bge-small-en-v1.5
+AGENTIC_MAIL_MCP_SEARCH_EMBEDDING_DIMENSION=384
+AGENTIC_MAIL_MCP_NOTIFICATIONS_WEBHOOK_URL=
+AGENTIC_MAIL_MCP_NOTIFICATIONS_REDIS_URL=
+AGENTIC_MAIL_MCP_LOGGING_LEVEL=INFO
+AGENTIC_MAIL_MCP_LOGGING_JSON_FORMAT=true

agentic_mail_mcp-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Secrets and OAuth credentials — never commit these
+/token.json
+/credentials.json
+# Default token_storage_path (Settings.gmail.token_storage_path)
+token.json
+# Encrypted token store (Settings.gmail.token_storage_path)
+/.secrets/
+# Build artifacts
+/dist/
+/build/
+*.egg-info/
+# Local persistence, encrypted token store, and downloaded model artifacts
+*.db
+*.sqlite
+*.sqlite3
+/models/
+.config/agentic-mail-mcp/
+__pycache__/
+*.py[codz]
+*$py.class
+.env
+.env*.local
+.env.development
+.env.production
+backend/keys/
+*.pem
+*.log
+/.coverage

agentic_mail_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,138 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### ⚠ Breaking
+
+- **Railguards default is now read-only** (Phase 6): `railguards.access_level` defaults to `read_only` (was `owner`), so all write operations (forward/archive/delete/draft) are denied until a deployment sets `AGENTIC_MAIL_MCP_RAILGUARDS_ACCESS_LEVEL=read_write`.
+
+### Fixed
+
+- **Environment-variable configuration now works** (Phase 8): the `Settings`
+  sub-sections (`gmail`, `database`, `railguards`, `mcp`, `llm`, `search`,
+  `notifications`, `logging`) previously ignored their `AGENTIC_MAIL_MCP_<SECTION>_<FIELD>`
+  environment variables and always used defaults. Each section now carries its
+  own env prefix, so documented variables such as
+  `AGENTIC_MAIL_MCP_RAILGUARDS_ACCESS_LEVEL`, `AGENTIC_MAIL_MCP_MCP_TRANSPORT`, and
+  `AGENTIC_MAIL_MCP_DATABASE_URL` take effect — required for pip/Docker deployments to
+  be configurable.
+
+### Changed
+
+- **Caller-first intelligence** ([ADR 0006](specs/docs/adr/0006-caller-first-intelligence.md)):
+  the calling agent is itself an LLM, so per-email reasoning (summarize, classify,
+  draft reply, extract action items) is now exposed as **MCP prompts** the agent
+  runs — no server-side inference, no added latency, and **no LLM key required**
+  for the core experience. Internal LLM inference is reserved for the digest tools
+  (map-reduce over many emails), which register only when an LLM is configured;
+  set `AGENTIC_MAIL_MCP_LLM_INTERNAL_TOOLS=true` to also expose the per-email tools
+  server-side. Embeddings for semantic search remain internal.
+
+### Added
+
+- **Live write-path smoke test** (`tests/e2e/test_live_write_path.py`, opt-in via
+  `AGENTIC_MAIL_MCP_LIVE_WRITE_E2E=1`). Self-contained and safe: it creates its own
+  throwaway message and exercises `create_draft` → `send_draft` → `add_label` →
+  `forward_email` (to self) → `archive_email` → `delete_email`, then trashes its
+  own artifacts. Verified green against a real account. Documented finding:
+  permanent delete needs the `https://mail.google.com/` scope (soft delete works
+  under `gmail.modify`); `add_label` uses Gmail label **ids** (system labels like
+  `STARRED`), not arbitrary user-label names.
+- **Bring-your-own Google app** ([ADR 0008](specs/docs/adr/0008-bring-your-own-google-app.md)).
+  The server is a local, bring-your-own-credentials tool — no central app, no
+  Google verification. Point `AGENTIC_MAIL_MCP_GMAIL_CLIENT_SECRETS_FILE` at the
+  `credentials.json` you download from your own Google Cloud project (or set the
+  client id/secret directly); credentials and token stay on your machine. Docs
+  now cover the full self-service Google setup, the unverified-app screen, and
+  avoiding the 7-day testing-token expiry.
+- **Persistence: read-through cache** ([ADR 0007](specs/docs/adr/0007-persistence-read-through-cache.md)).
+  Gmail is the source of truth; local persistence is a `CachedEmailRepository`, not
+  a mirror: single-email reads are live (fresh, full body), the SQLite cache stores
+  **metadata only — never bodies**, list views are served within a TTL
+  (`AGENTIC_MAIL_MCP_DATABASE_CACHE_TTL_SECONDS`, default 900s), and emails gone from the
+  server are evicted (no sync engine, no delete-propagation). Tools now identify an
+  email by its Gmail **`message_id`** end to end (write commands carry `message_id`;
+  the internal UUID is an implementation detail). The Gmail→domain mapper extracts
+  bare addresses from display-name headers (`"Name <a@b.com>"`) instead of failing.
+- **Runtime composition root + auth** (makes the server usable end to end)
+  - `agentic_mail_mcp/Bootstrap/Composition.py` assembles every use case from `Settings` —
+    SQLite persistence (schema applied via Alembic), a lazy OAuth-backed Gmail
+    gateway, railguard validator, event bus, LLM gateway, and optional semantic
+    search — into the `McpUseCases` bundle the server registers. The launched
+    `agentic-mail-mcp` now exposes its tools (previously zero).
+  - `LazyGmailGateway` builds the authenticated Gmail client on first use, so
+    tools register at startup and calls before authorization return a clear
+    "run `agentic-mail-mcp auth`" error.
+  - `agentic-mail-mcp auth` subcommand performs the one-time interactive Google
+    authorization and stores the encrypted token (`make auth`).
+  - Semantic search degrades gracefully: `semantic_search` is registered only
+    when the `search` extra (sentence-transformers + sqlite-vec) is installed.
+- **Distribution and polish** (Phase 8)
+  - `LICENSE` (MIT); `pyproject.toml` distribution metadata (`readme`,
+    `project.urls`, `license-files`) and a scoped sdist target producing a clean
+    source distribution + wheel with the `agentic-mail-mcp` entry point
+  - `specs/docs/api.md` — the MCP tool/resource/prompt reference with input
+    schemas, output shapes, and the structured error format
+  - Architecture ADRs `0002`–`0005` (DDD + vertical slicing, SQLite/PostgreSQL
+    persistence, railguards write-safety, MCP stdio transport)
+  - Expanded `README.md` (tool catalog, railguards security model, stdio
+    integration example, contributing, and the automated PyPI release flow)
+  - Multi-stage `Dockerfile` (builder + slim non-root runtime, health check),
+    multi-arch build support
+  - End-to-end MCP session tests (`tests/e2e/`) covering the read/write tool
+    flow, railguard enforcement, and a container health-check smoke test
+  - Removed the superseded pre-DDD `main.py` / `server.py` skeletons from the
+    repo root (replaced by `agentic_mail_mcp/MCP/Server.py` and `agentic_mail_mcp/Bootstrap/cli.py`)
+
+- **MCP server layer** (Phase 7)
+  - `create_server` bootstrap that assembles the server from the dependency container and integrates the application lifespan; configurable transport (`stdio` default, streamable HTTP) via `Settings.mcp.transport`; the `agentic-mail-mcp` console entry point launches it
+  - `ToolRegistry` with category-grouped tools (read/write/intelligence/search) and JSON-Schema input schemas; **defense-in-depth**: write-category tools are not registered when `railguards.access_level` is `read_only`, so they are never exposed to the agent
+  - Read tools: `search_emails`, `get_email`, `get_thread`, `list_unread`, `list_labels`
+  - Write tools (railguarded): `forward_email`, `archive_email`, `delete_email`, `create_draft`, `send_draft`, `add_label`
+  - Intelligence tools: `summarize_email`, `classify_email`, `suggest_reply`, `extract_action_items`, `daily_digest`, `weekly_digest`
+  - Search tool: `semantic_search`
+  - MCP resources (account info, watch status, index status) and prompts (search strategy, email management); structured tool-error mapping for railguard denials, missing entities, and invalid input
+  - `AddLabelUseCase` (railguarded) emitting `EmailLabeled`; digest use cases accept an optional date anchor
+  - `Settings.mcp.transport` (`stdio` default)
+- **Railguards framework** (Phase 6)
+  - `RailguardConfig` (access level, recipient allowlist with address/domain matching, action blocklist, windowed rate limits, archive-first policy) and `RailguardValidator` raising `PermissionError` on violation
+  - `audit_log` table, `AuditLogRepository` (SQLite), and `AuditLogHandler` event subscriber recording every write with a correlation id
+  - Railguarded write use cases: `ForwardEmailUseCase`, `ArchiveEmailUseCase`, `DeleteEmailUseCase` (soft-delete default, archive-first for permanent), `CreateDraftUseCase` / `SendDraftUseCase` (draft-first sending)
+  - `GmailGateway` draft operations (`create_draft`/`send_draft`/`delete_draft`) and their `GmailApiGateway` implementation
+  - `Settings.railguards.archive_first_policy`; Alembic migration `0002`
+- **Shared domain primitives** (Phase 2)
+  - `ValueObject` base class with structural equality, hashing, and repr
+  - `UUIDId` value object wrapping `uuid.UUID` with `generate()` factory
+  - Typed exception hierarchy: `DomainError`, `ValidationError`, `NotFoundError`, `PermissionError`, `ConcurrencyError`
+  - `EventBus` protocol and `InMemoryEventBus` implementation
+  - `Specification[T]` pattern with `And`, `Or`, `Not` composables
+  - `Clock` protocol with `SystemClock` and `FrozenClock` implementations
+  - `IdGenerator` protocol with `UuidIdGenerator` implementation
+- Exhaustive unit test coverage for all shared primitives
+- **Domain models for all bounded contexts** (Phase 3)
+  - Gmail: `Email`, `Thread`, `Attachment`, `Label` aggregates; `EmailAddress`, `GmailMessageId`, `ThreadId`, `HistoryId`, `GmailQuery` value objects; repository and `GmailGateway` ports; mappers; domain events
+  - Intelligence: `Summary`, `Classification`, `Suggestion` entities; `PromptTemplate`, `ModelConfig` value objects; `LlmGateway` port
+  - Search: `SearchDocument` entity; `EmbeddingGateway` and `VectorSearchRepository` ports
+  - Notification: `ImportantEmailDetected`, `InboxChanged`, `DigestReady` events; `NotificationGateway` port
+- **Application use cases** (Phase 4)
+  - Gmail read use cases: `SearchEmailsUseCase`, `GetEmailUseCase`, `GetThreadUseCase`, `ListUnreadUseCase`, `ListLabelsUseCase`; query/command objects and read DTOs
+  - Intelligence use cases: `SummarizeEmailUseCase`, `SuggestReplyUseCase`, `ClassifyEmailUseCase`, `DailyDigestUseCase`, `WeeklyDigestUseCase`, `ExtractActionItemsUseCase`
+  - Search use cases: `SemanticSearchUseCase`, `IndexEmailUseCase`, `RebuildIndexUseCase`
+  - Notification use cases: `NotifyImportantEmailUseCase`, `PublishInboxEventUseCase` (domain-event subscribers)
+
+### Changed
+
+- `EventBus` is now generic over concrete event types: handlers are registered and dispatched by the event's exact type, so domain events are no longer required to inherit `DomainEvent` (it remains an optional base for standard metadata).
+- **Database default is now a synchronous SQLite driver** (`sqlite:///…`) to match the synchronous repository ports (Phase 5). Set `AGENTIC_MAIL_MCP_DATABASE_URL` to a `postgresql+psycopg2://…` URL for PostgreSQL.
+
+### Added (Phase 5 — Infrastructure Adapters)
+
+- **Persistence**: synchronous SQLAlchemy engine/session wiring with a UTC-normalizing datetime type; ORM models and domain↔ORM mappers for Email/Thread/Attachment/Label; `SqliteEmailRepository` / `SqliteThreadRepository`; initial Alembic migration (`alembic.ini` + `migrations/`); PostgreSQL repository variants sharing the schema.
+- **Gmail Google adapter**: `GmailOAuthProvider` (Fernet-encrypted token storage), `GmailApiGateway` (Gmail API with retry/backoff and rate limiting), `GmailWatcher` (push notifications + webhook parsing), `GmailHistorySynchronizer` (idempotent history sync emitting domain events).
+- **Intelligence**: `LlamaCppGateway` implementing `LlmGateway` over an OpenAI-compatible endpoint or a local llama.cpp model.
+- **Search**: `BgeEmbeddingGateway` (`EmbeddingGateway`); `SqliteVecRepository` (default) and `PgVectorRepository` (optional) implementing `VectorSearchRepository`, verified interchangeable by a shared contract test.
+- **Notification**: `WebhookNotificationGateway` and `RedisNotificationGateway` implementing `NotificationGateway`.
+- **Wiring**: `register_infrastructure()` binds the default adapter stack on the DI container.
+- New Settings keys (`llm.base_url`, `llm.model_path`, `search.*`) and optional dependency extras (`postgresql`, `search`, `notifications`, `llm`); see `specs/docs/configuration.md` and `specs/docs/data-model.md`.

agentic_mail_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentic Mail MCP Team
+
+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.

agentic_mail_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,385 @@
+Metadata-Version: 2.4
+Name: agentic-mail-mcp
+Version: 0.1.0
+Summary: A Model Context Protocol (MCP) server exposing Gmail operations for AI agents
+Project-URL: Homepage, https://github.com/CoolDevGuys/agentic-mail-mcp
+Project-URL: Repository, https://github.com/CoolDevGuys/agentic-mail-mcp
+Project-URL: Documentation, https://github.com/CoolDevGuys/agentic-mail-mcp/tree/main/specs/docs
+Project-URL: Changelog, https://github.com/CoolDevGuys/agentic-mail-mcp/blob/main/CHANGELOG.md
+Author: Agentic Mail MCP Team
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Requires-Dist: alembic
+Requires-Dist: cryptography
+Requires-Dist: google-api-python-client
+Requires-Dist: google-auth-oauthlib
+Requires-Dist: httpx
+Requires-Dist: mcp
+Requires-Dist: pydantic
+Requires-Dist: pydantic-settings
+Requires-Dist: python-dotenv
+Requires-Dist: sqlalchemy
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: fakeredis; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest-httpserver; extra == 'dev'
+Requires-Dist: respx; extra == 'dev'
+Requires-Dist: ruff==0.16.1; extra == 'dev'
+Requires-Dist: setuptools>=83.0.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: llama-cpp-python; extra == 'llm'
+Provides-Extra: notifications
+Requires-Dist: redis; extra == 'notifications'
+Provides-Extra: postgresql
+Requires-Dist: pgvector; extra == 'postgresql'
+Requires-Dist: psycopg2-binary; extra == 'postgresql'
+Provides-Extra: search
+Requires-Dist: sentence-transformers; extra == 'search'
+Requires-Dist: sqlite-vec; extra == 'search'
+Description-Content-Type: text/markdown
+
+# 📧 Agentic Mail MCP
+
+> A [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI
+> agents work with a Gmail account **safely** — read, search, summarize, and
+> (opt-in) forward/archive/label — behind a layered safety model.
+
+> **🔐 You bring your own Google app.** This is a **local tool, not a hosted
+> service** — you create your own OAuth client in your own Google Cloud project
+> and authorize your own mailbox. Your credentials and token never leave your
+> machine, and because the app only ever authorizes you, **there's no central
+> service and no Google verification to wait for.**
+
+> **ℹ️ Status:** pre-release (`0.1.0`), fully functional locally. Not yet on PyPI —
+> install from source (below).
+
+## ✨ Features
+
+| | |
+|---|---|
+| 📥 **Email operations** | Search, read, forward, archive, delete, draft, and label |
+| 🧠 **Intelligence** | Caller-first prompts (summarize, classify, reply, action items) + optional server-side digests |
+| 🔎 **Semantic search** | Natural-language vector search over your mail |
+| 🔔 **Notifications** | Webhook / Redis event fan-out |
+| 🛡️ **Railguards** | Read-only by default, allowlists, rate limits, archive-first delete, draft-first send, audit log |
+
+## 🚀 Quick start
+
+You need **Python 3.11+** and a Google account. Five minutes end to end.
+
+```mermaid
+flowchart LR
+    A[1. Install] --> B[2. Google<br/>credentials]
+    B --> C[3. Configure<br/>.env]
+    C --> D[4. Authorize<br/>agentic-mail-mcp auth]
+    D --> E[5. Connect agent<br/>or run HTTP]
+```
+
+**1. Install** (from source until published — see [Installation](#-installation)):
+
+```bash
+pip install "git+https://github.com/CoolDevGuys/agentic-mail-mcp.git"
+```
+
+**2. Get Google credentials** — in *your* Google Cloud project, enable the Gmail
+API, make a **Desktop-app OAuth client**, and **download its `credentials.json`**.
+Full walkthrough with the exact clicks:
+[Getting your Google credentials 👉](specs/docs/configuration.md#getting-your-google-credentials-oauth).
+
+**3. Configure** — copy `.env.example` to `.env` and point at your downloaded file:
+
+```bash
+# Easiest: just point at the credentials.json you downloaded.
+AGENTIC_MAIL_MCP_GMAIL_CLIENT_SECRETS_FILE=/path/to/credentials.json
+AGENTIC_MAIL_MCP_GMAIL_TOKEN_ENCRYPTION_KEY=<any long random string>
+# 🔒 Writes are denied by default. Keep read_only until you trust the setup.
+AGENTIC_MAIL_MCP_RAILGUARDS_ACCESS_LEVEL=read_only
+```
+
+**4. Authorize** (one-time browser consent — stores an encrypted token):
+
+```bash
+agentic-mail-mcp auth
+```
+
+**5. Use it** — connect an AI agent over **stdio** or run the **HTTP** server.
+See [Usage](#-usage).
+
+## ✅ Requirements
+
+- 🐍 Python 3.11+
+- 🔑 Your own Google OAuth **`credentials.json`** (a Desktop-app client from your
+  Google Cloud project — [how to get it](specs/docs/configuration.md#getting-your-google-credentials-oauth))
+- 🤖 *(optional)* an LLM API key for the digest tools (OpenAI-compatible by default)
+
+## 📦 Installation
+
+**From source (works today):**
+
+```bash
+pip install "git+https://github.com/CoolDevGuys/agentic-mail-mcp.git"
+# or, from a clone:
+pip install .
+```
+
+**Optional extras** (combine as needed, e.g. `".[postgresql,search]"`):
+
+| Extra | Adds |
+|---|---|
+| `postgresql` | PostgreSQL + pgvector backends |
+| `search` | local embeddings + sqlite-vec semantic search |
+| `notifications` | Redis pub/sub notifications |
+| `llm` | local llama.cpp inference |
+| `dev` | test / lint / build tooling |
+
+**Docker:** `docker compose up --build` (see [HTTP server](#http-server-deployment)).
+
+> 💡 Once published to PyPI, the recommended install for MCP clients will be
+> `uvx agentic-mail-mcp` / `pipx run agentic-mail-mcp` — no virtualenv to manage.
+
+## ⚙️ Configuration
+
+Set environment variables with the `AGENTIC_MAIL_MCP_` prefix, or use a `.env` file
+(copy `.env.example`). The table below covers the essentials; **every** setting,
+with defaults and purpose — and the **Google OAuth walkthrough** — is in
+[`specs/docs/configuration.md`](specs/docs/configuration.md).
+
+| Variable | Description | Default |
+|---|---|---|
+| `AGENTIC_MAIL_MCP_GMAIL_CLIENT_SECRETS_FILE` | Path to your downloaded `credentials.json` (recommended) | (one of these two) |
+| `AGENTIC_MAIL_MCP_GMAIL_OAUTH_CLIENT_ID` / `_SECRET` | …or the OAuth client id/secret directly | (one of these two) |
+| `AGENTIC_MAIL_MCP_GMAIL_TOKEN_ENCRYPTION_KEY` | Secret used to encrypt the stored token | (required to store tokens) |
+| `AGENTIC_MAIL_MCP_GMAIL_TOKEN_STORAGE_PATH` | Encrypted token file path (set outside the repo in prod) | `token.json` |
+| `AGENTIC_MAIL_MCP_DATABASE_URL` | SQLAlchemy URL (synchronous driver) | `sqlite:///./agentic_mail_mcp.db` |
+| `AGENTIC_MAIL_MCP_RAILGUARDS_ACCESS_LEVEL` | `read_only` or `read_write` — **writes denied by default** | `read_only` |
+| `AGENTIC_MAIL_MCP_LLM_PROVIDER` | `openai` (HTTP) or `llamacpp` (local) | `openai` |
+| `AGENTIC_MAIL_MCP_LLM_API_KEY` | LLM API key | (required for intelligence) |
+| `AGENTIC_MAIL_MCP_MCP_TRANSPORT` | `stdio` (default) or `http` | `stdio` |
+| `AGENTIC_MAIL_MCP_MCP_HOST` / `AGENTIC_MAIL_MCP_MCP_PORT` | HTTP transport bind address | `127.0.0.1` / `8080` |
+
+## 🔌 Usage
+
+The server speaks MCP over two transports:
+
+| Transport | Best for | How |
+|---|---|---|
+| **stdio** (default) | one user on a laptop (Claude Desktop, IDE agents) | agent launches the process |
+| **HTTP** (streamable) | shared / containerized deployments | long-running server on a port |
+
+> ⚠️ **Authorize first.** Run `agentic-mail-mcp auth` once (browser consent) before
+> starting the server — it stores the encrypted token the server reads on every
+> start. Details:
+> [Authorize](specs/docs/configuration.md#6-authorize-one-time-consent).
+>
+> **Headless server (no browser)?** `auth` needs a browser + loopback redirect,
+> so you don't run it on the server. Authorize once on a machine that has a
+> browser, then copy the encrypted token file across — see
+> [Headless / server deployment](specs/docs/configuration.md#7-headless--server-deployment-no-browser).
+
+### 💻 Local (stdio) — connect an AI agent
+
+Point your MCP client at the `agentic-mail-mcp` command. Example client config:
+
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "agentic-mail-mcp",
+      "env": {
+        "AGENTIC_MAIL_MCP_GMAIL_OAUTH_CLIENT_ID": "...",
+        "AGENTIC_MAIL_MCP_GMAIL_OAUTH_CLIENT_SECRET": "...",
+        "AGENTIC_MAIL_MCP_GMAIL_TOKEN_ENCRYPTION_KEY": "...",
+        "AGENTIC_MAIL_MCP_RAILGUARDS_ACCESS_LEVEL": "read_only"
+      }
+    }
+  }
+}
+```
+
+The agent then discovers the tools, resources, and prompts described in the
+[MCP API reference](specs/docs/api.md). Start with `read_only` and enable
+`read_write` deliberately once you understand the [railguards](#railguards-security-model).
+
+### HTTP server (deployment)
+
+Run a standalone streamable-HTTP server:
+
+```bash
+AGENTIC_MAIL_MCP_MCP_TRANSPORT=http AGENTIC_MAIL_MCP_MCP_HOST=0.0.0.0 AGENTIC_MAIL_MCP_MCP_PORT=8080 \
+  agentic-mail-mcp
+```
+
+Or with Docker (the compose file already sets HTTP transport and a health check):
+
+```bash
+docker compose up --build           # server on http://localhost:8080
+```
+
+> 🔑 **Auth on a headless host:** authorize on your laptop and mount the
+> encrypted token into the container (e.g. `-v /etc/agentic-mail-mcp:/secrets:ro`)
+> — full steps under
+> [Headless / server deployment](specs/docs/configuration.md#7-headless--server-deployment-no-browser).
+
+Point an HTTP-capable MCP client at `http://<host>:8080`. Keep the server behind
+your own auth/TLS if it's reachable beyond localhost.
+
+## 🧰 MCP Tools
+
+Full input/output schemas, resources, prompts, and error formats are in the
+[MCP API reference](specs/docs/api.md).
+
+### Read Tools (always available)
+
+- `search_emails` — Search emails by subject, sender, recipient, date range, labels, attachments, unread status
+- `get_email` — Read a specific email by ID
+- `get_thread` — Read a conversation thread
+- `list_unread` — List unread emails
+- `list_labels` — List labels (system, user, or all)
+
+### Write Tools (require `read_write` access)
+
+- `forward_email` — Forward an email (recipient allowlist enforced)
+- `archive_email` — Archive an email or thread
+- `delete_email` — Delete an email (trash by default, archive-first policy)
+- `create_draft` — Create a draft for review
+- `send_draft` — Send a reviewed draft
+- `add_label` — Add a label to an email
+
+### Intelligence — caller-first 🧠
+
+The calling agent is itself an LLM, so per-email reasoning ships as **MCP prompts**
+the agent runs on data it fetches with `get_email` — **no server-side inference,
+no added latency, no LLM key required**:
+
+- prompts: `summarize_email` · `classify_email` · `draft_reply` · `extract_action_items`
+
+Internal LLM inference is reserved for where it pays off (map-reduce over many
+emails), and registers **only when an LLM is configured**:
+
+- tools: `daily_digest` · `weekly_digest`
+- *(opt-in)* set `AGENTIC_MAIL_MCP_LLM_INTERNAL_TOOLS=true` to also expose the per-email
+  ones as server-side tools. See [ADR 0006](specs/docs/adr/0006-caller-first-intelligence.md).
+
+### Search Tools
+
+- `semantic_search` — natural-language vector search *(needs the `search` extra)*
+
+## Project Structure
+
+```
+agentic_mail_mcp/
+  Bootstrap/           CLI, Settings, Logging, Lifespan, DI Container
+  Common/              Shared domain primitives
+  Gmail/               Gmail bounded context
+  Intelligence/        LLM-powered email analysis
+  Search/              Semantic/vector search
+  Notification/        Event notifications
+  MCP/                 MCP server, tools, resources, prompts
+tests/
+  unit/                Unit tests
+  integration/         Integration tests
+  fakes/               Test doubles
+```
+
+## Railguards (security model)
+
+Writes are **denied by default**. Safety is layered so an AI agent cannot mutate
+a mailbox unless a human deliberately enables it:
+
+- **Access level** — `read_only` (default) or `read_write`. The master switch.
+  Under `read_only`, write tools are **not even registered** with the MCP server
+  (defense in depth), so the agent never sees them — not merely blocked at call
+  time.
+- **Recipient allowlist** — forwarding is restricted to configured addresses or
+  domains (`@example.com`).
+- **Rate limits** — per-action caps within a trailing 1-hour window
+  (e.g. `{"forward": 50}`).
+- **Archive-first policy** — an email must be archived before it can be
+  permanently deleted; deletes are soft (Trash) by default.
+- **Draft-first sending** — the agent creates a draft for human review;
+  `send_draft` is a separate, explicit step.
+- **Audit log** — every write is recorded (action, email id, correlation id).
+
+A railguard denial surfaces to the agent as a structured `permission_denied`
+error, never as an unhandled exception. See the
+[railguards configuration](specs/docs/configuration.md#railguards) and
+[ADR 0004](specs/docs/adr/0004-railguards-write-safety.md).
+
+## Development
+
+A `Makefile` wraps the common tasks (run `make` to list them):
+
+```bash
+make setup        # first-time: create .venv, install dev deps, .env, run migrations
+make auth         # one-time Google authorization (browser consent)
+make run          # start the server (stdio); make run-http for HTTP transport
+make test         # full test suite with coverage gates (as CI runs)
+make check        # lint (ruff) + type-check (mypy) + tests
+make format       # auto-format and fix imports
+make migrate      # apply DB migrations; make migration m="..." to autogenerate
+make build        # build the sdist + wheel and validate metadata
+```
+
+Prefer raw tools? They work too: `pytest`, `ruff check agentic_mail_mcp tests`, `mypy agentic_mail_mcp`,
+`alembic upgrade head`. All `make` targets run inside a local `.venv`.
+
+## Contributing
+
+- The architecture (DDD + vertical slicing) and key decisions are recorded as
+  [ADRs](specs/docs/adr/); read them before adding a bounded context or changing
+  a boundary.
+- Changes follow the OpenSpec workflow under `openspec/` — propose a change,
+  generate its spec deltas, implement, then archive.
+- Keep the tiered coverage floors green (≥90% on `Domain/`, ≥80% overall) and
+  ensure `ruff check` and `mypy agentic_mail_mcp/` pass before opening a PR.
+
+## 📤 Distribution
+
+The recommended distribution is a **PyPI package launched via `uvx` / `pipx`**,
+not a compiled binary. MCP clients already know how to run
+`command: "uvx"` / `"pipx run"`, so users get a one-line config with no
+virtualenv to manage, and Python-native OAuth/optional-dependency handling stays
+simple. A single-file binary would fight the OAuth browser flow and the optional
+native extras (llama.cpp, sentence-transformers, sqlite-vec) for little gain. The
+**Docker image** covers HTTP/server deployments.
+
+### Releasing (maintainers)
+
+Releases are **fully automated** by the `publish` job in
+[`.github/workflows/ci.yml`](.github/workflows/ci.yml). Publishing a GitHub
+Release is the entire flow — it builds the sdist + wheel and uploads them to
+PyPI via **Trusted Publishing (OIDC)**, so no API token is stored in the repo.
+
+**One-time PyPI setup** (per project, done once in the PyPI web UI):
+
+1. On [PyPI](https://pypi.org/manage/account/publishing/) → *Publishing* → add a
+   **pending trusted publisher** with:
+   - **PyPI Project Name**: `agentic-mail-mcp`
+   - **Owner**: your GitHub org/user · **Repository**: this repo
+   - **Workflow name**: `ci.yml` · **Environment name**: `pypi`
+2. In GitHub → *Settings → Environments* → create an environment named **`pypi`**
+   (optionally add required reviewers to gate publishes).
+
+**To cut a release:**
+
+1. Bump `project.version` in `pyproject.toml`, move the `CHANGELOG.md`
+   `[Unreleased]` section under the new version, and merge to `main`.
+2. On GitHub → *Releases → Draft a new release* → create a tag (e.g. `v0.1.0`)
+   → **Publish release**.
+3. CI runs lint / type-check / tests / audit, then the `publish` job builds and
+   uploads to PyPI. Done — `uvx agentic-mail-mcp` now resolves the new version.
+
+## License
+
+Released under the [MIT License](LICENSE).