@jclvsh/iris 0.2.3 → 0.3.0

package/README.md

@@ -1,32 +1,108 @@
 # @jclvsh/iris
 
-MCP server for the [Iris](https://iris-ai.dev) API — AI-powered messaging assistant for automated multi-channel outreach campaigns.
+MCP server and CLI for the [Iris](https://iris-ai.dev) API — AI-powered messaging assistant for automated multi-channel outreach campaigns. Lets AI agents (Claude Code, Cursor) and humans manage campaigns, contacts, conversations, AI generations, discovery, channels, and webhooks.
 
-## Install
+## Installation
 
-The package ships two binaries: `iris-mcp` (the MCP server, used in MCP host configs below) and `iris` (the CLI, for terminal use). One-shot run:
+```bash
+npm install -g @jclvsh/iris
+```
+
+This installs two binaries:
+
+- `iris` — CLI for terminal use
+- `iris-mcp` — MCP server for AI agents
+
+Or run one-shot without installing:
 
 ```bash
 npx -y -p @jclvsh/iris iris-mcp
 ```
 
-## Configuration
+## CLI
+
+```bash
+# set your API key
+export IRIS_API_KEY=is_live_...
+
+# manage campaigns
+iris campaigns list
+iris campaigns create -n "spring outreach" -o product_promotion --product-name "acme widgets"
+iris campaigns analyze <id>
+iris campaigns usage <id>
+
+# manage contacts
+iris contacts list --campaign-id <id>
+iris contacts create --campaign-id <id> -e jane@example.com --full-name "Jane Doe" --company-name "Acme"
+
+# review the AI approval queue
+iris messages pending --campaign-id <id>
+iris messages approve <id>
+iris messages reject <id> --reason "off-topic"
+iris messages bulk -a approve --ids id1,id2,id3
+
+# manage webhooks
+iris webhooks create -u https://example.com/hook -e campaign.created,message.delivered
+iris webhooks test <id>
+iris webhooks deliveries <id>
+
+# check your key
+iris keys me
+
+# table output
+iris --format table campaigns list
+
+# full help
+iris --help
+iris campaigns --help
+```
+
+### CLI Commands
+
+| Group | Alias | Commands | Count |
+| --- | --- | --- | --- |
+| campaigns | `c` | list, get, create, update, delete, usage, analyze | 7 |
+| contacts | `ct` | list, get, create, update, delete, usage | 6 |
+| messages | `m` | pending, approve, reject, retry, feedback, bulk | 6 |
+| conversations | `conv` | list, get, messages, read | 4 |
+| discovery | `d` | search, search-campaign, sources, job | 4 |
+| ai | — | generate, generate-campaign, analyze, usage, suggestions | 5 |
+| keys | `k` | me, list, create, rename, revoke | 5 |
+| webhooks | `w` | list, create, get, update, delete, test, deliveries | 7 |
+| notifications | `n` | list, update, delete, read-all | 4 |
+| analytics | `a` | overview, campaign, performance, response-time, contact-types | 5 |
+| billing | `b` | plans | 1 |
+| channels | `ch` | accounts, availability, send | 3 |
+| credits | `cr` | balance, buy | 2 |
+
+## MCP Server Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `IRIS_API_KEY` | Yes | API key (must start with `is_live_`) |
+| `IRIS_API_URL` | No | API base URL (default: `https://iris-ai.dev/api/v1`) |
+
+> **Note:** the args use `-p @jclvsh/iris iris-mcp` to explicitly select the MCP-server bin. The package ships two binaries (`iris` for the CLI, `iris-mcp` for the MCP server), so a bare `npx @jclvsh/iris` would launch the CLI by default.
+
+Get your API key at [iris-ai.dev/settings/api-keys](https://iris-ai.dev/settings/api-keys).
 
 ### Claude Code
 
-Add to your Claude Code settings:
+Add to your `.claude/settings.json`:
 
 ```json
 {
-  "mcpServers": {
-    "iris": {
-      "command": "npx",
-      "args": ["-y", "-p", "@jclvsh/iris", "iris-mcp"],
-      "env": {
-        "IRIS_API_KEY": "is_live_..."
-      }
-    }
-  }
+	"mcpServers": {
+		"iris": {
+			"command": "npx",
+			"args": ["-y", "-p", "@jclvsh/iris", "iris-mcp"],
+			"env": {
+				"IRIS_API_KEY": "is_live_your_key_here"
+			}
+		}
+	}
 }
 ```
 
@@ -36,45 +112,306 @@ Add to `.cursor/mcp.json`:
 
 ```json
 {
-  "mcpServers": {
-    "iris": {
-      "command": "npx",
-      "args": ["-y", "-p", "@jclvsh/iris", "iris-mcp"],
-      "env": {
-        "IRIS_API_KEY": "is_live_..."
-      }
-    }
-  }
+	"mcpServers": {
+		"iris": {
+			"command": "npx",
+			"args": ["-y", "-p", "@jclvsh/iris", "iris-mcp"],
+			"env": {
+				"IRIS_API_KEY": "is_live_your_key_here"
+			}
+		}
+	}
 }
 ```
 
-## Environment Variables
+## Available Tools
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `IRIS_API_KEY` | Yes | API key (must start with `is_live_`) |
-| `IRIS_API_URL` | No | Base URL (default: `https://iris-ai.dev/api/v1`) |
+### Campaigns
 
-Get your API key at [iris-ai.dev/settings/api-keys](https://iris-ai.dev/settings/api-keys).
+| Tool | Description |
+| --- | --- |
+| `list_campaigns` | List campaigns with optional status filter |
+| `create_campaign` | Create a new outreach campaign |
+| `get_campaign` | Get a campaign by ID with stats |
+| `update_campaign` | Update a campaign's name, status, or follow-up settings |
+| `delete_campaign` | Soft-delete a campaign (sets status to `deleted`) |
+| `list_campaign_contacts` | List contacts in a campaign with optional status filter |
+| `get_campaign_usage` | Get usage limits and current counts for a campaign |
+| `analyze_campaign` | Trigger AI analysis to generate target profiles |
+| `list_target_profiles` | List target profiles for a campaign |
+| `create_target_profile` | Create a target profile for a campaign |
+| `delete_target_profile` | Delete a target profile from a campaign |
 
-## Available Tools
+#### `create_campaign` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string (1-100) | Yes | Campaign name |
+| `objective_type` | enum | Yes | `venue_dj`, `venue_host`, `product_promotion`, `custom` |
+| `product_name` | string (≤200) | No | Product name (for `product_promotion`) |
+| `product_url` | string (URL) | No | Product URL (for `product_promotion`) |
+| `product_description` | string (≤2000) | No | Product description (for `product_promotion`) |
+
+#### `update_campaign` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | string (UUID) | Yes | Campaign ID |
+| `name` | string (1-100) | No | New campaign name |
+| `status` | enum | No | `draft`, `active`, `paused`, `completed`, `deleted` |
+| `follow_up_enabled` | boolean | No | Enable follow-up emails |
+| `follow_up_max_count` | number (0-10) | No | Max follow-up count |
+| `follow_up_delay_days` | number (1-30) | No | Days between follow-ups |
+
+#### `create_target_profile` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | string (UUID) | Yes | Campaign ID |
+| `name` | string (1-200) | Yes | Profile name |
+| `profile_type` | enum | Yes | `local_business`, `content_creator`, `influencer`, `b2b_professional`, `ecommerce`, `saas_company`, `agency`, `freelancer`, `other` |
+| `job_titles` | string[] | No | Target job titles |
+| `industries` | string[] | No | Target industries |
+| `discovery_keywords` | string[] | No | Keywords for contact discovery |
+| `recommended_channels` | string[] | No | `email`, `instagram`, `twitter`, `linkedin` |
+
+### Contacts
+
+| Tool | Description |
+| --- | --- |
+| `list_contacts` | List contacts with search |
+| `create_contact` | Create a new contact |
+| `get_contact` | Get a contact by ID |
+| `update_contact` | Update a contact's details |
+| `delete_contact` | Soft-delete a contact |
+| `bulk_import_contacts` | Import up to 500 contacts at once |
+| `get_contact_usage` | Get usage limits for the billing period |
+| `list_contact_conversations` | List conversations for a specific contact |
+
+#### `create_contact` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `email` | string (email) | Yes | Contact email address |
+| `first_name` | string (≤100) | No | First name |
+| `last_name` | string (≤100) | No | Last name |
+| `company_name` | string (≤200) | No | Company name |
+| `job_title` | string (≤200) | No | Job title |
+| `phone` | string (≤50) | No | Phone number |
+| `website` | string (URL) | No | Website URL |
+| `tags` | string[] | No | Tags for categorization |
+
+#### `bulk_import_contacts` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `contacts` | object[] (1-500) | Yes | Array of contacts (`email`, `first_name?`, `last_name?`, `company_name?`, `job_title?`, `tags?`) |
+| `campaign_id` | string (UUID) | No | Campaign to add contacts to |
+
+### Messages
+
+| Tool | Description |
+| --- | --- |
+| `list_pending_messages` | List messages pending approval |
+| `approve_message` | Approve a single pending message |
+| `reject_message` | Reject a single pending message |
+| `retry_message` | Retry a failed message send |
+| `submit_message_feedback` | Submit feedback to improve future AI generations |
+| `bulk_message_action` | Bulk approve or reject pending messages |
 
-| Category | Tools |
-|----------|-------|
-| Campaigns | list, create, get, update, delete, contacts, usage, analyze, target profiles |
-| Contacts | list, create, get, update, delete, bulk import, usage, conversations |
-| Conversations | list, get, messages, mark read, engagement metrics |
-| Messages | list pending, approve, reject, retry, feedback, bulk action |
-| AI | generate content, campaign content, analyze response, usage, suggestions |
-| Discovery | search contacts, campaign search, job status, sources |
-| Analytics | overview, campaign analytics, performance, response time, contact types |
-| Billing | plans |
-| Channels | connected accounts, availability, send message |
-| Notifications | list, update, delete, mark all read |
-| API Keys | current key, list, create, revoke |
-| Webhooks | list, create, get, update, delete, test, deliveries |
-| Agent Credits | balance, purchase pack (x402/MPP only) |
+### Conversations
+
+| Tool | Description |
+| --- | --- |
+| `list_conversations` | List conversations with optional channel/status filters |
+| `get_conversation` | Get a conversation by ID |
+| `get_conversation_messages` | List messages in a conversation |
+| `mark_conversation_read` | Mark a conversation as read |
+| `get_engagement_metrics` | Get engagement metrics across conversations |
+
+### AI
+
+| Tool | Description |
+| --- | --- |
+| `generate_content` | Generate AI content for a contact conversation (initial email, follow-up, reply) |
+| `generate_campaign_content` | Generate campaign-level content (email templates, subject lines, briefs) |
+| `analyze_response` | Analyze inbound message sentiment, intent, and suggested action |
+| `get_ai_usage` | Get AI generation usage limits |
+| `get_ai_suggestions` | Get AI-powered suggestions for a conversation |
+
+#### `generate_content` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `contact_id` | string (UUID) | Yes | Contact ID |
+| `conversation_id` | string (UUID) | Yes | Conversation ID |
+| `generation_type` | enum | Yes | `initial_email`, `follow_up`, `reply` |
+| `context` | string (≤2000) | No | Additional context for the AI |
+
+### Discovery
+
+| Tool | Description |
+| --- | --- |
+| `search_contacts` | Search for contacts by criteria (location, keywords, sources) |
+| `search_campaign_contacts` | Run discovery scoped to a campaign's target profiles |
+| `get_discovery_job` | Get the status of a discovery job |
+| `list_discovery_sources` | List available discovery sources (Google Maps, social) |
+
+### Channels
+
+| Tool | Description |
+| --- | --- |
+| `list_connected_accounts` | List your connected social accounts (Twitter, Instagram, LinkedIn) |
+| `check_channel_availability` | Check which channels are reachable for a contact |
+| `send_channel_message` | Send a message via a specific channel |
+
+### Analytics
+
+| Tool | Description |
+| --- | --- |
+| `get_analytics_overview` | Account-level analytics overview |
+| `get_campaign_analytics` | Per-campaign performance metrics |
+| `get_performance_metrics` | Aggregate performance across campaigns |
+| `get_response_time` | Response time distribution |
+| `get_contact_types` | Engagement broken down by contact type |
+
+### Notifications
+
+| Tool | Description |
+| --- | --- |
+| `list_notifications` | List your notifications |
+| `update_notification` | Mark a notification as read or update its state |
+| `delete_notification` | Delete a notification |
+| `mark_all_notifications_read` | Mark every unread notification as read |
+
+### Billing
+
+| Tool | Description |
+| --- | --- |
+| `get_billing_plans` | List available subscription plans |
+
+### API Keys
+
+| Tool | Description |
+| --- | --- |
+| `get_current_api_key` | Get details about the currently authenticated key |
+| `list_api_keys` | List all API keys for the account |
+| `create_api_key` | Create a new API key (raw key returned once) |
+| `revoke_api_key` | Revoke (delete) an API key |
+
+#### `create_api_key` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `name` | string (1-100) | Yes | Key name for identification |
+| `scopes` | string[] | No | Permission scopes (defaults to all scopes) — see [Scopes](#api-key--scopes) |
+| `expires_at` | string (ISO 8601) | No | Expiration date |
+
+### Webhooks
+
+| Tool | Description |
+| --- | --- |
+| `list_webhooks` | List all configured webhooks |
+| `create_webhook` | Create a new webhook endpoint |
+| `get_webhook` | Get a webhook by ID |
+| `update_webhook` | Update a webhook's URL, events, or active status |
+| `delete_webhook` | Delete a webhook |
+| `test_webhook` | Send a test event to a webhook URL |
+| `rotate_webhook_secret` | Rotate the signing secret (new secret returned once) |
+| `list_webhook_deliveries` | List delivery history for a webhook |
+
+#### `create_webhook` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `url` | string (HTTPS URL) | Yes | Webhook endpoint URL — HTTPS only |
+| `events` | string[] (≥1) | Yes | Events to subscribe to — see [Webhook Events](#webhook-events) |
+| `description` | string (≤500) | No | Webhook description |
+
+#### `update_webhook` Parameters
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | string (UUID) | Yes | Webhook ID |
+| `url` | string (HTTPS URL) | No | New endpoint URL |
+| `events` | string[] (≥1) | No | New events to subscribe to |
+| `active` | boolean | No | Enable or disable the webhook |
+
+### Agent Credits
+
+> Credits apply only to agents authenticating via x402 (USDC on Base) or MPP (Stripe). API key users do not need credits.
+
+| Tool | Description |
+| --- | --- |
+| `get_credit_balance` | Check the agent credit balance |
+| `purchase_credit_pack` | Purchase a 5-credit pack via MPP ($12.00) |
+
+## API Key & Scopes
+
+Generate an API key at [iris-ai.dev/settings/api-keys](https://iris-ai.dev/settings/api-keys).
+
+API keys support fine-grained scopes per resource:
+
+| Scope | Access |
+| --- | --- |
+| `campaigns:read` / `campaigns:write` | Read or modify campaigns |
+| `contacts:read` / `contacts:write` | Read or modify contacts |
+| `conversations:read` / `conversations:write` | Read conversations or send messages |
+| `messages:read` / `messages:write` | Read the queue, approve/reject/send |
+| `ai:read` / `ai:write` | Read AI usage or trigger generations |
+| `discovery:read` / `discovery:write` | Read sources or run discovery jobs |
+| `analytics:read` | Read analytics dashboards |
+| `billing:read` | Read billing plans |
+| `channels:read` / `channels:write` | Read connected accounts or send via channels |
+| `notifications:read` / `notifications:write` | Read or modify notifications |
+| `webhooks:read` / `webhooks:write` | Read or manage webhook subscriptions |
+| `keys:read` / `keys:write` | Read or manage API keys |
+
+### Recommended Scopes by Use Case
+
+| Use Case | Recommended Scopes |
+| --- | --- |
+| AI agents / MCP | `campaigns:read`, `campaigns:write`, `contacts:read`, `contacts:write`, `messages:read`, `messages:write`, `ai:read`, `ai:write`, `conversations:read`, `conversations:write` |
+| Read-only monitoring | `*:read` scopes only |
+| Webhook management | `webhooks:read`, `webhooks:write` |
+| Discovery automation | `discovery:read`, `discovery:write`, `contacts:write`, `campaigns:read` |
+
+## Webhook Events
+
+| Event | Description |
+| --- | --- |
+| `campaign.created` | New campaign created |
+| `campaign.updated` | Campaign details changed |
+| `campaign.deleted` | Campaign soft-deleted |
+| `contact.created` | New contact added |
+| `contact.updated` | Contact details changed |
+| `contact.deleted` | Contact soft-deleted |
+| `conversation.created` | New conversation started |
+| `conversation.reply_received` | Inbound reply received |
+| `message.sent` | Outbound message sent |
+| `message.delivered` | Message confirmed delivered |
+| `message.opened` | Email opened (filtered for bots) |
+| `message.bounced` | Message bounced |
+| `message.approved` | Message approved in the queue |
+| `message.rejected` | Message rejected in the queue |
+| `discovery.completed` | Discovery job finished successfully |
+| `discovery.failed` | Discovery job failed |
+
+Webhook deliveries are signed with HMAC-SHA256 using the secret returned from `create_webhook` / `rotate_webhook_secret`. Verify the signature in the `X-Iris-Signature` header before trusting the payload.
 
 ## Documentation
 
-Full API documentation: [iris-ai.dev/docs](https://iris-ai.dev/docs)
+Full API reference: [iris-ai.dev/docs](https://iris-ai.dev/docs)
+
+## Development
+
+```bash
+# install dependencies
+npm install
+
+# build
+npm run build
+
+# run the MCP server
+IRIS_API_KEY=is_live_... npm start
+```

package/dist/cli.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
 import { Command } from "commander";
 import { IrisClient } from "./client.js";
 import { handleError } from "./cli-utils.js";
+const pkg = createRequire(import.meta.url)("../package.json");
 import { registerCampaignCommands } from "./commands/campaigns.js";
 import { registerContactCommands } from "./commands/contacts.js";
 import { registerMessageCommands } from "./commands/messages.js";
@@ -18,7 +20,7 @@ import { registerCreditCommands } from "./commands/credits.js";
 const program = new Command()
     .name("iris")
     .description("iris CLI - manage campaigns, contacts, messages, and outreach")
-    .version("0.2.0")
+    .version(pkg.version)
     .option("--json", "output as JSON (default)")
     .option("--format <fmt>", "output format: json, table", "json");
 try {

package/dist/client.js

@@ -1,3 +1,32 @@
+function safeStringify(value) {
+    if (Array.isArray(value)) {
+        const parts = value
+            .map((entry) => {
+            if (typeof entry === "string")
+                return entry;
+            if (entry && typeof entry === "object") {
+                const msg = entry.msg;
+                if (typeof msg === "string")
+                    return msg;
+            }
+            try {
+                return JSON.stringify(entry);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((p) => typeof p === "string" && p.length > 0);
+        if (parts.length > 0)
+            return parts.join("; ");
+    }
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
 export class IrisClient {
     apiKey;
     baseUrl;
@@ -77,7 +106,13 @@ export class IrisClient {
         try {
             const body = await response.json();
             if (body?.error) {
-                const parts = [body.error.message || "unknown error"];
+                const rawMessage = body.error.message;
+                const messageStr = typeof rawMessage === "string" && rawMessage.trim() !== ""
+                    ? rawMessage
+                    : rawMessage != null
+                        ? safeStringify(rawMessage)
+                        : "unknown error";
+                const parts = [messageStr];
                 if (body.error.code)
                     parts.unshift(`[${body.error.code}]`);
                 if (body.error.field)

package/dist/commands/channels.js

@@ -28,7 +28,7 @@ export function registerChannelCommands(program, client) {
     channels
         .command("send")
         .description("send a message through a specific channel in a conversation")
-        .requiredOption("--channel <channel>", "channel: email, instagram, twitter, linkedin")
+        .requiredOption("--channel <channel>", "channel: email, instagram, twitter")
         .requiredOption("--conversation-id <id>", "conversation ID")
         .requiredOption("--recipient-id <id>", "recipient (email for email channel; platform handle/ID for social)")
         .requiredOption("-c, --content <text>", "message content")

package/dist/commands/conversations.js

@@ -11,7 +11,7 @@ export function registerConversationCommands(program, client) {
         .option("-s, --page-size <n>", "items per page (max 100)", "50")
         .option("--status <status>", "filter by status")
         .option("--campaign-id <id>", "filter by campaign")
-        .option("--channel <channel>", "filter by channel: email, instagram, twitter, linkedin")
+        .option("--channel <channel>", "filter by channel: email, instagram, twitter")
         .action(async (opts) => {
         try {
             const params = {};

package/dist/commands/messages.js

@@ -7,7 +7,7 @@ export function registerMessageCommands(program, client) {
         .option("-p, --page <n>", "page number", "1")
         .option("-s, --page-size <n>", "items per page (max 100)", "50")
         .option("--campaign-id <id>", "filter by campaign")
-        .option("--channel <channel>", "filter by channel: email, instagram, twitter, linkedin")
+        .option("--channel <channel>", "filter by channel: email, instagram, twitter")
         .option("--status <status>", "queue status (default: pending_approval)")
         .action(async (opts) => {
         try {

package/dist/tools/campaigns.js

@@ -178,7 +178,7 @@ export function registerCampaignTools(server, client) {
         industries: z.array(z.string()).optional().describe("target industries"),
         discovery_keywords: z.array(z.string()).optional().describe("keywords for contact discovery"),
         recommended_channels: z
-            .array(z.enum(["email", "instagram", "twitter", "linkedin"]))
+            .array(z.enum(["email", "instagram", "twitter"]))
             .optional()
             .describe("recommended outreach channels"),
     }, async ({ id, ...body }) => {

package/dist/tools/channels.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-const CHANNELS = ["email", "instagram", "twitter", "linkedin"];
+const CHANNELS = ["email", "instagram", "twitter"];
 export function registerChannelTools(server, client) {
     server.tool("list_connected_accounts", "list all connected social media accounts. requires channels:read scope.", {}, async () => {
         try {

package/dist/tools/discovery.js

@@ -1,11 +1,52 @@
 import { z } from "zod";
-const DISCOVERY_SOURCES = ["google_maps", "instagram", "twitter", "linkedin"];
+const DISCOVERY_SOURCES = ["google_maps", "instagram", "twitter", "tiktok", "reddit"];
+const PROFILE_TYPES = [
+    "local_business",
+    "content_creator",
+    "influencer",
+    "b2b_professional",
+    "ecommerce",
+    "saas_company",
+    "agency",
+    "freelancer",
+    "other",
+];
 export function registerDiscoveryTools(server, client) {
-    server.tool("search_contacts", "search for new contacts using external data sources (Google Maps, social platforms). requires discovery:write scope.", {
-        query: z.string().min(1).max(500).describe("search query"),
-        source: z.enum(DISCOVERY_SOURCES).describe("data source to search"),
-        max_results: z.number().int().min(1).max(100).optional().describe("maximum number of results (default 20)"),
-        campaign_id: z.string().uuid().optional().describe("campaign to add discovered contacts to"),
+    server.tool("search_contacts", "kick off a multi-source contact discovery job (Apify-backed). returns a job_id and contacts when ready (waits up to 90s; if status=queued, poll get_discovery_job). closed source list: google_maps, instagram, twitter, tiktok, reddit. requires discovery:write scope.", {
+        keywords: z
+            .array(z.string().min(1))
+            .min(1)
+            .describe("non-empty array of search keywords (e.g. ['boutique hotel', 'rooftop venue'])"),
+        location: z
+            .string()
+            .optional()
+            .describe("location for geo-scoped goals (local_business / venue / brick-and-mortar). omit for global goals (creators, b2b, saas)."),
+        radius_miles: z.number().positive().optional().default(25).describe("search radius in miles (default 25)"),
+        max_results: z
+            .number()
+            .int()
+            .min(10)
+            .max(500)
+            .optional()
+            .describe("max contacts to return (10-500, default 50; server clamps to plan cap)"),
+        sources: z
+            .array(z.enum(DISCOVERY_SOURCES))
+            .optional()
+            .describe("override the default per-profile_type source mix. valid: google_maps, instagram, twitter, tiktok, reddit. omit to let the orchestrator pick."),
+        profile_type: z
+            .enum(PROFILE_TYPES)
+            .optional()
+            .describe("ICP profile type — drives default source mix when sources is omitted"),
+        campaign_id: z
+            .string()
+            .uuid()
+            .optional()
+            .describe("campaign to attach discovered contacts to on finalize"),
+        enrich_emails: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("run waterfall email enrichment (BetterContact → FullEnrich → ZeroBounce). default true."),
     }, async (args) => {
         try {
             const result = await client.post("/discovery/search", args);
@@ -33,7 +74,7 @@ export function registerDiscoveryTools(server, client) {
             };
         }
     });
-    server.tool("get_discovery_job", "get the status and results of a discovery job. requires discovery:read scope.", {
+    server.tool("get_discovery_job", "get the status, progress, and contacts of a discovery job. status values: pending, running, completed, failed. contacts populated only when status=completed. requires discovery:read scope.", {
         id: z.string().uuid().describe("discovery job ID"),
     }, async ({ id }) => {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jclvsh/iris",
-	"version": "0.2.3",
+	"version": "0.3.0",
 	"description": "MCP server for the Iris API",
 	"type": "module",
 	"main": "dist/index.js",