This server lets LLM clients convert .eml email files into clean Markdown, bundles, batch outputs, and quality diagnostics — all locally.
convert_eml: Convert a single .eml file to Markdown with YAML front matter; optionally write it to an output path.
convert_eml_to_bundle: Create a self-contained bundle with converted Markdown, extracted attachments, and a copy of the original .eml.
convert_directory: Recursively batch-convert all .eml files in a directory, returning a JSON summary of successes, failures, and output paths.
get_diagnostics: Inspect email quality and structure — body selection, segmentation, client hint, confidence, warnings, and conditional attachment/stripped-image details — without writing permanent files.
Presets and flags: Use default, clean, verbose, or raw presets, plus per-call overrides for signatures, disclaimers, tracking pixels, inline images, headers, calendar summaries, and thread mode/order.
Turn .eml email exports into clean, local, LLM-ready Markdown.
dead-letter converts .eml email exports into clean Markdown with YAML front matter — threads split, signatures stripped, attachments extracted, calendars parsed. One file or ten thousand.
Use it to build a readable email archive, move messages into Markdown-based knowledge systems, or prepare email for RAG and LLM pipelines without feeding raw MIME and base64 into your context window. No account, upload, or API key required.
If you already have uv, run dead-letter without installing it globally:
uvx --python 3.12 dead-letter convert message.emlOr install with Homebrew or pip below. Agents and MCP clients can use the client-specific setup in llms-install.md.
Related MCP server: DingusMail
Email → Markdown archives — turn exported .eml collections into readable, portable Markdown with structured metadata
RAG and LLM ingestion — normalize message text, thread structure, links, and attachment metadata before chunking or indexing
Agent workflows — expose conversion and diagnostics directly to Claude, Codex, and other MCP clients
Knowledge bases — move email into Markdown-first systems such as Obsidian, static archives, or local search pipelines
Digital preservation — retain human-readable content and useful message structure without depending on one mail client
Full-fidelity conversion — HTML sanitization, Gmail/Outlook thread segmentation, inline image handling, and calendar event summaries
CLI — point it at a file or a directory and go
Local web UI — dark command-center interface with drag-and-drop import, watch mode, conversion grade badges, processing history, and per-job diagnostics
Inbox/Cabinet workflow — drop .eml files into an Inbox, let dead-letter organize the Markdown bundles into a Cabinet
Install validation — dead-letter doctor checks your runtime environment
Conversion report — opt-in JSON report with per-file diagnostics, including attachment referenced/retained counts for automation and audit
MCP server — integrate with Claude Desktop, Claude Code, Codex, and other MCP clients
Claude plugin — marketplace install in Claude Code or Cowork with four slash commands (/dead-letter:convert, /dead-letter:summarize, /dead-letter:triage, /dead-letter:cabinet)
Portable Agent Skill — teaches skill-aware agents when and how to convert .eml files
Python API — from dead_letter import convert and you're off
Raw .eml files are noisy input for downstream LLM and retrieval pipelines — MIME headers, multipart boundaries, duplicated HTML/plain bodies, and encoded attachments all get mixed into the text path.
dead-letter normalizes that into Markdown with YAML front matter, so message text and metadata are ready for chunking or indexing without MIME parsing or base64 cleanup. Default convert() and convert_dir() runs write a single .md per message and keep attachment names in front matter.
To separate the filesystem artifacts too, bundle and Cabinet workflows write message.md plus retained decoded files under attachments/. The Markdown is ready for text ingestion, while PDFs, spreadsheets, calendar files, and other retained binary attachments stay cleanly split out for whatever downstream parser you already use.
For direct LLM integration, the MCP server lets clients call dead-letter's conversion tools without shelling out. Conversion is local; your chosen MCP host may still send returned email text to a remote model.
dead-letter's value isn't fewer tokens than every alternative — it's fidelity per token: keeping useful email structure without carrying raw MIME into context. Measured across an 11-message synthetic corpus of HTML threads, attachments, and newsletters (tokenizer o200k_base, structured thread mode):
~88% fewer tokens than the raw .eml in the reported aggregate comparison — the attachment category's median is ~126k tokens raw vs ~180 converted.
Structure survives — thread structure, per-message sender attribution, links, and attachment metadata remain readable. The tested naive baselines are often cheaper because they discard information (0/2 attachment names retained vs dead-letter's 2/2).
Those counts measure the Markdown representation, not the contents of retained binary attachments or downstream answer quality. The shipping default is latest-message mode; the benchmark uses structured mode for a same-thread comparison.
The benchmark is honest about where it loses: naive extraction is fewer tokens when you don't mind throwing away metadata, links, and thread structure. Full method, the complete table (including those rows), tokenizer disclosure, and a one-command reproduce are in benchmarks/.
Pick one route. The distribution map explains how the channels fit together; installing all of them is not necessary.
You want | Start here |
Core CLI or Python API | Homebrew / pip below, or the |
Local web UI |
|
Claude Desktop extension or another MCP client | |
Claude Code / Cowork commands | |
Container-isolated MCP | |
Portable agent instructions |
With Homebrew on Apple silicon macOS:
brew tap BigCactusLabs/tap
brew install dead-letterThe Homebrew formula installs the core CLI only: dead-letter convert and
dead-letter doctor. It intentionally does not bundle the optional web UI or
MCP server dependency stacks.
With pip:
pip install dead-letter # core + CLI
pip install 'dead-letter[cli]' # + watchfiles (used by backend/UI watch mode)
pip install 'dead-letter[ui]' # + web UI, API server, and watch mode
pip install 'dead-letter[mcp]' # + MCP serverUse pipx for an isolated UI or MCP install:
pipx install 'dead-letter[ui]' # installs dead-letter and dead-letter-ui
# Or, for MCP instead:
pipx install 'dead-letter[mcp]' # installs dead-letter and dead-letter-mcpOr run individual entrypoints without a global package install using uvx:
uvx --python 3.12 dead-letter convert message.eml
uvx --python 3.12 --from 'dead-letter[mcp]' dead-letter-mcpuv caches tools/dependencies and may download Python on first use. These unpinned trial commands do not promise a fresh latest version on every run; see version pinning for a reviewed deployment.
From source:
git clone https://github.com/BigCactusLabs/dead-letter.git
cd dead-letter
uv sync --extra dev --locked # all extras
# Or choose only the surface you're developing:
uv sync --extra ui --locked # UI only
uv sync --extra mcp --locked # MCP onlyInstall the portable Agent Skill into whichever agent you use:
gh skill install BigCactusLabs/dead-letter dead-letter --agent claude-code
gh skill install BigCactusLabs/dead-letter dead-letter --agent codex
gh skill install BigCactusLabs/dead-letter dead-letter --agent github-copilotNeeds gh 2.90 or newer. The skill is independent of the Claude plugin. Pin a
reviewed skill tag/commit for reproducibility; the default latest release can
also be a plugin release. For exact pin syntax, other hosts, manual installation,
and discovery metadata, see Agent Discovery.
CLI — convert a single file:
dead-letter convert message.emlConvert a whole directory:
dead-letter convert inbox/ --output out/Generate a JSON conversion report alongside the output:
dead-letter convert inbox/ --output out/ --reportWith --output, the report is written to that output directory as
.dead-letter-report.json. Without --output, file conversions write the
report next to the source message and directory conversions write it to the
input directory root.
Check your runtime environment:
dead-letter doctorDirectory conversion scans recursively for .eml files, matches the suffix
case-insensitively, skips symlinked files whose resolved targets escape the
requested input tree, and deduplicates in-tree symlink aliases that resolve to
the same message file.
Web UI — start the local server:
dead-letter-ui --host 127.0.0.1 --port 8765Open http://127.0.0.1:8765 — on first launch, a setup prompt suggests default Inbox and Cabinet folders. Configure those folders before importing or starting jobs. Skipping dismisses the prompt but leaves those actions gated until setup is completed. Import .eml files with drag and drop or the file picker. Single-file imports use file mode, while multi-file drops create one directory-mode batch job. Mixed drops ask for confirmation before skipping non-.eml files.
The backend enforces a 100 MB per-file import limit for both single and batch uploads; browser batches also have aggregate-size and file-count limits.
From a source checkout, prefix with uv run:
uv run dead-letter convert message.eml
uv run --extra ui dead-letter-ui --host 127.0.0.1 --port 8765from dead_letter import convert
result = convert("message.eml")
print(result.subject, result.sender)
print(result.output) # path to the generated .mdWith options:
from dead_letter import convert, ConvertOptions
result = convert("message.eml", options=ConvertOptions(
strip_signatures=True,
strip_quoted_headers=True,
))Strip signature images (logos, social icons) and tracking pixels:
result = convert("message.eml", options=ConvertOptions(
strip_signature_images=True,
strip_tracking_pixels=True,
))When enabled, these filters remove matched images from rendered Markdown and omit stripped inline signature/tracking assets from bundle attachment output.
Bundle conversion (Markdown + attachments + source in one directory):
from dead_letter import convert_to_bundle
bundle = convert_to_bundle("message.eml", bundle_root="cabinet/", source_handling="copy")
print(bundle.markdown) # cabinet/message/message.md
print(bundle.attachments) # retained extracted files under cabinet/message/attachments/source_handling="copy" preserves the original .eml in place. If omitted,
convert_to_bundle() defaults to source_handling="move" and moves the source
message into the bundle.
Retained extracted attachment filenames are normalized to safe basenames before
they are written under attachments/.
Quality diagnostics include referenced/retained attachment counts when a message has attachments eligible for retention, so dropped artifacts are machine-detectable. See Quality Diagnostics.
Batch:
from dead_letter import convert_dir
for r in convert_dir("inbox/", output="out/"):
print(f"{'✓' if r.success else '✗'} {r.source.name}")dead-letter ships an MCP server so LLM clients can convert .eml files directly without shelling out.
VS Code, Cursor, and Cline:
Install in VS Code · Install in Cursor
Requires uv/uvx on the desktop client's PATH. These links configure a local
stdio server using the published PyPI package; no catalog admission is needed.
First use may download Python and dependencies. Review the command, scope, and
tool permissions before accepting. Cline setup, manual JSON examples, and
verification: Client installation.
Launch it directly with uvx:
uvx --python 3.12 --from 'dead-letter[mcp]' dead-letter-mcpOr install the MCP extra first:
pip install 'dead-letter[mcp]'
dead-letter-mcpFrom a source checkout:
uv run --extra mcp dead-letter-mcpClaude Desktop (extension bundle):
Download the .mcpb file and its .sha256 sidecar from a published package release (vX.Y.Z) on the releases page. Plugin-only releases do not contain this bundle. Verify the bytes before installation:
# macOS: verifies against the downloaded sidecar
shasum -a 256 -c dead-letter-mcp-X.Y.Z.mcpb.sha256
# Windows (PowerShell): compare this hash to the sidecar's hash
certutil -hashfile dead-letter-mcp-X.Y.Z.mcpb SHA256Replace X.Y.Z with the selected package version. In a compatible Claude Desktop build, double-click the downloaded bundle, drag it onto the window, or use Settings > Extensions > Advanced settings > Install Extension. Check that the extension connects and exposes the four tools below, then convert a synthetic message.
The bundle uses a managed uv runtime and an exact package pin. First launch may download Python and dependencies. A checksum or command-line smoke test is not proof of a successful GUI installation on your client version. For hosts without MCPB support, use manual stdio setup below.
Claude Desktop (manual claude_desktop_config.json — alternative):
{
"mcpServers": {
"dead-letter": {
"command": "uvx",
"args": ["--python", "3.12", "--from", "dead-letter[mcp]", "dead-letter-mcp"]
}
}
}Merge the entry rather than replacing existing client settings. VS Code and other hosts can use different schemas; see the agent install guide.
Claude Code or Cowork (recommended — Claude plugin):
/plugin marketplace add BigCactusLabs/bigcactuslabs-plugins
/plugin install dead-letterThe plugin launches the MCP server via uvx and adds four slash commands: /dead-letter:convert, /dead-letter:summarize, /dead-letter:triage, /dead-letter:cabinet. Local Claude Code needs uv on PATH; see plugin/ for runtime-specific setup and updates. Email content is treated as untrusted data, not instructions: embedded requests for tool use, credentials, or exfiltration are not followed.
The marketplace pins the plugin tag and commit, and its launcher pins an exact published Python package. Claude Code and Cowork keep separate installed copies; update and verify each client. Those pins do not freeze every transitive dependency.
Claude Code (manual MCP add — alternative):
claude mcp add dead-letter -- uvx --python 3.12 --from 'dead-letter[mcp]' dead-letter-mcpCodex:
codex mcp add dead-letter -- uvx --python 3.12 --from 'dead-letter[mcp]' dead-letter-mcp
codex mcp listmcp list confirms registration, not a successful tool call. Connect through the target client, confirm all four tools, and convert a synthetic fixture before treating the installation as verified.
Tool | Required arguments | Returns |
|
| Markdown text. Also writes a file when |
|
| JSON with |
|
| JSON summary. Capped at 50 |
|
| Quality and structure JSON. Writes nothing permanent. |
All four take a preset (default, clean, verbose, raw) and per-flag overrides. Full contract, including the MCP-only constraints and the error-text table: docs/reference/v4-runtime-contracts.md.
src/dead_letter/
├── core/ # conversion pipeline (MIME, HTML, threads, rendering)
├── backend/ # CLI, API server, job runner, watch mode, MCP server
└── frontend/ # static web UI (Alpine.js ES modules + vanilla fetch)
tests/
├── core/ # conversion pipeline tests with .eml fixtures
├── backend/ # API, job, and watch tests
├── plugin/ # plugin, skill, packaging, and release contracts
└── frontend/ # JS unit testsThe agent guide maps bundle, container, skill, and maintainer tooling without turning this README into a file inventory.
uv sync --extra dev --locked
uv run pytest -q tests/core # conversion pipeline
uv run pytest -q tests/backend # API and job runner
uv run pytest -q tests/plugin # plugin, skill, packaging, and release contracts
node --test tests/frontend/*.test.js
python scripts/release.py check # offline distribution metadataCI also validates plugin/skill schemas, frontend syntax, maintained Markdown links, and cross-platform packaging. Full commands and the distinction between offline contracts and real client tests are in Contributing.
Docs Index — choose by task, not by filename
Distribution map — CLI, UI, MCPB, plugin, container, and skill choices
Agent install guide — client-specific setup and verification
Runtime Contracts — full API and core behavior spec
Publishing — tagging, channel order, and recovery
Agent Guide — operational guide for AI coding agents working in this repo
MarkEdit — TextEdit for Markdown, native macOS, ~4 MB. Opens dead-letter output like it was always meant to live there.
mo — local Markdown viewer that renders files in the browser with live reload. Point it at your Cabinet and read converted mail like a feed.
.eml input only; MBOX/Gmail Takeout containers, PST, and MSG are not shipped input formats. No live-mailbox connection.
Local-only, single-user, single-machine; no remote server or authentication service. An MCP host may send results to its model provider.
In-memory job registry: state resets on restart. Retained binary attachments need a separate parser for text indexing.
PolyForm Noncommercial 1.0.0 — free for personal, educational, and nonprofit use. Commercial use requires a separate license from Big Cactus Labs.
Batch convert all .eml files in a directory to Markdown.
Recursively finds all .eml files and converts them. Returns a JSON summary with total, successes, failures, output_paths, and errors.
Use convert_eml to retrieve individual converted file content.
| Name | Required | Description | Default |
|---|---|---|---|
| preset | No | default | |
| dry_run | No | ||
| directory | Yes | ||
| thread_mode | No | latest | |
| thread_order | No | oldest-first | |
| include_raw_html | No | ||
| output_directory | No | ||
| strip_signatures | No | ||
| strip_disclaimers | No | ||
| embed_inline_images | No | ||
| include_all_headers | No | ||
| no_calendar_summary | No | ||
| strip_quoted_headers | No | ||
| strip_tracking_pixels | No | ||
| strip_signature_images | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description adds value by stating batch conversion, recursion, and JSON summary structure, but lacks info on side effects, permissions, or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with purpose, no fluff, and ends with a helpful alternative reference.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (15 parameters), the description covers only basic behavior and output, leaving the agent without insight into key configuration options.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage and 15 parameters, the description provides no explanation for any parameter beyond the directory. Agent has no guidance on presets, dry_run, etc.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool batch converts .eml files in a directory to Markdown, with recursive behavior, and distinguishes itself from sibling convert_eml by mentioning individual file retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear alternative: use convert_eml for individual file content. However, it does not explicitly state when not to use this tool or mention the sibling convert_eml_to_bundle.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a .eml email file to Markdown with YAML front matter.
Returns the full Markdown content (front matter + body). When output_path is provided, also writes the file to disk.
Presets bundle common flag combinations:
default: strips signatures, tracking pixels, signature images
clean: default + strips disclaimers and quoted headers
verbose: includes all headers and raw HTML
raw: no stripping, preserves everything
Individual flags override the preset when provided.
| Name | Required | Description | Default |
|---|---|---|---|
| preset | No | default | |
| eml_path | Yes | ||
| output_path | No | ||
| thread_mode | No | latest | |
| thread_order | No | oldest-first | |
| include_raw_html | No | ||
| strip_signatures | No | ||
| strip_disclaimers | No | ||
| embed_inline_images | No | ||
| include_all_headers | No | ||
| no_calendar_summary | No | ||
| strip_quoted_headers | No | ||
| strip_tracking_pixels | No | ||
| strip_signature_images | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the return value (Markdown with front matter), the optional disk write, and the behavior of presets and flag overrides. However, it does not explain the thread_mode and thread_order parameters, leaving some behavioral aspects unexplained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with six sentences, front-loaded with the core action, and uses a clear bullet-like list for presets. Every sentence adds value without repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (14 parameters, presets, output schema), the description covers the main purpose, return value, presets, and override logic. It lacks explanation for thread_mode and thread_order, but overall provides sufficient context for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It explains presets and mentions several flags (signatures, tracking pixels, etc.), and notes that individual flags override presets. However, it omits details for thread_mode, thread_order, and some boolean flags. The presets bundling compensates partially.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool converts .eml to Markdown with YAML front matter, specifying the output format and the optional file write. It implicitly distinguishes from siblings like convert_directory and convert_eml_to_bundle by focusing on a single file conversion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on preset usage and flag overrides, but it does not explicitly state when to use this tool versus sibling tools like convert_directory or convert_eml_to_bundle, which would help an agent choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a .eml file to a self-contained bundle with markdown and attachments.
Creates a directory containing the converted markdown, extracted attachments, and optionally the original .eml source.
source_handling only accepts 'copy' over MCP: the original .eml is copied into the bundle and left untouched. The 'move' and 'delete' modes are rejected here — use the CLI or the Python API for those.
Returns JSON with bundle_path, markdown_path, attachment_paths, and optional diagnostics.
| Name | Required | Description | Default |
|---|---|---|---|
| preset | No | default | |
| eml_path | Yes | ||
| bundle_root | Yes | ||
| thread_mode | No | latest | |
| thread_order | No | oldest-first | |
| source_handling | No | copy | |
| include_raw_html | No | ||
| strip_signatures | No | ||
| strip_disclaimers | No | ||
| embed_inline_images | No | ||
| include_all_headers | No | ||
| no_calendar_summary | No | ||
| strip_quoted_headers | No | ||
| strip_tracking_pixels | No | ||
| strip_signature_images | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool creates a directory, copies the .eml, leaves the source untouched, and returns a JSON structure with specific fields. It also discloses that move/delete modes are rejected. However, it does not mention potential side effects like overwriting existing directories, error handling, or permissions. Still, the core mutation and side-effect profile is clear, warranting a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is about 120 words, organized into a brief purpose statement, a note on source_handling, and a return-value summary. It is not excessively verbose and front-loads the core action. Some redundancy exists (e.g., stating the return format), but it remains appropriately sized for the complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite an output schema (which the description partially covers by naming returned fields), the tool has 15 parameters and 0% schema description coverage. The description only addresses source_handling, leaving the meaning of presets, thread modes, and all boolean flags unexplained. This is a significant gap for an agent to invoke the tool correctly with the full range of options.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only explains source_handling, noting the 'copy' limitation. The other 14 parameters (preset, thread_mode, thread_order, boolean flags) are left undefined. The description adds value for one parameter but fails to clarify the vast majority, leaving agents without essential meaning for the options they may set.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: converting an .eml file into a self-contained bundle with markdown and attachments. It uses a specific verb and resource, but does not differentiate from sibling tools like convert_eml or convert_directory. The purpose is unambiguous, earning a 4 rather than a 5 because it lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a constraint on source_handling (only 'copy' is accepted over MCP, with guidance to use CLI/API for other modes) but does not explain when to choose this tool over its siblings. There is no mention of convert_eml, convert_directory, or get_diagnostics as alternatives for different scenarios. The guidance is parameter-specific rather than tool-selection-focused.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect email quality and structure without writing permanent files.
Use this to assess conversion quality before committing, or to troubleshoot problematic .eml files.
Always returns JSON with: state (normal/degraded/review_recommended), selected_body, segmentation_path, client_hint, confidence, fallback_used, and warnings. Two keys are conditional: stripped_images appears only when images were removed, and attachments only when the message had attachments eligible for retention.
| Name | Required | Description | Default |
|---|---|---|---|
| preset | No | default | |
| eml_path | Yes | ||
| thread_mode | No | latest | |
| thread_order | No | oldest-first | |
| include_raw_html | No | ||
| strip_signatures | No | ||
| strip_disclaimers | No | ||
| embed_inline_images | No | ||
| include_all_headers | No | ||
| no_calendar_summary | No | ||
| strip_quoted_headers | No | ||
| strip_tracking_pixels | No | ||
| strip_signature_images | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It explicitly states the operation is non-destructive ('without writing permanent files'), and thoroughly describes the return structure: 'Always returns JSON with: state (normal/degraded/review_recommended), selected_body, segmentation_path, client_hint, confidence, fallback_used, and warnings.' It also details conditional keys (stripped_images only when images removed, attachments only when eligible), providing comprehensive insight into output behavior without relying on annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: it opens with the core purpose, then provides usage guidance, and ends with a precise list of return keys and conditional behaviors. Each sentence adds value, there is no fluff, and the most critical information (non-destructive, purpose, use cases) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description thoroughly explains the return format and gives usage context, it leaves the 13 parameters completely undocumented. Given the tool's complexity (multiple enums, boolean toggles) and the lack of schema descriptions, an agent would not be able to correctly configure parameters without external knowledge. The output schema exists (per context signals) and the description explains return values, but the absence of parameter semantics makes the definition incomplete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description provides no explanation of any of the 13 parameters. While the description mentions some related behaviors (e.g., conditional keys for stripped images and attachments), it does not explain what parameters like 'preset', 'thread_mode', 'strip_signatures', or 'include_raw_html' actually control. The agent is left to infer from parameter names alone, which is insufficient for a tool with this many options. The description fails to compensate for the schema's lack of parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Inspect email quality and structure without writing permanent files.' It specifies the verb ('inspect'), the resource ('email quality and structure'), and the non-destructive nature. It also names use cases ('assess conversion quality before committing, or to troubleshoot problematic .eml files'), which effectively distinguishes it from the sibling conversion tools (convert_eml, convert_eml_to_bundle, convert_directory) that perform transformations rather than inspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage scenarios: 'Use this to assess conversion quality before committing, or to troubleshoot problematic .eml files.' This gives clear context for when to use the tool. However, it does not explicitly state when not to use it or mention the sibling conversion tools as alternatives, relying on the implicit inference that conversion tools are for transforming files while this inspects them. A slight improvement would be naming the alternatives directly, so 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.4convert_directoryconvert_emlconvert_eml_to_bundleget_diagnosticsScored across 4 tools
The tools are mostly distinct: single-file conversion, bundle conversion, batch directory conversion, and diagnostics each target a different workflow. convert_eml and convert_eml_to_bundle could be confused at a glance, but their descriptions clearly separate the content-only path from the attachment-inclusive bundle path.
Three tools follow the convert_* naming pattern, and get_diagnostics is a reasonable verb_noun deviation that still fits the overall style. The names are predictable and readable, with only the extra '_to_bundle' modifier creating a slight inconsistency.
Four tools is well-scoped for an email conversion server: single conversion, bundle conversion, batch conversion, and diagnostics. Each tool has a clear purpose and none feel redundant or excessive.
The server covers the core workflow of converting EML files to Markdown, including batch processing, attachment bundling, and pre-conversion diagnostics. Minor gaps exist—such as no direct batch-with-options or bundle-specific options—but the main workflows have no dead ends.
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
Document conversion MCP server: PDF to Markdown, image OCR, spreadsheet parsing.
