@zyphr-dev/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# @zyphr-dev/mcp-server
+
+Model Context Protocol (MCP) server for [Zyphr](https://zyphr.dev). Wraps the Zyphr API as MCP tools so any MCP-compatible client can send emails, push notifications, SMS, and in-app messages directly from inside an AI loop.
+
+## Install
+
+```bash
+npx -y @zyphr-dev/mcp-server
+```
+
+The binary is also exposed as `zyphr-mcp` when installed globally or as a dependency.
+
+## Configure
+
+Add the following to your MCP client's server configuration:
+
+```json
+{
+  "mcpServers": {
+    "zyphr": {
+      "command": "npx",
+      "args": ["-y", "@zyphr-dev/mcp-server"],
+      "env": {
+        "ZYPHR_API_KEY": "zy_test_..."
+      }
+    }
+  }
+}
+```
+
+End users always point at production (`https://api.zyphr.dev/v1`) using either a `zy_test_*` or `zy_live_*` key from the Zyphr dashboard.
+
+## Environment variables
+
+| Variable | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `ZYPHR_API_KEY` | Yes | — | `zy_live_*` or `zy_test_*` |
+| `ZYPHR_BASE_URL` | No | `https://api.zyphr.dev/v1` | Override for non-production environments |
+| `ZYPHR_READ_ONLY` | No | `false` | When `true`, mutating tools (sends, creates, updates) are not registered |
+| `ZYPHR_ALLOWED_TOOLS` | No | _(all)_ | Comma-separated whitelist of tool names. Overrides `ZYPHR_READ_ONLY` |
+
+The server fails fast with a clear stderr message if `ZYPHR_API_KEY` is missing.
+
+## Tools
+
+### Integration (zero-to-first-send helpers)
+
+| Tool | Description |
+| --- | --- |
+| `get_sdk_install_for_language` | Return install commands + minimal init snippet + env vars for the chosen language (`node`, `python`, `ruby`, `go`, `php`, `csharp`). Optional `packageManager` override narrows to a single command (e.g. `yarn` instead of `npm`). |
+| `get_quickstart_for_channel` | Return drop-in service file(s) for the chosen channel (`email`, `push`, `sms`, `inbox`, `webhook`) + language + optional framework (`express`, `nextjs`, `flask`, `fastapi`, `rails`, `laravel`, `aspnetcore`). Webhook handlers always verify the HMAC signature. Unrecognized frameworks fall back to plain SDK code. |
+
+### Send
+
+| Tool | Description |
+| --- | --- |
+| `send_email` | Send a transactional email. Supports inline `html`/`text` or `templateId`+`templateData`. |
+| `send_push` | Send a push notification to a user, device, or subscriber. |
+| `send_sms` | Send an SMS message (E.164 recipient). |
+| `send_inbox_message` | Deliver an in-app inbox message to a subscriber. |
+
+### Templates
+
+| Tool | Description |
+| --- | --- |
+| `list_templates` | List templates in the account. |
+| `get_template` | Fetch a single template by ID. |
+| `render_template` | Preview a template with the given variables _without_ sending. Returns rendered subject/html/text. |
+| `create_template` | Create a new template. |
+
+### Subscribers
+
+| Tool | Description |
+| --- | --- |
+| `find_subscriber` | Look up a subscriber by external ID. |
+| `list_subscribers` | List subscribers (filter by status or email). |
+| `create_subscriber` | Create a subscriber. |
+| `update_subscriber` | Update a subscriber. Pass `null` for email/phone/name/avatarUrl to clear them. |
+| `set_subscriber_preferences` | Set notification preferences for a subscriber. |
+
+### Webhooks
+
+| Tool | Description |
+| --- | --- |
+| `list_webhooks` | List configured webhook endpoints. |
+| `create_webhook` | Register a new webhook endpoint subscribed to one or more event types. |
+| `get_webhook_deliveries` | Inspect delivery history for a webhook (filter by status, event type, or date range). |
+
+## Safety
+
+Two environment variables let you scope what the AI is allowed to do:
+
+- **`ZYPHR_READ_ONLY=true`** suppresses every mutating tool — sends, creates, updates. Only the read-only tools (`list_*`, `get_*`, `find_*`, `render_template`, `get_webhook_deliveries`) remain. Use this when you want the AI to investigate or report without touching state.
+- **`ZYPHR_ALLOWED_TOOLS="tool_a,tool_b"`** is a comma-separated whitelist. When set, only those tools are registered. Whitelist takes precedence over `ZYPHR_READ_ONLY`, so you can explicitly allow a mutating tool inside an otherwise read-only profile.
+
+No `delete_*` tools are exposed in this release. Destructive operations remain dashboard-only.
+
+### Example prompts
+
+Once the server is connected, your AI client can act on prompts like:
+
+- "I'm starting a new Node project and want to use Zyphr — what do I install?" → calls `get_sdk_install_for_language`
+- "Add Zyphr email to my Express app." → calls `get_quickstart_for_channel`, returns SDK singleton + Express route
+- "Show me how to verify a Zyphr webhook in a FastAPI route." → calls `get_quickstart_for_channel`, returns a handler with HMAC verification and 5-minute replay tolerance
+- "Send a welcome email to alice@example.com with subject 'Welcome to Acme' and a short HTML greeting."
+- "Preview the welcome email template with name='Alice' and verify_link='https://example.com/v/abc'."
+- "Look up the subscriber for external ID `user_123` and update their email preferences for marketing to false."
+- "Push a notification titled 'Order shipped' to subscriber `usr_42`."
+- "Send an SMS to +14155551234 letting them know their appointment is confirmed."
+- "Drop an inbox message for subscriber `usr_42` with title 'New report ready' and an action URL to the report page."
+- "Show me the last 20 webhook deliveries for webhook `whk_abc` that failed in the past hour and tell me why."
+
+Errors from the Zyphr API are surfaced verbatim as MCP errors, so the AI can react to validation failures, rate limits, or auth problems without guessing.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }