@jclvsh/iris 0.19.0 → 0.20.0

package/README.md

@@ -61,10 +61,10 @@ iris campaigns --help
 
 | Group         | Alias  | Commands                                                      | Count |
 | ------------- | ------ | ------------------------------------------------------------- | ----- |
-| campaigns     | `c`    | list, get, create, update, delete, usage, analyze             | 7     |
+| campaigns     | `c`    | list, get, create, update, delete, usage, analyze, contacts, add-contacts, chats, chat-messages, rename-chat, delete-chat | 13 |
 | 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     |
+| conversations | `conv` | list, get, create, send, messages, read, update                | 7     |
 | discovery     | `d`    | search, search-campaign, sources, job                         | 4     |
 | ai            | —      | generate, generate-campaign, analyze, usage                   | 4     |
 | keys          | `k`    | me, list, create, rename, revoke                              | 5     |
@@ -136,6 +136,11 @@ Add to `.cursor/mcp.json`:
 | `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 |
+| `add_campaign_contacts`  | Add contacts to a campaign by id or inline; needed before activation |
+| `list_campaign_chats`    | List iris chat sessions (the conversational campaign builder) |
+| `get_campaign_chat_messages` | List the messages in a chat session, oldest first    |
+| `rename_campaign_chat`   | Rename a chat session                                   |
+| `delete_campaign_chat`   | Soft-delete a chat session                              |
 | `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                     |
@@ -225,6 +230,7 @@ Add to `.cursor/mcp.json`:
 | --------------------------- | ------------------------------------------------------- |
 | `list_conversations`        | List conversations with optional channel/status filters |
 | `get_conversation`          | Get a conversation by ID                                |
+| `update_conversation`       | Update a conversation's status (active, archived, closed) |
 | `get_conversation_messages` | List messages in a conversation                         |
 | `mark_conversation_read`    | Mark a conversation as read                             |
 | `get_engagement_metrics`    | Get engagement metrics across conversations             |

package/dist/commands/campaigns.js

@@ -120,6 +120,93 @@ export function registerCampaignCommands(program, client) {
             handleError(error);
         }
     });
