mailflat-mcp 0.1.0__tar.gz

mailflat_mcp-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+dist/
+build/
+*.egg-info/
+.venv/
+__pycache__/
+.pytest_cache/

mailflat_mcp-0.1.0/LICENSE

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

mailflat_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: mailflat-mcp
+Version: 0.1.0
+Summary: MailFlat MCP server — disposable inbox tools (create, wait_for_otp, send, ...) for Claude Desktop, Cursor, and any MCP client.
+Project-URL: Homepage, https://mailflat.net
+Project-URL: Documentation, https://mailflat.net/docs
+Project-URL: Source, https://github.com/onderyentar/mailflat
+Author-email: MailFlat <support@mailflat.net>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude,cursor,disposable-email,email,mcp,model-context-protocol,otp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.10
+Requires-Dist: mailflat>=0.1.0
+Requires-Dist: mcp>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MailFlat — MCP server
+
+Native [Model Context Protocol](https://modelcontextprotocol.io) server for
+[MailFlat](https://mailflat.net). Gives Claude Desktop, Cursor, or any MCP client
+**disposable inbox tooling** — create inboxes, wait for OTP codes, send DKIM-signed mail,
+and clean up. Built on the [`mailflat`](https://pypi.org/project/mailflat/) Python SDK.
+
+## Run
+
+```bash
+# zero-install, isolated (recommended)
+MAILFLAT_API_KEY=mf_live_… uvx mailflat-mcp
+
+# or install it
+pipx install mailflat-mcp
+MAILFLAT_API_KEY=mf_live_… mailflat-mcp
+```
+
+## Claude Desktop / Cursor config
+
+Add to `claude_desktop_config.json` (or your client's MCP config):
+
+```json
+{
+  "mcpServers": {
+    "mailflat": {
+      "command": "uvx",
+      "args": ["mailflat-mcp"],
+      "env": { "MAILFLAT_API_KEY": "mf_live_..." }
+    }
+  }
+}
+```
+
+Get your API key from the [MailFlat dashboard](https://mailflat.net) → Agents.
+
+## Tools (6)
+
+| Tool | What it does |
+|---|---|
+| `create_inbox(prefix?, label?, retention_hours?)` | Open a disposable inbox; `retention_hours` capped by your plan |
+| `list_inboxes()` | All inboxes this key can see |
+| `read_messages(address)` | Read every message in an inbox |
+| `wait_for_otp(address, timeout=30)` | Poll until an OTP arrives, then return it |
+| `send_email(address, to, subject?, body?, html?)` | Send a DKIM-signed mail from the inbox |
+| `delete_inbox(address)` | Delete the inbox and its messages |
+
+## Configuration
+
+- `MAILFLAT_API_KEY` — your account API key (required).
+- `MAILFLAT_API_URL` — override the API base (default `https://mailflat.net`; for self-hosted / BYOD).
+
+## License
+
+MIT

mailflat_mcp-0.1.0/README.md

@@ -0,0 +1,55 @@
+# MailFlat — MCP server
+
+Native [Model Context Protocol](https://modelcontextprotocol.io) server for
+[MailFlat](https://mailflat.net). Gives Claude Desktop, Cursor, or any MCP client
+**disposable inbox tooling** — create inboxes, wait for OTP codes, send DKIM-signed mail,
+and clean up. Built on the [`mailflat`](https://pypi.org/project/mailflat/) Python SDK.
+
+## Run
+
+```bash
+# zero-install, isolated (recommended)
+MAILFLAT_API_KEY=mf_live_… uvx mailflat-mcp
+
+# or install it
+pipx install mailflat-mcp
+MAILFLAT_API_KEY=mf_live_… mailflat-mcp
+```
+
+## Claude Desktop / Cursor config
+
+Add to `claude_desktop_config.json` (or your client's MCP config):
+
+```json
+{
+  "mcpServers": {
+    "mailflat": {
+      "command": "uvx",
+      "args": ["mailflat-mcp"],
+      "env": { "MAILFLAT_API_KEY": "mf_live_..." }
+    }
+  }
+}
+```
+
+Get your API key from the [MailFlat dashboard](https://mailflat.net) → Agents.
+
+## Tools (6)
+
+| Tool | What it does |
+|---|---|
+| `create_inbox(prefix?, label?, retention_hours?)` | Open a disposable inbox; `retention_hours` capped by your plan |
+| `list_inboxes()` | All inboxes this key can see |
+| `read_messages(address)` | Read every message in an inbox |
+| `wait_for_otp(address, timeout=30)` | Poll until an OTP arrives, then return it |
+| `send_email(address, to, subject?, body?, html?)` | Send a DKIM-signed mail from the inbox |
+| `delete_inbox(address)` | Delete the inbox and its messages |
+
+## Configuration
+
+- `MAILFLAT_API_KEY` — your account API key (required).
+- `MAILFLAT_API_URL` — override the API base (default `https://mailflat.net`; for self-hosted / BYOD).
+
+## License
+
+MIT

mailflat_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mailflat-mcp"
+version = "0.1.0"
+description = "MailFlat MCP server — disposable inbox tools (create, wait_for_otp, send, ...) for Claude Desktop, Cursor, and any MCP client."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "MailFlat", email = "support@mailflat.net" }]
+keywords = ["mcp", "model-context-protocol", "email", "disposable-email", "otp", "ai-agents", "claude", "cursor"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Communications :: Email",
+]
+dependencies = [
+    "mailflat>=0.1.0",
+    "mcp>=1.2",
+]
+
+[project.scripts]
+mailflat-mcp = "mailflat_mcp.server:main"
+
+[project.urls]
+Homepage = "https://mailflat.net"
+Documentation = "https://mailflat.net/docs"
+Source = "https://github.com/onderyentar/mailflat"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mailflat_mcp"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/mailflat_mcp", "README.md", "LICENSE"]

mailflat_mcp-0.1.0/src/mailflat_mcp/__init__.py

@@ -0,0 +1,18 @@
+"""MailFlat MCP server paketi — `mailflat` SDK üstünde MCP tool seti.
+
+`uvx mailflat-mcp` ile çalışır; Claude Desktop / Cursor / agent framework'lerine
+disposable inbox araçları açar.
+
+Connected to:
+  - imports from: mailflat_mcp.server
+  - imported by:  console script `mailflat-mcp`, MCP client'lar
+
+Key exports:
+  - `mcp` — FastMCP instance
+  - `main()` — stdio server giriş noktası
+"""
+from .server import main, mcp
+
+__version__ = "0.1.0"
+
+__all__ = ["mcp", "main", "__version__"]

mailflat_mcp-0.1.0/src/mailflat_mcp/__main__.py

@@ -0,0 +1,9 @@
+"""`python -m mailflat_mcp` giriş noktası → stdio MCP server.
+
+Connected to:
+  - imports from: mailflat_mcp.server
+"""
+from .server import main
+
+if __name__ == "__main__":
+    main()

mailflat_mcp-0.1.0/src/mailflat_mcp/server.py

@@ -0,0 +1,118 @@
+"""MailFlat MCP server — GPT/Claude/Cursor/LangChain için 6 araçlık tool seti.
+
+`mailflat` Python SDK'sının üstüne ince bir MCP kabuğu; HTTP/iş mantığı SDK'da (DRY).
+Auth: `MAILFLAT_API_KEY` env (dashboard'dan alınan `mf_live_...`).
+
+Çalıştırma:
+    uvx mailflat-mcp                 # PyPI'den, izolasyonlu
+    MAILFLAT_API_KEY=mf_live_... uvx mailflat-mcp
+
+Connected to:
+  - depends on: mailflat (SDK), mcp (FastMCP)
+  - used by:    Claude Desktop / Cursor / herhangi bir MCP client
+
+Key exports (MCP tools):
+  - create_inbox(prefix?, label?, retention_hours?)
+  - list_inboxes()
+  - read_messages(address)
+  - wait_for_otp(address, timeout=30)
+  - send_email(address, to, subject?, body?, html?)
+  - delete_inbox(address)
+"""
+import os
+
+from mcp.server.fastmcp import FastMCP
+
+from mailflat import EncryptedInboxError, MailFlat, MailFlatError, OTPTimeoutError
+
+mcp = FastMCP("mailflat")
+
+
+def _client() -> MailFlat:
+    """SDK client (MAILFLAT_API_KEY ile). Testlerde monkeypatch edilir."""
+    return MailFlat(
+        api_key=os.environ.get("MAILFLAT_API_KEY") or "",
+        base_url=os.environ.get("MAILFLAT_API_URL", "https://mailflat.net"),
+    )
+
+
+@mcp.tool()
+def create_inbox(prefix: str = "", label: str = "", retention_hours: int = 0) -> dict:
+    """Create a real disposable email inbox. Returns the inbox address.
+    `retention_hours` is optional (0 = your plan's max); requests above your plan are capped."""
+    try:
+        with _client() as c:
+            inbox = c.create(
+                prefix=prefix or None,
+                label=label or None,
+                retention_hours=retention_hours if retention_hours and retention_hours > 0 else None,
+            )
+            return inbox.raw
+    except MailFlatError as e:
+        return {"error": str(e)}
+
+
+@mcp.tool()
+def list_inboxes() -> dict:
+    """List all inboxes available to this API key."""
+    try:
+        with _client() as c:
+            return {"ok": True, "inboxes": [i.raw for i in c.list()]}
+    except MailFlatError as e:
+        return {"error": str(e)}
+
+
+@mcp.tool()
+def read_messages(address: str) -> dict:
+    """Read all messages in the given inbox address."""
+    try:
+        with _client() as c:
+            return {"ok": True, "emails": [m.raw for m in c.inbox(address).messages()]}
+    except MailFlatError as e:
+        return {"error": str(e)}
+
+
+@mcp.tool()
+def wait_for_otp(address: str, timeout: int = 30) -> dict:
+    """Poll the inbox until an OTP code arrives (or timeout). Returns {otp_code, email}."""
+    try:
+        with _client() as c:
+            inbox = c.inbox(address)
+            otp = inbox.wait_for_otp(timeout=timeout)
+            latest = inbox.latest()
+            return {"otp_code": otp, "email": latest.raw if latest else None}
+    except OTPTimeoutError:
+        return {"otp_code": None, "error": "timeout"}
+    except EncryptedInboxError as e:
+        return {"otp_code": None, "encrypted": True, "error": str(e)}
+    except MailFlatError as e:
+        return {"otp_code": None, "error": str(e)}
+
+
+@mcp.tool()
+def send_email(address: str, to: str, subject: str = "", body: str = "", html: str = "") -> dict:
+    """Send an email FROM the given inbox address (DKIM-signed via MailFlat's MTA).
+    Use for replies or outbound automation. `html` is optional."""
+    try:
+        with _client() as c:
+            return c.inbox(address).send(to, subject=subject, body=body, html=html or None)
+    except MailFlatError as e:
+        return {"error": str(e)}
+
+
+@mcp.tool()
+def delete_inbox(address: str) -> dict:
+    """Delete an inbox and all its messages by address. Irreversible."""
+    try:
+        with _client() as c:
+            return c.inbox(address).delete()
+    except MailFlatError as e:
+        return {"error": str(e)}
+
+
+def main():
+    mcp.run()  # stdio transport (MCP client'lar buna bağlanır)
+
+
+if __name__ == "__main__":
+    main()