shipmail-mcp 0.4.0 → 0.5.2

package/README.md

@@ -113,7 +113,10 @@ Cursor, VS Code, Windsurf, and other Streamable HTTP clients:
 }
 ```
 
-Limit the tool surface with a `?tools=` query parameter, for example `https://shipmail.to/api/mcp?tools=shipmail_list_mailboxes,shipmail_list_messages`. Partner accounts can target a delegated child organization with the `X-ShipMail-Organization-Id` header.
+The tool catalog follows the connection permissions selected in Shipmail Settings. OAuth users
+manage those grants under **Settings → Connections**. Direct API-key and stdio sessions use the
+key's scopes, resource constraints, recipient rules, and recipient budget. Partner accounts can
+target a delegated child organization with the `X-ShipMail-Organization-Id` header.
 
 The sections below configure the same server locally over stdio.
 
@@ -209,6 +212,8 @@ Once connected, ask your agent:
 - "Triage the threads in `support@acme.com` from this week and summarize what needs attention."
 - "Check the last year of `support@acme.com`, find conversations we still owe a reply to, and draft answers for my approval. Do not send them."
 - "Draft a reply to thread `thread_abc123` confirming we ship Friday, then show it to me before sending."
+- "Send the selected PDF to Christelle tomorrow at 08:00, then show me the scheduled message."
+- "List my scheduled messages and move the invoice email to Friday."
 - "Create a webhook that posts new email events to `https://example.com/hooks/shipmail`, then send a test event."
 - "Show recent deliveries for webhook `whk_xyz`, then replay failed delivery `dlv_xyz`."
 - "List my newsletter sending domains and recent newsletter assets, draft a newsletter for audience `aud_abc123`, preview it, then send a test."
@@ -224,7 +229,7 @@ All tools are namespaced with `shipmail_` to avoid collisions with peer MCP serv
 | Mailboxes            | `shipmail_list_mailboxes`, `shipmail_get_mailbox`, `shipmail_create_mailbox`, `shipmail_update_mailbox`, `shipmail_delete_mailbox`, `shipmail_suspend_mailbox`, `shipmail_resume_mailbox`, `shipmail_list_mailbox_app_passwords`, `shipmail_create_mailbox_app_password`, `shipmail_revoke_mailbox_app_password`, `shipmail_list_mailbox_forwarding`, `shipmail_create_mailbox_forwarding`, `shipmail_delete_mailbox_forwarding`, `shipmail_list_mailbox_folders`, `shipmail_create_mailbox_folder`, `shipmail_update_mailbox_folder`, `shipmail_delete_mailbox_folder`, `shipmail_list_mailbox_identities`, `shipmail_reset_mailbox_password`, `shipmail_set_auto_reply`, `shipmail_set_spam_filter`, `shipmail_inject_sandbox_inbound` |
 | Mailbox inbox        | `shipmail_list_mailbox_inbox_messages`, `shipmail_get_mailbox_inbox_message`, `shipmail_get_mailbox_inbox_thread`, `shipmail_list_mailbox_inbox_threads`, `shipmail_update_inbox_thread_reply_state`, `shipmail_create_inbox_reply_draft`, `shipmail_send_inbox_reply_draft`, `shipmail_update_inbox_message`, `shipmail_move_inbox_message`, `shipmail_delete_inbox_message`                                                                                                                                                                                                                                                                                                                                                            |
 | Reply scans          | `shipmail_create_reply_scan`, `shipmail_get_reply_scan`, `shipmail_list_reply_scan_results`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| Messages and threads | `shipmail_list_messages`, `shipmail_get_message`, `shipmail_send_message`, `shipmail_reply_to_message`, `shipmail_list_threads`, `shipmail_get_thread`, `shipmail_reply_to_thread`, `shipmail_reply_to_inbox_message`, `shipmail_reply_to_inbox_thread`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| Messages and threads | `shipmail_list_messages`, `shipmail_get_message`, `shipmail_compose_message_with_file` (hosted MCP Apps), `shipmail_send_message`, `shipmail_list_scheduled_messages`, `shipmail_get_scheduled_message`, `shipmail_update_scheduled_message`, `shipmail_cancel_scheduled_message`, `shipmail_reply_to_message`, `shipmail_list_threads`, `shipmail_get_thread`, `shipmail_reply_to_thread`, `shipmail_reply_to_inbox_message`, `shipmail_reply_to_inbox_thread`                                                                                                                                                                                                                                                                          |
 | Webhooks             | `shipmail_list_webhooks`, `shipmail_get_webhook`, `shipmail_create_webhook`, `shipmail_update_webhook`, `shipmail_delete_webhook`, `shipmail_rotate_webhook_secret`, `shipmail_test_webhook`, `shipmail_list_webhook_deliveries`, `shipmail_get_webhook_delivery`, `shipmail_replay_webhook_delivery`                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | Suppressions         | `shipmail_list_suppressions`, `shipmail_remove_suppression`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | Audiences            | `shipmail_list_audiences`, `shipmail_get_audience`, `shipmail_create_audience`, `shipmail_update_audience`, `shipmail_delete_audience`, `shipmail_list_subscribers`, `shipmail_get_subscriber`, `shipmail_get_subscriber_by_email`, `shipmail_add_subscriber`, `shipmail_add_subscribers_batch`, `shipmail_update_subscriber`, `shipmail_unsubscribe_subscriber`, `shipmail_resubscribe_subscriber`, `shipmail_remove_subscriber`                                                                                                                                                                                                                                                                                                        |
