Problem/Motivation

Operators and governed agents that work with a site over MCP cannot see the state of this module. "Is webhook intake alive?", "Is a secret about to expire?" and "Will mail to this address be blocked, and why?" can only be answered in the admin UI or with Drush on the server.

The module already has bounded, recipient-free services for these questions: HealthEvaluator::evaluate(), PolicyPreview::diagnostics(), PolicyPreview::preview(), IntegrationOutbox::inspect() and, in the reconcile submodule, ScheduledReconciliation::reports().

Proposed resolution

Add an optional submodule, postmark_webhooks_mcp, that exposes read-only Tool API plugins over those services. The base module keeps its dependencies and its Drupal floor. The submodule depends on Tool API and MCP Sentinel and requires Drupal 10.6 or 11.3 and later, which is what those projects support.

  • postmark_webhooks_health: the health report. No mailboxes, no secrets.
  • postmark_webhooks_diagnostics: readiness, coverage and intake counters.
  • postmark_webhooks_delivery_preview: for one address and mail path, whether this module would block the message and the reason code. The address is input only and is never returned or logged. The lookup is written to the operator audit.
  • postmark_webhooks_message_timeline: retained events for one exact MessageID, with recipients masked. Requires the existing view permission.
  • postmark_webhooks_outbox_status: recent integration outbox rows.
  • postmark_webhooks_drift_reports: recent drift reports, available only when the reconcile submodule is installed.

Every tool is read-only, bounded, uses a new restricted permission, and refuses with one fixed message so caller input and exception text are never echoed.

Not tools, by design: hard-bounce recovery, recipient export and erasure, reconciliation apply, outbox dispatch or replay, retention drain, and anything that touches webhook credentials. Those stay human-confirmed.

Remaining tasks

  • Kernel tests: discovery and direct execution, anonymous and wrong-permission refusal, governance not ready, invalid input does not leak, no recipient in any output, reconcile tool hidden when the submodule is absent.
  • CI step for the optional submodule on the 10.6 and 11.x lanes.
  • README section and CHANGELOG entry.

API changes

None in the base module. The tools bind to services marked internal, inside the same project.

Comments

jmcerda created an issue. See original summary.

jmcerda’s picture

jmcerda
Location Boca Raton, FL
commented
Status: Active » Fixed

Committed to 1.x. The optional postmark_webhooks_mcp submodule adds six read-only tools: health, diagnostics, delivery preview, message timeline, outbox status and drift reports. A findings review after the first commit tightened the output: the outbox tool returns an error flag instead of the stored error text, results are capped at the lower of 128 KiB and the MCP Sentinel profile cap, and CI fails unless the submodule tests ran. The stored error text itself is tracked in #3624451.

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

  • jmcerda committed 17fd6e5f on 1.x 
    Issue #3624443: Inject the response-size resolver instead of a static...

  • jmcerda committed 5568ee3c on 1.x 
    Issue #3624443: Tighten tool output after review

- Outbox status...

  • jmcerda committed cc519eb6 on 1.x 
    Issue #3624443: Add optional read-only MCP tools submodule...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.