email-thread-mcp 0.2.0__py3-none-any.whl

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/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/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()

email_thread_mcp/thread.py

@@ -0,0 +1,565 @@
+"""Split an inbound email body into the latest message and its quoted history.
+
+Output shape: contracts/thread.schema.json (schema_version 1.0).
+
+The body arrives as raw HTML (Outlook, Gmail, Apple Mail) or plain text, newest message on top.
+It is converted to text with line structure kept, then cut at every quote boundary:
+
+- a mail client's HTML quote marker (see html_text.QUOTE_MARKER) - works in any UI language,
+- a header block of known labels: a `From:` line followed within a few lines by `Sent:`/`Date:`,
+- any `label: value` block that starts with an address and holds a date with a time - unknown languages,
+- `-----Original Message-----` and forwarded-message separators,
+- attribution lines (`On <date>, <name> wrote:`, `Am <date> schrieb <name>:`, ...).
+
+Words per language live in vocab.py. A missed quote boundary is the harmful failure (old history read
+as the new message), so boundaries never depend on words alone; names and dates degrade to null.
+"""
+
+from __future__ import annotations
+
+import re
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+import dateparser
+
+from . import vocab
+from .html_text import QUOTE_MARKER, html_to_text, looks_like_html, normalise_text, strip_invisible
+
+SCHEMA_VERSION = "1.0"
+
+# Bounds on attacker-sized input: the body is customer-controlled text.
+_MAX_RAW_CHARS = 2_000_000
+_MAX_TEXT_CHARS = 300_000
+
+
+def _alternation(words: list[str]) -> str:
+    return "|".join(re.escape(w).replace(r"\ ", r"\s+") for w in sorted(words, key=lambda w: (-len(w), w)))
+
+
+_LABELS = vocab.header_labels()
+_LABEL_LANGUAGES = vocab.label_languages()
+_FROM_LABELS = [label for label, key in _LABELS.items() if key == "from"]
+_SENT_LABELS = [label for label, key in _LABELS.items() if key == "sent"]
+
+_HEADER_FROM = re.compile(rf"^({_alternation(_FROM_LABELS)})\s*:\s*(?P<value>.*)$", re.IGNORECASE)
+_HEADER_DATE = re.compile(rf"^({_alternation(_SENT_LABELS)})\s*:", re.IGNORECASE)
+_HEADER_LINE = re.compile(rf"^(?P<key>{_alternation(list(_LABELS))})\s*:\s*(?P<value>.*)$", re.IGNORECASE)
+_SEPARATOR = re.compile(rf"^-{{2,}}\s*({_alternation(vocab.all_words('separators'))})\s*-{{2,}}$", re.IGNORECASE)
+_WROTE_VERB = re.compile(rf"(?<!\w)({_alternation(vocab.all_words('wrote'))})(?!\w)", re.IGNORECASE)
+_HEADER_LOOKAHEAD = 5
+_MIN_KNOWN_HEADERS = 3
+
+# Any-language header line: a label of 1-3 words of letters, then a value.
+_LABEL_LINE = re.compile(r"^(?P<label>[^\W\d_]+(?:[ .'-][^\W\d_]+){0,2})\s*:\s*(?P<value>\S.*)$")
+_LABEL_MAX = 25
+_GENERIC_HEADERS_MIN, _GENERIC_HEADERS_MAX = 3, 8
+_TIME = re.compile(r"(?<!\d)\d{1,2}[:.]\d{2}(?!\d)")
+_NUMERIC_DATE = re.compile(r"\d{1,4}[./-]\d{1,2}[./-]\d{2,4},?(\s+\d{1,2}[:.]\d{2})?")
+_YEAR = re.compile(r"(?<!\d)(19|20)\d{2}(?!\d)")
+
+_GREETING = re.compile(
+    rf"^({_alternation(vocab.all_words('greetings'))})(?!\w)[\s,]*(?P<name>[^,!:]*?)\s*[,!:]?$",
+    re.IGNORECASE,
+)
+_HONORIFIC = re.compile(rf"^({_alternation(vocab.all_words('honorifics'))})\.?(\s+|$)", re.IGNORECASE)
+_CLOSING = re.compile(
+    rf"^({_alternation(vocab.all_words('closings'))})(?!\w)\s*[,.!-]?\s*(?P<rest>.*)$",
+    re.IGNORECASE,
+)
+_NAME_PARTICLES = {"von", "van", "der", "de", "da", "di", "le", "la", "du", "del", "den", "ten", "zu"}
+_NOT_NAME_WORDS = {
+    "accounts", "payable", "receivable", "department", "team", "finance", "procurement", "gmbh", "ltd",
+    "inc", "ag", "ab", "llc", "co", "corp", "company", "credit", "collections", "manager", "sent",
+    "from", "iphone", "office", "support", "customer", "service", "bv", "nv", "sa", "srl", "spa", "sas",
+    "sarl", "oy", "oyj", "aps", "kg", "se",
+}
+# Bounded parts keep the search linear on long runs of word characters without an '@'.
+_EMAIL = re.compile(r"[\w.+-]{1,64}@[\w-]{1,63}(?:\.[\w-]{1,63}){1,8}")
+_NAME_BEFORE_ADDRESS = re.compile(r"((?:[^\W\d_][\w.'’-]*\s+){0,4})(<[^<>\s]+@[^<>\s]+>)")
+# Words that sit between an attribution's date and the sender's name ("at 9:15 AM Anna Keller").
+_ATTRIBUTION_FILLERS = {"am", "pm", "at", "um", "à", "om", "alle", "a", "las", "às", "o", "kl", "klo", "v"}
+
+
+@dataclass
+class Message:
+    body: str
+    headers: dict[str, str] = field(default_factory=dict)
+    role: str = "unknown"
+    greeting_name: str | None = None
+    signer_name: str | None = None
+    signature: str | None = None
+    text_without_signature: str = ""
+    sent_at: str | None = None
+    notes: list[str] = field(default_factory=list)
+
+
+# --------------------------------------------------------------------------------------------- #
+# Splitting
+# --------------------------------------------------------------------------------------------- #
+
+_OUTLOOK_BOLD_FROM = re.compile(rf"<b>\s*({_alternation(_FROM_LABELS)}):\s*</b>", re.IGNORECASE)
+
+
+def detect_format(raw: str, quoted_messages: int) -> str:
+    if looks_like_html(raw):
+        if re.search(r'id="divRplyFwdMsg"|border-top:\s*solid', raw, re.IGNORECASE) or _OUTLOOK_BOLD_FROM.search(raw):
+            return "outlook-html"
+        if "gmail_quote" in raw:
+            return "gmail-html"
+        if re.search(r'<blockquote[^>]*type="cite"', raw, re.IGNORECASE):
+            return "apple-html"
+        return "html-unknown"
+    return "plain-text" if quoted_messages else "plain-text-no-quotes"
+
+
+def _is_wrote(line: str) -> bool:
+    """Attribution line: a 'wrote' verb plus an address or a year, ending the line (any language)."""
+    if len(line) > 300 or not _WROTE_VERB.search(line):
+        return False
+    if not (_EMAIL.search(line) or _YEAR.search(line)):
+        return False
+    return line.rstrip().endswith(":") or bool(_WROTE_VERB.search(line.rstrip()[-20:]))
+
+
+def _is_marker_attribution(line: str) -> bool:
+    """Line right after an HTML quote marker that ends in ':' and names an address: an attribution in a
+    language whose 'wrote' verb is not in the vocabulary."""
+    return len(line) <= 300 and line.rstrip().endswith(":") and bool(_EMAIL.search(line))
+
+
+def _known_header_block(lines: list[str], i: int) -> bool:
+    if not _HEADER_FROM.match(lines[i]):
+        return False
+    window = lines[i : i + 1 + 2 * _HEADER_LOOKAHEAD]  # header lines may be separated by blanks
+    if not any(_HEADER_DATE.match(w) for w in window[1:]):
+        return False
+    return sum(1 for w in window if _HEADER_LINE.match(w)) >= _MIN_KNOWN_HEADERS
+
+
+def _label_line(line: str) -> re.Match[str] | None:
+    m = _LABEL_LINE.match(line)
+    return m if m and len(m.group("label")) <= _LABEL_MAX else None
+
+
+def _generic_header_block(lines: list[str], i: int) -> list[int] | None:
+    """Indexes of a `label: value` block starting at i, whatever the labels' language, or None.
+
+    The first value must carry an address (the sender) and a later one a date with a time of day:
+    every mail client's quote header has both, a remittance table in the body rarely does.
+    """
+    first = _label_line(lines[i])
+    if not first or not _EMAIL.search(first.group("value")) or len(first.group("value")) > 150:
+        return None
+    found = [i]
+    j = i + 1
+    while j < len(lines) and len(found) < _GENERIC_HEADERS_MAX:
+        if not lines[j]:
+            j += 1
+            continue
+        if not _label_line(lines[j]):
+            break
+        found.append(j)
+        j += 1
+    if len(found) < _GENERIC_HEADERS_MIN:
+        return None
+    values = [_label_line(lines[k]).group("value") for k in found[1:]]  # type: ignore[union-attr]
+    if not any(_TIME.search(v) and "@" not in v and parse_sent(v) for v in values):
+        return None
+    return found
+
+
+def _boundaries(lines: list[str]) -> list[int]:
+    """Line indexes where a quoted message starts (its marker, header, separator or attribution line)."""
+    starts: list[int] = []
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        is_start = (
+            line == QUOTE_MARKER
+            or bool(_SEPARATOR.match(line))
+            or _is_wrote(line)
+            or _known_header_block(lines, i)
+            or _generic_header_block(lines, i) is not None
+            or (i + 1 < len(lines) and _is_wrote(f"{line} {lines[i + 1]}"))  # attribution wrapped over two lines
+        )
+        if not is_start:
+            i += 1
+            continue
+        starts.append(i)
+        # Marker, separator, attribution and header block of one quoted message: one boundary, not several.
+        i += 1
+        while i < len(lines):
+            block = _generic_header_block(lines, i)
+            if block:
+                i = block[-1] + 1
+            elif (
+                not lines[i]
+                or lines[i] == QUOTE_MARKER
+                or _SEPARATOR.match(lines[i])
+                or _HEADER_LINE.match(lines[i])
+                or _is_wrote(lines[i])
+                or _is_marker_attribution(lines[i])
+            ):
+                i += 1
+            else:
+                break
+    return starts
+
+
+def _attribution_from(line: str) -> str | None:
+    """Sender out of an attribution line: 'Name <address>', else the address, else the name before the verb."""
+    m = _NAME_BEFORE_ADDRESS.search(line)
+    if m:
+        tokens = m.group(1).split()
+        while tokens and (
+            tokens[0].lower() in _ATTRIBUTION_FILLERS or not tokens[0][0].isupper() or _WROTE_VERB.fullmatch(tokens[0])
+        ):
+            tokens.pop(0)
+        return " ".join([*tokens, m.group(2)])
+    m = _EMAIL.search(line)
+    if m:
+        return m.group(0)
+    verb = _WROTE_VERB.search(line)
+    before = line[: verb.start()] if verb else line
+    name = before.rsplit(",", 1)[-1].strip(" :")
+    return name or None
+
+
+def _attribution_date(line: str, sender: str | None) -> str | None:
+    text = line.replace(sender, " ") if sender else line
+    text = _WROTE_VERB.sub(" ", text).strip(" :,")
+    words = text.split()
+    for skip in range(3):  # leading 'On' / 'Am' / 'Le' / 'W dniu' ...
+        if (value := parse_sent(" ".join(words[skip:]).strip(" ,"))) is not None:
+            return value
+    numeric = _NUMERIC_DATE.search(text)  # words of an unknown language around a numeric date
+    return parse_sent(numeric.group(0)) if numeric else None
+
+
+def _parse_quoted(block: list[str]) -> Message:
+    headers: dict[str, str] = {}
+    unknown_labels: list[str] = []
+    sent_languages: list[str] | None = None
+    attribution: str | None = None
+    marker_only = True
+    after_marker = False
+    idx = 0
+    while idx < len(block):
+        line = block[idx]
+        if not line or line == QUOTE_MARKER:
+            after_marker = after_marker or line == QUOTE_MARKER
+            idx += 1
+            continue
+        if _SEPARATOR.match(line):
+            marker_only = False
+            idx += 1
+            continue
+        if not headers and attribution is None:
+            if _is_wrote(line) or (after_marker and _is_marker_attribution(line)):
+                attribution = line
+                idx += 1
+                continue
+            if idx + 1 < len(block) and _is_wrote(f"{line} {block[idx + 1]}"):
+                attribution = f"{line} {block[idx + 1]}"
+                idx += 2
+                continue
+        m = _HEADER_LINE.match(line)
+        if m:
+            label = m.group("key").lower()
+            headers.setdefault(_LABELS[label], m.group("value").strip())
+            if _LABELS[label] == "sent":
+                sent_languages = _LABEL_LANGUAGES.get(label)
+            idx += 1
+            continue
+        generic = _generic_header_block(block, idx)
+        if generic:
+            unknown_labels += _assign_generic_headers([block[k] for k in generic], headers)
+            idx = generic[-1] + 1
+            continue
+        break
+
+    if attribution is not None:
+        sender = _attribution_from(attribution)
+        if sender:
+            headers.setdefault("from", sender)
+        sent_at = _attribution_date(attribution, sender)
+    else:
+        sent_at = parse_sent(headers.get("sent"), sent_languages)
+
+    message = Message(
+        body=normalise_text("\n".join(re.sub(r"^(>\s?)+", "", line) for line in block[idx:])),
+        headers=headers,
+        sent_at=sent_at,
+    )
+    if unknown_labels:
+        message.notes.append(f"header labels not recognised: {', '.join(unknown_labels)}")
+    if headers.get("sent") and sent_at is None:
+        message.notes.append(f"sent date not parsed: {headers['sent']!r}")
+    if marker_only and not headers and attribution is None:
+        message.notes.append("found by the HTML quote marker only: sender and date unknown")
+    return message
+
+
+def _assign_generic_headers(lines: list[str], headers: dict[str, str]) -> list[str]:
+    """Map a header block's labels to from/to/sent/subject. Unknown labels are mapped by their value:
+    the first address is the sender, the next the recipient, a date the sent time, the last line the
+    subject. Returns the labels that were not in the vocabulary."""
+    unknown: list[str] = []
+    pairs = [(m.group("label"), m.group("value").strip()) for m in map(_label_line, lines) if m]
+    for n, (label, value) in enumerate(pairs):
+        key = _LABELS.get(label.lower())
+        if key is None:
+            unknown.append(label)
+            if _EMAIL.search(value):
+                key = "from" if "from" not in headers else "to" if "to" not in headers else "cc"
+            elif "sent" not in headers and _TIME.search(value) and parse_sent(value):
+                key = "sent"
+            elif n == len(pairs) - 1:
+                key = "subject"
+            else:
+                continue
+        headers.setdefault(key, value)
+    return unknown
+
+
+# --------------------------------------------------------------------------------------------- #
+# Names
+# --------------------------------------------------------------------------------------------- #
+
+
+def looks_like_name(text: str) -> bool:
+    text = text.strip().strip(",.")
+    if not text or len(text) > 50 or any(ch.isdigit() for ch in text) or "@" in text:
+        return False
+    tokens = text.replace("-", " ").split()
+    if not 1 <= len(tokens) <= 4:
+        return False
+    if any(t.lower().strip(".,") in _NOT_NAME_WORDS for t in tokens):
+        return False
+    return all(t[0].isupper() or t.lower() in _NAME_PARTICLES for t in tokens)
+
+
+def find_greeting(lines: list[str]) -> str | None:
+    for line in lines[:3]:
+        m = _GREETING.match(line)
+        if m:
+            name = m.group("name").strip()
+            return name if name and looks_like_name(_HONORIFIC.sub("", name)) else None
+    return None
+
+
+def find_signoff(lines: list[str]) -> tuple[int | None, str | None, str | None]:
+    """Return (index of the closing line, signer name, signature block) for the LAST sign-off."""
+    for idx in range(len(lines) - 1, -1, -1):
+        line = lines[idx]
+        if len(line) > 60:
+            continue
+        m = _CLOSING.match(line)
+        if not m:
+            continue
+        rest = m.group("rest").strip()
+        if rest and not looks_like_name(rest):
+            continue  # "Thank you for your collaboration." is a sentence, not a sign-off
+        after = [l for l in lines[idx + 1 : idx + 9] if l]
+        signer = rest or (after[0] if after and looks_like_name(after[0]) else None)
+        signature_lines = ([rest] if rest else []) + after
+        return idx, signer, "\n".join(signature_lines) or None
+    return None, None, None
+
+
+def _annotate(message: Message, lines: list[str]) -> None:
+    message.greeting_name = find_greeting(lines)
+    idx, message.signer_name, message.signature = find_signoff(lines)
+    message.text_without_signature = normalise_text("\n".join(lines[:idx] if idx is not None else lines))
+
+
+# --------------------------------------------------------------------------------------------- #
+# Roles, dates, reply-to
+# --------------------------------------------------------------------------------------------- #
+
+
+def _addresses(value: str | None) -> set[str]:
+    return {m.group(0).lower() for m in _EMAIL.finditer(value or "")}
+
+
+def assign_role(headers: dict[str, str], ar_mailboxes: list[str]) -> str:
+    """recipient = written by the AR team (us); sender = written by the customer side."""
+    if not ar_mailboxes:
+        return "unknown"
+
+    def is_ours(addresses: set[str]) -> bool:
+        for entry in (e.lower().strip() for e in ar_mailboxes):
+            if any(a == entry or (entry.startswith("@") and a.endswith(entry)) for a in addresses):
+                return True
+        return False
+
+    if is_ours(_addresses(headers.get("from"))):
+        return "recipient"
+    if is_ours(_addresses(headers.get("to"))):
+        return "sender"
+    return "unknown"
+
+
+# Outlook's English forms, parsed without dateparser's start-up cost.
+_DATE_FORMATS = (
+    "%A, %B %d, %Y %I:%M %p",
+    "%A, %B %d, %Y %H:%M",
+    "%d.%m.%Y %H:%M",
+    "%Y-%m-%d %H:%M",
+)
+# Absolute dates only: a relative word ("yesterday") must not become today's date, and a missing year
+# must not be filled in.
+_MAX_DATE_CHARS = 100  # a header date is ~50 chars; dateparser's cost grows with the text
+_DATEPARSER_CALLS = 50  # per parse_email_thread call: real threads need a few, crafted bodies thousands
+_date_budget: ContextVar[list[int] | None] = ContextVar("_date_budget", default=None)  # [calls left, refused]
+_date_cache: dict[tuple[str, tuple[str, ...] | None, str], str | None] = {}
+_DATEPARSER_SETTINGS = {
+    "PARSERS": ["timestamp", "absolute-time"],
+    "REQUIRE_PARTS": ["day", "month", "year"],
+    "RETURN_AS_TIMEZONE_AWARE": False,
+}
+
+
+def parse_sent(value: str | None, languages: list[str] | None = None) -> str | None:
+    """A quote header's date as ISO 8601, in any of dateparser's languages; None when not parseable."""
+    if not value:
+        return None
+    text = value.strip()
+    for fmt in _DATE_FORMATS:
+        try:
+            return datetime.strptime(text, fmt).isoformat()
+        except ValueError:
+            continue
+    if len(text) > _MAX_DATE_CHARS:
+        return None
+    order = "MDY" if re.search(r"\b[ap]\.?m\.?\b", text, re.IGNORECASE) else "DMY"
+    key = (text, tuple(languages) if languages else None, order)
+    if key in _date_cache:
+        return _date_cache[key]
+    budget = _date_budget.get()
+    if budget is not None:
+        if budget[0] <= 0:
+            budget[1] += 1
+            return None
+        budget[0] -= 1
+    try:
+        parsed = dateparser.parse(text, languages=languages, settings={**_DATEPARSER_SETTINGS, "DATE_ORDER": order})  # type: ignore[arg-type]
+    except Exception:  # dateparser raises assorted errors on odd input; a date is never worth failing the parse
+        parsed = None
+    if len(_date_cache) > 4096:
+        _date_cache.clear()
+    _date_cache[key] = parsed.isoformat() if parsed else None
+    return _date_cache[key]
+
+
+def resolve_reply_to_name(latest: Message, history_newest_first: list[Message]) -> str | None:
+    """Who the draft reply should greet.
+
+    Agreed order:
+      1. the signer of the latest message;
+      2. else the name OUR most recent quoted message greeted (the customer replied to it);
+      3. else None - the drafter then uses a neutral greeting. Never guess a name.
+
+    Step 2 trusts only a message positively identified as ours (role "recipient", which needs
+    ar_mailboxes). With unknown roles the greeting could be our own colleague's name, so it is skipped.
+    """
+    if latest.signer_name:
+        return latest.signer_name
+    ours = next((m for m in history_newest_first if m.role == "recipient"), None)
+    return ours.greeting_name if ours else None
+
+
+# --------------------------------------------------------------------------------------------- #
+# Entry point
+# --------------------------------------------------------------------------------------------- #
+
+
+def parse_email_thread(body: str, ar_mailboxes: list[str] | None = None) -> dict[str, Any]:
+    budget = [_DATEPARSER_CALLS, 0]
+    token = _date_budget.set(budget)
+    try:
+        result = _parse_email_thread(body, ar_mailboxes)
+    finally:
+        _date_budget.reset(token)
+    if budget[1]:
+        result["parse_info"]["warnings"].append("date parsing limit reached: some dates left null")
+    return result
+
+
+def _parse_email_thread(body: str, ar_mailboxes: list[str] | None) -> dict[str, Any]:
+    warnings: list[str] = []
+    raw = (body or "").replace("\x00", "")  # NUL is the quote marker's delimiter; the body cannot forge one
+    if len(raw) > _MAX_RAW_CHARS:
+        raw = raw[:_MAX_RAW_CHARS]
+        warnings.append(f"body truncated to {_MAX_RAW_CHARS} characters before parsing")
+    if looks_like_html(raw):
+        text, hidden_chars = html_to_text(raw)
+        if hidden_chars:
+            warnings.append(f"hidden HTML text removed: {hidden_chars} characters a reader would not see")
+    else:
+        text = normalise_text(raw)
+    text, invisible = strip_invisible(text)
+    if invisible:
+        warnings.append(f"invisible characters removed: {invisible} (zero-width, bidirectional or control)")
+    if len(text) > _MAX_TEXT_CHARS:
+        text = text[:_MAX_TEXT_CHARS]
+        warnings.append(f"text truncated to {_MAX_TEXT_CHARS} characters; the end of the quoted history is lost")
+    lines = text.split("\n")
+    starts = _boundaries(lines)
+
+    latest_lines = [l for l in lines[: starts[0]] if l and l != QUOTE_MARKER] if starts else [l for l in lines if l and l != QUOTE_MARKER]
+    latest = Message(body=normalise_text("\n".join(latest_lines)))
+    _annotate(latest, latest_lines)
+
+    quoted: list[Message] = []
+    for n, start in enumerate(starts):
+        end = starts[n + 1] if n + 1 < len(starts) else len(lines)
+        msg = _parse_quoted(lines[start:end])
+        msg.body = normalise_text("\n".join(l for l in msg.body.split("\n") if l != QUOTE_MARKER))
+        if not msg.body:
+            warnings.append(f"quoted message {n + 1} has no body text")
+            continue
+        msg_lines = [l for l in msg.body.split("\n") if l]
+        _annotate(msg, msg_lines)
+        msg.role = assign_role(msg.headers, ar_mailboxes or [])
+        warnings += [f"quoted message {n + 1}: {note}" for note in msg.notes]
+        quoted.append(msg)
+
+    if not starts:
+        warnings.append("no quote marker found: whole body treated as the latest message")
+    if latest.signer_name is None:
+        warnings.append("latest message: no signer name found in the sign-off")
+    if not latest.text_without_signature:
+        warnings.append("latest message has no text besides greeting/signature")
+
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "latest_message": {
+            "text": latest.text_without_signature or latest.body,
+            "greeting_name": latest.greeting_name,
+            "signer_name": latest.signer_name,
+            "signature": latest.signature,
+        },
+        "thread_context": [
+            {
+                "role": m.role,
+                "from": m.headers.get("from"),
+                "to": m.headers.get("to"),
+                "sent_at": m.sent_at,
+                "subject": m.headers.get("subject"),
+                "greeting_name": m.greeting_name,
+                "signer_name": m.signer_name,
+                "body": m.body,
+            }
+            for m in reversed(quoted)  # contract: oldest first
+        ],
+        "reply_to_name": resolve_reply_to_name(latest, quoted),
+        "parse_info": {
+            "format": detect_format(raw, len(quoted)),
+            "quoted_messages": len(quoted),
+            "warnings": warnings,
+        },
+    }

