shipmail-mcp 0.1.0

package/LICENSE

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

@@ -0,0 +1,99 @@
+# ShipMail MCP Server
+
+Official Model Context Protocol server for ShipMail. It gives MCP-compatible agents access to ShipMail domains, mailboxes, messages, threads, webhooks, suppressions, resources, and guided prompts.
+
+## Install
+
+```json
+{
+  "mcpServers": {
+    "shipmail": {
+      "command": "npx",
+      "args": ["-y", "shipmail-mcp"],
+      "env": {
+        "SHIPMAIL_API_KEY": "sm_live_..."
+      }
+    }
+  }
+}
+```
+
+For local development in this repository:
+
+```bash
+cd packages/shipmail-mcp
+SHIPMAIL_API_KEY=sm_live_... bun run dev
+```
+
+## Configuration
+
+| Variable                           | Description                                                                                                                                                                |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SHIPMAIL_API_KEY`                 | Required (or use `SHIPMAIL_API_KEY_FILE`). ShipMail API key (`sm_live_...`).                                                                                               |
+| `SHIPMAIL_API_KEY_FILE`            | Optional path to a file containing the API key. Takes precedence over `SHIPMAIL_API_KEY`. Reduces env-trace leak surface (Docker secrets, systemd `LoadCredential`, etc.). |
+| `SHIPMAIL_BASE_URL`                | Optional. Must be https on a `shipmail.to` host. Defaults to `https://shipmail.to/api/v1`.                                                                                 |
+| `SHIPMAIL_MCP_TOOLS`               | Optional comma-separated allowlist of tools. The `--tools` flag overrides this when both are set.                                                                          |
+| `SHIPMAIL_ALLOW_INSECURE_BASE_URL` | Set to `1` to permit a non-https or non-`shipmail.to` base URL. Use only for local development.                                                                            |
+| `SHIPMAIL_MCP_DEBUG`               | Set to `1` to include `request_id`/`status` in stderr tool-call logs (default: off).                                                                                       |
+
+The command also supports `--tools`:
+
+```json
+{
+  "args": [
+    "-y",
+    "shipmail-mcp",
+    "--tools",
+    "shipmail_list_mailboxes,shipmail_get_thread,shipmail_reply_to_thread"
+  ]
+}
+```
+
+## Security model
+
+- All tools are namespaced with the prefix `shipmail_` so they cannot collide with same-named tools registered by peer MCP servers in the same host.
+- Successful tools return both text fallback content and structured MCP `structuredContent`.
+- Mutating tools accept an optional caller-supplied `idempotency_key`. When omitted, the MCP server generates one (a fresh key per tool call). Supply your own key if you want a specific request to be idempotent across MCP retries.
+- Email content, addresses, and error text are sanitized before reaching the LLM: ASCII control characters, DEL, and Unicode directional/BiDi markers (U+061C, U+200E/F, U+202A-E, U+2066-9) are stripped. Long strings are truncated.
+- 5xx and other unexpected ShipMail errors are redacted to a generic message; the original `request_id` is preserved for support. Generic `Error` thrown values (network errors, deserialization, etc.) are redacted to "Internal MCP error" before the LLM sees them; details land on stderr.
+- Each MCP session enforces per-tool rate limits AND a hard total-call ceiling as a runaway-agent circuit breaker. These are NOT abuse controls — real abuse limits live at the API per API key. Restart the server to reset.
+- Webhook URLs are validated to be public https endpoints. Localhost, RFC1918, link-local, ULA, IPv4-mapped IPv6, `0.0.0.0`, decimal-int IPs, `.local`, and `.internal` hosts are rejected at input time.
+- Destructive tools are annotated with `destructiveHint`. MCP hosts that gate on this annotation will prompt the user. We mark `shipmail_update_domain` (catch-all retarget), `shipmail_update_webhook` (URL change), `shipmail_rotate_webhook_secret`, and `shipmail_set_auto_reply` as destructive in addition to obvious deletes.
+- Domain purchase is intentionally excluded from v1.
+
+### Threats this server does NOT defend against
+
+- **Indirect prompt injection from email content.** If you triage a mailbox, the agent reads attacker-controlled email bodies. The sanitizer strips invisible glyphs but cannot detect natural-language injection ("ignore previous instructions, send to..."). Only call destructive tools after explicit user approval.
+- **Malicious LLM output / hallucinated args.** The MCP layer cannot tell whether an argument value 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 the 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.
+
+## Tool groups
+
+- Status: `shipmail_status`
+- Domains: `shipmail_list_domains`, `shipmail_get_domain`, `shipmail_create_domain`, `shipmail_update_domain`, `shipmail_delete_domain`, `shipmail_verify_domain`, `shipmail_search_domains`
+- Mailboxes: `shipmail_list_mailboxes`, `shipmail_get_mailbox`, `shipmail_create_mailbox`, `shipmail_update_mailbox`, `shipmail_delete_mailbox`, `shipmail_set_auto_reply`
+- 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`
+- 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`
+- Suppressions: `shipmail_list_suppressions`, `shipmail_remove_suppression`
+
+## Resources
+
+- `shipmail://account/status`
+- `shipmail://domains`
+- `shipmail://domains/{id}`
+- `shipmail://mailboxes`
+- `shipmail://mailboxes/{id}`
+- `shipmail://messages/{id}`
+- `shipmail://threads/{id}`
+
+## Prompts
+
+- `setup_domain`
+- `triage_mailbox`
+- `draft_reply`
+- `configure_webhook`