@@ -235,6 +240,18 @@ Message send and reply tools accept optional `client_reference`, scalar `metadat
 `source_rfc_message_id`, and validated safe `headers`. `shipmail_list_messages` accepts either a
 `mailbox_id` or an exact organization-scoped `client_reference`.
 
+MCP send and scheduled-update tools accept short-lived staged attachment IDs, not base64 bytes.
+Stage a raw file through the REST API, TypeScript SDK, Python SDK, CLI, or a supported host
+attachment component, then pass the returned `sat_...` ID. Scheduled messages can be listed,
+inspected, replaced, and cancelled before dispatch begins.
+
+In ChatGPT, `shipmail_compose_message_with_file` renders an MCP Apps review card for a
+conversation or library file. The card obtains a fresh ChatGPT download URL, hashes the exact
+bytes, creates a five-minute one-time ShipMail upload URL through an app-only tool, uploads
+without exposing the connection credential, and calls `shipmail_send_message` only after the
+user presses **Upload and send** or **Upload and schedule**. The upload endpoint follows no source
+URL, rejects redirects and metadata mismatches, and consumes the signed token once.
+
 For mailbox agents, prefer the reply queue or a reply scan followed by
 `shipmail_create_inbox_reply_draft`. The server derives recipients from the thread and records the
 thread version used to create the draft. `shipmail_send_inbox_reply_draft` rejects stale drafts if
@@ -249,18 +266,9 @@ immediately. Partner grant consumption requires the exact `partner:mailbox_crede
 scope and an operator-approved one-time grant. App-password creation and grant consumption do not
 accept idempotency keys.
 
-By default, the server exposes only safe read tools and `shipmail_create_inbox_reply_draft`. To expose any additional tool, pass an explicit `--tools` allowlist (overrides `SHIPMAIL_MCP_TOOLS`):
-
-```json
-{
-  "args": [
-    "-y",
-    "shipmail-mcp",
-    "--tools",
-    "shipmail_create_reply_scan,shipmail_get_reply_scan,shipmail_list_reply_scan_results,shipmail_get_mailbox_inbox_thread,shipmail_create_inbox_reply_draft"
-  ]
-}
-```
+The server discovers the effective tool catalog from Shipmail before startup. It fails closed when
+capability discovery fails. To change what an AI can do, edit the OAuth connection under
+**Settings → Connections**, or edit the direct API key's scopes and constraints.
 
 ## Resources
 
