Metadata-Version: 2.4
Name: emancipation
Version: 0.1.0
Summary: MCP server that connects AI agents to IMAP
Author-email: Flavio Veloso Soares <flaviovs@magnux.com>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-Expression: MIT
License-File: LICENSE.txt
Requires-Dist: mcp>=1.9.0
Requires-Dist: mypy ; extra == "dev"
Requires-Dist: ruff ; extra == "dev"
Requires-Dist: vulture ; extra == "dev"
Provides-Extra: dev

# Emancipation MCP Server

`emancipation` is a MCP server that lets AI agents read IMAP mailboxes
and send plain-text emails over SMTP.

## Features

- No external dependencies besides the MCP SDK
- MCP server over stdio
- IMAP mailbox listing, search, message listing, and message retrieval
- SMTP plain-text email sending with optional `cc`, `bcc`, and `reply_to`
- TLS/SSL options for both IMAP and SMTP transports
- Environment-variable configuration for runtime credentials and behavior

---

## Requirements

- Python 3.11+
- IMAP server credentials
- SMTP server credentials

---

## Installation

```bash
pip install emancipation
```

---

## Running the server

Transport is a positional argument and defaults to `stdio`.

```bash
emancipation
```

This starts the MCP server over stdio (same as `emancipation stdio`).

For SSE transport:

```bash
emancipation sse --host 127.0.0.1 --port 8143
```

For streamable HTTP transport:

```bash
emancipation streamable-http --host 127.0.0.1 --port 8143
```

Network transports (`sse`, `streamable-http`) support:

- `--host` (optional, default: `127.0.0.1`)
- `--port` (optional, default: `8143`)

Equivalent invocation patterns:

```bash
emancipation [stdio]
emancipation sse [--host HOST] [--port PORT]
emancipation streamable-http [--host HOST] [--port PORT]
```


You can register multiple entries with different credentials and
`SERVER_NAME` values.

---

## Agent Configuration

### Example

Register the server in your MCP client configuration:

```json
{
  "mcpServers": {
    "emancipation": {
      "command": "emancipation",
      "env": {
        "SERVER_NAME": "mail-primary",
        "IMAP_HOST": "imap.example.com",
        "IMAP_PORT": "993",
        "IMAP_TIMEOUT": "15",
        "IMAP_USERNAME": "agent@example.com",
        "IMAP_PASSWORD": "your-imap-password",
        "IMAP_MAILBOX": "INBOX",
        "IMAP_ENABLED": "true",
        "SMTP_HOST": "smtp.example.com",
        "SMTP_PORT": "587",
        "SMTP_USERNAME": "agent@example.com",
        "SMTP_PASSWORD": "your-smtp-password",
        "SMTP_FROM": "agent@example.com",
        "SMTP_ENABLED": "true",
        "SMTP_TIMEOUT": "15",
        "SMTP_USE_TLS": "true",
        "SMTP_USE_SSL": "false"
      }
    }
  }
}
```

### Environment Variables

Set these environment variables to configure the server:

Global configuration:
- `SERVER_NAME` (optional, default: `emancipation`)
- `SERVER_LOG_LEVEL` (optional, default: `info`; accepted values: `debug`,
  `info`, `warning`, `error`, `critical`)

For IMAP email access:
- `IMAP_ENABLED` (optional, default: `true`; set to `false`, `no`, or `0` to
  disable IMAP tool export)
- `IMAP_HOST` (required)
- `IMAP_PORT` (optional, default: `993`)
- `IMAP_TIMEOUT` (optional, timeout in seconds; must be greater than `0`)
- `IMAP_SESSION_TTL` (optional, default: `120`; reuse IMAP connections for
  this many seconds; set to `0` to disable reuse and reconnect per call)
- `IMAP_USERNAME` (required)
- `IMAP_PASSWORD` (required)
- `IMAP_MAILBOX` (optional, default: `INBOX`)

For sending emails:
- `SMTP_ENABLED` (optional, default: `true`; set to `false`, `no`, or `0` to
  disable SMTP tool export)
- `SMTP_HOST` (required)
- `SMTP_PORT` (optional, default: `587`; `465` when SSL is enabled)
- `SMTP_TIMEOUT` (optional, timeout in seconds; must be greater than `0`)
- `SMTP_USERNAME` (required)
- `SMTP_PASSWORD` (required)
- `SMTP_FROM` (required)
- `SMTP_USE_TLS` (optional, default: `true`)
- `SMTP_USE_SSL` (optional, default: `false`)

`SMTP_USE_TLS` and `SMTP_USE_SSL` cannot both be `true`.
`IMAP_ENABLED` and `SMTP_ENABLED` accept only `true`, `yes`, `1`, `false`,
`no`, and `0`; any other value raises a startup error.

### About `SERVER_NAME`

`SERVER_NAME` sets the MCP server identity exposed to the client/LLM.

Common use cases:

- Run multiple `emancipation` instances at once, each with a different
  IMAP/SMTP account (for example: `mail-primary`, `mail-finance`,
  `mail-support`).
- Make tool provenance clearer in multi-server setups, so logs and MCP UIs
  show which server handled each tool call.
- Separate environments (for example: `mail-staging` vs `mail-production`)
  while reusing the same binary and tool set.

If omitted, the server name defaults to `emancipation`.

---

## Available MCP tools

- `emcp_list_mailboxes`: list available mailboxes
- `emcp_search_messages`: search message IDs (`query`, `limit`, `offset`)
- `emcp_list_messages`: list message metadata (`id`, `subject`, `sender`,
  `date`) using query and paging
- `emcp_get_message`: fetch one message by ID, with optional plain-text body
- `emcp_send_email`: send a plain-text email (`to`, `subject`, `text_body`)
  with optional `cc`, `bcc`, and `reply_to`
- `emcp_delete_message`: mark one message as deleted (`message_id`, optional
  `mailbox`, optional `expunge`)
- `emcp_move_message`: move one message to another mailbox (`message_id`,
  `destination_mailbox`, optional `source_mailbox`, optional `expunge`)