email_thread_mcp/validate.py

@@ -0,0 +1,146 @@
+"""Deterministic checks of the agent's output envelope.
+
+Output shape: contracts/validation.schema.json (schema_version 1.0).
+
+Corrects only what is unambiguous and reports the rest. In particular it never maps a category by
+similarity or prefix: "Invoice" is not silently turned into "Copy of Invoice".
+"""
+
+from __future__ import annotations
+
+import copy
+import re
+import unicodedata
+from typing import Any
+
+SCHEMA_VERSION = "1.0"
+
+_DATE_LIKE = re.compile(r"^\d{1,2}[./-]\d{1,2}[./-]\d{2,4}$|^\d{4}-\d{2}-\d{2}$")
+_PROMISES_DOCUMENT = re.compile(
+    r"\b(send|attach|resend|forward|provide)\b[^.\n]{0,60}\b(copy|copies|invoice|statement|proof of delivery|pod|credit note)\b",
+    re.IGNORECASE,
+)
+_PLACEHOLDER = re.compile(r"\[[^\]]*attached\]", re.IGNORECASE)
+_HONORIFIC = re.compile(r"^(mr|ms|mrs|dr|frau|herr)\.?\s+", re.IGNORECASE)
+
+
+def normalise_name(name: str) -> str:
+    """Case, Unicode form, quotes, dashes, slashes and whitespace - nothing that changes the words."""
+    s = unicodedata.normalize("NFKC", name).casefold()
+    s = re.sub(r"[‘’“”\"']", "", s)
+    s = re.sub(r"[‐-―−]", "-", s)
+    s = re.sub(r"\s*([/-])\s*", r"\1", s)
+    return re.sub(r"\s+", " ", s).strip()
+
+
+def _issue(check: str, severity: str, path: str, message: str, corrected: bool) -> dict[str, Any]:
+    return {"check": check, "severity": severity, "path": path, "message": message, "corrected": corrected}
+
+
+def _category_names(categories: list[Any]) -> list[str]:
+    return [c["name"] if isinstance(c, dict) else str(c) for c in categories]
+
+
+def _check_categories(out: dict[str, Any], allowed: list[str], issues: list[dict[str, Any]]) -> None:
+    cats = (out.get("classification") or {}).get("categories")
+    if not isinstance(cats, list):
+        issues.append(_issue("category_in_list", "error", "$.classification.categories", "missing categories list", False))
+        return
+    by_norm: dict[str, list[str]] = {}
+    for name in allowed:
+        by_norm.setdefault(normalise_name(name), []).append(name)
+
+    seen: set[str] = set()
+    kept: list[dict[str, Any]] = []
+    for i, item in enumerate(cats):
+        path = f"$.classification.categories[{i}].category"
+        value = item.get("category") if isinstance(item, dict) else None
+        if not isinstance(value, str):
+            issues.append(_issue("category_in_list", "error", path, "category is not a string", False))
+            kept.append(item)
+            continue
+        if value not in allowed:
+            matches = by_norm.get(normalise_name(value), [])
+            if len(matches) == 1:
+                issues.append(_issue("category_in_list", "warning", path,
+                                     f"'{value}' differs from the request's '{matches[0]}' only in case or punctuation; corrected", True))
+                item = {**item, "category": matches[0]}
+                value = matches[0]
+            else:
+                issues.append(_issue("category_in_list", "error", path,
+                                     f"'{value}' is not in the request's category list", False))
+        if value in seen:
+            issues.append(_issue("category_duplicate", "warning", path, f"'{value}' listed twice; duplicate removed", True))
+            continue
+        seen.add(value)
+        kept.append(item)
+    out["classification"]["categories"] = kept
+
+
+def _check_invoices(out: dict[str, Any], issues: list[dict[str, Any]]) -> None:
+    data = out.get("extracted_data")
+    if not isinstance(data, dict):
+        return
+    invoices = data.get("invoice_numbers")
+    if not isinstance(invoices, list):
+        return
+    clean: list[str] = []
+    for i, raw in enumerate(invoices):
+        path = f"$.extracted_data.invoice_numbers[{i}]"
+        value = str(raw).strip().strip("()[]{},;:")
+        if value != str(raw):
+            issues.append(_issue("invoice_numbers", "warning", path, f"stray punctuation removed from '{raw}'", True))
+        if _DATE_LIKE.match(value):
+            issues.append(_issue("invoice_numbers", "warning", path, f"'{value}' is a date, not an invoice number; removed", True))
+            continue
+        if value in clean:
+            issues.append(_issue("invoice_numbers", "warning", path, f"'{value}' listed twice; duplicate removed", True))
+            continue
+        clean.append(value)
+    data["invoice_numbers"] = clean or None
+
+
+def _check_draft(out: dict[str, Any], thread: dict[str, Any] | None, issues: list[dict[str, Any]]) -> None:
+    draft = out.get("draft_response")
+    if not isinstance(draft, dict):
+        return
+    if draft.get("requires_human_review") is not True:
+        draft["requires_human_review"] = True
+        issues.append(_issue("requires_human_review", "warning", "$.draft_response.requires_human_review",
+                             "must always be true; set to true", True))
+    body = draft.get("draft_body") or ""
+    first_line = body.strip().split("\n", 1)[0] if body.strip() else ""
+
+    if thread:
+        latest = thread.get("latest_message") or {}
+        ours = latest.get("greeting_name")
+        reply_to = thread.get("reply_to_name")
+        if ours and _surname(ours) and _surname(ours) in first_line and (not reply_to or _surname(reply_to) != _surname(ours)):
+            issues.append(_issue("greeting_matches_reply_to", "warning", "$.draft_response.draft_body",
+                                 f"the draft greets '{ours}', who is the AR team member the customer wrote to", False))
+        elif reply_to and _surname(reply_to) and _surname(reply_to) not in first_line:
+            issues.append(_issue("greeting_matches_reply_to", "warning", "$.draft_response.draft_body",
+                                 f"the draft does not greet '{reply_to}', the person to reply to", False))
+
+    if _PROMISES_DOCUMENT.search(body) and not _PLACEHOLDER.search(body):
+        issues.append(_issue("attachment_placeholder", "warning", "$.draft_response.draft_body",
+                             "the draft promises a document but has no '[... attached]' placeholder", False))
+
+
+def _surname(name: str) -> str:
+    tokens = _HONORIFIC.sub("", name.strip()).split()
+    return tokens[-1] if tokens else ""
+
+
+def validate_output(output: dict[str, Any], categories: list[Any], thread: dict[str, Any] | None = None) -> dict[str, Any]:
+    out = copy.deepcopy(output)
+    issues: list[dict[str, Any]] = []
+    _check_categories(out, _category_names(categories), issues)
+    _check_invoices(out, issues)
+    _check_draft(out, thread, issues)
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "valid": not any(i["severity"] == "error" and not i["corrected"] for i in issues),
+        "output": out,
+        "issues": issues,
+    }