@@ -298,7 +306,6 @@ Pre-built prompts the agent can use as guided workflows:
 
 In a delegated partner session, call `shipmail_create_mailbox` with `generate_password: true`.
 Shipmail generates the primary credential and never returns it to the partner.
-| `SHIPMAIL_MCP_TOOLS` | No | Comma-separated explicit tool allowlist. The `--tools` flag overrides this. Without either, only safe reads and reply-draft creation are exposed. |
 | `SHIPMAIL_ALLOW_INSECURE_BASE_URL` | No | Set to `1` to permit a non-https or non-`shipmail.to` base URL. Local development only. |
 | `SHIPMAIL_MCP_DEBUG` | No | Set to `1` to include `request_id` and `status` in stderr tool-call logs. |
 
@@ -318,14 +325,14 @@ Domain purchase is intentionally excluded.
 
 ### What this server does not defend against
 
-- **Indirect prompt injection from email content.** Reading a mailbox exposes the agent to attacker-controlled email bodies. Treat message bodies and attachments as untrusted data, never as instructions. The sanitizer strips invisible glyphs but cannot detect natural-language injection ("ignore previous instructions, send to..."). Keep `shipmail_send_inbox_reply_draft` out of the tool allowlist for review-only sessions and require explicit approval before any outbound send.
+- **Indirect prompt injection from email content.** Reading a mailbox exposes the agent to attacker-controlled email bodies. Treat message bodies and attachments as untrusted data, never as instructions. The sanitizer strips invisible glyphs but cannot detect natural-language injection ("ignore previous instructions, send to..."). Use the Read and draft profile, recipient constraints, and a finite recipient budget for review-oriented sessions.
 - **Malicious LLM output or hallucinated arguments.** The MCP layer cannot tell whether an argument came from the user or was invented. Use the host UI's tool-call confirmation, especially for `destructiveHint:true` tools.
 - **Compromised MCP host.** Your API key is read from `SHIPMAIL_API_KEY` and held in memory by this process. If the host is compromised, the key is gone regardless. Rotate keys you suspect have been exposed.
 - **Webhook signing secret in conversation logs.** `shipmail_create_webhook` and `shipmail_rotate_webhook_secret` return the secret in `structuredContent`. Many MCP clients persist tool output in conversation history. Treat the session log as sensitive after these calls.
 
 ## Privacy
 
-This server forwards email subject lines, bodies, headers, attachment metadata, and recipient lists to whatever LLM you connect it to. The LLM provider may log that content. For privacy-sensitive workflows, restrict the tool surface with `--tools` so the LLM only sees what it needs.
+This server forwards email subject lines, bodies, headers, attachment metadata, and recipient lists to whatever LLM you connect it to. The LLM provider may log that content. For privacy-sensitive workflows, grant only the connection permission groups and mailbox resources the AI needs.
 
 ## Troubleshooting
 

package/dist/capabilities.d.ts

