OraCool/email-thread-mcp

MCP server (stdio) with three 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). A table row of short cells becomes one line, cells joined by \| , so an invoice stays next to its date and amount | 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 |
| assemble_output(envelope, schema?, allowed_categories?, thread?, allowed_actions?) | last step of a workflow whose engine assembles the envelope from earlier steps' values with a template, so no model copies them: the validate_output checks, then a JSON Schema check. Returns the envelope plus validation | contracts/assemble.schema.json |
Use
Any MCP client that starts stdio servers can run it with uvx:
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,
envelope, schema, allowed_categories, allowed_actions, 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.
Use assemble_output instead when a workflow engine can build the envelope itself. A model that copies
identifiers, invoice numbers or a draft into a final JSON answer changes some of them; a template that
renders each value with a JSON filter does not. Its argument names (envelope, schema,
allowed_categories, thread, allowed_actions) are chosen not to clash with the usual step outputs, since some engines
fill an argument from a context variable of the same name. A failed check does not raise: it is
reported in validation, so the caller still gets the output to review. With allowed_actions (the
suggested-action vocabulary), an action that differs from a listed one only in case, punctuation or
underscores is corrected; one outside the list is kept as a new action, with a warning. An argument that is still an
unrendered template (a variable it uses was not set) raises an error that says so.
For the reply, two fields save the drafting model from reading the whole thread:
- reply_to_greeting: how to address reply_to_name. If our earlier message opened "Dear Mr. Berg,",
it is Mr. Berg for Jan Berg; otherwise the name as given. No honorific is added that no message states.
- our_signature: the signature block of our quoted message, to sign the reply with. Our message is
the one from ar_mailboxes or, without them, the one signed by the person the customer greets