email_thread_mcp/vocab.py

@@ -0,0 +1,202 @@
+"""Per-language words the thread parser looks for: quote-header labels, separators, attribution verbs,
+greetings, sign-offs and honorifics.
+
+These words only label and enrich what the parser finds. Quote boundaries are also found by structure
+(HTML quote markers, a `label: value` block with an address and a date), so a language missing here
+still splits correctly; only names and header labels degrade, and parse_info.warnings says so.
+
+Adding a language: add an entry below, then a case to tests/test_languages.py. Set `verified` once a
+real thread in that language (anonymised like tests/fixtures/outlook-2026-09-29) has been checked.
+Keys of HEADERS are the canonical header names the parser emits. `dateparser` is the language code
+dateparser expects for that language's dates.
+"""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class Language(TypedDict):
+    verified: bool
+    dateparser: str
+    headers: dict[str, list[str]]
+    separators: list[str]
+    wrote: list[str]
+    greetings: list[str]
+    closings: list[str]
+    honorifics: list[str]
+
+
+LANGUAGES: dict[str, Language] = {
+    "en": {
+        "verified": True,  # tests/fixtures/outlook-2026-09-29
+        "dateparser": "en",
+        "headers": {"from": ["from"], "sent": ["sent", "date"], "to": ["to"], "cc": ["cc", "bcc"], "subject": ["subject"]},
+        "separators": ["original message", "forwarded message"],
+        "wrote": ["wrote"],
+        "greetings": ["dear", "hi", "hello", "hey", "good morning", "good afternoon", "good evening"],
+        "closings": [
+            "kind regards", "best regards", "warm regards", "kindest regards", "regards", "best wishes", "best",
+            "thanks", "thank you", "many thanks", "sincerely", "yours sincerely", "yours faithfully",
+            "yours truly", "cheers",
+        ],
+        "honorifics": ["mr", "ms", "mrs", "miss", "dr"],
+    },
+    "de": {
+        "verified": False,
+        "dateparser": "de",
+        "headers": {"from": ["von"], "sent": ["gesendet", "datum"], "to": ["an"], "cc": ["cc", "bcc"], "subject": ["betreff"]},
+        "separators": ["ursprüngliche nachricht", "weitergeleitete nachricht"],
+        "wrote": ["schrieb"],
+        "greetings": ["hallo", "liebe", "lieber", "liebes", "sehr geehrte", "sehr geehrter", "guten tag", "guten morgen", "moin"],
+        "closings": [
+            "mit freundlichen grüßen", "mit freundlichen grüssen", "freundliche grüße", "freundliche grüsse",
+            "viele grüße", "beste grüße", "liebe grüße", "herzliche grüße", "schöne grüße", "grüße", "gruß",
+            "vielen dank", "danke", "mfg",
+        ],
+        "honorifics": ["herr", "frau", "hr", "fr"],
+    },
+    "fr": {
+        "verified": False,
+        "dateparser": "fr",
+        "headers": {"from": ["de"], "sent": ["envoyé", "date"], "to": ["à", "a"], "cc": ["cc", "cci"], "subject": ["objet"]},
+        "separators": ["message d'origine", "message transféré"],
+        "wrote": ["a écrit"],
+        "greetings": ["bonjour", "bonsoir", "cher", "chère", "salut"],
+        "closings": [
+            "cordialement", "bien cordialement", "bien à vous", "salutations", "meilleures salutations",
+            "sincères salutations", "merci", "merci beaucoup", "bonne journée",
+        ],
+        "honorifics": ["m", "mme", "mlle", "monsieur", "madame"],
+    },
+    "nl": {
+        "verified": False,
+        "dateparser": "nl",
+        "headers": {"from": ["van"], "sent": ["verzonden", "datum"], "to": ["aan"], "cc": ["cc", "bcc"], "subject": ["onderwerp"]},
+        "separators": ["oorspronkelijk bericht", "doorgestuurd bericht"],
+        "wrote": ["schreef"],
+        "greetings": ["beste", "geachte", "hallo", "hoi", "goedemorgen", "goedemiddag", "dag"],
+        "closings": [
+            "met vriendelijke groet", "met vriendelijke groeten", "vriendelijke groet", "vriendelijke groeten",
+            "hartelijke groet", "groeten", "groet", "mvg", "alvast bedankt", "bedankt", "dank u wel",
+        ],
+        "honorifics": ["dhr", "mevr", "heer", "mevrouw", "de heer"],
+    },
+    "it": {
+        "verified": False,
+        "dateparser": "it",
+        "headers": {"from": ["da"], "sent": ["inviato", "data"], "to": ["a"], "cc": ["cc", "ccn"], "subject": ["oggetto"]},
+        "separators": ["messaggio originale", "messaggio inoltrato"],
+        "wrote": ["ha scritto"],
+        "greetings": ["gentile", "gentilissimo", "gentilissima", "egregio", "caro", "cara", "buongiorno", "buonasera", "salve", "ciao"],
+        "closings": ["cordiali saluti", "distinti saluti", "un saluto", "saluti", "cordialmente", "grazie mille", "grazie"],
+        "honorifics": ["sig", "sig.ra", "dott", "dott.ssa", "signor", "signora"],
+    },
+    "es": {
+        "verified": False,
+        "dateparser": "es",
+        "headers": {"from": ["de"], "sent": ["enviado", "fecha"], "to": ["para"], "cc": ["cc", "cco"], "subject": ["asunto"]},
+        "separators": ["mensaje original", "mensaje reenviado"],
+        "wrote": ["escribió"],
+        "greetings": ["estimado", "estimada", "estimados", "hola", "buenos días", "buenas tardes", "apreciado", "apreciada"],
+        "closings": ["saludos cordiales", "un saludo", "saludos", "atentamente", "cordialmente", "muchas gracias", "gracias"],
+        "honorifics": ["sr", "sra", "srta", "don", "doña"],
+    },
+    "pt": {
+        "verified": False,
+        "dateparser": "pt",
+        "headers": {"from": ["de"], "sent": ["enviado", "enviada", "data"], "to": ["para"], "cc": ["cc", "cco"], "subject": ["assunto"]},
+        "separators": ["mensagem original", "mensagem encaminhada"],
+        "wrote": ["escreveu"],
+        "greetings": ["prezado", "prezada", "caro", "cara", "olá", "bom dia", "boa tarde", "exmo", "exma"],
+        "closings": [
+            "atenciosamente", "com os melhores cumprimentos", "melhores cumprimentos", "cumprimentos",
+            "saudações", "obrigado", "obrigada", "abraço",
+        ],
+        "honorifics": ["sr", "sra", "dr", "dra"],
+    },
+    "pl": {
+        "verified": False,
+        "dateparser": "pl",
+        "headers": {"from": ["od"], "sent": ["wysłano", "data"], "to": ["do"], "cc": ["dw", "udw"], "subject": ["temat"]},
+        "separators": ["wiadomość oryginalna", "oryginalna wiadomość", "wiadomość przekazana dalej"],
+        "wrote": ["napisał(a)", "napisał", "napisała"],
+        "greetings": ["szanowny", "szanowna", "szanowni państwo", "dzień dobry", "witam", "cześć"],
+        "closings": ["z poważaniem", "z wyrazami szacunku", "serdecznie pozdrawiam", "pozdrawiam", "pozdrowienia", "dziękuję"],
+        "honorifics": ["pan", "pani", "panie"],
+    },
+    "cs": {
+        "verified": False,
+        "dateparser": "cs",
+        "headers": {"from": ["od"], "sent": ["odesláno", "datum"], "to": ["komu"], "cc": ["kopie"], "subject": ["předmět"]},
+        "separators": ["původní zpráva", "přeposlaná zpráva"],
+        "wrote": ["napsal(a)", "napsal", "napsala"],
+        "greetings": ["dobrý den", "vážený", "vážená", "vážení", "ahoj"],
+        "closings": ["s přátelským pozdravem", "s pozdravem", "děkuji", "díky"],
+        "honorifics": ["pan", "paní", "pane"],
+    },
+    "sv": {
+        "verified": False,
+        "dateparser": "sv",
+        "headers": {"from": ["från"], "sent": ["skickat", "datum"], "to": ["till"], "cc": ["kopia"], "subject": ["ämne"]},
+        "separators": ["ursprungligt meddelande", "vidarebefordrat meddelande"],
+        "wrote": ["skrev"],
+        "greetings": ["hej", "hejsan", "hallå", "god morgon", "bästa"],
+        "closings": ["med vänliga hälsningar", "vänliga hälsningar", "bästa hälsningar", "hälsningar", "mvh", "tack på förhand", "tack"],
+        "honorifics": [],
+    },
+    "da": {
+        "verified": False,
+        "dateparser": "da",
+        "headers": {"from": ["fra"], "sent": ["sendt", "dato"], "to": ["til"], "cc": ["cc"], "subject": ["emne"]},
+        "separators": ["oprindelig meddelelse", "videresendt meddelelse"],
+        "wrote": ["skrev"],
+        "greetings": ["hej", "kære", "goddag", "god morgen"],
+        "closings": ["med venlig hilsen", "venlig hilsen", "bedste hilsner", "hilsen", "mvh", "mange tak", "tak"],
+        "honorifics": [],
+    },
+    "no": {
+        "verified": False,
+        "dateparser": "nb",
+        "headers": {"from": ["fra"], "sent": ["sendt", "dato"], "to": ["til"], "cc": ["kopi"], "subject": ["emne"]},
+        "separators": ["opprinnelig melding", "videresendt melding"],
+        "wrote": ["skrev"],
+        "greetings": ["hei", "hallo", "kjære", "god morgen"],
+        "closings": ["med vennlig hilsen", "vennlig hilsen", "hilsen", "mvh", "tusen takk", "takk"],
+        "honorifics": [],
+    },
+    "fi": {
+        "verified": False,
+        "dateparser": "fi",
+        "headers": {
+            "from": ["lähettäjä"], "sent": ["lähetetty", "päivämäärä"], "to": ["vastaanottaja"], "cc": ["kopio"], "subject": ["aihe"],
+        },
+        "separators": ["alkuperäinen viesti", "välitetty viesti"],
+        "wrote": ["kirjoitti"],
+        "greetings": ["hei", "hyvä", "moi", "terve", "hyvää huomenta"],
+        "closings": ["ystävällisin terveisin", "parhain terveisin", "terveisin", "kiitos paljon", "kiitos"],
+        "honorifics": [],
+    },
+}
+
+
+def all_words(field: str) -> list[str]:
+    """Every word of one field across languages, longest first so regex alternation prefers it."""
+    words = {w for lang in LANGUAGES.values() for w in lang[field]}  # type: ignore[literal-required]
+    return sorted(words, key=lambda w: (-len(w), w))
+
+
+def header_labels() -> dict[str, str]:
+    """label (lowercase) -> canonical header name."""
+    return {label: key for lang in LANGUAGES.values() for key, labels in lang["headers"].items() for label in labels}
+
+
+def label_languages() -> dict[str, list[str]]:
+    """Sent/date label -> dateparser codes of the languages using it (e.g. 'data' -> it, pt, pl)."""
+    out: dict[str, list[str]] = {}
+    for lang in LANGUAGES.values():
+        for label in lang["headers"]["sent"]:
+            out.setdefault(label, [])
+            if lang["dateparser"] not in out[label]:
+                out[label].append(lang["dateparser"])
+    return out

