@neschadin/sendgrid-mcp 0.0.0-stage → 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neschadin
+
+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.

package/MCP_TOOLS.md

@@ -0,0 +1,457 @@
+# SendGrid MCP Tools
+
+Scope: transactional email hardening and SendGrid-side diagnostics.  
+Out of scope: contact/list marketing CRUD.
+
+**Handshake metadata (v2):** Server name is `sendgrid-mcp-server`. The handshake `instructions` carry the safe-send and delivery workflow for this process (region, API base, from address). All tools are exposed as `sendgrid_<name>`. Mutating tools with required `confirmToken` automatically append `Requires confirmToken="CONFIRM".` to the tool `description`. Read tools expose `outputSchema`, `structuredContent`, optional `response_format` (`markdown`|`json`), and list pagination metadata (`total_count`, `count`, `offset`, `has_more`, `next_offset`). A tool call whose arguments contain more than 10000 combined array elements and object members is rejected before the handler runs. Tool results redact `oauth_client_secret` and `api_key`.
+
+## Core Runbooks
+
+### Runbook: Safe Send
+
+1. `sendgrid_validate_send_request`
+2. `sendgrid_send_with_preflight` (or `sendgrid_send_email_advanced`)
+3. On failure: `sendgrid_classify_sendgrid_error`
+4. On delivery doubts: `sendgrid_triage_delivery_issue`
+
+### Runbook: Delivery Incident
+
+1. `sendgrid_search_message_activity` / `sendgrid_get_message_activity` (or `sendgrid_search_email_logs` when Activity is empty or 403, especially on EU)
+2. `sendgrid_check_suppression` and `sendgrid_list_suppressions`; lift a hit with `sendgrid_delete_suppression`
+3. `sendgrid_triage_delivery_issue`
+4. If webhook exists: `sendgrid_get_received_webhook_events` + `sendgrid_analyze_engagement_anomalies`
+
+### Runbook: Webhook Operations
+
+1. `sendgrid_list_event_webhooks`
+2. `sendgrid_update_event_webhook` / `sendgrid_toggle_event_webhook_signature`
+3. `sendgrid_get_webhook_receiver_status`
+4. Send test traffic and inspect `sendgrid_get_received_webhook_events`
+
+---
+
+## Tool Catalog
+
+### `sendgrid_list_templates`
+- **Purpose:** List all dynamic templates from SendGrid (full pagination).
+- **Inputs:** none.
+- **Typical flow:** Inventory before edits/migrations.
+- **Caveats:** Returns dynamic templates only.
+
+### `sendgrid_rename_template`
+- **Purpose:** Rename one template by template ID.
+- **Inputs:** `confirmToken="CONFIRM"`, `templateId`, `newName`.
+- **Typical flow:** Safe targeted rename.
+- **Caveats:** Changes template display name only.
+
+### `sendgrid_rename_templates_bulk`
+- **Purpose:** Bulk rename by `templateId` and/or `oldName`.
+- **Inputs:** `renames[]`, optional `dryRun`, `confirmToken`, `stopOnError`, `requireUniqueOldName`.
+- **Typical flow:** Large naming migrations.
+- **Caveats:** Use `dryRun=true` first on production accounts.
+
+### `sendgrid_get_template_html`
+- **Purpose:** Read HTML of active or explicit template version.
+- **Inputs:** `templateId`, optional `versionId`.
+- **Output:** `structuredContent` with `templateId`, `versionId`, `active`, `name`, `subject`, `updatedAt`, `htmlContent`.
+- **Typical flow:** Inspect/render debugging.
+- **Caveats:** If `versionId` omitted, active version is used.
+
+### `sendgrid_create_template`
+- **Purpose:** Create a dynamic template with first active version.
+- **Inputs:** `confirmToken="CONFIRM"`, `name`, `versionName`, `subject`, `htmlContent`.
+- **Typical flow:** Bootstrap new notification templates.
+- **Caveats:** Creates both template and version in one operation.
+
+### `sendgrid_update_template_html`
+- **Purpose:** Update version-level content/subject/name.
+- **Inputs:** `confirmToken="CONFIRM"`, `templateId`, `versionId`, optional `htmlContent`, `subject`, `name`.
+- **Typical flow:** Iterative edits to an existing version.
+- **Caveats:** Does not auto-activate version.
+
+### `sendgrid_activate_template_version`
+- **Purpose:** Activate a template version.
+- **Inputs:** `confirmToken="CONFIRM"`, `templateId`, `versionId`.
+- **Typical flow:** Release updated template content.
+- **Caveats:** Only one version can be active.
+
+### `sendgrid_prune_inactive_template_versions`
+- **Purpose:** Delete inactive versions for one or more templates, keeping active versions.
+- **Inputs:** `templateIds[]`, optional `dryRun` (default `true`), optional `confirmToken` required when `dryRun=false`.
+- **Typical flow:** Cleanup after template version migrations.
+- **Caveats:** Destructive when `dryRun=false`; use dry-run first.
+
+### `sendgrid_delete_template`
+- **Purpose:** Permanently delete a template.
+- **Inputs:** `confirmToken="CONFIRM"`, `templateId`.
+- **Typical flow:** Cleanup unused templates.
+- **Caveats:** Irreversible.
+
+### `sendgrid_sync_template_ids`
+- **Purpose:** Compare local `SENDGRID_TEMPLATES` constants with live SendGrid templates.
+- **Inputs:** `constantsPath`.
+- **Typical flow:** Keep backend constants aligned with real template IDs.
+- **Caveats:** Local constants parsing is regex-based.
+
+### `sendgrid_validate_send_request`
+- **Purpose:** Preflight checks before send. Run this before any `send_*` call. Validates `/v3/mail/send` payload shape, active dynamic template, sender identity (domain authentication or verified sender), link branding alignment, recipient suppressions (including ASM group unsubscribe when `asm.groupId` is set), DMARC warn-list domains from `GET /v3/verified_senders/domains`, and scheduling limits (`send_at` future + within 72 hours).
+- **Inputs:** `request`, optional `partnerAccountId`, `checkSenderIdentity`.
+- **Output:** `structuredContent` with `ok`, `blockers`, `warnings`, `info`.
+- **Typical flow:** Dry-run review before every production send.
+- **Caveats:** Does not send email.
+
+### `sendgrid_send_with_preflight`
+- **Purpose:** Preferred production send path: runs `sendgrid_validate_send_request` checks first, then `POST /v3/mail/send` only when no blockers (and optionally no warnings with `abortOnWarnings`).
+- **Inputs:** `request`, optional `abortOnWarnings`, sender/account checks.
+- **Output:** `structuredContent` with `sent`, `report`, `statusCode`, `messageId`.
+- **Typical flow:** Default send path for automation. Use `sendgrid_validate_send_request` alone when you only need a dry-run.
+- **Caveats:** `abortOnWarnings=true` can block sends even without blockers.
+
+### `sendgrid_send_email_advanced`
+- **Purpose:** Full `/v3/mail/send` payload send.
+- **Inputs:** `request` (all advanced fields).
+- **Typical flow:** Use when payload already validated externally.
+- **Caveats:** No automatic preflight.
+
+### `sendgrid_send_template_email_advanced`
+- **Purpose:** Advanced dynamic template send.
+- **Inputs:** `to`, `templateId`, `dynamicTemplateData`, optional cc/bcc/asm/schedule.
+- **Typical flow:** Template-based transactional mails.
+- **Caveats:** Template/data mismatch can still fail if skipped preflight.
+
+### `sendgrid_send_sandbox_email`
+- **Purpose:** Send in SendGrid sandbox mode.
+- **Inputs:** `request`.
+- **Typical flow:** Validate payload integration without live delivery.
+- **Caveats:** No recipient delivery occurs.
+
+### `sendgrid_send_test_email`
+- **Purpose:** Thin convenience wrapper for template test send; sandbox mode is used by default.
+- **Inputs:** `to`, `templateId`, `mockData`, optional from override, optional `liveDelivery` + `confirmToken="CONFIRM"`.
+- **Typical flow:** Quick manual smoke tests.
+- **Caveats:** No live delivery occurs unless `liveDelivery=true` and `confirmToken` is provided.
+
+### `sendgrid_create_batch_id`
+- **Purpose:** Create batch ID for scheduling controls.
+- **Inputs:** none.
+- **Typical flow:** Prior to scheduled campaigns.
+- **Caveats:** Batch lifecycle controls require this ID.
+
+### `sendgrid_schedule_email`
+- **Purpose:** Schedule send (`send_at`) with optional batch auto-create.
+- **Inputs:** `request`, `sendAt`, optional `batchId`, `autoCreateBatchId`.
+- **Typical flow:** Deferred delivery and pacing.
+- **Caveats:** `sendAt` must be in the future and within SendGrid's 72-hour scheduling window.
+
+### `sendgrid_list_scheduled_sends`
+- **Purpose:** List batches that are paused or canceled (`GET /v3/user/scheduled_sends`).
+- **Inputs:** none.
+- **Caveats:** A `send_at` batch that was never paused or canceled is absent.
+
+### `sendgrid_get_scheduled_send`
+- **Purpose:** Read pause/cancel state for one `batch_id`.
+- **Inputs:** `batchId`.
+- **Caveats:** A missing batch comes back from SendGrid as `200` and `[]`, not 404. This tool reports that as not found.
+
+### `sendgrid_pause_scheduled_send`
+- **Purpose:** Pause scheduled batch.
+- **Inputs:** `confirmToken="CONFIRM"`, `batchId`.
+- **Typical flow:** Temporary stop before campaign window.
+- **Caveats:** Requires valid existing batch state.
+
+### `sendgrid_resume_scheduled_send`
+- **Purpose:** Resume by removing pause/cancel state.
+- **Inputs:** `confirmToken="CONFIRM"`, `batchId`.
+- **Typical flow:** Continue paused/canceled batch.
+- **Caveats:** Behavior is API `DELETE` of scheduled-send state entry.
+
+### `sendgrid_cancel_scheduled_send`
+- **Purpose:** Cancel scheduled batch.
+- **Inputs:** `confirmToken="CONFIRM"`, `batchId`.
+- **Typical flow:** Emergency stop.
+- **Caveats:** Near-send-time cancellation is not guaranteed by SendGrid.
+
+### `sendgrid_classify_sendgrid_error`
+- **Purpose:** Map SendGrid errors to probable causes and actions.
+- **Inputs:** `statusCode`, `errorMessage`, `rawBody`.
+- **Typical flow:** First response after API failure.
+- **Caveats:** Heuristic classification; combine with activity/suppressions.
+
+### `sendgrid_triage_delivery_issue`
+- **Purpose:** Scenario-based delivery runbook with live checks.
+- **Inputs:** `scenario` + optional recipient/from/template/message/activity params.
+- **Typical flow:** `202 accepted`, `processing`, template/auth/DMARC/deferral incidents.
+- **Caveats:** Depth depends on API access and provided identifiers.
+
+### `sendgrid_search_message_activity`
+- **Purpose:** Query Email Activity (`GET /v3/messages`) by SendGrid query syntax.
+- **Inputs:** `query` and/or `xMessageId`, optional `limit`. `offset` above 0 is rejected: this API has no offset.
+- **Typical flow:** Identify affected messages in an incident. Pass the Mail Send `x-message-id` response header as `xMessageId`; it is compiled to `msg_id LIKE '<id>%'`.
+- **Caveats:** May require the Email Activity add-on. `limit` is 1–1000. There is no cursor. On 403/404, and on an empty result when `SENDGRID_REGION=eu`, the tool falls back to `POST /v3/logs`.
+
+### `sendgrid_search_email_logs`
+- **Purpose:** Search Email Logs (`POST /v3/logs`) when Activity is missing, especially for EU regional subusers.
+- **Inputs:** optional `query`, `limit` (1–1000), `subusers` (parent account, exactly one username).
+- **Typical flow:** `to_email='user@example.com'`, `status IN ('bounced','deferred')`, or `sg_message_id='<full id>'`.
+- **Caveats:** Allowed fields are `sg_message_id`, `subject`, `to_email`, `status`, `reason`, `categories`, `sg_message_id_created_at`. Operators are `=` / `IN` / time comparisons. Combine with `AND`. No nesting. No event chain.
+
+### `sendgrid_get_message_activity`
+- **Purpose:** Fetch one message by `msg_id`, including the event chain (`reason`, `bounce_type`, `mx_server`, `asm_group_id`, `outbound_ip`).
+- **Inputs:** `msgId` — full `msg_id` or the Mail Send `x-message-id`.
+- **Typical flow:** Deep dive after search. An `x-message-id` is resolved with `msg_id LIKE` and then re-fetched.
+- **Caveats:** Activity may require the add-on. A full id that 403/404s is loaded from Email Logs, which has status and reason but no events. EU regional subusers often have no Activity detail.
+
+### `sendgrid_list_asm_groups`
+- **Purpose:** List ASM unsubscribe groups (`GET /v3/asm/groups`) so `asm.groupId` does not have to be guessed.
+- **Inputs:** none.
+- **Caveats:** Not a marketing contact list.
+
+### `sendgrid_create_asm_group`
+- **Purpose:** Create an ASM unsubscribe group.
+- **Inputs:** `confirmToken="CONFIRM"`, `name`, `description`, optional `isDefault`.
+- **Caveats:** Does not add recipients.
+
+### `sendgrid_list_categories`
+- **Purpose:** List category names (`GET /v3/categories`) for `sendgrid_get_email_stats` `dimension=category`.
+- **Inputs:** optional `category`, `limit`, `offset`.
+- **Caveats:** Names only, not metrics.
+
+### `sendgrid_list_suppressions`
+- **Purpose:** Enumerate suppression entries by type.
+- **Inputs:** `type`, optional pagination/time/email filters.
+- **Typical flow:** Bulk suppression audits.
+- **Caveats:** Does not mutate suppression lists. `global_unsubscribes` is an alias for SendGrid global unsubscribe listing.
+
+### `sendgrid_check_suppression`
+- **Purpose:** Check bounce, block, global unsubscribe, spam report, invalid-email, and ASM group suppression flags for one recipient (`GET /v3/asm/suppressions/{email}`).
+- **Inputs:** `email`.
+- **Typical flow:** Per-recipient delivery triage. Group rows include `id`, `name`, and `suppressed`.
+- **Caveats:** The ASM call returns every group, not only suppressed ones. A failed group lookup is reported in `groupLookupError` and does not clear the other flags.
+
+### `sendgrid_delete_suppression`
+- **Purpose:** Remove one recipient from bounce, block, spam report, invalid email, global unsubscribe, or a single ASM group.
+- **Inputs:** `confirmToken="CONFIRM"`, `email`, `type` (`bounce` | `block` | `spam_report` | `invalid_email` | `global` | `group`), `groupId` when `type=group`.
+- **Typical flow:** After `check_suppression` shows the list that is dropping mail.
+- **Caveats:** Does not delete the ASM group. `READ_ONLY=true` blocks the call before the API request.
+
+### `sendgrid_get_email_stats`
+- **Purpose:** Aggregate delivery metrics. `dimension=global` is the daily account rollup.
+- **Inputs:** `startDate`, optional `endDate`, `dimension` (`global` | `category` | `category_sums` | `mailbox_provider` | `geo` | `browser` | `device` | `client`), `aggregatedBy` (`day` | `week` | `month`). `category` requires `categories`. Optional `mailboxProviders`, `country`, `browsers`, `limit`.
+- **Typical flow:** Trend and blast-radius checks. Use `category` for categories sent on the mail payload, `mailbox_provider` for provider-specific drops.
+- **Caveats:** Aggregated metrics, not per-message forensics. Browser, device, and client stats retain about 7 days.
+
+### `sendgrid_list_subusers`
+- **Purpose:** List subusers on the parent account (`GET /v3/subusers`), including region when `includeRegion` is true (the default).
+- **Inputs:** optional `username`, `region` (`all` | `global` | `eu`), `limit`, `offset`, `includeRegion`.
+- **Typical flow:** Pick `username`, then pass it as `onBehalfOf` on later tools. `onBehalfOf` is optional on every tool. `onBehalfOf="parent"` ignores `SENDGRID_ON_BEHALF_OF` for that call.
+- **Caveats:** The parent API key must be allowed to list subusers. A key already scoped with `SENDGRID_ON_BEHALF_OF` is not the parent; pass `onBehalfOf="parent"` for this list.
+
+### `sendgrid_get_scopes`
+- **Purpose:** List scopes on the current API key (`GET /v3/scopes`).
+- **Inputs:** none.
+- **Typical flow:** After a 403, before guessing which scope is missing.
+- **Caveats:** Read-only. With `SENDGRID_ON_BEHALF_OF` set, scopes are evaluated for that subuser/customer account.
+
+### `sendgrid_list_event_webhooks`
+- **Purpose:** List Event Webhook configurations in SendGrid.
+- **Inputs:** optional `includeAccountStatusChange`.
+- **Typical flow:** Validate webhook fleet and event subscriptions.
+- **Caveats:** Read-only inventory.
+
+### `sendgrid_get_event_webhook`
+- **Purpose:** Read one webhook configuration by ID.
+- **Inputs:** `id`, optional include flag.
+- **Typical flow:** Confirm exact event toggles and URL.
+- **Caveats:** Requires valid webhook ID.
+
+### `sendgrid_update_event_webhook`
+- **Purpose:** Update webhook URL, enabled flag, and event toggles.
+- **Inputs:** `id` + selected fields.
+- **Typical flow:** Enable missing events / switch endpoint URL.
+- **Caveats:** Signature mode is managed separately.
+
+### `sendgrid_manage_event_webhook`
+- **Purpose:** Create, delete, or test an Event Webhook (`POST /user/webhooks/event/settings`, `DELETE /user/webhooks/event/settings/{id}`, `POST /user/webhooks/event/test`).
+- **Inputs:** `confirmToken="CONFIRM"`, `action` (`create` | `delete` | `test`), `url` for create, `id` for delete. Test uses `url`, or the saved webhook URL when only `id` is set. Optional event toggles match `update_event_webhook`.
+- **Typical flow:** Point `url` at the local receiver, create, then test.
+- **Caveats:** `oauth_client_secret` is redacted in the tool result. Delete does not remove the local receiver.
+
+### `sendgrid_toggle_event_webhook_signature`
+- **Purpose:** Enable/disable signed Event Webhook mode.
+- **Inputs:** `id`, `enabled`.
+- **Typical flow:** Enforce cryptographic source verification.
+- **Caveats:** Public key changes can require receiver updates.
+
+### `sendgrid_get_webhook_receiver_status`
+- **Purpose:** Show local receiver runtime state and counters.
+- **Inputs:** none.
+- **Typical flow:** Verify receiver health after config or ngrok changes.
+- **Caveats:** Local receiver must be enabled via env.
+
+### `sendgrid_get_received_webhook_events`
+- **Purpose:** Read buffered incoming Event Webhook payloads.
+- **Inputs:** optional `limit`, `eventType`, `email`, `messageId`, `onlyVerified`.
+- **Typical flow:** Incident reconstruction from near-real-time events.
+- **Caveats:** In-memory buffer only; not persistent storage.
+
+### `sendgrid_clear_received_webhook_events`
+- **Purpose:** Clear local buffered webhook events.
+- **Inputs:** `confirm=true`.
+- **Typical flow:** Reset local buffer between test runs.
+- **Caveats:** Irreversible in-memory clear.
+
+---
+
+## Account & Console Settings
+
+### Runbook: Account Audit (read-only)
+
+1. `sendgrid_get_account_info` + `sendgrid_get_user_credits`
+2. `sendgrid_list_verified_senders` + `sendgrid_list_authenticated_domains` + `sendgrid_list_branded_links`
+3. `sendgrid_list_mail_settings` / `sendgrid_list_tracking_settings` + targeted `get_*_setting`
+4. `sendgrid_list_alerts` + `sendgrid_list_inbound_parse_settings`
+
+### Runbook: Console Change (mutating)
+
+1. Read current state with Phase 1 tools
+2. Apply change with `confirmToken=CONFIRM` on mutating tool
+3. Re-read setting and run delivery preflight if sender/domain related
+
+### Phase 1 — Account read tools
+
+All Phase 1 read tools return `structuredContent` + `outputSchema` (account/profile/credits as JSON records; list tools return `{ count, <items> }`).
+
+- `sendgrid_get_account_info` — `GET /user/account`
+- `sendgrid_get_user_profile` — `GET /user/profile`
+- `sendgrid_get_user_credits` — `GET /user/credits`
+- `sendgrid_list_verified_senders` / `sendgrid_get_verified_sender`
+- `sendgrid_list_authenticated_domains` / `sendgrid_get_authenticated_domain`
+- `sendgrid_list_branded_links` / `sendgrid_get_branded_link`
+- `sendgrid_list_alerts` / `sendgrid_get_alert`
+- `sendgrid_get_enforced_tls` — `GET /user/settings/enforced_tls`
+- `sendgrid_list_mail_settings` / `sendgrid_get_mail_setting`
+- `sendgrid_list_tracking_settings` / `sendgrid_get_tracking_setting`
+- `sendgrid_list_inbound_parse_settings`
+
+### Phase 2 — Console mutation tools
+
+All mutating tools require `confirmToken: "CONFIRM"` (also stated in each tool's MCP `description`).
+
+- `sendgrid_create_verified_sender` / `sendgrid_resend_verified_sender_verification` / `sendgrid_delete_verified_sender`
+- `sendgrid_create_authenticated_domain` / `sendgrid_validate_authenticated_domain` / `sendgrid_validate_branded_link`
+- `sendgrid_update_branded_link`
+- `sendgrid_create_alert` / `sendgrid_update_alert` / `sendgrid_delete_alert`
+- `sendgrid_update_mail_setting` — PATCH `/mail_settings/{name}`
+- `sendgrid_update_tracking_setting` — PATCH `/tracking_settings/{name}`
+- `sendgrid_create_inbound_parse_setting` / `sendgrid_update_inbound_parse_setting` / `sendgrid_delete_inbound_parse_setting`
+
+**Caveats:** API key must include scopes for the target endpoint (e.g. `mail_settings.footer.update`, `tracking_settings.click.update`, `alerts.create`). Some settings are account-plan dependent.
+
+---
+
+## Optional Event Webhook Receiver (ngrok-ready)
+
+Enable by setting env:
+
+- `SENDGRID_EVENT_WEBHOOK_PORT` (required)
+- `SENDGRID_EVENT_WEBHOOK_HOST` (default `0.0.0.0`)
+- `SENDGRID_EVENT_WEBHOOK_PATH` (default `/sendgrid/events`)
+- `SENDGRID_EVENT_WEBHOOK_HEALTH_PATH` (default `/sendgrid/events/health`)
+- `SENDGRID_EVENT_WEBHOOK_MAX_EVENTS` (default `5000`)
+
+Signature mode:
+
+- `SENDGRID_EVENT_WEBHOOK_REQUIRE_SIGNATURE` (`true`/`false`)
+- `SENDGRID_EVENT_WEBHOOK_PUBLIC_KEY` (required if signature required)
+
+---
+
+## Risk Matrix
+
+Risk levels:
+
+- `read-only` — no mutation in SendGrid/local state
+- `send` — can enqueue/send email
+- `mutates-sendgrid` — changes remote SendGrid configuration/state
+- `mutates-local` — changes local in-memory/buffer state
+
+Tool risk classification:
+
+- `sendgrid_list_templates`: `read-only`
+- `sendgrid_rename_template`: `mutates-sendgrid`
+- `sendgrid_rename_templates_bulk`: `mutates-sendgrid`
+- `sendgrid_get_template_html`: `read-only`
+- `sendgrid_create_template`: `mutates-sendgrid`
+- `sendgrid_update_template_html`: `mutates-sendgrid`
+- `sendgrid_activate_template_version`: `mutates-sendgrid`
+- `sendgrid_prune_inactive_template_versions`: `mutates-sendgrid`
+- `sendgrid_delete_template`: `mutates-sendgrid`
+- `sendgrid_sync_template_ids`: `read-only`
+- `sendgrid_validate_send_request`: `read-only`
+- `sendgrid_send_with_preflight`: `send`
+- `sendgrid_send_email_advanced`: `send`
+- `sendgrid_send_template_email_advanced`: `send`
+- `sendgrid_send_sandbox_email`: `send`
+- `sendgrid_send_test_email`: `send`
+- `sendgrid_create_batch_id`: `mutates-sendgrid`
+- `sendgrid_list_scheduled_sends`: `read-only`
+- `sendgrid_get_scheduled_send`: `read-only`
+- `sendgrid_schedule_email`: `send`
+- `sendgrid_pause_scheduled_send`: `mutates-sendgrid`
+- `sendgrid_resume_scheduled_send`: `mutates-sendgrid`
+- `sendgrid_cancel_scheduled_send`: `mutates-sendgrid`
+- `sendgrid_search_message_activity`: `read-only`
+- `sendgrid_search_email_logs`: `read-only`
+- `sendgrid_get_message_activity`: `read-only`
+- `sendgrid_list_event_webhooks`: `read-only`
+- `sendgrid_get_event_webhook`: `read-only`
+- `sendgrid_update_event_webhook`: `mutates-sendgrid`
+- `sendgrid_toggle_event_webhook_signature`: `mutates-sendgrid`
+- `sendgrid_manage_event_webhook`: `mutates-sendgrid`
+- `sendgrid_get_webhook_receiver_status`: `read-only`
+- `sendgrid_get_received_webhook_events`: `read-only`
+- `sendgrid_clear_received_webhook_events`: `mutates-local`
+- `sendgrid_classify_sendgrid_error`: `read-only`
+- `sendgrid_triage_delivery_issue`: `read-only`
+- `sendgrid_analyze_engagement_anomalies`: `read-only`
+- `sendgrid_list_asm_groups`: `read-only`
+- `sendgrid_create_asm_group`: `mutates-sendgrid`
+- `sendgrid_list_categories`: `read-only`
+- `sendgrid_list_suppressions`: `read-only`
+- `sendgrid_check_suppression`: `read-only`
+- `sendgrid_delete_suppression`: `mutates-sendgrid`
+- `sendgrid_get_email_stats`: `read-only`
+- `sendgrid_get_scopes`: `read-only`
+- `sendgrid_list_subusers`: `read-only`
+- `sendgrid_get_account_info`: `read-only`
+- `sendgrid_get_user_profile`: `read-only`
+- `sendgrid_get_user_credits`: `read-only`
+- `sendgrid_list_verified_senders`: `read-only`
+- `sendgrid_get_verified_sender`: `read-only`
+- `sendgrid_list_authenticated_domains`: `read-only`
+- `sendgrid_get_authenticated_domain`: `read-only`
+- `sendgrid_list_branded_links`: `read-only`
+- `sendgrid_get_branded_link`: `read-only`
+- `sendgrid_list_alerts`: `read-only`
+- `sendgrid_get_alert`: `read-only`
+- `sendgrid_get_enforced_tls`: `read-only`
+- `sendgrid_list_mail_settings`: `read-only`
+- `sendgrid_get_mail_setting`: `read-only`
+- `sendgrid_list_tracking_settings`: `read-only`
+- `sendgrid_get_tracking_setting`: `read-only`
+- `sendgrid_list_inbound_parse_settings`: `read-only`
+- `sendgrid_create_verified_sender`: `mutates-sendgrid`
+- `sendgrid_resend_verified_sender_verification`: `mutates-sendgrid`
+- `sendgrid_delete_verified_sender`: `mutates-sendgrid`
+- `sendgrid_create_authenticated_domain`: `mutates-sendgrid`
+- `sendgrid_validate_authenticated_domain`: `mutates-sendgrid`
+- `sendgrid_validate_branded_link`: `mutates-sendgrid`
+- `sendgrid_update_branded_link`: `mutates-sendgrid`
+- `sendgrid_create_alert`: `mutates-sendgrid`
+- `sendgrid_update_alert`: `mutates-sendgrid`
+- `sendgrid_delete_alert`: `mutates-sendgrid`
+- `sendgrid_update_mail_setting`: `mutates-sendgrid`
+- `sendgrid_update_tracking_setting`: `mutates-sendgrid`
+- `sendgrid_create_inbound_parse_setting`: `mutates-sendgrid`
+- `sendgrid_update_inbound_parse_setting`: `mutates-sendgrid`
+- `sendgrid_delete_inbound_parse_setting`: `mutates-sendgrid`

package/README.md

@@ -1,3 +1,176 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="assets/sendgrid-logo.png" alt="SendGrid" width="320" />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# SendGrid MCP Server
+
+This server is for **transactional send and delivery**, not a map of the whole SendGrid API.
+
+A thin SendGrid MCP treats `POST /v3/mail/send` as one call and spends the rest of its tools on contacts, lists, and campaigns. Those marketing APIs are out of scope here. The tools follow the checks SendGrid's own delivery troubleshooting expects:
+
+1. **Before send.** `sendgrid_validate_send_request` checks the `/v3/mail/send` payload, that the dynamic template version is active, sender identity (domain authentication or a verified sender), link branding, recipient suppressions including the ASM group on the send, the DMARC warn list (`GET /v3/verified_senders/domains`), and that `send_at` is in the future and inside 72 hours. `sendgrid_send_with_preflight` posts only when that report has no blockers. Sandbox mode accepts the payload and does not deliver.
+2. **After accept.** The `x-message-id` response header is not a `msg_id`. Pass it as `xMessageId`; search compiles `msg_id LIKE '<id>%'`, then `sendgrid_get_message_activity` reads the event chain (`reason`, `bounce_type`, `asm_group_id`, `outbound_ip`). Email Activity has no real offset. If Activity returns 403/404, or the region is `eu` and Activity is empty, use Email Logs (`POST /v3/logs`) with `to_email` equality. Logs rejects `msg_id`, `from_email`, and `LIKE`.
+3. **When it did not arrive.** `sendgrid_check_suppression` and `sendgrid_triage_delivery_issue` cover bounce, block, spam, invalid, global unsubscribe, and ASM groups. `sendgrid_delete_suppression` lifts one entry. `sendgrid_classify_sendgrid_error` and `sendgrid_get_scopes` explain a 403. Paused or canceled scheduled batches are listed; a batch that was only given `send_at` is not in that list until you pause or cancel it.
+4. **The pipe around the send.** Dynamic templates (including bulk rename and pruning inactive versions), Event Webhook create/update/test plus an optional local receiver, and the console settings that change delivery: domains, link branding, enforced TLS, mail and tracking settings, alerts, inbound parse.
+
+Install: `bunx --no-env-file x @neschadin/sendgrid-mcp`.
+
+Full catalog and runbooks: [`MCP_TOOLS.md`](./MCP_TOOLS.md).
+
+This project is community-maintained and is not affiliated with, endorsed by, or sponsored by Twilio SendGrid.
+
+## Requirements
+
+- [Bun](https://bun.sh) ≥ 1.4.2
+- A [SendGrid API key](https://app.sendgrid.com/settings/api_keys) with scopes for the tools you call. Keys normally start with `SG.`; any other prefix only logs a warning
+- A verified sender address in `SENDGRID_FROM_EMAIL`
+- An MCP client (Cursor, Claude Desktop, VS Code, etc.)
+
+One process, one API key. Do not share a hosted instance across tenants.
+
+## Configuration
+
+### Required
+
+| Variable              | Description                            |
+| --------------------- | -------------------------------------- |
+| `SENDGRID_API_KEY`    | SendGrid API key                       |
+| `SENDGRID_FROM_EMAIL` | Default From address (verified sender) |
+
+### SendGrid
+
+| Variable                 | Default        | Description                                                                                                      |
+| ------------------------ | -------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `SENDGRID_FROM_NAME`     | `SendGrid MCP` | Default From display name                                                                                        |
+| `SENDGRID_REGION`        | `global`       | `global` or `eu` (case-insensitive). `eu` uses `https://api.eu.sendgrid.com/v3` and falls back to Email Logs when Activity is empty |
+| `SENDGRID_API_BASE_URL`  | from region    | Override the API host. `https://` or `http://`                                                                   |
+| `SENDGRID_ON_BEHALF_OF`  | —              | Default `on-behalf-of` header: a subuser username, or `account-id <id>`                                          |
+| `READ_ONLY`              | `false`        | `true` blocks send and mutating tools before any request                                                         |
+| `SENDGRID_MCP_LOG_LEVEL` | `info`         | `debug`, `info`, `warn`, or `error`                                                                              |
+
+Every tool also accepts `onBehalfOf`. The value `"parent"` skips `SENDGRID_ON_BEHALF_OF` for that call. List subusers with `sendgrid_list_subusers` (the parent key needs that scope; this key may 403).
+
+Handshake `instructions` repeat the region, API base, from address, and the workflow above. A tool call with more than 10000 combined array elements and object members is rejected. Results replace `oauth_client_secret` and `api_key` values with a length marker.
+
+### Remote HTTP
+
+Leave `MCP_TRANSPORT` unset for stdio. Set `MCP_TRANSPORT=http` to serve Streamable HTTP on `/mcp` (`/health` is unauthenticated).
+
+| Variable              | Default        | Description                                                                 |
+| --------------------- | -------------- | --------------------------------------------------------------------------- |
+| `MCP_HTTP_HOST`       | `127.0.0.1`    | Bind address                                                                |
+| `MCP_HTTP_PORT`       | `3000`         | Port                                                                        |
+| `MCP_AUTH_MODE`       | `token`        | `token` or `none`. `none` is refused when the bind address is not loopback |
+| `MCP_AUTH_TOKEN`      | —              | Bearer token. Required for `token` mode                                    |
+| `MCP_ALLOWED_HOSTS`   | loopback names | Comma-separated `Host` allowlist. Required off loopback                     |
+| `MCP_ALLOWED_ORIGINS` | loopback names | Comma-separated `Origin` allowlist. A missing `Origin` is allowed           |
+| `MCP_TLS_KEY_FILE`    | —              | TLS key. Set together with `MCP_TLS_CERT_FILE`                              |
+| `MCP_TLS_CERT_FILE`   | —              | TLS certificate                                                             |
+| `MCP_TRUST_PROXY`     | `false`        | Allow plaintext HTTP off loopback only behind your own TLS proxy            |
+
+### Local Event Webhook receiver
+
+Off until `SENDGRID_EVENT_WEBHOOK_PORT` is set. The buffer is in-memory (default 5000 events) and is dropped when the process exits.
+
+| Variable                                   | Default                   |
+| ------------------------------------------ | ------------------------- |
+| `SENDGRID_EVENT_WEBHOOK_HOST`              | `0.0.0.0`                 |
+| `SENDGRID_EVENT_WEBHOOK_PATH`              | `/sendgrid/events`        |
+| `SENDGRID_EVENT_WEBHOOK_HEALTH_PATH`       | `/sendgrid/events/health` |
+| `SENDGRID_EVENT_WEBHOOK_MAX_EVENTS`        | `5000`                    |
+| `SENDGRID_EVENT_WEBHOOK_VERBOSE`           | `false`                   |
+| `SENDGRID_EVENT_WEBHOOK_REQUIRE_SIGNATURE` | `false`                   |
+| `SENDGRID_EVENT_WEBHOOK_PUBLIC_KEY`        | required when signature is required |
+
+Point the SendGrid Event Webhook URL at the tunnel, for example `https://<ngrok-host>/sendgrid/events`. Read what arrived with `sendgrid_get_received_webhook_events` and `sendgrid_get_webhook_receiver_status`. Create or test the SendGrid-side webhook with `sendgrid_manage_event_webhook`.
+
+## MCP client setup
+
+### Cursor
+
+[`mcp.json.example`](./mcp.json.example). `--no-env-file` stops Bun from also reading a `.env` in the client cwd. In `~/.cursor/mcp.json`, `envFile` must be an absolute path.
+
+```json
+{
+  "mcpServers": {
+    "sendgrid": {
+      "command": "bunx",
+      "args": ["--no-env-file", "x", "@neschadin/sendgrid-mcp"],
+      "envFile": "${workspaceFolder}/.env"
+    }
+  }
+}
+```
+
+Remote HTTP, after the server process is started with `MCP_TRANSPORT=http`:
+
+```json
+{
+  "mcpServers": {
+    "sendgrid": {
+      "url": "https://mcp.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer <MCP_AUTH_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+No `envFile`. The desktop cwd is not your repo, so pass an absolute `--env-file`:
+
+```json
+{
+  "mcpServers": {
+    "sendgrid": {
+      "command": "bunx",
+      "args": [
+        "--no-env-file",
+        "--env-file=/absolute/path/.env",
+        "x",
+        "@neschadin/sendgrid-mcp"
+      ]
+    }
+  }
+}
+```
+
+Restart the client after changing MCP config.
+
+## Safety
+
+- Send tools can enqueue real mail. They do not ask for `confirmToken`. Use `sendgrid_send_with_preflight`, or set `READ_ONLY=true`.
+- Tools that change SendGrid (templates, suppressions, webhooks, domains, settings, scheduled-send pause/cancel) require `confirmToken` `"CONFIRM"`.
+- `READ_ONLY=true` blocks both sends and those mutations before the HTTP call.
+- Email Activity (`/v3/messages`) may require the [Email Activity add-on](https://www.twilio.com/docs/sendgrid/api-reference/email-activity/filter-all-messages).
+
+## Development
+
+A git tag `vX.Y.Z` runs tests, publishes `@neschadin/sendgrid-mcp` to npm, then publishes `io.github.Neschadin/sendgrid-mcp` to the MCP registry. The release has no binary assets.
+
+```bash
+git clone https://github.com/Neschadin/sendgrid-mcp.git
+cd sendgrid-mcp
+bun install
+bun run dev          # stdio MCP; loads .env
+bun run lint
+bun run typecheck
+bun run smoke
+bun test
+```
+
+```bash
+bun run inspect
+```
+
+## Docs
+
+- [MCP_TOOLS.md](./MCP_TOOLS.md) — tools, runbooks, risk matrix
+- [SendGrid API reference](https://www.twilio.com/docs/sendgrid/api-reference)
+- [SendGrid for developers](https://www.twilio.com/docs/sendgrid/for-developers)
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/sendgrid-mcp

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import '../src/index.ts';

package/mcp.json.example

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "sendgrid": {
+      "command": "bunx",
+      "args": ["--no-env-file", "x", "@neschadin/sendgrid-mcp"],
+      "envFile": "${workspaceFolder}/.env"
+    }
+  }
+}