email-thread-mcp 0.2.0__tar.gz

email_thread_mcp-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+# Real customer emails and their ground truth: local only, never pushed.
+tests/fixtures/
+tests/test_client_threads.py
+.DS_Store

email_thread_mcp-0.2.0/LICENSE

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

email_thread_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.5
+Name: email-thread-mcp
+Version: 0.2.0
+Summary: MCP server for the AR email agent: parses an inbound email thread into the thread contract and validates the agent's output envelope.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: dateparser<2,>=1.2
+Requires-Dist: mcp<3,>=2.3
+Description-Content-Type: text/markdown
+
+# email-thread-mcp
+
+MCP server (stdio) with two deterministic tools for an accounts-receivable (AR) email agent:
+no LLM inside, no network access, no credentials.
+
+| Tool | Role in the agent | Output contract |
+|---|---|---|
+| `parse_email_thread(body, ar_mailboxes?)` | first step: request preprocessing. Splits the raw email body (Outlook/Gmail/Apple HTML or plain text) into the latest message, its signer and greeting, and the quoted history (oldest first) | [`contracts/thread.schema.json`](contracts/thread.schema.json) |
+| `validate_output(output, categories, thread?)` | last step: deterministic checks of the final envelope. Corrects only unambiguous problems (category case/punctuation, duplicates, invoice-number noise, human-review flag); reports the rest | [`contracts/validation.schema.json`](contracts/validation.schema.json) |
+
+## Use
+
+Any MCP client that starts stdio servers can run it with `uvx`:
+
+```json
+{
+  "mcpServers": {
+    "email-thread-mcp": {
+      "command": "uvx",
+      "args": ["email-thread-mcp@0.2.0"]
+    }
+  }
+}
+```
+
+Pin a version: a client that keeps the server running may otherwise serve a stale cached build.
+
+Each tool returns one JSON object. Structured arguments (`ar_mailboxes`, `categories`, `output`,
+`thread`) may be passed as values or as text: clients that render arguments through a template
+engine first can send JSON or a Python-style repr, and both are accepted.
+
+A typical agent calls `parse_email_thread` first, as preprocessing, and uses `latest_message`,
+`reply_to_name` and `thread_context` in later steps; it calls `validate_output` last, on its final
+envelope. If parsing fails, falling back to the plain-text body before the first quote marker keeps
+the agent working.
+
+## Language support
+
+Inbound mail may be in any language, so the parser treats its three kinds of miss differently:
+
+| Miss | Effect | How it is avoided |
+|---|---|---|
+| quote boundary | old history read as the new message | found by structure in any language: the mail client's HTML quote marker (Outlook `divRplyFwdMsg`, Gmail `gmail_quote`, Apple/Thunderbird `blockquote type="cite"`), or a `label: value` block that starts with an address and holds a date with a time |
+| greeting / signer name | `reply_to_name` is null, the draft greets neutrally | per-language words in `src/email_thread_mcp/vocab.py` |
+| sent date | `sent_at` is null (thread order comes from position, not dates) | [`dateparser`](https://pypi.org/project/dateparser/), absolute dates only |
+
+`vocab.py` covers EN, DE, FR, NL, IT, ES, PT, PL, CS, SV, DA, NO, FI. Only EN is `verified` against
+real threads; the others are built from Outlook's localized reply headers. A language outside the
+list still splits, and `parse_info.warnings` names what was not understood, e.g.
+`quoted message 1: header labels not recognised: Kimden, Gönderildi, Kime, Konu`. Search traces
+for those warnings to see which language to add next.
+
+To add or verify a language: add its entry to `vocab.py` and a case to `tests/test_languages.py`.
+Once a real thread in it (anonymised as below) parses correctly, add it as a fixture and set `verified`.
+
+## Untrusted input
+
+The body is written by the customer, and anyone can send one. The parser:
+
+- drops text a reader cannot see (CSS `display:none`, `visibility:hidden`, `font-size:0`, `opacity:0`,
+  `mso-hide:all`, the `hidden` attribute) and zero-width, bidirectional and control characters, and
+  reports both in `parse_info.warnings`;
+- bounds its own cost: the body is cut at 2M raw / 300k text characters, and dates beyond 50 parser
+  calls per email stay null.
+
+It does not make the content trustworthy. The quoted history in particular is plain text the customer
+can edit, including a fake message "from" the AR team (role `recipient`). Prompts must treat
+`latest_message` and `thread_context` as data, never as instructions.
+
+## Release
+
+1. Bump `version` in `pyproject.toml`, then `uv run pytest`.
+2. Commit, tag `v<version>`, push both. Never move or reuse a tag or a version.
+3. `uv build`, check that the sdist holds only `src/`, `README.md` and `pyproject.toml`, then
+   `uv publish`.
+4. Check: `uvx email-thread-mcp@<version>` starts and waits on stdin.
+
+## Develop
+
+```
+uv sync
+uv run pytest            # 14 real Outlook threads, synthetic variants, 13 languages, hostile input
+uv run email-thread-mcp # stdio server
+```
+
+Real customer threads stay out of this repository. Locally, `tests/fixtures/` and
+`tests/test_client_threads.py` (both gitignored) hold anonymised real threads and their expected
+results; the suite runs them when present. Replace every real address and name before using a
+thread there.

email_thread_mcp-0.2.0/README.md

@@ -0,0 +1,89 @@
+# email-thread-mcp
+
+MCP server (stdio) with two deterministic tools for an accounts-receivable (AR) email agent:
+no LLM inside, no network access, no credentials.
+
+| Tool | Role in the agent | Output contract |
+|---|---|---|
+| `parse_email_thread(body, ar_mailboxes?)` | first step: request preprocessing. Splits the raw email body (Outlook/Gmail/Apple HTML or plain text) into the latest message, its signer and greeting, and the quoted history (oldest first) | [`contracts/thread.schema.json`](contracts/thread.schema.json) |
+| `validate_output(output, categories, thread?)` | last step: deterministic checks of the final envelope. Corrects only unambiguous problems (category case/punctuation, duplicates, invoice-number noise, human-review flag); reports the rest | [`contracts/validation.schema.json`](contracts/validation.schema.json) |
+
+## Use
+
+Any MCP client that starts stdio servers can run it with `uvx`:
+
+```json
+{
+  "mcpServers": {
+    "email-thread-mcp": {
+      "command": "uvx",
+      "args": ["email-thread-mcp@0.2.0"]
+    }
+  }
+}
+```
+
+Pin a version: a client that keeps the server running may otherwise serve a stale cached build.
+
+Each tool returns one JSON object. Structured arguments (`ar_mailboxes`, `categories`, `output`,
+`thread`) may be passed as values or as text: clients that render arguments through a template
+engine first can send JSON or a Python-style repr, and both are accepted.
+
+A typical agent calls `parse_email_thread` first, as preprocessing, and uses `latest_message`,
+`reply_to_name` and `thread_context` in later steps; it calls `validate_output` last, on its final
+envelope. If parsing fails, falling back to the plain-text body before the first quote marker keeps
+the agent working.
+
+## Language support
+
+Inbound mail may be in any language, so the parser treats its three kinds of miss differently:
+
+| Miss | Effect | How it is avoided |
+|---|---|---|
+| quote boundary | old history read as the new message | found by structure in any language: the mail client's HTML quote marker (Outlook `divRplyFwdMsg`, Gmail `gmail_quote`, Apple/Thunderbird `blockquote type="cite"`), or a `label: value` block that starts with an address and holds a date with a time |
+| greeting / signer name | `reply_to_name` is null, the draft greets neutrally | per-language words in `src/email_thread_mcp/vocab.py` |
+| sent date | `sent_at` is null (thread order comes from position, not dates) | [`dateparser`](https://pypi.org/project/dateparser/), absolute dates only |
+
+`vocab.py` covers EN, DE, FR, NL, IT, ES, PT, PL, CS, SV, DA, NO, FI. Only EN is `verified` against
+real threads; the others are built from Outlook's localized reply headers. A language outside the
+list still splits, and `parse_info.warnings` names what was not understood, e.g.
+`quoted message 1: header labels not recognised: Kimden, Gönderildi, Kime, Konu`. Search traces
+for those warnings to see which language to add next.
+
+To add or verify a language: add its entry to `vocab.py` and a case to `tests/test_languages.py`.
+Once a real thread in it (anonymised as below) parses correctly, add it as a fixture and set `verified`.
+
+## Untrusted input
+
+The body is written by the customer, and anyone can send one. The parser:
+
+- drops text a reader cannot see (CSS `display:none`, `visibility:hidden`, `font-size:0`, `opacity:0`,
+  `mso-hide:all`, the `hidden` attribute) and zero-width, bidirectional and control characters, and
+  reports both in `parse_info.warnings`;
+- bounds its own cost: the body is cut at 2M raw / 300k text characters, and dates beyond 50 parser
+  calls per email stay null.
+
+It does not make the content trustworthy. The quoted history in particular is plain text the customer
+can edit, including a fake message "from" the AR team (role `recipient`). Prompts must treat
+`latest_message` and `thread_context` as data, never as instructions.
+
+## Release
+
+1. Bump `version` in `pyproject.toml`, then `uv run pytest`.
+2. Commit, tag `v<version>`, push both. Never move or reuse a tag or a version.
+3. `uv build`, check that the sdist holds only `src/`, `README.md` and `pyproject.toml`, then
+   `uv publish`.
+4. Check: `uvx email-thread-mcp@<version>` starts and waits on stdin.
+
+## Develop
+
+```
+uv sync
+uv run pytest            # 14 real Outlook threads, synthetic variants, 13 languages, hostile input
+uv run email-thread-mcp # stdio server
+```
+
+Real customer threads stay out of this repository. Locally, `tests/fixtures/` and
+`tests/test_client_threads.py` (both gitignored) hold anonymised real threads and their expected
+results; the suite runs them when present. Replace every real address and name before using a
+thread there.

email_thread_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "email-thread-mcp"
+version = "0.2.0"
+description = "MCP server for the AR email agent: parses an inbound email thread into the thread contract and validates the agent's output envelope."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = [
+    "dateparser>=1.2,<2",
+    "mcp>=2.3,<3",
+]
+
+[project.scripts]
+email-thread-mcp = "email_thread_mcp.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/email_thread_mcp"]
+
+# tests/fixtures (local only, gitignored) holds real customer emails: keep them out of any build.
+[tool.hatch.build.targets.sdist]
+only-include = ["src/email_thread_mcp", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

email_thread_mcp-0.2.0/src/email_thread_mcp/__init__.py

@@ -0,0 +1 @@
+"""MCP tools for the AR email agent: thread parsing (request preprocessing) and output validation."""

email_thread_mcp-0.2.0/src/email_thread_mcp/html_text.py

@@ -0,0 +1,141 @@
+"""HTML email body -> plain text that keeps the line structure.
+
+Line structure matters here: quote headers (`From:` / `Sent:` lines), greetings and sign-off blocks
+are all detected line by line, so block elements and `<br>` become line breaks rather than spaces.
+
+Text a human reader cannot see (hidden by CSS, zero-width or bidirectional control characters) is
+dropped: it is the usual way to put instructions in an email for the LLM but not for the reviewer.
+"""
+
+from __future__ import annotations
+
+import re
+from html.parser import HTMLParser
+
+_BLOCK_TAGS = {
+    "address", "article", "blockquote", "br", "dd", "div", "dl", "dt", "footer", "h1", "h2", "h3",
+    "h4", "h5", "h6", "header", "hr", "li", "ol", "p", "pre", "section", "table", "tr", "ul",
+}
+_CELL_TAGS = {"td", "th"}
+_SKIP_TAGS = {"head", "script", "style", "title"}
+_VOID_TAGS = {"area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "source", "track", "wbr"}
+_HIDDEN_STYLE = re.compile(
+    r"display\s*:\s*none|visibility\s*:\s*hidden|mso-hide\s*:\s*all"
+    r"|(?<![\w-])font-size\s*:\s*0*\.?0+(px|pt|em|rem|%)?\s*(;|!|$)|(?<![\w-])opacity\s*:\s*0*\.?0+\s*(;|!|$)",
+    re.IGNORECASE,
+)
+# Zero-width, bidirectional-control and other invisible format characters, plus C0 controls but tab/newline.
+_INVISIBLE = re.compile("[\u00ad\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff\x01-\x08\x0b\x0c\x0e-\x1f\x7f]")
+
+# Line emitted where a mail client marks the start of quoted history. The markup is the same in every
+# UI language, so the thread parser can split on it even when it knows none of the header words.
+QUOTE_MARKER = "\x00quote\x00"
+
+
+def _is_quote_marker(tag: str, attrs: list[tuple[str, str | None]]) -> bool:
+    a = {k.lower(): (v or "") for k, v in attrs}
+    classes = a.get("class", "").split()
+    return (
+        a.get("id") == "divRplyFwdMsg"  # Outlook
+        or "gmail_quote" in classes  # Gmail
+        or "moz-cite-prefix" in classes  # Thunderbird
+        or (tag == "blockquote" and a.get("type", "").lower() == "cite")  # Apple Mail, Thunderbird
+    )
+
+
+def _is_hidden(attrs: list[tuple[str, str | None]]) -> bool:
+    return any(k == "hidden" or (k == "style" and v and _HIDDEN_STYLE.search(v)) for k, v in attrs)
+
+
+class _TextExtractor(HTMLParser):
+    def __init__(self, drop_hidden: bool = True) -> None:
+        super().__init__(convert_charrefs=True)
+        self._parts: list[str] = []
+        self._skip_depth = 0
+        self._drop_hidden = drop_hidden
+        # A hidden element is left at its own closing tag: only that tag name is counted, so unclosed
+        # <p>/<li> inside it cannot keep the rest of the email hidden.
+        self._hidden_tag: str | None = None
+        self._hidden_depth = 0
+        self.hidden_chars = 0
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag in _SKIP_TAGS:
+            self._skip_depth += 1
+            return
+        if self._hidden_tag:
+            self._hidden_depth += tag == self._hidden_tag
+            return
+        if self._drop_hidden and tag not in _VOID_TAGS and _is_hidden(attrs):
+            self._hidden_tag, self._hidden_depth = tag, 1
+            return
+        if not self._skip_depth and _is_quote_marker(tag, attrs):
+            self._parts.append(f"\n{QUOTE_MARKER}\n")
+        if tag in _BLOCK_TAGS:
+            self._parts.append("\n")
+        elif tag in _CELL_TAGS:
+            self._parts.append("\t")
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in _SKIP_TAGS:
+            self._skip_depth = max(0, self._skip_depth - 1)
+        elif self._hidden_tag:
+            if tag == self._hidden_tag:
+                self._hidden_depth -= 1
+                if not self._hidden_depth:
+                    self._hidden_tag = None
+        elif tag in _BLOCK_TAGS:
+            self._parts.append("\n")
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        if tag in _BLOCK_TAGS and not self._hidden_tag:
+            self._parts.append("\n")
+
+    def handle_data(self, data: str) -> None:
+        if self._skip_depth:
+            return
+        if self._hidden_tag:
+            self.hidden_chars += len(data.strip())
+            return
+        self._parts.append(data)
+
+    def text(self) -> str:
+        return "".join(self._parts)
+
+
+def looks_like_html(body: str) -> bool:
+    return bool(re.search(r"<(html|body|div|p|br|span|table)[\s/>]", body, re.IGNORECASE))
+
+
+def html_to_text(body: str) -> tuple[str, int]:
+    """Visible text of an HTML body, and how many characters of hidden text were dropped.
+
+    If the whole body is hidden (broken markup rather than an attack), the hidden text is kept: losing
+    the message would be worse, and the caller still sees the count."""
+    parser = _TextExtractor()
+    parser.feed(body)
+    parser.close()
+    text = normalise_text(parser.text())
+    if not text.replace(QUOTE_MARKER, "").strip() and parser.hidden_chars:
+        everything = _TextExtractor(drop_hidden=False)
+        everything.feed(body)
+        everything.close()
+        return normalise_text(everything.text()), parser.hidden_chars
+    return text, parser.hidden_chars
+
+
+def strip_invisible(text: str) -> tuple[str, int]:
+    """Remove characters that change what an LLM reads without changing what a person sees."""
+    cleaned, count = _INVISIBLE.subn("", text)
+    return cleaned, count
+
+
+def normalise_text(text: str) -> str:
+    """Unify whitespace: no-break spaces become spaces, each line is trimmed, blank runs collapse."""
+    text = text.replace("\r\n", "\n").replace("\r", "\n").replace(" ", " ")
+    lines = [re.sub(r"[ \t]+", " ", line).strip() for line in text.split("\n")]
+    out: list[str] = []
+    for line in lines:
+        if line or (out and out[-1]):
+            out.append(line)
+    return "\n".join(out).strip()

email_thread_mcp-0.2.0/src/email_thread_mcp/server.py

@@ -0,0 +1,85 @@
+"""MCP server (stdio) exposing the AR email tools. MCP clients start it with `uvx email-thread-mcp`.
+
+Some clients render structured arguments through a template engine first, so they may arrive as
+text: JSON or a Python-style repr. Both are accepted.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+from importlib.metadata import version
+from typing import Any
+
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+
+from .thread import parse_email_thread as _parse_email_thread
+from .validate import validate_output as _validate_output
+
+mcp = MCPServer("email-thread-mcp", version=version("email-thread-mcp"))
+
+
+def _coerce(value: Any, name: str = "argument") -> Any:
+    if not isinstance(value, str):
+        return value
+    text = value.strip()
+    if not text:
+        return None
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+    except (RecursionError, MemoryError):
+        raise ToolError(f"{name} is nested too deeply") from None
+    try:
+        return ast.literal_eval(text)
+    except (ValueError, SyntaxError, TypeError):
+        # ToolError, not ValueError: the SDK hides a plain exception's text from the caller.
+        raise ToolError(f"{name} is neither JSON nor a Python literal") from None
+    except (RecursionError, MemoryError):
+        raise ToolError(f"{name} is nested too deeply") from None
+
+
+@mcp.tool()
+def parse_email_thread(body: str, ar_mailboxes: list[str] | str | None = None) -> dict[str, Any]:
+    """Split an inbound email body (HTML or plain text, newest message on top) into the latest
+    message, its signer and greeting, and the quoted history (oldest first), per the thread contract.
+
+    Args:
+        body: the raw email body (HTML or plain text), unchanged.
+        ar_mailboxes: addresses (or '@domain' entries) of the AR team; quoted messages from these are
+            role 'recipient' (us), messages sent to them are role 'sender' (the customer).
+    """
+    mailboxes = _coerce(ar_mailboxes, "ar_mailboxes") if isinstance(ar_mailboxes, str) else ar_mailboxes
+    if isinstance(mailboxes, str):
+        mailboxes = [mailboxes]
+    return _parse_email_thread(body, mailboxes or [])
+
+
+@mcp.tool()
+def validate_output(
+    output: dict[str, Any] | str,
+    categories: list[Any] | str,
+    thread: dict[str, Any] | str | None = None,
+) -> dict[str, Any]:
+    """Check the agent's output envelope: category names must come from the request's list,
+    invoice numbers clean, the draft greets the right person and marks promised attachments.
+    Safe corrections are applied to the returned `output`; everything else is reported in `issues`.
+
+    Args:
+        output: the final envelope (classification, draft_response, extracted_data, ...).
+        categories: the allowed categories (objects with `name`, or plain names).
+        thread: the parse_email_thread result, used for the greeting check. Optional.
+    """
+    return _validate_output(
+        _coerce(output, "output"), _coerce(categories, "categories") or [], _coerce(thread, "thread")
+    )
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()