macos-apps-mcp

Overview Schema Source Related Servers Discussions Admin

mail_index_ids

Read-only

Builds or refreshes a Message-ID sidecar for SQLite mail access on macOS 15 and earlier by harvesting headers from local .emlx files, enabling message citation without opening or altering Mail data.

Instructions

Build/refresh the Message-ID sidecar that enables the sqlite mail plane on macOS 15 (Sequoia) and earlier (#201). Those systems' Envelope Index never stored the RFC822 Message-ID (#199); this harvests it headers-only from the .emlx files at rest into this server's own sidecar — never launches Mail, never writes in Mail's data. On macOS 26+ the index has the column natively and this build is unnecessary. Safe to re-run: a re-run harvests only what is missing and retries messages whose files had not been downloaded yet; rebuild=True starts from scratch. A full first build reads every message's headers — about a minute per 35k messages on a slow disk. Returns {harvested, mapped, total_ids, coverage, skipped_no_file, skipped_no_message_id, rows_without_local_store, high_water_rowid, index_rebuilt}. coverage is the number that matters: messages it could not map stay uncitable, exactly as they would be on macOS 26 until Mail backfills its own column. Read-only for Mail; needs Full Disk Access (it reads .emlx at rest), NOT Automation.

Input Schema

Name	Required	Description	Default
`rebuild`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.15.1Oct 26, 2026

TDQS

A4.1/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description says it builds/refreshes a sidecar and that rebuild=True starts from scratch, which implies persistent writes to server-side storage. This conflicts with the annotation readOnlyHint=true, even though the description limits read-only behavior to Mail's data specifically.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and the information is dense and useful, including auth and performance context. It is somewhat overlong and redundantly lists return fields despite an output schema, but most sentences still carry meaningful operational detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the key operational context: macOS applicability, Full Disk Access versus Automation, safety for Mail, re-run semantics, performance expectations, and coverage interpretation. Given the output schema, the remaining return-field explanation is extra rather than missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema provides 0% parameter description coverage, the description fully explains the single rebuild boolean: default re-runs harvest only missing data, while rebuild=True starts from scratch. This adds the exact semantics an agent needs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: build/refresh a Message-ID sidecar for the sqlite mail plane on macOS 15 and earlier. It also explains the OS boundary where it is unnecessary, so an agent can distinguish it from related mail-index tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when the tool is needed (macOS 15 and earlier without native Message-ID storage) and when it is unnecessary (macOS 26+). It also clarifies re-run behavior and the effect of rebuild=True, giving clear invocation guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server