agent-jmap-mcp 0.2.0__tar.gz

agent_jmap_mcp-0.2.0/.env.example

@@ -0,0 +1,11 @@
+# JMAP Server & Authentication Configuration Example
+# Copy this file to .env and configure with your credentials
+
+# Fastmail Session URL (default for Fastmail users)
+JMAP_SESSION_URL=https://api.fastmail.com/.well-known/jmap
+
+# JMAP Bearer API Token (generate in Fastmail / Stalwart / Cyrus settings)
+JMAP_API_TOKEN=fmu1-xxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Optional: Specific Primary Account ID (auto-discovered if omitted)
+# JMAP_ACCOUNT_ID=u12345678

agent_jmap_mcp-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install .[dev]
+
+    - name: Lint with Ruff
+      run: |
+        ruff check src tests
+
+    - name: Test with Pytest
+      run: |
+        pytest -v --cov=agent_jmap_mcp

agent_jmap_mcp-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  pypi-publish:
+    name: Build and publish Python 🐍 distributions 📦 to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # Mandatory for PyPI Trusted Publishing (OIDC)
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agent_jmap_mcp-0.2.0/.gitignore

@@ -0,0 +1,80 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# Environments
+.env
+.env.*
+!.env.example
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Secrets & Credentials
+*credential*.json
+*token*.json
+*secret*.json
+*.pem
+*.key
+jmap-credentials.json
+
+# IDE & Editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store

agent_jmap_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Maddox
+
+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.

