From 95ae2f76e0f7bd2058334560ba9e96c0d64c7436 Mon Sep 17 00:00:00 2001 From: Greg Methvin Date: Tue, 24 Feb 2026 02:08:53 -0800 Subject: [PATCH] Restructure README and create CONTRIBUTING file --- CONTRIBUTING.md | 121 +++++++++++++++++++++++++ LICENSE => LICENSE.md | 2 +- README.md | 199 ++++++++++++++---------------------------- _sidebar.md | 2 + 4 files changed, 191 insertions(+), 133 deletions(-) create mode 100644 CONTRIBUTING.md rename LICENSE => LICENSE.md (96%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f4fc48a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,121 @@ +# Contributing + +Thanks for your interest in contributing to the Iterable MCP Server! We welcome bug reports, feature requests, and pull requests. If you find a bug or have an idea, please [open an issue](https://github.com/Iterable/mcp-server/issues). + +## Prerequisites + +- Node.js >= 20 (v22 LTS recommended) +- [pnpm](https://pnpm.io/) (see `packageManager` in `package.json` for the exact version) + +## Install from source + +To test changes locally, clone the repo and use one of the `install-dev` scripts. This builds the project and links it as a local MCP server in your AI client, so you can test your changes without publishing to npm. + +```bash +git clone https://github.com/iterable/mcp-server.git +cd mcp-server +pnpm install-dev:cursor # or install-dev:claude-desktop, install-dev:claude-code, install-dev:gemini-cli, install-dev:windsurf, install-dev:antigravity +``` + +To enable debug logging during local development, use the `:debug` variants: + +```bash +pnpm install-dev:cursor:debug +``` + +## Project structure + +MCP tools live in `src/tools/`, one file per domain (campaigns, templates, catalogs, etc.). Each file exports a creator function that returns an array of MCP `Tool` definitions. These are registered in `src/tools/index.ts` via the `TOOL_CREATORS_BY_CATEGORY` array — adding a tool to the appropriate domain file is all that's needed for it to be picked up. + +Tool visibility is controlled by `src/tool-filter.ts`, which uses safe-lists to gate tools based on the `ITERABLE_USER_PII`, `ITERABLE_ENABLE_WRITES`, and `ITERABLE_ENABLE_SENDS` permission flags. + +### API client + +The MCP server uses [`@iterable/api`](https://github.com/Iterable/api-client) as its underlying API client. Tool definitions in this repo map user requests to API client methods. If you need to add support for a new Iterable API endpoint, you'll need to add it to the [api-client](https://github.com/Iterable/api-client) first, then expose it as an MCP tool here. + +## Development workflow + +```bash +# Install dependencies +pnpm install + +# Build the project (runs lint:fix, compiles TypeScript, updates TOOLS.md) +pnpm build + +# Build and watch for changes (TypeScript only, does not update TOOLS.md) +pnpm build:watch + +# Run in development mode (auto-reloads on file changes) +pnpm dev + +# Build and link locally for testing +pnpm run install-dev +``` + +## Code quality + +The build automatically runs `lint:fix`, but you can also run these independently: + +```bash +# Run all checks (format, typecheck, lint) +pnpm check + +# Auto-format with Prettier +pnpm format + +# Auto-fix lint issues with ESLint +pnpm lint:fix +``` + +## 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 + +# Watch mode +pnpm test:watch +``` + +### 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 add a key to key manager (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 ` to switch between them. + +3. Run the integration tests: + ```bash + pnpm test:integration + ``` + +**Note:** Integration tests require a valid API key (env var or active key manager key). The suite fails fast if none is found. + +## How TOOLS.md stays in sync + +`TOOLS.md` is auto-generated. The `scripts/update-tools.js` script reads the tool registry (`TOOL_CREATORS_BY_CATEGORY`) and the permission safe-lists (`tool-filter.ts`) to produce the full tool listing with permission badges. It runs automatically as part of `pnpm build`. + +To regenerate it manually: + +```bash +pnpm update-tools +``` diff --git a/LICENSE b/LICENSE.md similarity index 96% rename from LICENSE rename to LICENSE.md index c6a29d7..8a37ec1 100644 --- a/LICENSE +++ b/LICENSE.md @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2025 Greg Methvin +Copyright (c) 2025-2026 Iterable, Inc. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 36710b9..dcb147d 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ By default, the setup wizard configures the server in a safe, read‑only mode ( npx @iterable/mcp setup --advanced ``` -What you’ll choose (optional): +What you'll choose (optional): - **User PII** (`ITERABLE_USER_PII`): access user profile data, including email addresses, phone numbers, and custom data fields. - **Writes** (`ITERABLE_ENABLE_WRITES`): create, update, and delete resources such as templates, lists, catalogs, campaigns, snippets, and user profiles. - **Sends** (`ITERABLE_ENABLE_SENDS`): send messages (email, SMS, push, in-app, WhatsApp), trigger campaigns and journeys, schedule and abort campaigns, and track events. Requires writes to be enabled. *Note: creating a blast campaign will schedule it for delivery, matching the behavior of the underlying Iterable API; there is no way to create a draft campaign. If you only need to draft content, you can do so with sends disabled by working with templates instead.* @@ -53,25 +53,67 @@ What you’ll choose (optional): Note that permission settings are saved per key (see key management section below), allowing you to enable different permissions for different projects, e.g. only enable writes and sends for a sandbox project and disable them in production. -### Prefer a global install? +## 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). + +Try these prompts: +- *"Get details on campaign 12345"* +- *"What email templates are available?"* +- *"Show me all my product catalogs"* +- *"What journeys are currently active?"* +- *"Show me events for user@example.com from the last 30 days"* +- *"Create a campaign called 'Holiday Sale' using template 456"* +- *"Export all user data from January 2024"* +- *"List users in my 'VIP Customers' list"* + +## API Key Management + +**Key Storage:** + +API keys are stored in the `~/.iterable-mcp/keys.json` file and managed via the `npx @iterable/mcp keys` commands. On macOS the actual API key values are stored in the system Keychain. On Windows, API key values are encrypted using the Windows Data Protection API (DPAPI). On Linux, the API key values are stored directly in the file with restricted permissions (0o600). + +Each key is tied to its API endpoint (US, EU, or custom) and to its permissions (view PII, write operations, send messages). + +**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 -pnpm add -g @iterable/mcp -iterable-mcp setup +# List stored keys (shows which one is active with ● ACTIVE badge) +npx @iterable/mcp keys list + +# Add a new key (interactive: prompts for name, region/endpoint, and API key) +# Your first key becomes active automatically +npx @iterable/mcp keys add + +# Switch to a different key by name or ID (also switches endpoint) +npx @iterable/mcp keys activate production +npx @iterable/mcp keys activate staging + +# Delete a key by ID (requires ID for safety) +# Note: Cannot delete the currently active key - activate another first +npx @iterable/mcp keys delete + +# To update a key: delete the old one and add a new one with the same name ``` -**Note:** The setup command automatically configures the correct command path. +## Advanced setup -Throughout this guide, commands are shown as `iterable-mcp` for brevity. If not globally installed, use `npx @iterable/mcp` instead (e.g., `npx @iterable/mcp keys list`). +### Prefer a global install? -### Install from source +If you'd rather not use `npx`, you can install globally. This lets you use `iterable-mcp` as a shorthand for `npx @iterable/mcp`. ```bash -git clone https://github.com/iterable/mcp-server.git -cd mcp-server -pnpm install-dev:cursor # or install-dev:claude-desktop, install-dev:claude-code, or install-dev:gemini-cli +pnpm add -g @iterable/mcp +iterable-mcp setup ``` +**Note:** The setup command automatically configures the correct command path. + ### Claude Code The `setup --claude-code` command automatically configures Claude Code by running `claude mcp add` for you. @@ -79,8 +121,8 @@ The `setup --claude-code` command automatically configures Claude Code by runnin Alternatively, you can configure it manually: ```bash -# Add your API key first (see API Key Management section below) -iterable-mcp keys add +# Add your API key first (see API Key Management section above) +npx @iterable/mcp keys add # Then configure Claude Code claude mcp add iterable -- npx -y @iterable/mcp @@ -119,7 +161,7 @@ All five use the same configuration format: **Recommended: Using key manager:** ```bash # First, add your API key (interactive prompts) -iterable-mcp keys add +npx @iterable/mcp keys add ``` Then edit your config file: @@ -180,60 +222,10 @@ Alternatively, you can manually edit your configuration file (after adding your No `env` section is needed if using the key manager. -## 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). - -Try these prompts: -- *"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 & security - -### API Key Management - -**Key Storage:** - -API keys are stored in the `~/.iterable-mcp/keys.json` file and managed via the `iterable-mcp keys` commands. On macOS the actual API key values are stored in the system Keychain. On Linux, the API key values are stored directly in the file with restricted permissions (0o600). On Windows, the file is protected by default NTFS home directory permissions. - -Each key is tied to its API endpoint (US, EU, or custom) and to its permissions (view PII, write operations, send messages). - -**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 - -# To update a key: delete the old one and add a new one with the same name -``` - ### Environment variables +The setup wizard and key manager handle most of these automatically. Setting environment variables directly is useful for CI/CD pipelines, Docker containers, or other non-interactive environments where the key manager isn't available. When both are present, key manager settings take precedence over environment variables. + | Variable | Required | Description | |----------|----------|-------------| | `ITERABLE_API_KEY` | No* | Your Iterable API key (*Optional if using key manager, otherwise required) | @@ -252,70 +244,9 @@ iterable-mcp keys delete - 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 add a key to key manager (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 ` to switch between them. - -3. Run the integration tests: - ```bash - pnpm test:integration - ``` - -**Note:** Integration tests require a valid API key (env var or active key manager 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 -``` - ## Troubleshooting -- Claude CLI missing: install `claude` CLI, then re-run `iterable-mcp setup --claude-code`. +- Claude CLI missing: install `claude` CLI, then re-run `npx @iterable/mcp setup --claude-code`. - macOS Keychain issues: Ensure Keychain is accessible and re-run setup if needed. ### Client-specific limitations @@ -332,12 +263,12 @@ pnpm run install-dev You can configure permissions when adding a key: ```bash -iterable-mcp keys add --advanced +npx @iterable/mcp keys add --advanced ``` Or update an existing key's permissions: ```bash -iterable-mcp keys update --advanced +npx @iterable/mcp keys update --advanced ``` **Process persistence:** After switching API keys with `keys activate`, you must **fully restart Windsurf** (quit and reopen the application). Windsurf keeps MCP server processes running in the background, and they don't automatically reload when you switch keys. @@ -354,14 +285,18 @@ iterable-mcp keys update --advanced You can configure permissions when adding a key: ```bash -iterable-mcp keys add --advanced +npx @iterable/mcp keys add --advanced ``` Or update an existing key's permissions: ```bash -iterable-mcp keys update --advanced +npx @iterable/mcp keys update --advanced ``` +## Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, building from source, and running tests. + ## Beta Feature Reminder Iterable's MCP server is currently in beta. MCP functionality may change, be suspended, or be discontinued at any time without notice. This software is @@ -370,4 +305,4 @@ more information, refer to [Iterable Beta Terms](https://iterable.com/trust/beta ## License -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +This project is licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details. diff --git a/_sidebar.md b/_sidebar.md index 589d2e9..c37d5d5 100644 --- a/_sidebar.md +++ b/_sidebar.md @@ -1,2 +1,4 @@ - [Home](/) - [Available Tools](TOOLS.md) +- [Contributing](CONTRIBUTING.md) +- [License](LICENSE.md)