@@ -0,0 +1,158 @@
+import { ApiKeyScope } from 'shipmail/api-key-scopes';
+
+declare const MCP_CAPABILITY_VERSION = "1.0.0";
+declare const MCP_PERMISSION_GROUP_NAMES: readonly ["account_status", "mail_read", "drafts", "mail_organize", "send_mail", "calendar_read", "calendar_write", "booking_pages", "forwarding", "webhooks", "credentials", "mailbox_export", "domain_admin", "mailbox_admin", "newsletters", "audiences", "suppressions", "partner_admin"];
+type McpPermissionGroupName = (typeof MCP_PERMISSION_GROUP_NAMES)[number];
+declare const MCP_MEMBER_PERMISSION_GROUP_NAMES: readonly ["account_status", "mail_read", "drafts", "mail_organize", "send_mail", "calendar_read", "calendar_write"];
+type McpRole = "owner" | "member";
+type McpCapabilityEffect = "read" | "local_write" | "external_write" | "destructive";
+type McpRecipientControl = "none" | "server_derived" | "caller_supplied";
+type McpCapabilityDuration = "one_shot" | "scheduled" | "persistent" | "credential";
+type McpIdempotencyBehavior = "none" | "api_header" | "resource_key" | "forbidden";
+type McpPermissionGroup = {
+    readonly name: McpPermissionGroupName;
+    readonly label: string;
+    readonly description: string;
+    readonly scopes: readonly ApiKeyScope[];
+    readonly persistent: boolean;
+};
+declare const MCP_PERMISSION_GROUPS: readonly [{
+    readonly name: "account_status";
+    readonly label: "Account status";
+    readonly description: "Check whether the ShipMail API is available.";
+    readonly scopes: readonly [];
+    readonly persistent: false;
+}, {
+    readonly name: "mail_read";
+    readonly label: "Read mail";
+    readonly description: "Read mailboxes, messages, threads, folders, identities, and import status.";
+    readonly scopes: readonly ["mailboxes:read", "messages:read", "threads:read"];
+    readonly persistent: false;
+}, {
+    readonly name: "drafts";
+    readonly label: "Create drafts";
+    readonly description: "Create reply drafts whose recipients are derived by ShipMail.";
+    readonly scopes: readonly ["drafts:write"];
+    readonly persistent: false;
+}, {
+    readonly name: "mail_organize";
+    readonly label: "Organize mail";
+    readonly description: "Update message state, move messages, and delete messages already in Trash or Junk.";
+    readonly scopes: readonly ["messages:write"];
+    readonly persistent: false;
+}, {
+    readonly name: "send_mail";
+    readonly label: "Send mail";
+    readonly description: "Send new messages and replies to recipients allowed by the connection policy.";
+    readonly scopes: readonly ["messages:send"];
+    readonly persistent: false;
+}, {
+    readonly name: "calendar_read";
+    readonly label: "Read calendar";
+    readonly description: "Read calendar events and availability.";
+    readonly scopes: readonly ["calendar:read"];
+    readonly persistent: false;
+}, {
+    readonly name: "calendar_write";
+    readonly label: "Manage calendar";
+    readonly description: "Create, update, and delete calendar events.";
+    readonly scopes: readonly ["calendar:write"];
+    readonly persistent: false;
+}, {
+    readonly name: "booking_pages";
+    readonly label: "Booking pages";
+    readonly description: "Read and manage public booking pages.";
+    readonly scopes: readonly ["booking_pages:read", "booking_pages:write"];
+    readonly persistent: true;
+}, {
+    readonly name: "forwarding";
+    readonly label: "Mailbox forwarding";
+    readonly description: "Read and manage persistent forwarding destinations.";
+    readonly scopes: readonly ["mailbox_forwarding:read", "mailbox_forwarding:write"];
+    readonly persistent: true;
+}, {
+    readonly name: "webhooks";
+    readonly label: "Webhooks";
+    readonly description: "Read and manage persistent webhook destinations and deliveries.";
+    readonly scopes: readonly ["webhooks:read", "webhooks:write"];
+    readonly persistent: true;
+}, {
+    readonly name: "credentials";
+    readonly label: "Mailbox credentials";
+    readonly description: "List, create, and revoke mailbox app passwords.";
+    readonly scopes: readonly ["mailbox_credentials:read", "mailbox_credentials:write"];
+    readonly persistent: true;
+}, {
+    readonly name: "mailbox_export";
+    readonly label: "Mailbox export";
+    readonly description: "Create and retrieve mailbox content exports.";
+    readonly scopes: readonly ["mailboxes:export"];
+    readonly persistent: true;
+}, {
+    readonly name: "domain_admin";
+    readonly label: "Domain administration";
+    readonly description: "Read and manage domains and DNS verification.";
+    readonly scopes: readonly ["domains:read", "domains:write"];
+    readonly persistent: true;
+}, {
+    readonly name: "mailbox_admin";
+    readonly label: "Mailbox administration";
+    readonly description: "Create, change, suspend, import, and delete mailboxes and mailbox settings.";
+    readonly scopes: readonly ["mailboxes:read", "mailboxes:write"];
+    readonly persistent: true;
+}, {
+    readonly name: "newsletters";
+    readonly label: "Newsletters";
+    readonly description: "Read, create, test, schedule, and manage newsletter campaigns.";
+    readonly scopes: readonly ["newsletters:read", "newsletters:write"];
+    readonly persistent: false;
+}, {
+    readonly name: "audiences";
+    readonly label: "Audiences";
+    readonly description: "Read and manage newsletter audiences and subscribers.";
+    readonly scopes: readonly ["audiences:read", "audiences:write"];
+    readonly persistent: false;
+}, {
+    readonly name: "suppressions";
+    readonly label: "Suppressions";
+    readonly description: "Read and remove suppressed recipient addresses.";
+    readonly scopes: readonly ["suppressions:read", "suppressions:write"];
+    readonly persistent: false;
+}, {
+    readonly name: "partner_admin";
+    readonly label: "Partner administration";
+    readonly description: "Manage delegated partner organizations, credential grants, and usage.";
+    readonly scopes: readonly ["partner:organizations:read", "partner:organizations:write", "partner:organizations:access", "partner:mailbox_credentials:issue", "partner:usage:read"];
+    readonly persistent: true;
+}];
+declare const CAPABILITY_ROWS: readonly [readonly ["shipmail_status", "getStatus", "public"], readonly ["shipmail_create_domain", "createDomain", "domains:write"], readonly ["shipmail_list_domains", "listDomains", "domains:read"], readonly ["shipmail_get_domain", "getDomain", "domains:read"], readonly ["shipmail_get_domain_dns_records", "getDomainDnsRecords", "domains:read"], readonly ["shipmail_update_domain", "updateDomain", "domains:write"], readonly ["shipmail_delete_domain", "deleteDomain", "domains:write"], readonly ["shipmail_verify_domain", "verifyDomain", "domains:write"], readonly ["shipmail_search_domains", "searchDomains", "domains:read"], readonly ["shipmail_create_mailbox", "createMailbox", "mailboxes:write"], readonly ["shipmail_list_mailboxes", "listMailboxes", "mailboxes:read"], readonly ["shipmail_get_mailbox", "getMailbox", "mailboxes:read"], readonly ["shipmail_list_mailbox_app_passwords", "listMailboxAppPasswords", "mailbox_credentials:read"], readonly ["shipmail_create_mailbox_app_password", "createMailboxAppPassword", "mailbox_credentials:write"], readonly ["shipmail_revoke_mailbox_app_password", "revokeMailboxAppPassword", "mailbox_credentials:write"], readonly ["shipmail_suspend_mailbox", "suspendMailbox", "mailboxes:write"], readonly ["shipmail_resume_mailbox", "resumeMailbox", "mailboxes:write"], readonly ["shipmail_create_mailbox_export", "createMailboxExport", "mailboxes:export"], readonly ["shipmail_get_mailbox_export", "getMailboxExport", "mailboxes:export"], readonly ["shipmail_update_mailbox", "updateMailbox", "mailboxes:write"], readonly ["shipmail_delete_mailbox", "deleteMailbox", "mailboxes:write"], readonly ["shipmail_list_mailbox_folders", "listMailboxFolders", "mailboxes:read"], readonly ["shipmail_create_mailbox_folder", "createMailboxFolder", "mailboxes:write"], readonly ["shipmail_update_mailbox_folder", "updateMailboxFolder", "mailboxes:write"], readonly ["shipmail_delete_mailbox_folder", "deleteMailboxFolder", "mailboxes:write"], readonly ["shipmail_list_mailbox_identities", "listMailboxIdentities", "mailboxes:read"], readonly ["shipmail_list_mailbox_inbox_messages", "listMailboxInboxMessages", "messages:read"], readonly ["shipmail_get_mailbox_inbox_message", "getMailboxInboxMessage", "messages:read"], readonly ["shipmail_list_mailbox_inbox_threads", "listMailboxInboxThreads", "messages:read"], readonly ["shipmail_get_mailbox_inbox_thread", "getMailboxInboxThread", "messages:read"], readonly ["shipmail_update_inbox_thread_reply_state", "updateMailboxInboxThreadReplyState", "messages:write"], readonly ["shipmail_create_inbox_reply_draft", "createMailboxInboxReplyDraft", "drafts:write"], readonly ["shipmail_send_inbox_reply_draft", "sendMailboxInboxReplyDraft", "messages:send"], readonly ["shipmail_reply_to_inbox_message", "replyToMailboxInboxMessage", "messages:send"], readonly ["shipmail_reply_to_inbox_thread", "replyToMailboxInboxThread", "messages:send"], readonly ["shipmail_update_inbox_message", "updateMailboxInboxMessage", "messages:write"], readonly ["shipmail_move_inbox_message", "moveMailboxInboxMessage", "messages:write"], readonly ["shipmail_delete_inbox_message", "deleteMailboxInboxMessage", "messages:write"], readonly ["shipmail_list_mailbox_forwarding", "listMailboxForwarding", "mailbox_forwarding:read"], readonly ["shipmail_create_mailbox_forwarding", "createMailboxForwarding", "mailbox_forwarding:write"], readonly ["shipmail_delete_mailbox_forwarding", "deleteMailboxForwarding", "mailbox_forwarding:write"], readonly ["shipmail_reset_mailbox_password", "resetMailboxPassword", "mailboxes:write"], readonly ["shipmail_set_auto_reply", "updateAutoReply", "mailboxes:write"], readonly ["shipmail_set_spam_filter", "updateSpamFilter", "mailboxes:write"], readonly ["shipmail_create_mailbox_import", "createMailboxImport", "mailboxes:write"], readonly ["shipmail_list_mailbox_imports", "listMailboxImports", "mailboxes:read"], readonly ["shipmail_get_mailbox_import", "getMailboxImport", "mailboxes:read"], readonly ["shipmail_cancel_mailbox_import", "cancelMailboxImport", "mailboxes:write"], readonly ["shipmail_undo_mailbox_import", "undoMailboxImport", "mailboxes:write"], readonly ["shipmail_inject_sandbox_inbound", "injectSandboxInbound", "messages:write"], readonly ["shipmail_list_messages", "listMessages", "messages:read"], readonly ["shipmail_compose_message_with_file", "prepareStagedAttachmentUpload", "messages:send"], readonly ["shipmail_prepare_staged_attachment_upload", "prepareStagedAttachmentUpload", "messages:send"], readonly ["shipmail_send_message", "sendMessage", "messages:send"], readonly ["shipmail_list_scheduled_messages", "listScheduledMessages", "messages:read"], readonly ["shipmail_get_scheduled_message", "getScheduledMessage", "messages:read"], readonly ["shipmail_update_scheduled_message", "updateScheduledMessage", "messages:send"], readonly ["shipmail_cancel_scheduled_message", "cancelScheduledMessage", "messages:send"], readonly ["shipmail_get_message", "getMessage", "messages:read"], readonly ["shipmail_reply_to_message", "replyToMessage", "messages:send"], readonly ["shipmail_list_threads", "listThreads", "threads:read"], readonly ["shipmail_get_thread", "getThread", "threads:read"], readonly ["shipmail_reply_to_thread", "replyToThread", "messages:send"], readonly ["shipmail_create_reply_scan", "createReplyScan", "messages:read"], readonly ["shipmail_get_reply_scan", "getReplyScan", "messages:read"], readonly ["shipmail_list_reply_scan_results", "listReplyScanResults", "messages:read"], readonly ["shipmail_create_webhook", "createWebhook", "webhooks:write"], readonly ["shipmail_list_webhooks", "listWebhooks", "webhooks:read"], readonly ["shipmail_get_webhook", "getWebhook", "webhooks:read"], readonly ["shipmail_update_webhook", "updateWebhook", "webhooks:write"], readonly ["shipmail_delete_webhook", "deleteWebhook", "webhooks:write"], readonly ["shipmail_rotate_webhook_secret", "rotateWebhookSecret", "webhooks:write"], readonly ["shipmail_test_webhook", "testWebhook", "webhooks:write"], readonly ["shipmail_list_webhook_deliveries", "listWebhookDeliveries", "webhooks:read"], readonly ["shipmail_get_webhook_delivery", "getWebhookDelivery", "webhooks:read"], readonly ["shipmail_replay_webhook_delivery", "replayWebhookDelivery", "webhooks:write"], readonly ["shipmail_list_suppressions", "listSuppressions", "suppressions:read"], readonly ["shipmail_remove_suppression", "removeSuppression", "suppressions:write"], readonly ["shipmail_create_audience", "createAudience", "audiences:write"], readonly ["shipmail_list_audiences", "listAudiences", "audiences:read"], readonly ["shipmail_get_audience", "getAudience", "audiences:read"], readonly ["shipmail_update_audience", "updateAudience", "audiences:write"], readonly ["shipmail_delete_audience", "deleteAudience", "audiences:write"], readonly ["shipmail_add_subscriber", "addSubscriber", "audiences:write"], readonly ["shipmail_add_subscribers_batch", "addSubscribersBatch", "audiences:write"], readonly ["shipmail_list_subscribers", "listSubscribers", "audiences:read"], readonly ["shipmail_get_subscriber", "getSubscriber", "audiences:read"], readonly ["shipmail_get_subscriber_by_email", "getSubscriberByEmail", "audiences:read"], readonly ["shipmail_update_subscriber", "updateSubscriber", "audiences:write"], readonly ["shipmail_unsubscribe_subscriber", "unsubscribeSubscriber", "audiences:write"], readonly ["shipmail_resubscribe_subscriber", "resubscribeSubscriber", "audiences:write"], readonly ["shipmail_remove_subscriber", "removeSubscriber", "audiences:write"], readonly ["shipmail_list_newsletter_domains", "listNewsletterDomains", "newsletters:read"], readonly ["shipmail_create_newsletter", "createNewsletter", "newsletters:write"], readonly ["shipmail_create_newsletter_from_changelog", "createNewsletterFromChangelog", "newsletters:write"], readonly ["shipmail_list_newsletters", "listNewsletters", "newsletters:read"], readonly ["shipmail_get_newsletter", "getNewsletter", "newsletters:read"], readonly ["shipmail_update_newsletter", "updateNewsletter", "newsletters:write"], readonly ["shipmail_list_newsletter_assets", "listNewsletterAssets", "newsletters:read"], readonly ["shipmail_register_newsletter_asset", "uploadNewsletterAsset", "newsletters:write"], readonly ["shipmail_preview_newsletter", "previewNewsletter", "newsletters:read"], readonly ["shipmail_run_newsletter_preflight", "runNewsletterPreflight", "newsletters:write"], readonly ["shipmail_send_newsletter_test", "sendNewsletterTest", "newsletters:write"], readonly ["shipmail_schedule_newsletter", "scheduleNewsletter", "newsletters:write"], readonly ["shipmail_cancel_newsletter", "cancelNewsletter", "newsletters:write"], readonly ["shipmail_resume_newsletter", "resumeNewsletter", "newsletters:write"], readonly ["shipmail_list_calendar_events", "listCalendarEvents", "calendar:read"], readonly ["shipmail_create_calendar_event", "createCalendarEvent", "calendar:write"], readonly ["shipmail_get_calendar_event", "getCalendarEvent", "calendar:read"], readonly ["shipmail_update_calendar_event", "updateCalendarEvent", "calendar:write"], readonly ["shipmail_delete_calendar_event", "deleteCalendarEvent", "calendar:write"], readonly ["shipmail_get_calendar_availability", "getCalendarAvailability", "calendar:read"], readonly ["shipmail_list_booking_pages", "listBookingPages", "booking_pages:read"], readonly ["shipmail_create_booking_page", "createBookingPage", "booking_pages:write"], readonly ["shipmail_get_booking_page", "getBookingPage", "booking_pages:read"], readonly ["shipmail_update_booking_page", "updateBookingPage", "booking_pages:write"], readonly ["shipmail_delete_booking_page", "deleteBookingPage", "booking_pages:write"], readonly ["shipmail_list_partner_organizations", "listPartnerOrganizations", "partner:organizations:read"], readonly ["shipmail_create_partner_organization", "createPartnerOrganization", "partner:organizations:write"], readonly ["shipmail_get_partner_organization", "getPartnerOrganization", "partner:organizations:read"], readonly ["shipmail_update_partner_organization", "updatePartnerOrganization", "partner:organizations:write"], readonly ["shipmail_resend_partner_ownership_invitation", "resendPartnerOwnershipInvitation", "partner:organizations:write"], readonly ["shipmail_suspend_partner_organization", "suspendPartnerOrganization", "partner:organizations:write"], readonly ["shipmail_resume_partner_organization", "resumePartnerOrganization", "partner:organizations:write"], readonly ["shipmail_offboard_partner_organization", "offboardPartnerOrganization", "partner:organizations:write"], readonly ["shipmail_list_partner_mailbox_credential_grants", "listPartnerMailboxCredentialGrants", "partner:mailbox_credentials:issue"], readonly ["shipmail_consume_partner_mailbox_credential_grant", "consumePartnerMailboxCredentialGrant", "partner:mailbox_credentials:issue"], readonly ["shipmail_get_partner_usage", "getPartnerUsage", "partner:usage:read"]];
+type McpToolName = (typeof CAPABILITY_ROWS)[number][0];
+type McpCapability = {
+    readonly toolName: McpToolName;
+    readonly operationId: string;
+    readonly requiredScope: ApiKeyScope | "public";
+    readonly permissionGroup: McpPermissionGroupName;
+    readonly allowedRoles: readonly McpRole[];
+    readonly effect: McpCapabilityEffect;
+    readonly recipientControl: McpRecipientControl;
+    readonly duration: McpCapabilityDuration;
+    readonly idempotency: McpIdempotencyBehavior;
+    readonly annotations: {
+        readonly readOnlyHint: boolean;
+        readonly destructiveHint: boolean;
+        readonly openWorldHint: boolean;
+    };
+    readonly auditAction: string | null;
+    readonly transports: {
+        readonly hostedOAuth: boolean;
+        readonly directApiKeyHttp: boolean;
+        readonly stdio: boolean;
+    };
+};
+declare const MCP_CAPABILITIES: readonly McpCapability[];
+declare const MCP_TOOL_NAMES: readonly McpToolName[];
+declare function getMcpCapability(toolName: string): McpCapability | undefined;
+declare function getAllowedMcpToolNames(grantedScopes: readonly string[], transport: keyof McpCapability["transports"]): ReadonlySet<McpToolName>;
+declare function permissionGroupsToScopes(groupNames: readonly McpPermissionGroupName[]): readonly ApiKeyScope[];
+
+export { MCP_CAPABILITIES, MCP_CAPABILITY_VERSION, MCP_MEMBER_PERMISSION_GROUP_NAMES, MCP_PERMISSION_GROUPS, MCP_PERMISSION_GROUP_NAMES, MCP_TOOL_NAMES, type McpCapability, type McpCapabilityDuration, type McpCapabilityEffect, type McpIdempotencyBehavior, type McpPermissionGroup, type McpPermissionGroupName, type McpRecipientControl, type McpRole, type McpToolName, getAllowedMcpToolNames, getMcpCapability, permissionGroupsToScopes };