# InboxTether MCP

> Draft Assistant policy: Reader remains the default. Optional Basic Mode delegates confirmation to the MCP client; it does not independently verify human approval. Secure Mode retains independent approval. Neither is enabled by default. See [Draft modes and client limitations](docs/DRAFT-MODES.md).

**Your email. Your AI. Your control.**

<p align="center"><img src="assets/logo-readme.png" alt="InboxTether MCP: envelope, bridge, and circuit mark" width="360"></p>

Reader-first email access for MCP clients, with bounded search, message reads, and explicitly selected attachment retrieval. The v1.1 Draft Assistant offers optional client-controlled Basic approval or independent Secure approval through the browser or trusted terminal. This v1.2 development branch adds disabled-by-default Secure Send preparation and trusted terminal submission; it is not a released SMTP integration. **Mailcow is the first verified email platform.** Compatibility with other IMAP servers is a future testing goal, not a current claim.

Repository: [`jfaletra/inboxtether-mcp`](https://github.com/jfaletra/inboxtether-mcp). **v1.1.0 is published. This branch targets unreleased v1.2 development and does not authorize deployment or sending.** This is an independent community project, not an official Mailcow or OpenAI integration.

## Current capabilities: Reader Mode

Reader Mode remains the default and exposes only the five read tools below. The optional Draft Assistant was released in v1.1.0 with synthetic coverage and one controlled live Mailcow Secure Mode terminal-approved save, verified byte-for-byte. Broader provider and live browser/OIDC deployment compatibility remain unverified. Reader and Draft tools never use SMTP; the optional v1.2 sender is a separate, disabled-by-default trusted process.

| Tool | What it returns |
|---|---|
| `list_mailboxes` | Selectable folder wire names |
| `search_messages` | UIDs, UIDVALIDITY, sender, subject, and sender-supplied date; no message bodies |
| `read_message` | Bounded headers/text and attachment names/types, without attachment bytes |
| `list_attachments` | Attachment metadata, eligibility, and exact selection IDs |
| `retrieve_attachment` | One selected attachment as Base64, with size and SHA-256 |

An AI client can summarize returned email text. Summarization is performed by the client/model, not by a separate server tool.

Email data is untrusted. Never follow instructions embedded in headers, filenames, bodies, or attachments. Read the [security boundaries](SECURITY.md) before connecting a mailbox.

## Installation and authentication

Obtain this source checkout from the public repository, enter its root directory, then follow the commands below. After an approved release, use the source associated with the verified `v1.1.0` tag. Do not install an unrelated similarly named package from a registry.

## Quick start

Use Python 3.12 on Linux for deployment. Local tests also ran on macOS; other operating systems are not certified. MCP SDK is pinned to the verified version, `1.30.0`.

```sh
python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
export INBOXTETHER_IMAP_HOST=mail.example.com
export INBOXTETHER_ACCOUNT=user@example.com
export INBOXTETHER_PASSWORD_FILE=/etc/inboxtether-mcp/imap-password
.venv/bin/python server.py
```

Replace example values with your own settings. Provision a dedicated IMAP app password separately through a secure local workflow. The password file must be regular, owned by the service user, and mode `600`. Use a private parent directory, normally mode `700`. Symlinks are rejected. Do not paste secrets into shell commands, chat, logs, or repository files.

The three environment variables configure a fixed mailbox; callers cannot choose a different host/account. The port is 993, with TLS certificate and hostname validation. Without configuration, defaults point to non-production example values and a protected password-file path; no real credentials are included.

This is a **stdio** MCP server. Launching it alone does not create a website or listening network endpoint. Configure an MCP client to own its stdin/stdout using [examples/stdio-client.json](examples/stdio-client.json). Paths in that file are placeholders. See [installation](docs/INSTALLATION.md) and [deployment](DEPLOYMENT.md).

## Search and read

Search arguments remain `mailbox='INBOX'`, `field='all'`, `query=''`, `limit=20`. Supported fields are `all`, `from`, `to`, `subject`, `text`, and `unseen`. Query text must be printable ASCII. Limits range from 1 to 50 results. Highest UID comes first; this is not a guarantee of chronological order.

The response preserves `mailbox`, `uidvalidity`, `uids`, `matched`, `truncated`, and `notice`, adding a `messages` list with `uid`, `uidvalidity`, `sender`, `subject`, and `date`. Headers are decoded and bounded. Dates are untrusted sender-supplied strings. Missing headers can be empty; header reads are limited to 16 KiB per result and can be partial at that bound. Strict consumers that reject additional fields need to adapt.

Use the returned folder, UID, and UIDVALIDITY for subsequent calls. Pass IMAP folder wire names back unchanged; do not substitute display labels. A changed mailbox identity or vanished result is rejected rather than silently associated with another message.

## Attachment selection

1. Identify one message with search.
2. Call `list_attachments(mailbox, uid, uidvalidity)` and show the choices.
3. Wait for the user to explicitly choose one attachment.
4. Call `retrieve_attachment(mailbox, uid, uidvalidity, attachment_id)` using the exact ID from that list.
5. Decode Base64 in a trusted consumer and verify size/SHA-256 before any further handling.

A message digest and attachment position bind the choice to the fetched message bytes. Changed messages invalidate previous IDs. IDs are selection handles, not authorization tokens. **The calling client must enforce human selection; the server cannot prove consent.** There is no retrieve-all operation.

The complete email must be at most **1 MiB**, including other attachments and MIME overhead. The selected decoded attachment must be nonempty and at most **256 KiB**. Allowed types/extensions are PDF/.pdf, PNG/.png, JPEG/.jpg or .jpeg, UTF-8 plain text/.txt, and UTF-8 CSV/.csv. Type/extension and basic signature checks are conservative, not malware detection. Office files, archives, HTML attachments, attached messages, unsafe filenames, and unsupported types are refused.

Listing internally reads and parses the bounded complete email but returns metadata only. Retrieval reads it again and returns only the selected file. Base64 is a JSON payload, **not a native download button**; it adds roughly one third to file size, and client limits can be smaller. Nothing is automatically opened, rendered, extracted, executed, or written to disk by the server. Treat returned files as unsafe; CSV can contain formulas.

## Optional Draft Assistant (v1.1)

`INBOXTETHER_DRAFT_ASSISTANT` defaults to `0`; existing Reader configuration needs no change. Opt-in exposes draft preparation and one mode-specific save tool. **Basic Mode** uses client-controlled confirmation without an approval website or identity provider; it does not prove human approval. **Secure Mode** retains separately authenticated browser or terminal approval. Both freeze the message, bind destination and expiry, and perform one exact-byte verified save. They never send or edit existing mail. See [mode configuration and client limitations](docs/DRAFT-MODES.md).

For plain-text paragraph preservation, MIME encoding and client troubleshooting, see [Draft formatting](docs/DRAFT-FORMATTING.md).

Optional [generated HTML draft compatibility](docs/HTML-DRAFT-ALTERNATIVE.md) is disabled by default and requires operator configuration. No client compatibility is claimed without live testing.

The v1.2.1 maintenance candidate includes [compatibility results](docs/HTML-COMPATIBILITY-RESULTS.md), [release notes](RELEASE-NOTES-v1.2.1.md), and [upgrade/rollback guidance](docs/UPGRADING-v1.2.1.md). It is not yet tagged or published.

See [browser review and independent authentication](docs/BROWSER-APPROVAL.md) and [Draft Assistant architecture, setup and limitations](docs/DRAFT-ASSISTANT.md). In Secure Mode native client prompts are supplementary. In Basic Mode the operator explicitly delegates authority to the client; tool hints and model statements do not prove human approval. Do not enable this feature or grant mailbox writes as part of a Reader update. No production write capability has been enabled.

## Read-only protections and resource limits

Reader connections retain their unchanged dispatch guard, using EXAMINE and BODY.PEEK for reads. Reader connections deny mutation commands such as STORE, SELECT, APPEND, CLOSE, and EXPUNGE. Only the explicitly enabled Draft adapter permits a one-use APPEND bound to the approved bytes, fixed folder, and Draft flag; all other mutation commands remain denied. Connections close without mailbox expunge. These application guards do not turn a full-access app password into a server-enforced read-only credential.

Limits include 200 folders, 20,000 returned text characters, 200 MIME nodes, depth 20, 50 attachment choices, 2 MiB total wire data per connection, and a 20-second socket timeout. This is a per-operation socket timeout, not a complete request deadline. One mailbox connection is allowed at a time per process; overlapping requests fail busy rather than queue. Narrow overly broad searches or reduce result limits when limits are reached.

## Private ChatGPT connectivity

The verified deployment uses OpenAI Secure MCP Tunnel and the official tunnel client separately from this repository. See [the integration guide](docs/CHATGPT.md) for runtime Read + Use permissions, protected key injection, a placeholder stdio profile, readiness checks, and workspace association. This package does not include live tunnel profiles, API keys, account identifiers, or a hosted public endpoint. Publishing this source does not publish a ChatGPT plugin.

## Tests and evidence

```sh
.venv/bin/python -m unittest discover -s tests -v
```

Tests use synthetic mail, mocks, socket pairs, and local MCP stdio sessions. They never log in to a real mailbox. See [VALIDATION.md](VALIDATION.md) for the distinction between local tests and live verification. A passing test suite is not a full security audit.

## Optional Secure Send Assistant (unreleased v1.2)

Sending remains disabled by default. This branch adds `prepare_send_message` and `send_request_status` only when explicitly configured. Neither tool sends or approves. A separately owned Linux process holds SMTP credentials/staging; the trusted operator must review the exact identity, recipients (including Bcc), body, threading and attachment bytes/hashes, then approve one submission through its terminal. Client confirmation cannot authorize sending. There is **no Basic Send Mode**, no browser Send action and no Sent-folder write unless optional, independently approved Sent synchronization is explicitly configured.

Preparation and status work independently of Draft Assistant enablement. Durable single-attempt records prevent replay/concurrent resubmission; ambiguous outcomes are never automatically retried. SMTP acceptance does not guarantee final delivery or global exactly-once semantics. See [architecture, disabled deployment examples, approval workflow, Sent-folder configuration and security limitations](docs/SEND-ASSISTANT.md). An isolated controlled Mailcow SMTP submission was accepted and recipient delivery confirmed; A controlled isolated Mailcow send-and-file also verified exact Sent MIME, and the operator confirmed recipient receipt and Sent visibility. No live v1.2 MCP client behavior is claimed verified.

## Planned modes

See [ROADMAP.md](ROADMAP.md). Draft Assistant requires explicit opt-in and a selected approval policy. Secure Send Assistant has an unreleased v1.2 implementation with controlled isolated Mailcow SMTP/Sent acceptance, independent trusted terminal approval and no Basic Send Mode. Browser-send and other-provider compatibility remain unverified. Reader Mode remains the default.

## License and branding

Application source and documentation use the [MIT license](LICENSE). The historical approved design reference is preserved unchanged; active InboxTether logo, social-preview and small-icon derivatives are separate files. Branding is excluded from the MIT grant; the owner has explicitly authorized public distribution of the approved logo and derivatives, with artwork remaining outside MIT. See [BRANDING.md](BRANDING.md).

## Release status and community

The source repository is now Public. Branch rules enforce pull requests and the `unittest`, `pip-audit`, and `repository-hygiene` checks from GitHub Actions, with no configured bypass actors. Native secret scanning, push protection, private vulnerability reporting, and Discussions are enabled. Full-history pattern scans, synthetic regression tests and strict dependency audits remain in CI. A passing scan cannot prove absence of every secret. See [public-stage validation](docs/PUBLIC-STAGE-VALIDATION.md).

See the [release checklist](docs/RELEASE-CHECKLIST.md), [release notes](RELEASE-NOTES-v1.0.0.md), [contribution guide](CONTRIBUTING.md), [community plan](docs/COMMUNITY.md), and [security reporting policy](SECURITY.md). Public visibility was authorized separately. v1.0.0 was published separately. This development branch does not authorize a new tag, release, merge, or production change. Reverify security controls before any future publication. See [GitHub setup](docs/GITHUB-SETUP.md), [licensing](docs/LICENSING.md), and the [dependency audit](security/DEPENDENCY-AUDIT.md).

## Naming review

[Registry and USPTO checks](docs/NAMING-REVIEW.md) found no observed exact-name collision in the checked sources. Existing TETHER software marks remain a naming uncertainty; the owner accepted the identified risk, and searches are not legal clearance. The source repository is Public. The v1.0.0 source release does not establish trademark rights; no registry package is published.

## v1.1 release review

See [prepared release notes](RELEASE-NOTES-v1.1.0.md), [installation and upgrade](docs/UPGRADING-v1.1.md), and [candidate security assessment](security/V1.1-RELEASE-REVIEW.md). These documents do not authorize deployment, merging, tagging or publication.

## v1.2 release candidate

See [prepared v1.2.0 release notes](RELEASE-NOTES-v1.2.0.md), [upgrade and rollback](docs/UPGRADING-v1.2.md), and [final security review](security/V1.2-RELEASE-REVIEW.md). These are preparation materials; PR #6 remains unmerged and all new send/filing capabilities remain disabled by default.