@iterable/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Greg Methvin
+
+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,318 @@
+# Iterable MCP Server
+
+A Model Context Protocol (MCP) server for interacting with the Iterable marketing automation platform.
+
+## Quick Start
+
+## Security & Defaults
+
+- API keys are stored in macOS Keychain (values), and metadata lives in `~/.iterable-mcp/keys.json` with 0600 permissions. No plaintext keys on disk.
+- PII access, write operations, and message sends are disabled by default for safety.
+  - Enable explicitly via envs:
+    - `ITERABLE_USER_PII=true`
+    - `ITERABLE_ENABLE_WRITES=true`
+    - `ITERABLE_ENABLE_SENDS=true` (requires writes enabled as well)
+- Custom endpoints must be HTTPS and require confirmation when not an `*.iterable.com` domain.
+- Logs avoid printing headers/bodies and sanitize 32‑character hex keys.
+
+## Troubleshooting
+
+- Node.js: v18+ recommended. You’ll see a warning on older runtimes.
+- Claude CLI missing: install `claude` CLI, then re-run `iterable-mcp setup --claude-code`.
+- Keychain issues: Ensure Keychain is available; re-run setup. Stale locks are auto‑recovered.
+- Emojis too noisy? Set `ITERABLE_UI_ICONS=false` (default). Enable with `ITERABLE_UI_ICONS=true`.
+
+### Install using npx
+
+**Prerequisites:**
+- Node.js >= 18
+- Iterable API key
+- macOS (for secure keychain storage; Windows/Linux use environment variables)
+
+**Note:** On macOS, API keys are stored securely in Keychain. The setup wizard will prompt you to name your key and store it automatically.
+
+Click the button to install to Cursor:
+
+<a href="https://raw.githubusercontent.com/iterable/mcp-server/gh-pages/docs/cursor-install.html"><img alt="Add Iterable MCP server to Cursor" src="https://cursor.com/deeplink/mcp-install-dark.png" style="max-height: 16px;"></a>
+
+If the button doesn't work, install the MCP server for your preferred AI tool(s):
+
+```bash
+# Configure your preferred AI tool(s)
+npx @iterable/mcp setup --cursor --claude-desktop --claude-code
+```
+
+#### Advanced permissions (`--advanced`)
+
+By default, the setup wizard configures the server in a safe, read‑only mode (no PII tools, no writes, no sends). To selectively enable elevated capabilities during setup, pass `--advanced`:
+
+```bash
+# Example: enable advanced selection when configuring Cursor
+npx @iterable/mcp setup --cursor --advanced
+```
+
+You will be prompted to toggle these flags:
+- User PII (ITERABLE_USER_PII)
+- Writes (ITERABLE_ENABLE_WRITES)
+- Sends (ITERABLE_ENABLE_SENDS)
+
+Notes:
+- Sends are only allowed when both Writes and Sends are enabled.
+- When you select an existing macOS Keychain key, the chosen flags are saved with that key for future sessions.
+- Prompts exposed to AI tools are generated from read‑only tools for extra safety, regardless of advanced flags.
+
+### Install package globally using pnpm
+
+```bash
+pnpm add -g @iterable/mcp
+iterable-mcp setup --cursor --claude-desktop --claude-code
+```
+
+**Note:** The setup command automatically configures the correct command path.
+
+### Install from Source
+
+```bash
+git clone https://github.com/iterable/mcp-server.git
+cd mcp-server
+pnpm install-dev:cursor  # or install-dev:claude-desktop or install-dev:claude-code
+```
+
+### Claude Code
+
+The `setup --claude-code` command automatically configures Claude Code by running `claude mcp add` for you and stores your API key securely in macOS Keychain.
+
+Alternatively, you can run it manually:
+
+```bash
+# Manual installation (alternative to setup --claude-code)
+# First, add your API key to the keychain (interactive prompts)
+iterable-mcp keys add
+
+# Then configure Claude Code
+claude mcp add iterable -- npx -y @iterable/mcp
+
+# Verify it was added
+claude mcp list
+
+# Optional: Configure privacy settings
+claude mcp add iterable \
+  --env ITERABLE_USER_PII=false \
+  --env ITERABLE_ENABLE_WRITES=false \
+  -- npx -y @iterable/mcp
+```
+
+If you have already configured Claude Desktop successfully, you can run this command to copy your MCP server settings to Claude Code:
+
+```bash
+claude mcp add-from-claude-desktop
+```
+
+**Note:** All of the above `claude mcp` commands will save the settings to `~/.claude.json`, which makes the configured MCP servers available across all projects. For shared, project-specific MCP configs, create a `.mcp.json` file in the root of your project.
+
+For more information, see the [Claude Code MCP documentation](https://docs.claude.com/en/docs/claude-code/mcp).
+
+### Manual Configuration (Cursor & Claude Desktop)
+
+The above commands will automatically configure your AI tool to use the MCP server by editing the appropriate configuration file, but you can also manually edit the appropriate configuration file:
+- **Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Cursor:** `~/.cursor/mcp.json`
+
+**macOS (with Keychain):**
+```bash
+# First, add your API key to the keychain (interactive prompts)
+iterable-mcp keys add
+```
+
+Then edit your config file:
+```json
+{
+  "mcpServers": {
+    "iterable": {
+      "command": "npx",
+      "args": ["-y", "@iterable/mcp"]
+    }
+  }
+}
+```
+
+Note: No `env` needed on macOS - API key and base URL are loaded from Keychain.
+
+**Windows/Linux (using environment variable):**
+```json
+{
+  "mcpServers": {
+    "iterable": {
+      "command": "npx",
+      "args": ["-y", "@iterable/mcp"],
+      "env": {
+        "ITERABLE_API_KEY": "your-iterable-api-key-here",
+        "ITERABLE_BASE_URL": "https://api.iterable.com"
+      }
+    }
+  }
+}
+```
+
+**Using Custom Node/NPX Paths:**
+
+If you need to use a custom path to node or npx (for example, if they are not in your PATH), you can set environment variables before running the setup command:
+
+```bash
+# Set custom paths
+export ITERABLE_MCP_NODE_PATH="/path/to/custom/node"
+export ITERABLE_MCP_NPX_PATH="/path/to/custom/npx"
+
+# Then run setup
+npx @iterable/mcp setup --cursor
+```
+
+Alternatively, you can manually edit your configuration file (after adding your key to the keychain):
+
+```json
+{
+  "mcpServers": {
+    "iterable": {
+      "command": "/custom/path/to/npx",
+      "args": ["-y", "@iterable/mcp"]
+    }
+  }
+}
+```
+
+Note: No `env` needed on macOS - API key and base URL are loaded from Keychain.
+
+## What You Can Do
+
+See [TOOLS.md](TOOLS.md) for all available tools with descriptions. All tools map directly to [Iterable API endpoints](https://api.iterable.com/api/docs).
+
+### Examples:
+- *"How many campaigns do I have running?"*
+- *"Get details on campaign 12345"*
+- *"Show me events for user@example.com from the last 30 days"*
+- *"Create a campaign called 'Holiday Sale' using template 456"*
+- *"What email templates are available?"*
+- *"Export all user data from January 2024"*
+- *"List users in my 'VIP Customers' list"*
+- *"Show me all my product catalogs"*
+- *"What journeys are currently active?"*
+- *"Send a welcome email to new-user@company.com"*
+
+## Configuration
+
+### API Key Management
+
+**macOS Users:** API keys are stored securely in macOS Keychain. Each key is tightly coupled to its API endpoint (US vs EU vs custom).
+
+**How Key Selection Works:**
+- You can store multiple API keys with different names (e.g., "production", "staging", "dev")
+- Only ONE key is marked as **active** at a time
+- The MCP server automatically uses whichever key is currently active
+- Your first key is automatically set as active
+- Switch between keys using the `activate` command
+
+```bash
+# List stored keys (shows which one is active with ● ACTIVE badge)
+iterable-mcp keys list
+
+# Add a new key (interactive: prompts for name, region/endpoint, and API key)
+# Your first key becomes active automatically
+iterable-mcp keys add
+
+# Switch to a different key by name or ID (also switches endpoint)
+iterable-mcp keys activate production
+iterable-mcp keys activate staging
+
+# Delete a key by ID (requires ID for safety)
+# Note: Cannot delete the currently active key - activate another first
+iterable-mcp keys delete <key-id>
+
+# To update a key: delete the old one and add a new one with the same name
+```
+
+**Windows/Linux:** Use the `ITERABLE_API_KEY` and `ITERABLE_BASE_URL` environment variables (key management commands are not available on Windows/Linux).
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ITERABLE_API_KEY` | ❌* | Your Iterable API key (*Required on non-macOS platforms, optional on macOS if using key manager) |
+| `ITERABLE_BASE_URL` | ❌** | Base URL for the Iterable API (**Not needed on macOS when using key manager - URL is stored with each key) |
+| `ITERABLE_DEBUG` | ❌ | Set to `true` for API request logging |
+| `LOG_LEVEL` | ❌ | Set to `debug` for troubleshooting |
+| `ITERABLE_USER_PII` | ❌ | Set to `true` to enable tools that access user PII data (default: `false`) |
+| `ITERABLE_ENABLE_WRITES` | ❌ | Set to `true` to enable tools that perform write operations (default: `false`) |
+| `ITERABLE_ENABLE_SENDS` | ❌ | Set to `true` to enable tools that can send messages (default: `false`). Requires writes to be enabled |
+
+### Custom Endpoints
+
+- The CLI supports selecting the US or EU region, or entering a custom endpoint.
+- For security, HTTPS is required for custom endpoints. The only exception is localhost development:
+  - Allowed: `http://localhost:3000`, `http://127.0.0.1:8080`, `http://[::1]:4000`
+  - Not allowed: plain `http://` on non-local hosts (use `https://` instead)
+- When a non-`*.iterable.com` domain is provided, the CLI will ask for confirmation.
+
+## Development
+
+### Running Tests
+
+The project includes both unit and integration tests:
+
+```bash
+# Run all tests
+pnpm test
+
+# Run only unit tests (no API key required)
+pnpm test:unit
+
+# Run only integration tests (requires valid API key)
+pnpm test:integration
+```
+
+### Integration Tests
+
+Integration tests make real API calls to Iterable and require a valid API key.
+
+**Setup:**
+
+1. Set your API key as an environment variable:
+   ```bash
+   export ITERABLE_API_KEY=your_actual_api_key
+   ```
+
+2. Or on macOS, add a key to the keychain (interactive):
+   ```bash
+   iterable-mcp keys add
+   ```
+
+   **Note:** The key name can be anything (e.g., "dev", "test", "staging"). The system automatically uses whichever key is marked as **active**. Your first key is automatically set as active. If you have multiple keys, use `iterable-mcp keys activate <name>` to switch between them.
+
+3. Run the integration tests:
+   ```bash
+   pnpm test:integration
+   ```
+
+**Note:** Integration tests require a valid API key (env or active macOS Keychain key). The suite fails fast if none is found.
+
+### Development Workflow
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the project
+pnpm build
+
+# Build and watch for changes
+pnpm build:watch
+
+# Run in development mode
+pnpm dev
+
+# Install locally for testing
+pnpm run install-dev
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/TOOLS.md

@@ -0,0 +1,133 @@
+# Available Iterable MCP Tools (104 tools)
+
+**Legend:** 🔒 = Contains PII, ✏️ = Write operation
+
+## Campaigns (13 tools)
+- **abort_campaign** ✏️: Abort a campaign that is currently running
+- **activate_triggered_campaign** ✏️: Activate a triggered campaign (requires API triggered campaign activation enabled)
+- **archive_campaigns** ✏️: Archive one or more campaigns. Scheduled/recurring campaigns will be cancelled, running campaigns will be aborted.
+- **cancel_campaign** ✏️: Cancel a scheduled or recurring campaign
+- **create_campaign** ✏️: Create a new blast or triggered campaign from an existing template. If listIds are provided, the campaign will be a blast campaign, otherwise it will be a triggered campaign. Blast campaigns will be sent immediately if sendAt is not provided.
+- **deactivate_triggered_campaign** ✏️: Deactivate a triggered campaign (requires API triggered campaign deactivation enabled)
+- **get_campaign**: Get detailed information about a specific campaign
+- **get_campaign_metrics**: Get campaign performance metrics
+- **get_campaigns**: Retrieve campaigns
+- **get_child_campaigns**: Get child campaigns generated by a recurring campaign
+- **schedule_campaign** ✏️: Schedule an existing campaign to be sent at a specific time
+- **send_campaign** ✏️: Send an existing scheduled campaign immediately
+- **trigger_campaign** ✏️: Trigger a campaign to send to specified lists
+
+## Catalogs (12 tools)
+- **bulk_delete_catalog_items** ✏️: Bulk delete catalog items by their IDs
+- **create_catalog** ✏️: Create a new catalog
+- **delete_catalog** ✏️: Delete a catalog
+- **delete_catalog_item** ✏️: Delete a specific catalog item by ID
+- **get_catalog_field_mappings**: Get field mappings and data types for a catalog
+- **get_catalog_item**: Get a specific catalog item by ID
+- **get_catalog_items**: Get items from a catalog with optional pagination and sorting
+- **get_catalogs**: Get list of all catalogs with optional pagination
+- **partial_update_catalog_item** ✏️: Partial update (PATCH) a catalog item - updates only specified fields
+- **replace_catalog_item** ✏️: Replace (PUT) a catalog item - replaces the entire item with new value
+- **update_catalog_field_mappings** ✏️: Update catalog field mappings (data types). Valid types: boolean, date, geo_location, long, double, object, and string
+- **update_catalog_items** ✏️: Update catalog items
+
+## Data Export (5 tools)
+- **cancel_export_job** 🔒✏️: Cancel a queued or running export job created with 'start_export_job'. Use the jobId returned from the start export endpoint.
+- **get_available_export_data_types** 🔒✏️: Get the list of all available export data types that can be used with start_export_job. Returns an array of data type names that are supported by the Iterable API.
+- **get_export_files** 🔒: Get the job status and download URLs for files from a completed export job. Files are added to the list as the export job runs. Use 'startAfter' parameter to paginate through files. Each file is up to 10MB, with exports limited to 100GB total size.
+- **get_export_jobs** 🔒: Get a list of recent export jobs for the current project. Jobs can be filtered by state (enqueued, queued, running, completed, failed, cancelled, cancelling).
+- **start_export_job** 🔒✏️: Start a data export job that processes as a background job. Use 'get_export_files' to check status and obtain download links. Supports many data types including: email events (emailSend, emailOpen, emailClick, emailBounce, etc.), push events (pushSend, pushOpen, etc.), SMS events (smsSend, smsBounce, etc.), WhatsApp events, in-app message events, user data, purchase events, and more. Additional requests are queued if concurrent limit is reached.
+
+## Events (4 tools)
+- **get_user_events_by_email** 🔒: Get event history for a user by email address
+- **get_user_events_by_user_id** 🔒: Get event history for a user by user ID
+- **track_bulk_events** 🔒✏️: Track multiple events in a single request for better performance
+- **track_event** 🔒✏️: Track a custom event for a user
+
+## Experiments (1 tools)
+- **get_experiment_metrics**: Get experiment metrics for A/B testing analysis (currently supports email experiments only)
+
+## Journeys (2 tools)
+- **get_journeys**: Get journeys (workflows) with optional pagination and state filtering
+- **trigger_journey** 🔒✏️: Trigger a journey (workflow) for a user
+
+## Lists (8 tools)
+- **create_list** ✏️: Create a new user list
+- **delete_list** ✏️: Delete a user list
+- **get_list_preview_users** 🔒: Preview users in a list (up to 5000 users)
+- **get_list_size**: Get the count of users in a specific list
+- **get_list_users** 🔒: Get users in a specific list
+- **get_lists**: Retrieve user lists
+- **subscribe_to_list** 🔒✏️: Subscribe users to a specific list
+- **unsubscribe_from_list** 🔒✏️: Unsubscribe users from a specific list
+
+## Messaging (16 tools)
+- **cancel_email** 🔒✏️: Cancel scheduled email for specific user
+- **cancel_in_app** 🔒✏️: Cancel scheduled in-app message for specific user
+- **cancel_push** 🔒✏️: Cancel scheduled push notification for specific user
+- **cancel_sms** 🔒✏️: Cancel scheduled SMS message for specific user
+- **cancel_web_push** 🔒✏️: Cancel scheduled web push notification for specific user
+- **cancel_whatsapp** 🔒✏️: Cancel scheduled WhatsApp message for specific user
+- **get_channels**: Get all available communication channels (email, SMS, push, etc.)
+- **get_embedded_messages** 🔒: Get embedded messages for a user, grouped by placement ID
+- **get_in_app_messages** 🔒: Get in-app messages for a user
+- **get_message_types**: Get all message types within the project for use in templates
+- **send_email** 🔒✏️: Send email to user
+- **send_in_app** 🔒✏️: Send in-app message to user
+- **send_push** 🔒✏️: Send push notification to user
+- **send_sms** 🔒✏️: Send SMS message to user
+- **send_web_push** 🔒✏️: Send web push notification to user
+- **send_whatsapp** 🔒✏️: Send WhatsApp message to user
+
+## Snippets (5 tools)
+- **create_snippet** ✏️: Create a new snippet with Handlebars templating support
+- **delete_snippet** ✏️: Delete a snippet by ID (numeric) or name (string)
+- **get_snippet**: Get a snippet by ID (numeric) or name (string)
+- **get_snippets**: Get all snippets for the current project
+- **update_snippet** ✏️: Update a snippet by ID (numeric) or name (string)
+
+## Subscriptions (5 tools)
+- **bulk_update_subscriptions** 🔒✏️: Subscribe or unsubscribe multiple users to/from a subscription group
+- **subscribe_user_by_email** 🔒✏️: Subscribe a user to a subscription group by email
+- **subscribe_user_by_userid** 🔒✏️: Subscribe a user to a subscription group by userId
+- **unsubscribe_user_by_email** 🔒✏️: Unsubscribe a user from a subscription group by email
+- **unsubscribe_user_by_userid** 🔒✏️: Unsubscribe a user from a subscription group by userId
+
+## Templates (21 tools)
+- **delete_templates** ✏️: Delete one or more templates by ID
+- **get_email_template**: Get details for specific email template by ID
+- **get_inapp_template**: Get details for specific in-app message template by ID
+- **get_push_template**: Get details for specific push notification template by ID
+- **get_sms_template**: Get details for specific SMS template by ID
+- **get_template_by_client_id**: Get template by client template ID
+- **get_templates**: Retrieve templates
+- **preview_email_template**: Preview email template with custom data. Returns fully rendered HTML with user, event, and/or data feed data substituted.
+- **preview_inapp_template**: Preview in-app message template with custom data. Returns fully rendered HTML with user, event, and/or data feed data substituted.
+- **send_email_template_proof** 🔒✏️: Send a proof of a email template to a specific user
+- **send_inapp_template_proof** 🔒✏️: Send a proof of a in-app message template to a specific user
+- **send_push_template_proof** 🔒✏️: Send a proof of a push notification template to a specific user
+- **send_sms_template_proof** 🔒✏️: Send a proof of a SMS template to a specific user
+- **update_email_template** ✏️: Update existing email template by templateId
+- **update_inapp_template** ✏️: Update existing in-app message template by templateId
+- **update_push_template** ✏️: Update existing push notification template by templateId
+- **update_sms_template** ✏️: Update existing SMS template by templateId
+- **upsert_email_template** ✏️: Create or update email template. If a template with the specified clientTemplateId exists, it will be updated; otherwise, a new template will be created.
+- **upsert_inapp_template** ✏️: Create or update in-app message template. If a template with the specified clientTemplateId exists, it will be updated; otherwise, a new template will be created.
+- **upsert_push_template** ✏️: Create or update push notification template. If a template with the specified clientTemplateId exists, it will be updated; otherwise, a new template will be created.
+- **upsert_sms_template** ✏️: Create or update SMS template. If a template with the specified clientTemplateId exists, it will be updated; otherwise, a new template will be created.
+
+## Users (10 tools)
+- **bulk_update_users** 🔒✏️: Update multiple users at once
+- **delete_user_by_email** 🔒✏️: Delete a user by email address (asynchronous - does not prevent future data collection)
+- **delete_user_by_user_id** 🔒✏️: Delete a user by user ID (asynchronous - does not prevent future data collection, deletes all users with same userId)
+- **get_sent_messages** 🔒: Get messages sent to a specific user with optional filtering
+- **get_user_by_email** 🔒: Get user profile information by email address
+- **get_user_by_user_id** 🔒: Get user profile information by user ID
+- **get_user_fields**: Get all user profile field definitions and their types
+- **update_email** 🔒✏️: Update a user's email address (only use with email-based projects; for userId/hybrid projects, use update_user instead)
+- **update_user** 🔒✏️: Update user profile information (accepts email OR userId in params)
+- **update_user_subscriptions** 🔒✏️: Update user subscriptions (IMPORTANT: overwrites existing data for any non-null fields specified)
+
+## Webhooks (2 tools)
+- **get_webhooks**: Get all webhooks for the project
+- **update_webhook** ✏️: Update a webhook configuration

package/dist/client-detection.d.ts

@@ -0,0 +1,7 @@
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+/**
+ * Simple client detection that uses MCP handshake information.
+ * Only checks MCP_SOURCE override, then uses client-provided name directly.
+ */
+export declare function detectClientName(server?: Server): string;
+//# sourceMappingURL=client-detection.d.ts.map

package/dist/client-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-detection.d.ts","sourceRoot":"","sources":["../src/client-detection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAExE;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAiBxD"}

package/dist/client-detection.js

@@ -0,0 +1,22 @@
+/**
+ * Simple client detection that uses MCP handshake information.
+ * Only checks MCP_SOURCE override, then uses client-provided name directly.
+ */
+export function detectClientName(server) {
+    // 1) Explicit override
+    if (process.env.MCP_SOURCE) {
+        return process.env.MCP_SOURCE.toLowerCase();
+    }
+    // 2) Use client info from MCP handshake
+    try {
+        const clientInfo = server?.getClientVersion();
+        if (clientInfo?.name) {
+            return clientInfo.name.toLowerCase();
+        }
+    }
+    catch {
+        // Ignore handshake errors
+    }
+    return "unknown";
+}
+//# sourceMappingURL=client-detection.js.map

package/dist/client-detection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-detection.js","sourceRoot":"","sources":["../src/client-detection.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAe;IAC9C,uBAAuB;IACvB,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC;QAC3B,OAAO,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC;IAC9C,CAAC;IAED,wCAAwC;IACxC,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,MAAM,EAAE,gBAAgB,EAAE,CAAC;QAC9C,IAAI,UAAU,EAAE,IAAI,EAAE,CAAC;YACrB,OAAO,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QACvC,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0BAA0B;IAC5B,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Configuration for MCP server restrictions
+ */
+export interface McpServerConfig {
+    /** If false, exclude tools that can access or return user PII */
+    readonly allowUserPii: boolean;
+    /** If false, exclude tools that perform write operations */
+    readonly allowWrites: boolean;
+    /** If false, exclude tools that can send messages (campaign/journey/event-triggered sends) */
+    readonly allowSends: boolean;
+    /** The active Iterable API key (optional for tests) */
+    readonly apiKey?: string;
+    /** The Iterable API base URL (defaults to https://api.iterable.com) */
+    readonly baseUrl?: string;
+}
+export declare function resolveAllowFlags(keyEnv: Record<string, string> | undefined, env: NodeJS.ProcessEnv): {
+    allowUserPii: boolean;
+    allowWrites: boolean;
+    allowSends: boolean;
+};
+/**
+ * Load configuration from environment variables and key manager
+ */
+export declare function loadMcpServerConfig(): Promise<McpServerConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAKA;;GAEG;AAEH,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,8FAA8F;IAC9F,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EAC1C,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB;IAAE,YAAY,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAKtE;AAED;;GAEG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,eAAe,CAAC,CAiFpE"}

package/dist/config.js

@@ -0,0 +1,74 @@
+import { logger } from "@iterable/api";
+import { getKeyManager } from "./key-manager.js";
+import { sanitizeString } from "./utils/sanitize.js";
+export function resolveAllowFlags(keyEnv, env) {
+    const allowUserPii = (keyEnv?.ITERABLE_USER_PII ?? env.ITERABLE_USER_PII) === "true";
+    const allowWrites = (keyEnv?.ITERABLE_ENABLE_WRITES ?? env.ITERABLE_ENABLE_WRITES) === "true";
+    const allowSends = (keyEnv?.ITERABLE_ENABLE_SENDS ?? env.ITERABLE_ENABLE_SENDS) === "true";
+    return { allowUserPii, allowWrites, allowSends };
+}
+/**
+ * Load configuration from environment variables and key manager
+ */
+export async function loadMcpServerConfig() {
+    let apiKey = null;
+    let baseUrl = process.env.ITERABLE_BASE_URL || "https://api.iterable.com";
+    let keyEnv;
+    // Try to load API key from KeyManager first (macOS only)
+    // SAFETY: Skip keyManager in test environments to prevent production data access
+    if (process.platform === "darwin" && process.env.NODE_ENV !== "test") {
+        try {
+            const keyManager = getKeyManager();
+            await keyManager.initialize();
+            // Check if we have stored keys
+            if (await keyManager.hasKeys()) {
+                apiKey = await keyManager.getActiveKey();
+                // Get the base URL from the active key metadata
+                const activeKeyMetadata = await keyManager.getActiveKeyMetadata();
+                if (activeKeyMetadata?.baseUrl) {
+                    baseUrl = activeKeyMetadata.baseUrl;
+                }
+                if (activeKeyMetadata?.env) {
+                    keyEnv = activeKeyMetadata.env;
+                }
+            }
+            // If no stored keys and ITERABLE_API_KEY env var exists, migrate it
+            if (!apiKey && process.env.ITERABLE_API_KEY) {
+                await keyManager.migrateLegacyKey(process.env.ITERABLE_API_KEY, baseUrl);
+                apiKey = await keyManager.getActiveKey();
+            }
+        }
+        catch (error) {
+            // Distinguish between expected "no keys" vs unexpected errors
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            if (errorMessage.includes("Key store not initialized") ||
+                errorMessage.includes("No API key found")) {
+                // Expected - no keys stored yet, will fall back to env
+                logger.debug("No keys in key manager, falling back to environment variable");
+            }
+            else {
+                // Unexpected error - log more details (sanitized to prevent key leakage)
+                const sanitizedMessage = sanitizeString(errorMessage);
+                logger.error("Unexpected error loading from key manager", {
+                    error: sanitizedMessage,
+                });
+                console.error("⚠️  Warning: Failed to load API key from macOS Keychain:", sanitizedMessage);
+                // Provide helpful guidance for sync issues
+                if (sanitizedMessage.includes("could not be found")) {
+                    console.error("\n💡 This may be a sync issue. Restarting the server will automatically clean up orphaned keys.");
+                }
+                console.error("   Falling back to ITERABLE_API_KEY environment variable");
+            }
+        }
+    }
+    // Fall back to environment variable if key manager didn't work
+    if (!apiKey && process.env.ITERABLE_API_KEY) {
+        apiKey = process.env.ITERABLE_API_KEY;
+    }
+    if (!apiKey) {
+        throw new Error("No API key found. Please run 'iterable-mcp setup' or set ITERABLE_API_KEY environment variable.");
+    }
+    const { allowUserPii, allowWrites, allowSends } = resolveAllowFlags(keyEnv, process.env);
+    return { allowUserPii, allowWrites, allowSends, apiKey, baseUrl };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/http-headers.d.ts

@@ -0,0 +1,5 @@
+export declare const HEADER_USER_AGENT = "User-Agent";
+export declare const HEADER_CLIENT = "Iterable-MCP-Client";
+export declare const HEADER_SESSION_ID = "Iterable-MCP-Session-Id";
+export declare const HEADER_TOOL = "Iterable-MCP-Tool";
+//# sourceMappingURL=http-headers.d.ts.map

package/dist/http-headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-headers.d.ts","sourceRoot":"","sources":["../src/http-headers.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAC9C,eAAO,MAAM,aAAa,wBAAwB,CAAC;AACnD,eAAO,MAAM,iBAAiB,4BAA4B,CAAC;AAC3D,eAAO,MAAM,WAAW,sBAAsB,CAAC"}

package/dist/http-headers.js

@@ -0,0 +1,5 @@
+export const HEADER_USER_AGENT = "User-Agent";
+export const HEADER_CLIENT = "Iterable-MCP-Client";
+export const HEADER_SESSION_ID = "Iterable-MCP-Session-Id";
+export const HEADER_TOOL = "Iterable-MCP-Tool";
+//# sourceMappingURL=http-headers.js.map

package/dist/http-headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-headers.js","sourceRoot":"","sources":["../src/http-headers.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,iBAAiB,GAAG,YAAY,CAAC;AAC9C,MAAM,CAAC,MAAM,aAAa,GAAG,qBAAqB,CAAC;AACnD,MAAM,CAAC,MAAM,iBAAiB,GAAG,yBAAyB,CAAC;AAC3D,MAAM,CAAC,MAAM,WAAW,GAAG,mBAAmB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}