+    campaigns
+        .command("contacts <id>")
+        .description("list the contacts in a campaign")
+        .option("-p, --page <n>", "page number", "1")
+        .option("-s, --page-size <n>", "items per page (max 100)", "50")
+        .option("--status <status>", "filter by contact status")
+        .action(async (id, opts) => {
+        try {
+            const params = {};
+            if (opts.page)
+                params.page = opts.page;
+            if (opts.pageSize)
+                params.page_size = opts.pageSize;
+            if (opts.status)
+                params.status = opts.status;
+            const result = await client.get(`/campaigns/${id}/contacts`, params);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    campaigns
+        .command("add-contacts <id>")
+        .description("link existing contacts to a campaign (a campaign needs at least one before it can start)")
+        .requiredOption("--contact-ids <ids>", "comma-separated contact IDs to link")
+        .option("--no-deduplicate", "link even if already linked (default skips duplicates)")
+        .action(async (id, opts) => {
+        try {
+            const body = { contact_ids: parseList(opts.contactIds) };
+            if (opts.deduplicate === false)
+                body.deduplicate = false;
+            const result = await client.post(`/campaigns/${id}/contacts`, body);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    campaigns
+        .command("chats")
+        .description("list iris chat sessions, most recently updated first")
+        .action(async () => {
+        try {
+            const result = await client.get("/campaigns/chats");
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    campaigns
+        .command("chat-messages <chat-id>")
+        .description("list the messages in a chat session, oldest first")
+        .action(async (chatId) => {
+        try {
+            const result = await client.get(`/campaigns/chats/${chatId}/messages`);
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    campaigns
+        .command("rename-chat <chat-id> <title>")
+        .description("rename a chat session")
+        .action(async (chatId, title) => {
+        try {
+            const result = await client.patch(`/campaigns/chats/${chatId}`, { title });
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    campaigns
+        .command("delete-chat <chat-id>")
+        .description("soft-delete a chat session")
+        .action(async (chatId) => {
+        try {
+            await client.delete(`/campaigns/chats/${chatId}`);
+            console.log("chat deleted");
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
     const targetProfiles = campaigns
         .command("target-profiles")
         .alias("tp")

package/dist/commands/conversations.js

@@ -110,4 +110,17 @@ export function registerConversationCommands(program, client) {
             handleError(error);
         }
     });
+    conversations
+        .command("update <id>")
+        .description("update a conversation's status")
+        .requiredOption("--status <status>", "one of: active, archived, closed")
+        .action(async (id, opts) => {
+        try {
+            const result = await client.patch(`/conversations/${id}`, { status: opts.status });
+            formatOutput(result, getFormat(program.opts()));
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
 }

package/dist/tools/campaigns.js

@@ -115,6 +115,73 @@ export function registerCampaignTools(server, client) {
             return formatMcpError(error);
         }
     });
+    server.tool("add_campaign_contacts", "add contacts to a campaign, by id or by creating them inline. a campaign needs at least one contact before it can be activated. requires write scope.", {
+        id: z.string().uuid().describe("campaign ID"),
+        contact_ids: z.array(z.string().uuid()).optional().describe("ids of existing contacts to link"),
+        contacts: z
+            .array(z.record(z.string(), z.unknown()))
+            .optional()
+            .describe("new contacts to create and link (same shape as create_contact)"),
+        deduplicate: z.boolean().optional().describe("skip contacts already linked (default true)"),
+    }, async ({ id, contact_ids, contacts, deduplicate }) => {
+        try {
+            const body = {};
+            if (contact_ids)
+                body.contact_ids = contact_ids;
+            if (contacts)
+                body.contacts = contacts;
+            if (deduplicate !== undefined)
+                body.deduplicate = deduplicate;
+            const result = await client.post(`/campaigns/${id}/contacts`, body);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+    server.tool("list_campaign_chats", "list your iris chat sessions (the conversational campaign builder), most recently updated first, max 100. the live chat turn itself is a server-sent-events stream outside this tool set. requires read scope.", {}, async () => {
+        try {
+            const result = await client.get("/campaigns/chats");
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+    server.tool("get_campaign_chat_messages", "list the messages in a chat session, oldest first. `content` is an array of opaque blocks (text / tool_use / tool_result). requires read scope.", {
+        chat_id: z.string().uuid().describe("chat session ID"),
+    }, async ({ chat_id }) => {
+        try {
+            const result = await client.get(`/campaigns/chats/${chat_id}/messages`);
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+    server.tool("rename_campaign_chat", "rename a chat session. requires write scope.", {
+        chat_id: z.string().uuid().describe("chat session ID"),
+        title: z.string().min(1).max(200).describe("new title"),
+    }, async ({ chat_id, title }) => {
+        try {
+            const result = await client.patch(`/campaigns/chats/${chat_id}`, { title });
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
+    server.tool("delete_campaign_chat", "soft-delete a chat session. requires write scope.", {
+        chat_id: z.string().uuid().describe("chat session ID"),
+    }, async ({ chat_id }) => {
+        try {
+            await client.delete(`/campaigns/chats/${chat_id}`);
+            return { content: [{ type: "text", text: `chat ${chat_id} deleted` }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
     server.tool("get_campaign_usage", "get usage limits and current counts for a campaign. requires read scope.", {
         id: z.string().uuid().describe("campaign ID"),
     }, async ({ id }) => {

package/dist/tools/conversations.js

@@ -106,6 +106,18 @@ export function registerConversationTools(server, client) {
             return formatMcpError(error);
         }
     });
+    server.tool("update_conversation", "update a conversation's status: active, archived, or closed. requires write scope.", {
+        id: z.string().uuid().describe("conversation ID"),
+        status: z.enum(["active", "archived", "closed"]).describe("new conversation status"),
+    }, async ({ id, status }) => {
+        try {
+            const result = await client.patch(`/conversations/${id}`, { status });
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (error) {
+            return formatMcpError(error);
+        }
+    });
     server.tool("get_engagement_metrics", "get overall engagement metrics across all conversations. requires read scope.", {}, async () => {
         try {
             const result = await client.get("/conversations/engagement");

package/dist/tools/messages.js

@@ -56,7 +56,10 @@ export function registerMessageTools(server, client) {
         }
     });
     server.tool("mark_message_sent", "mark a pending manual-channel draft (tiktok, or instagram cold first-touch) as sent outside the platform. API-sendable drafts must use approve_message instead. requires write scope.", {
-        id: z.string().uuid().describe("approval queue item ID"),
+        id: z
+            .string()
+            .uuid()
+            .describe("approval queue item ID, or the message ID for drafts created via create_message (they have no approval item)"),
     }, async ({ id }) => {
         try {
             const result = await client.post(`/messages/${id}/mark-sent`);

package/dist/types.d.ts

@@ -52,6 +52,29 @@ export interface CampaignUsage {
     discovery_runs: number;
     discovery_limit: number;
 }
+/** `POST /campaigns/{id}/contacts` */
+export interface AddCampaignContactsResult {
+    added_count: number;
+    duplicates_count: number;
+    total_contacts: number;
+}
+/** `GET /campaigns/chats`, `PATCH /campaigns/chats/{id}` */
+export interface CampaignChat {
+    id: string;
+    campaign_id: string | null;
+    title: string | null;
+    status: string;
+    created_at: string;
+    updated_at: string;
+}
+/** `GET /campaigns/chats/{id}/messages` — `content` is an opaque block array. */
+export interface CampaignChatMessage {
+    id: string;
+    chat_id: string;
+    role: string;
+    content: unknown;
+    created_at: string;
+}
 export interface TargetProfile {
     id: string;
     campaign_id: string;

package/package.json

@@ -1,7 +1,12 @@
 {
 	"name": "@jclvsh/iris",
-	"version": "0.19.0",
+	"version": "0.20.0",
 	"description": "MCP server for the Iris API",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/JCLVSH/monorepo.git",
+		"directory": "apps/iris/packages/mcp"
+	},
 	"type": "module",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",