agent_jmap_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.5
+Name: agent-jmap-mcp
+Version: 0.2.0
+Summary: Modern, stateless JMAP email client and Model Context Protocol (MCP) server for AI agents.
+Project-URL: Homepage, https://github.com/ericmaddox/agent-jmap-mcp
+Project-URL: Repository, https://github.com/ericmaddox/agent-jmap-mcp.git
+Project-URL: Issues, https://github.com/ericmaddox/agent-jmap-mcp/issues
+Author-email: Eric Maddox <eric.maddox@outlook.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude,cursor,email,fastmail,hermes-agent,jmap,mcp,mcp-server,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Requires-Dist: html2text<2025.0.0,>=2024.2.26
+Requires-Dist: httpx<1.0.0,>=0.28.0
+Requires-Dist: mcp<2.0.0,>=1.3.0
+Requires-Dist: pydantic<3.0.0,>=2.10.0
+Requires-Dist: rich<14.0.0,>=13.9.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agent-jmap-mcp
+
+[![CI](https://github.com/ericmaddox/agent-jmap-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ericmaddox/agent-jmap-mcp/actions/workflows/ci.yml)
+[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP Protocol](https://img.shields.io/badge/MCP-1.3.0%2B-purple.svg)](https://modelcontextprotocol.io)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+A stateless, production-grade JSON Meta Application Protocol (JMAP) client and Model Context Protocol (MCP) server for AI agents, automation pipelines, and developer workflows.
+
+Compliant with [RFC 8620](https://datatracker.ietf.org/doc/html/rfc8620) (JMAP Core) and [RFC 8621](https://datatracker.ietf.org/doc/html/rfc8621) (JMAP Mail), `agent-jmap-mcp` allows language models (e.g. Claude, Hermes Agent, GPT-4, Cursor) to inspect mailboxes, search and retrieve messages, navigate conversation threads, download attachments, perform automated inbox triage, and compose/send emails atomically over pure HTTP.
+
+---
+
+## Architecture
+
+```mermaid
+flowchart TD
+    subgraph Host["AI Agent / Host Application"]
+        Agent["AI Agent / LLM Client"]
+    end
+
+    subgraph MCP["agent-jmap-mcp Server"]
+        Server["FastMCP stdio Engine"]
+        Tools["Tools Interface<br/>(list, search, get, thread, download, send, triage)"]
+        TriageEng["Rule-Based Triage Engine"]
+        Converter["HTML-to-Markdown Engine"]
+        Client["RFC 8620/8621 JMAP Client"]
+    end
+
+    subgraph Upstream["JMAP Email Server"]
+        JMAPEndpoint["JMAP API Endpoint<br/>(Fastmail / Stalwart / Cyrus)"]
+    end
+
+    Agent <-->|"JSON-RPC / stdio"| Server
+    Server --> Tools
+    Tools --> TriageEng
+    Tools --> Converter
+    Tools --> Client
+    Client <-->|"Stateless HTTPS (JSON Batches / Binary Streams)"| JMAPEndpoint
+```
+
+---
+
+## Key Capabilities
+
+- **Stateless HTTP Architecture**: Operates over standard HTTPS with bearer token authentication. Avoids persistent IMAP socket overhead and connection timeout state.
+- **Atomic Operations**: Executes message creation and dispatch in a single atomic transaction combining `Email/set` and `EmailSubmission/set`.
+- **Conversation Threading (`Thread/get`)**: Full RFC 8621 conversation thread retrieval aggregating multi-turn email dialogues chronologically.
+- **Binary Attachment Downloads**: High-speed streaming downloads for PDF, image, and data attachments via session `downloadUrl`.
+- **Rich HTML-to-Markdown Extraction**: Automated markdown conversion for HTML-only newsletters and styled emails.
+- **Session Auto-Discovery**: Automatically queries `/.well-known/jmap` to discover API endpoints, upload/download URLs, and primary account IDs.
+- **Zero-Footprint Model Context**: Optimized JSON payloads structured specifically for minimal LLM context window consumption.
+- **Automated Inbox Triage**: Built-in heuristic classification for inbox sorting (Urgent, Action Required, Personal, Notifications, Newsletters).
+- **Universal MCP Compatibility**: Plugs directly into Claude Desktop, Hermes Agent, Cursor, Zed, and any MCP-compliant environment.
+
+---
+
+## Installation
+
+### Using uv (Recommended)
+
+```bash
+uv tool install agent-jmap-mcp
+```
+
+### Using pipx or pip
+
+```bash
+pipx install agent-jmap-mcp
+# or
+pip install agent-jmap-mcp
+```
+
+---
+
+## Configuration
+
+Set the required environment variables:
+
+| Variable | Description | Example / Default |
+| :--- | :--- | :--- |
+| `JMAP_SESSION_URL` | JMAP Session discovery URL | `https://api.fastmail.com/.well-known/jmap` |
+| `JMAP_API_TOKEN` | Bearer API token | `fmu1-...` |
+| `JMAP_ACCOUNT_ID` | Optional target account ID | Auto-discovered from session if omitted |
+
+A `.env.example` template is provided in the repository.
+
+---
+
+## MCP Server Integration
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "jmap": {
+      "command": "uvx",
+      "args": ["agent-jmap-mcp"],
+      "env": {
+        "JMAP_SESSION_URL": "https://api.fastmail.com/.well-known/jmap",
+        "JMAP_API_TOKEN": "YOUR_JMAP_API_TOKEN"
+      }
+    }
+  }
+}
+```
+
+### Hermes Agent
+
+Add to `~/.hermes/config.yaml`:
+
+```yaml
+mcp_servers:
+  jmap:
+    command: "uvx"
+    args: ["agent-jmap-mcp"]
+    env:
+      JMAP_SESSION_URL: "https://api.fastmail.com/.well-known/jmap"
+      JMAP_API_TOKEN: "${JMAP_API_TOKEN}"
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "jmap": {
+      "command": "uvx",
+      "args": ["agent-jmap-mcp"],
+      "env": {
+        "JMAP_SESSION_URL": "https://api.fastmail.com/.well-known/jmap",
+        "JMAP_API_TOKEN": "YOUR_JMAP_API_TOKEN"
+      }
+    }
+  }
+}
+```
+
+### Zed Editor
+
+Add to `settings.json`:
+
+```json
+{
+  "context_servers": {
+    "jmap": {
+      "command": {
+        "path": "uvx",
+        "args": ["agent-jmap-mcp"],
+        "env": {
+          "JMAP_SESSION_URL": "https://api.fastmail.com/.well-known/jmap",
+          "JMAP_API_TOKEN": "YOUR_JMAP_API_TOKEN"
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Available MCP Tools
+
+| Tool Name | Parameters | Description |
+| :--- | :--- | :--- |
+| `jmap_list_mailboxes` | None | Returns metadata for all mailboxes (IDs, names, roles, unread/total counts). |
+| `jmap_list_emails` | `mailbox`, `limit`, `unread_only`, `query`, `from_address`, `subject_contains` | Queries email headers with filtering, search conditions, and sorting. |
+| `jmap_get_email` | `email_id` (str), `mark_as_read` (bool) | Fetches full email body (converted to markdown if HTML), headers, and attachments. |
+| `jmap_get_thread` | `thread_id` (str) | Fetches full multi-message conversation thread chronologically. |
+| `jmap_download_attachment` | `blob_id` (str), `filename` (str), `save_directory` (str) | Downloads binary attachment from JMAP server and saves to disk. |
+| `jmap_send_email` | `to` (list), `subject` (str), `body` (str), `from_address` (str), `cc` (list), `bcc` (list), `draft_only` (bool) | Atomically creates and submits an outgoing message (or saves to drafts). |
+| `jmap_triage_inbox` | `mailbox` (str), `limit` (int), `unread_only` (bool) | Analyzes recent messages and returns categorization, priorities, and action items. |
+
+---
+
+## Command Line Interface (CLI)
+
+The package includes a standalone CLI tool `agent-jmap`:
+
+```bash
+# Start MCP server over stdio
+agent-jmap serve
+
+# List available mailboxes
+agent-jmap mailboxes
+
+# List recent emails
+agent-jmap list --limit 10
+agent-jmap list --unread --query "invoice"
+
+# View specific email
+agent-jmap get <email-id>
+
+# View entire conversation thread
+agent-jmap thread <thread-id>
+
+# Download binary attachment
+agent-jmap download <blob-id> --name report.pdf --output ./downloads
+
+# Run inbox triage
+agent-jmap triage --limit 20
+
+# Send email from command line
+agent-jmap send --to user@example.com --subject "Status Update" --body "Processing completed."
+```
+
+---
+
+## Development and Testing
+
+### Setup Environment
+
+```bash
+git clone https://github.com/ericmaddox/agent-jmap-mcp.git
+cd agent-jmap-mcp
+uv sync --extra dev
+```
+
+### Running Test Suite
+
+```bash
+uv run pytest -v
+```
+
+### Code Formatting and Linting
+
+```bash
+uv run ruff check .
+uv run ruff format .
+```
+
+### Building Distribution Packages
+
+```bash
+uv build
+```
+
+---
+
+## RFC Compliance
+
+- [RFC 8620: The JSON Meta Application Protocol (JMAP)](https://datatracker.ietf.org/doc/html/rfc8620)
+- [RFC 8621: The JSON Meta Application Protocol (JMAP) for Mail](https://datatracker.ietf.org/doc/html/rfc8621)
+- [RFC 5322: Internet Message Format](https://datatracker.ietf.org/doc/html/rfc5322)
+
+---
+
+## License
+
+MIT License. Copyright (c) 2026 Eric Maddox. See [LICENSE](LICENSE) for details.