email_thread_mcp-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,11 @@
+email_thread_mcp/__init__.py,sha256=VA_x7-P1kBOna1dMzKIvEjtjwmIsfCw-7uiOWi_gCvs,102
+email_thread_mcp/html_text.py,sha256=B76VSdt0fOW5_D7dImXibhSVHWuvIYMHfbTDf-4ytBM,5863
+email_thread_mcp/server.py,sha256=TmS0u6mYxELpngU88jCg7aWjpWbv67UvgskmbvJ4kBk,3180
+email_thread_mcp/thread.py,sha256=nKxJ8BM-Q_h_ML9asDB2x0Oj6qP4d0nRU0zadzuIChY,23458
+email_thread_mcp/validate.py,sha256=8KQxmlf99kBEKbkRvtpjEcXM2GjEMYfgZ3laPsbtJ1U,6698
+email_thread_mcp/vocab.py,sha256=e-seY064BuWrj9_UaU2czklgzoxoGjQDq2Jn0QOqUJg,10228
+email_thread_mcp-0.2.0.dist-info/METADATA,sha256=Azvkc1eoAVlbszpftc2km835KB4KPnB76z60VBrK_3E,5035
+email_thread_mcp-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+email_thread_mcp-0.2.0.dist-info/entry_points.txt,sha256=-wnZhzz3442_FZ632-C0cOkbSGUNSE8BqLbUGIVsp7s,66
+email_thread_mcp-0.2.0.dist-info/licenses/LICENSE,sha256=_tqcjbZk3EIYBYNlVAYkpebamRyLpBhbuKiOvfoEXTk,1064
+email_thread_mcp-0.2.0.dist-info/RECORD,,

email_thread_mcp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

email_thread_mcp-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+email-thread-mcp = email_thread_mcp.server:main

email_thread_mcp-0.2.0.dist-info/licenses/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.