@audienti/cli 0.1.30 → 0.1.32

package/.mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "audienti": {
+      "title": "Audienti",
+      "description": "Bridge MCP clients to Audienti's app-hosted /mcp endpoint for accounts, plays, prospects, lists, analytics, and operator workflows.",
+      "cwd": ".",
+      "command": "node",
+      "args": [
+        "./bin/audienti-mcp.js"
+      ]
+    }
+  }
+}

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to the Audienti CLI are documented here.
 
 ## [Unreleased]
 
+## [0.1.32] - 2026-08-11
+
+### Added
+
+- Add `audienti auth login` for browser-based local authentication through a loopback callback.
+- Add the `audienti-mcp` stdio bridge and Codex MCP manifest for Audienti's app-hosted MCP endpoint, including stage analytics and cohort list creation.
+
+## [0.1.31] - 2026-08-10
+
+### Added
+
+- Add `audienti setup play preflight` for checking LinkedIn connected-account readiness and returning direct setup, mapping, or edit URLs before an agent activates a play.
+- Add `audienti analytics stages` for weekly or monthly stage conversion cohorts and current stage aging/overdue metrics.
+
 ## [0.1.30] - 2026-08-04
 
 ### Changed

package/README.md

@@ -1,9 +1,10 @@
 # Audienti CLI
 
 Audienti CLI is the agent-first command-line client for the Audienti production
-API. It lets local coding agents and operators inspect accounts, create and
-manage plays, import prospects, build lists, manage task reminders, and work
-supported operator flows.
+API and the local bridge for Audienti's app-hosted MCP endpoint. It lets local
+coding agents and operators inspect accounts,
+create and manage plays, import prospects, build lists, manage task reminders,
+and work supported operator flows.
 
 ## Install
 
@@ -25,16 +26,26 @@ For one-off use, run `npx @audienti/cli --help`.
 
 ## Authenticate
 
-Create an Audienti API token through the product, then configure this machine:
+Authenticate through the browser, then configure the default account context:
 
 ```bash
-audienti auth token <token>
+audienti auth login
 audienti accounts list --json
 audienti accounts select <acct_id>
 audienti users list
 audienti users select <account_user_id|email|name|me>
 ```
 
+`audienti auth login` opens Audienti in your browser, creates an API token from
+your signed-in web session, sends it back to a temporary `127.0.0.1` callback,
+and stores it in the local CLI config after validating it.
+
+If you already have a token, you can still configure it directly:
+
+```bash
+audienti auth token <token>
+```
+
 The CLI writes its local configuration to `~/.config/audienti/config.json` with
 owner-only permissions. Do not place a production token in an agent prompt,
 repository file, issue, or CI secret.
@@ -55,6 +66,71 @@ Use `--json` whenever another program or agent will consume the result. Inspect
 the target state before mutations, and use the command-specific help before
 creating, changing, or deleting data.
 
+## MCP
+
+Audienti serves MCP from the app at `/mcp`. The package ships a small stdio
+bridge for MCP hosts that need a local command:
+
+```bash
+audienti-mcp
+```
+
+Use it this way:
+
+1. Install the package.
+2. Run `audienti auth login`.
+3. Run `audienti accounts select <acct_id>`.
+4. Configure your MCP host with the packaged `.mcp.json`, or point it at the
+   `audienti-mcp` command.
+5. In the MCP host, list tools and call the account-scoped tool you need.
+
+The bridge reads the same `~/.config/audienti/config.json` as the CLI, forwards
+MCP JSON-RPC messages to the app, and injects the selected account when a tool
+call does not include `account_id`. If you want a tool to run against a
+different account, pass `account_id` in that tool call.
+
+MCP clients that can call HTTP directly may use the hosted endpoint instead of
+the stdio bridge:
+
+```bash
+curl https://app.audienti.com/mcp \
+  -H "Authorization: Bearer $AUDIENTI_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
+```
+
+Example tool call:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/call",
+  "params": {
+    "name": "analytics.stages",
+    "arguments": {
+      "account_id": "acct_...",
+      "query": {
+        "interval": "weekly",
+        "cohort_start_date": "2026-07-01",
+        "cohort_end_date": "2026-07-31"
+      }
+    }
+  }
+}
+```
+
+Useful MCP tools to start with:
+
+- `auth.me` confirms the token identity.
+- `accounts.list` shows accessible accounts.
+- `setup.play_preflight` returns LinkedIn connected-account readiness and setup
+  or mapping URLs.
+- `offers.create`, `icps.create`, and `motions.create` set up the offer, ICP,
+  and play.
+- `analytics.stages` returns stage conversion cohorts and stage aging.
+- `analytics.cohort_lists.create` materializes event cohorts as reusable lists.
+
 Common inspection commands:
 
 ```bash

package/bin/audienti-mcp.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runMcpServer } from "../src/mcp.js";
+
+await runMcpServer();

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@audienti/cli",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "description": "Agent-first command-line client for Audienti.",
   "type": "module",
   "bin": {
-    "audienti": "./bin/audienti.js"
+    "audienti": "./bin/audienti.js",
+    "audienti-mcp": "./bin/audienti-mcp.js"
   },
   "files": [
     "bin/",
     "src/",
     "skills/",
+    ".mcp.json",
     "install",
     "README.md",
     "LICENSE",

package/skills/audienti/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: audienti
-description: Use when the user wants to operate Audienti through the production CLI, including account selection, plays, prospect imports, lists, message previews, or supported operator outcomes.
+description: Use when the user wants to operate Audienti through the production CLI or app-hosted MCP endpoint, including account selection, plays, prospect imports, lists, message previews, analytics, or supported operator outcomes.
 ---
 
-# Audienti CLI
+# Audienti CLI and MCP
 
-Use the installed `audienti` command as the production contract. Do not build a
-parallel wrapper or call undocumented API endpoints.
+Use the installed `audienti` command or Audienti's app-hosted MCP endpoint as
+the production contract. The packaged `audienti-mcp` command is only a local
+stdio bridge for MCP hosts. Do not build a parallel wrapper or call
+undocumented API endpoints.
 
 ## Setup
 
@@ -23,9 +25,15 @@ curl -fsSL https://cli.audienti.com/install | bash
 ```
 
 3. Authentication is explicit and per machine. Do not ask a user to paste a
-production token into chat, a repository file, an issue, or a CI secret. Use
-the existing `audienti auth token` flow only after the user supplies a token
-through an approved secure channel.
+production token into chat, a repository file, an issue, or a CI secret. Prefer
+browser login:
+
+```bash
+audienti auth login
+```
+
+Use `audienti auth token` only after the user supplies a token through an
+approved secure channel.
 
 4. Start with discovery, not mutation:
 
@@ -35,6 +43,39 @@ audienti accounts list --json
 audienti help agent-workflows
 ```
 
+For MCP hosts, configure the packaged `.mcp.json` or run:
+
+```bash
+audienti-mcp
+```
+
+The bridge reads the same local config as the CLI and forwards MCP JSON-RPC to
+the app-hosted `/mcp` endpoint. Before starting the bridge, select account
+context:
+
+```bash
+audienti auth login
+audienti accounts list --json
+audienti accounts select <acct_id>
+audienti users select me
+```
+
+If the MCP host can call HTTP directly, use `POST /mcp` with the same bearer
+token as the API. Call `tools/list` first, then call named tools with
+`tools/call`. Account-scoped tools accept `account_id`; the local bridge injects
+the selected CLI account when it is omitted.
+
+Useful MCP tools:
+
+- `auth.me` confirms the token identity.
+- `accounts.list` shows accessible accounts.
+- `setup.play_preflight` returns connected-account readiness and setup or
+  mapping URLs.
+- `offers.create`, `icps.create`, and `motions.create` set up the offer, ICP,
+  and play.
+- `analytics.stages` returns stage conversion cohorts and stage aging.
+- `analytics.cohort_lists.create` materializes event cohorts as reusable lists.
+
 ## Operating Rules
 
 - Use `--json` whenever another agent or tool will consume the response.

package/src/api-client.js

@@ -40,10 +40,21 @@ export class AudientiClient {
     return this.requestJson("/api/v1/accounts.json");
   }
 
+  mcp(message) {
+    return this.requestJson("/mcp", {
+      method: "POST",
+      body: message
+    });
+  }
+
   users(accountId) {
     return this.requestJson(accountPath(accountId, ["users"]));
   }
 
+  socialCookies(accountId, query = {}) {
+    return this.requestJson(accountPath(accountId, ["social_cookies"], query));
+  }
+
   userActivity(accountId, userId, query = {}) {
     return this.requestJson(accountPath(accountId, ["operations", "users", userId, "activity"], query));
   }
@@ -572,6 +583,10 @@ export class AudientiClient {
     return this.requestJson(accountPath(accountId, ["analytics", "dashboard"], query));
   }
 
+  analyticsStages(accountId, query = {}) {
+    return this.requestJson(accountPath(accountId, ["analytics", "stages"], query));
+  }
+
   createAnalyticsCohortList(accountId, body = {}) {
     return this.requestJson(accountPath(accountId, ["analytics", "cohort_lists"]), {
       method: "POST",

package/src/cli.js

@@ -1,4 +1,7 @@
 import { parseArgs } from "node:util";
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { ApiError, AudientiClient, DEFAULT_HOST, normalizeHost } from "./api-client.js";
@@ -17,6 +20,7 @@ const DEFAULT_LIST_LIMIT = 20;
 const API_MAX_LIST_LIMIT = 100;
 const DEFAULT_LOOKUP_TIMEOUT_SECONDS = 60;
 const DEFAULT_LOOKUP_POLL_INTERVAL_SECONDS = 2;
+const DEFAULT_AUTH_LOGIN_TIMEOUT_SECONDS = 180;
 const DEFAULT_WRITER_TEST_RUN_TIMEOUT_SECONDS = 180;
 const DEFAULT_WRITER_TEST_RUN_POLL_INTERVAL_SECONDS = 2;
 const PACKAGE_NAME = "@audienti/cli";
@@ -61,6 +65,7 @@ const TASKS_LIST_USAGE = "Usage: audienti tasks list [--status <open|completed>]
 const TASKS_ADD_USAGE = "Usage: audienti tasks add --title <text> --due <time> [--prospect <prsp_id>] [--list <list_id>] [--assigned-user <id|me>] [--notes <text>] [--json] [--account <acct_id>]";
 const TASKS_COMPLETE_USAGE = "Usage: audienti tasks complete <ptsk_id> [--json] [--account <acct_id>]";
 const USERS_ACTIVITY_USAGE = "Usage: audienti users activity [account_user_id|me] [--mode <actor|account_usage|related>] [--window <24h|7d|30d>] [--platform <linkedin|email|gmail>] [--query <text>] [--limit <n>] [--page <n>] [--json] [--account <acct_id>]";
+const SETUP_PLAY_PREFLIGHT_USAGE = "Usage: audienti setup play preflight [--principal <account_user_id|email|name|me>] [--platform linkedin] [--json] [--account <acct_id>]";
 const OFFERS_SHOW_USAGE = "Usage: audienti offers show <offr_id> [--json] [--account <acct_id>]";
 const OFFERS_UPDATE_USAGE = "Usage: audienti offers update <offr_id> [--name <text>] [--description <text>] [--url <url>] [--json] [--account <acct_id>]";
 const OFFERS_DELETE_USAGE = "Usage: audienti offers delete <offr_id> --confirm <yes|true|Y|y> [--json] [--account <acct_id>]";
@@ -94,6 +99,7 @@ const ANALYTICS_PROSPECTS_USAGE = "Usage: audienti analytics prospects [--window
 const ANALYTICS_PROSPECTS_COHORT_ANALYSIS_USAGE = "Usage: audienti analytics prospects cohort-analysis [--weeks <n>] [--window 24h] [--motion <motn_id>] [--list <list_id>] [--provenance <source>] [--user <account_user_id|email|name|me>] [--json] [--account <acct_id>]";
 const ANALYTICS_USERS_USAGE = "Usage: audienti analytics users [--user <account_user_id|email|name|me>] [--window 30d | --start YYYY-MM-DD --end YYYY-MM-DD] [--cohort-start YYYY-MM-DD --cohort-end YYYY-MM-DD] [--motion <motn_id>] [--list <list_id>] [--provenance <source>] [--platform <linkedin|email|gmail>] [--json] [--account <acct_id>]";
 const ANALYTICS_DASHBOARD_USAGE = "Usage: audienti analytics dashboard [--cohort-start YYYY-MM-DD --cohort-end YYYY-MM-DD] [--play-tag <tag>] [--motion <motn_id>] [--list <list_id>] [--offer <offr_id>] [--icp <icp_id>] [--user <account_user_id|email|name|me>] [--json] [--account <acct_id>]";
+const ANALYTICS_STAGES_USAGE = "Usage: audienti analytics stages [--interval weekly|monthly] [--cohort-start YYYY-MM-DD --cohort-end YYYY-MM-DD] [--play-tag <tag>] [--motion <motn_id>] [--list <list_id>] [--offer <offr_id>] [--icp <icp_id>] [--user <account_user_id|email|name|me>] [--json] [--account <acct_id>]";
 const ANALYTICS_COHORT_LIST_USAGE = "Usage: audienti analytics cohorts create-list --name <text> --start YYYY-MM-DD --end YYYY-MM-DD [--event connection_request_sent] [--user <account_user_id|email|name|me>] [--note-mode <any|with_note|blank>] [--motion <motn_id>] [--offer <offr_id>] [--icp <icp_id>] [--play-tag <tag>] [--json] [--account <acct_id>]";
 const TOOLS_LIST_USAGE = "Usage: audienti tools list [--json]";
 const TOOLS_LINKEDIN_REVIEW_USAGE = "Usage: audienti tools linkedin-review --url <linkedin_url> [--icp <icp_id>] [--json] [--account <acct_id>]";
@@ -180,6 +186,7 @@ async function dispatch(argv, context) {
   const normalizedResource = normalizeResource(resource);
 
   if (normalizedResource === "auth" && action === "token") return authToken(rest, context);
+  if (normalizedResource === "auth" && action === "login") return authLogin(rest, context);
   if (normalizedResource === "auth" && action === "status") return authStatus(rest, context, { accountOverride });
   if (normalizedResource === "auth" && action === "logout") return authLogout(rest, context);
   if (normalizedResource === "config" && action === "list") return configList(rest, context);
@@ -189,6 +196,7 @@ async function dispatch(argv, context) {
   if (normalizedResource === "users" && action === "list") return usersList(rest, context, { accountOverride });
   if (normalizedResource === "users" && action === "select") return usersSelect(rest, context, { accountOverride });
   if (normalizedResource === "users" && action === "activity") return usersActivity(rest, context, { accountOverride });
+  if (normalizedResource === "setup" && action === "play" && rest[0] === "preflight") return setupPlayPreflight(rest.slice(1), context, { accountOverride });
   if (normalizedResource === "offers" && action === "list") return offersList(rest, context, { accountOverride });
   if (normalizedResource === "offers" && action === "show") return offersShow(rest, context, { accountOverride });
   if (normalizedResource === "offers" && action === "create") return offersCreate(rest, context, { accountOverride });
@@ -288,6 +296,7 @@ async function dispatch(argv, context) {
   if (normalizedResource === "analytics" && ["visibility", "visops"].includes(action)) return analyticsVisibility(rest, context, { accountOverride });
   if (normalizedResource === "analytics" && action === "content") return analyticsContent(rest, context, { accountOverride });
   if (normalizedResource === "analytics" && ["dashboard", "campaign", "campaigns"].includes(action)) return analyticsDashboard(rest, context, { accountOverride });
+  if (normalizedResource === "analytics" && action === "stages") return analyticsStages(rest, context, { accountOverride });
   if (normalizedResource === "analytics" && ["cohorts", "cohort"].includes(action)) return analyticsCohorts(rest, context, { accountOverride });
 
   throw new CommandError(usage(), { exitCode: resource ? 1 : 0 });
@@ -402,12 +411,148 @@ async function authToken(args, context) {
   writeLine(context.stdout, "Run `audienti accounts list` to choose an account.");
 }
 
+async function authLogin(args, context) {
+  const { values, positionals } = parseCommandArgs(args, {
+    ...jsonOptions(),
+    host: { type: "string" },
+    "timeout-seconds": { type: "string" },
+    "no-open": { type: "boolean" }
+  });
+
+  if (positionals.length > 0) {
+    throw new CommandError("Usage: audienti auth login [--host https://app.audienti.com] [--timeout-seconds <n>] [--no-open] [--json]");
+  }
+
+  const host = normalizeHost(values.host || DEFAULT_HOST);
+  const timeoutSeconds = normalizeOptionalPositiveInteger(values["timeout-seconds"], "--timeout-seconds") || DEFAULT_AUTH_LOGIN_TIMEOUT_SECONDS;
+  const state = randomBytes(24).toString("hex");
+  const callback = await createAuthCallbackServer({ state, context });
+  const authUrl = new URL("/cli/auth", host);
+  authUrl.searchParams.set("redirect_uri", callback.redirectUri);
+  authUrl.searchParams.set("state", state);
+
+  if (values.json) {
+    writeJson(context.stdout, {
+      kind: "auth_login_start",
+      auth_url: authUrl.toString(),
+      callback_url: callback.redirectUri,
+      timeout_seconds: timeoutSeconds
+    });
+  } else {
+    writeLine(context.stdout, "Open this URL to authenticate Audienti CLI:");
+    writeLine(context.stdout, authUrl.toString());
+  }
+
+  if (!values["no-open"]) openBrowser(authUrl.toString(), context);
+
+  let payload;
+  try {
+    payload = await callback.wait(timeoutSeconds);
+  } finally {
+    await callback.close();
+  }
+
+  const client = new AudientiClient({ host: payload.host || host, token: payload.token, fetchImpl: context.fetchImpl });
+  const user = await client.me();
+  await writeConfig({
+    host: client.host,
+    token: payload.token,
+    accountId: payload.account_id || undefined,
+    accountName: payload.account_name || undefined
+  }, { env: context.env });
+
+  const result = {
+    kind: "auth_login_complete",
+    host: client.host,
+    user: user?.name || payload.user_name || payload.user_email || user?.email || null,
+    account_id: payload.account_id || null,
+    account_name: payload.account_name || null
+  };
+
+  if (values.json) return writeJson(context.stdout, result);
+
+  writeLine(context.stdout, `Authenticated to ${client.host} as ${result.user || "current user"}.`);
+  if (result.account_id) writeLine(context.stdout, `Selected account ${result.account_name || result.account_id} (${result.account_id}).`);
+  if (!result.account_id) writeLine(context.stdout, "Run `audienti accounts list` to choose an account.");
+}
+
+async function createAuthCallbackServer({ state, context }) {
+  let resolvePayload;
+  let rejectPayload;
+  const waitPromise = new Promise((resolve, reject) => {
+    resolvePayload = resolve;
+    rejectPayload = reject;
+  });
+
+  const server = createServer((request, response) => {
+    const url = new URL(request.url, "http://127.0.0.1");
+    if (url.pathname !== "/callback") {
+      response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+      response.end("Not found.");
+      return;
+    }
+
+    const payload = Object.fromEntries(url.searchParams.entries());
+    if (payload.state !== state) {
+      response.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+      response.end("Audienti CLI authentication failed: state mismatch.");
+      rejectPayload(new CommandError("Browser authentication state mismatch."));
+      return;
+    }
+
+    if (!payload.token) {
+      response.writeHead(400, { "Content-Type": "text/plain; charset=utf-8" });
+      response.end("Audienti CLI authentication failed: missing token.");
+      rejectPayload(new CommandError("Browser authentication callback did not include a token."));
+      return;
+    }
+
+    response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+    response.end("<!doctype html><title>Audienti CLI authenticated</title><p>Audienti CLI is authenticated. You can close this window.</p>");
+    resolvePayload(payload);
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+
+  const { port } = server.address();
+
+  return {
+    redirectUri: `http://127.0.0.1:${port}/callback`,
+    wait(timeoutSeconds) {
+      let timeoutId;
+      const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => reject(new CommandError(`Timed out waiting for browser authentication after ${timeoutSeconds} seconds.`)), timeoutSeconds * 1000);
+      });
+
+      return Promise.race([waitPromise, timeoutPromise]).finally(() => clearTimeout(timeoutId));
+    },
+    close() {
+      return new Promise((resolve) => server.close(() => resolve()));
+    }
+  };
+}
+
+function openBrowser(url, context) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+
+  try {
+    const child = spawn(command, args, { detached: true, stdio: "ignore" });
+    child.unref();
+  } catch (error) {
+    writeLine(context.stderr, `Could not open browser automatically: ${error.message}`);
+  }
+}
+
 async function authStatus(args, context, { accountOverride } = {}) {
   assertNoPositionals(args, "Usage: audienti auth status [--account <acct_id>]");
 
   const config = await readConfig({ env: context.env });
   if (!config.token) {
-    writeLine(context.stdout, "Not authenticated. Run `audienti auth token <token>`.");
+    writeLine(context.stdout, "Not authenticated. Run `audienti auth login`.");
     return 1;
   }
 
@@ -722,6 +867,24 @@ async function usersActivity(args, context, { accountOverride } = {}) {
   renderUserActivity(payload, context);
 }
 
+async function setupPlayPreflight(args, context, { accountOverride } = {}) {
+  const { values, positionals } = parseCommandArgs(args, {
+    ...jsonOptions(),
+    principal: { type: "string" },
+    platform: { type: "string" }
+  });
+  if (positionals.length > 0) throw new CommandError(SETUP_PLAY_PREFLIGHT_USAGE);
+
+  const { client, accountId, config } = await requireAccountContext(context, { accountOverride });
+  const payload = await client.socialCookies(accountId, compactObject({
+    account_user_id: resolveAccountUserId(values.principal || "me", config, { accountOverride }),
+    platform: values.platform || "linkedin"
+  }));
+  if (values.json) return writeJson(context.stdout, payload);
+
+  renderSetupPlayPreflight(payload, context);
+}
+
 async function offersList(args, context, { accountOverride } = {}) {
   const { values, positionals } = parseCommandArgs(args, jsonOptions());
   if (positionals.length > 0) throw new CommandError("Usage: audienti offers list [--json] [--account <acct_id>]");
@@ -2751,6 +2914,18 @@ async function analyticsDashboard(args, context, { accountOverride } = {}) {
   renderAnalyticsDashboard(payload, context);
 }
 
+async function analyticsStages(args, context, { accountOverride } = {}) {
+  const { values, positionals } = parseCommandArgs(args, analyticsStagesOptions());
+  if (positionals.length > 0) throw new CommandError(ANALYTICS_STAGES_USAGE);
+  validateDatePair(values["cohort-start"], values["cohort-end"], "--cohort-start", "--cohort-end");
+
+  const { client, accountId, config } = await requireAccountContext(context, { accountOverride });
+  const payload = await client.analyticsStages(accountId, analyticsStagesQuery(values, config, { accountOverride }));
+  if (values.json) return writeJson(context.stdout, payload);
+
+  renderAnalyticsStages(payload, context);
+}
+
 async function analyticsCohorts(args, context, { accountOverride } = {}) {
   const action = args[0];
   if (action !== "create-list") throw new CommandError(ANALYTICS_COHORT_LIST_USAGE);
@@ -2799,7 +2974,7 @@ function assertNoPositionals(args, usageText) {
 async function requireAuthenticatedConfig(context) {
   const config = await readConfig({ env: context.env });
   if (!config.token) {
-    throw new CommandError("Not authenticated. Run `audienti auth token <token>`.");
+    throw new CommandError("Not authenticated. Run `audienti auth login` or `audienti auth token <token>`.");
   }
 
   return config;
@@ -3024,6 +3199,13 @@ function analyticsDashboardOptions() {
   };
 }
 
+function analyticsStagesOptions() {
+  return {
+    ...analyticsDashboardOptions(),
+    interval: { type: "string" }
+  };
+}
+
 function analyticsCohortListOptions() {
   return {
     ...jsonOptions(),
@@ -3082,6 +3264,13 @@ function analyticsDashboardQuery(values, config = {}, { accountOverride } = {})
   });
 }
 
+function analyticsStagesQuery(values, config = {}, { accountOverride } = {}) {
+  return compactObject({
+    ...analyticsDashboardQuery(values, config, { accountOverride }),
+    interval: values.interval
+  });
+}
+
 function validateDatePair(start, end, startFlag, endFlag) {
   if ((start && !end) || (!start && end)) {
     throw new CommandError(`${startFlag} and ${endFlag} must be provided together.`);
@@ -3875,6 +4064,51 @@ function renderUserActivity(payload, context) {
   }
 }
 
+function renderSetupPlayPreflight(payload, context) {
+  const accountUser = payload?.account_user || {};
+  const socialCookie = payload?.social_cookie || null;
+  const urls = socialCookie?.urls || {};
+
+  writeLine(
+    context.stdout,
+    `Setup preflight: ${display(payload?.platform, "linkedin")} for ${display(accountUser.name || accountUser.email)} (${display(accountUser.id)})`
+  );
+  writeLine(context.stdout, `Status: ${payload?.ready ? "ready" : "blocked"} (${display(payload?.reason, "unknown")})`);
+
+  if (socialCookie) {
+    writeLine(
+      context.stdout,
+      `Connected account: ${display(socialCookie.username || socialCookie.name)} (${display(socialCookie.prefix_id)})`
+    );
+    writeLine(context.stdout, `Connection status: ${display(socialCookie.status)}`);
+    writeLine(context.stdout, `Mapped to account: ${socialCookie.accessible_to_account ? "yes" : "no"}`);
+    writeLine(context.stdout, `Actionable: ${socialCookie.actionable ? "yes" : "no"}`);
+    renderSetupAutomationSummary(socialCookie.automation || {}, context);
+  } else {
+    writeLine(context.stdout, "Connected account: none");
+  }
+
+  if (!socialCookie && payload?.setup_url) {
+    writeLine(context.stdout, `Setup URL: ${payload.setup_url}`);
+  } else if (payload?.reason === "needs_account_access" && urls.mapping_url) {
+    writeLine(context.stdout, `Mapping URL: ${urls.mapping_url}`);
+  } else if (payload?.reason === "needs_reconnect" && urls.edit_url) {
+    writeLine(context.stdout, `Edit URL: ${urls.edit_url}`);
+  } else if (urls.edit_url) {
+    writeLine(context.stdout, `Edit URL: ${urls.edit_url}`);
+  }
+}
+
+function renderSetupAutomationSummary(automation, context) {
+  const summary = [
+    `autopilot ${automation.autopilot_enabled ? "on" : "off"}`,
+    `automatic sending ${automation.automatic_sending_enabled ? "on" : "off"}`,
+    `connection requests ${automation.connection_request_autopilot_enabled ? "on" : "off"}`
+  ];
+
+  writeLine(context.stdout, `Automation: ${summary.join(", ")}`);
+}
+
 function renderCountRows(context, label, rows) {
   if (!Array.isArray(rows) || rows.length === 0) return;
 
@@ -5107,6 +5341,82 @@ function renderAnalyticsDashboard(payload, context) {
   writeCountTable(context, "Current pipeline stages", payload?.pipeline_stage_counts, ["STAGE", "COUNT"], countRow);
 }
 
+function renderAnalyticsStages(payload, context) {
+  const conversionGrid = payload?.conversion_grid || {};
+  writeLine(context.stdout, `Stage analytics (${display(payload?.cohort?.label, "selected cohort")})`);
+  if (payload?.cohort) {
+    writeLine(context.stdout, `Cohort: ${payload.cohort.start_date} to ${payload.cohort.end_date} (${display(payload.cohort.field, "account_prospects.created_at")})`);
+  }
+  writeDashboardFilters(payload, context);
+  writeLine(context.stdout, `Conversion interval: ${display(conversionGrid.interval, "weekly")}`);
+  writeLine(context.stdout, `Connection maturity window: ${display(conversionGrid.maturity_days, 21)} days`);
+  writeStageConversionTable(conversionGrid, context);
+  writeStageAgingTable(payload?.stage_aging, context);
+}
+
+function writeStageConversionTable(conversionGrid, context) {
+  const rows = Array.isArray(conversionGrid?.rows) ? conversionGrid.rows : [];
+  const definitions = Array.isArray(conversionGrid?.stage_definitions) ? conversionGrid.stage_definitions : [];
+  const columns = definitions.filter((definition) => definition?.key);
+
+  writeLine(context.stdout, "");
+  writeLine(context.stdout, display(conversionGrid?.window_description, "Conversion cohorts"));
+  if (rows.length === 0 || columns.length === 0) return writeLine(context.stdout, "None");
+
+  const headers = ["COHORT", ...columns.map((column) => display(column.label || column.key))];
+  const tableRows = rows.map((row) => [
+    display(row?.label),
+    ...columns.map((column) => stageMetricValueLabel(row?.values?.[column.key]))
+  ]);
+
+  writeAlignedTable(context, headers, tableRows);
+}
+
+function writeStageAgingTable(stageAging, context) {
+  const rows = Array.isArray(stageAging?.rows) ? stageAging.rows : [];
+  writeLine(context.stdout, "");
+  writeLine(context.stdout, "Stage Aging");
+  if (rows.length === 0) return writeLine(context.stdout, "None");
+
+  const totals = stageAging?.totals || {};
+  writeLine(
+    context.stdout,
+    `Totals: ${display(totals.current_count, 0)} current, ${display(totals.due_soon_count, 0)} due soon, ${display(totals.overdue_count, 0)} overdue (${percentageLabel(totals.overdue_rate)})`
+  );
+  writeAlignedTable(
+    context,
+    ["STAGE", "CURRENT", "DUE SOON", "OVERDUE", "OVERDUE %", "MED AGE", "OLDEST IDLE"],
+    rows.map(stageAgingRow),
+    { numericColumns: [false, true, true, true, true, true, true] }
+  );
+}
+
+function stageAgingRow(row) {
+  return [
+    display(row?.label || row?.key),
+    display(row?.current_count, 0),
+    display(row?.due_soon_count, 0),
+    display(row?.overdue_count, 0),
+    percentageLabel(row?.overdue_rate),
+    dayCountLabel(row?.median_stage_age_days),
+    dayCountLabel(row?.oldest_idle_days)
+  ];
+}
+
+function stageMetricValueLabel(value) {
+  if (!value) return "-";
+  if (value.kind === "count") return display(value.count, 0);
+
+  const numerator = display(value.numerator, 0);
+  const denominator = display(value.denominator, 0);
+  const suffix = value.maturing ? " maturing" : "";
+  return `${numerator}/${denominator} ${percentageLabel(value.rate)}${suffix}`;
+}
+
+function dayCountLabel(value) {
+  return value === undefined || value === null || value === "" ? "-" : `${value}d`;
+}
+
 function renderAnalyticsCohortList(payload, context) {
   const list = payload?.list || {};
   writeLine(context.stdout, `Created analytics cohort list ${display(list.name)} (${display(list.prefix_id)}).`);
@@ -5813,6 +6123,7 @@ const HELP_TOPICS = new Map([
     "  audienti <command> [options]",
     "",
     "Start:",
+    "  audienti auth login                 Sign in through the browser",
     "  audienti auth token <token>         Save an API token",
     "  audienti accounts list             See accounts available to this token",
     "  audienti accounts select <acct_id>  Use one account by default",
@@ -5824,6 +6135,7 @@ const HELP_TOPICS = new Map([
     "    audienti auth status",
     "    audienti config list",
     "    audienti update check",
+    "    audienti setup play preflight",
     "    audienti users list",
     "    audienti users select <account_user_id|email|name|me>",
     "    audienti users activity [account_user_id|me]",
@@ -5914,6 +6226,7 @@ const HELP_TOPICS = new Map([
     "  Analytics",
     "    audienti analytics prospects --window 24h",
     "    audienti analytics dashboard --play-tag <tag>",
+    "    audienti analytics stages --interval weekly",
     "    audienti analytics cohorts create-list --name \"Blank note test\" --start 2026-07-20 --end 2026-07-20 --note-mode blank",
     "    audienti analytics prospects cohort-analysis --weeks 4 --motion <motn_id>",
     "    audienti analytics users --user me --window 30d",
@@ -5934,6 +6247,7 @@ const HELP_TOPICS = new Map([
     "  Preview a campaign:  audienti writer test-run <prsp_id>",
     "  Analyze one motion:  audienti motions analytics <motn_id>",
     "  Count one campaign:   audienti analytics dashboard --play-tag <tag>",
+    "  Compare stage rates:  audienti analytics stages --interval weekly",
     "  Audit your work:     audienti analytics users --user me --window 30d",
     "  Review reminders:    audienti tasks list",
     "",
@@ -5949,6 +6263,7 @@ const HELP_TOPICS = new Map([
 
   ["auth", [
     "Usage:",
+    "  audienti auth login [--host <url>] [--timeout-seconds <n>] [--no-open] [--json]",
     "  audienti auth token <token> [--host <url>]",
     "  audienti auth status",
     "  audienti auth logout",
@@ -5956,11 +6271,32 @@ const HELP_TOPICS = new Map([
     "Status: implemented",
     "",
     "Commands:",
+    "  audienti auth login          Open Audienti in a browser and save the returned token",
     "  audienti auth token <token>  Validate and save a bearer API token",
     "  audienti auth status         Check live auth and show selected account",
     "  audienti auth logout         Delete local CLI auth config",
     "",
-    "Run `audienti auth token help` for token input shape."
+    "Run `audienti auth login help` for browser authentication."
+  ].join("\n")],
+
+  ["auth login", [
+    "Usage:",
+    "  audienti auth login [--host <url>] [--timeout-seconds <n>] [--no-open] [--json]",
+    "",
+    "Status: implemented",
+    "",
+    "Options:",
+    "  --host <url>           Audienti host. Default: https://app.audienti.com",
+    "  --timeout-seconds <n>  Wait budget before the command fails. Default: 180",
+    "  --no-open              Print the URL without opening a browser",
+    "  --json                 Print machine-readable start and completion payloads",
+    "",
+    "Flow:",
+    "  Starts a temporary 127.0.0.1 callback server, opens /cli/auth in the browser,",
+    "  and saves the returned API token to ~/.config/audienti/config.json after validation.",
+    "",
+    "Example:",
+    "  audienti auth login --host https://app.audienti.com"
   ].join("\n")],
 
   ["auth token", [
@@ -6114,6 +6450,53 @@ const HELP_TOPICS = new Map([
     "  Saves accountId and accountName in local CLI config."
   ].join("\n")],
 
+  ["setup", [
+    "Usage:",
+    "  audienti setup play preflight [--principal <account_user_id|email|name|me>] [--platform linkedin] [--json]",
+    "",
+    "Status: implemented",
+    "",
+    "Purpose:",
+    "  Preflight account setup before an agent creates or activates an Audienti play.",
+    "",
+    "Commands:",
+    "  audienti setup play preflight  Check connected-account readiness and direct setup URLs"
+  ].join("\n")],
+
+  ["setup play", [
+    "Usage:",
+    "  audienti setup play preflight [--principal <account_user_id|email|name|me>] [--platform linkedin] [--json]",
+    "",
+    "Status: implemented",
+    "",
+    "Purpose:",
+    "  Check the sender identity prerequisites for a new motion or play."
+  ].join("\n")],
+
+  ["setup play preflight", [
+    "Usage:",
+    `  ${SETUP_PLAY_PREFLIGHT_USAGE.slice("Usage: ".length)}`,
+    "",
+    "Status: implemented",
+    "",
+    "Purpose:",
+    "  Verify that the selected principal has a connected account mapped to the current Audienti account before a play starts capture or outreach.",
+    "",
+    "Output shape:",
+    "  ready: true when the selected principal has a mapped, actionable platform account",
+    "  reason: ready | needs_setup | needs_account_access | needs_reconnect",
+    "  setup_url: direct operations URL for creating a connected account",
+    "  social_cookie.urls.mapping_url: owner URL for granting account access",
+    "  social_cookie.urls.edit_url: operations URL for reconnect/settings review when mapped",
+    "",
+    "Examples:",
+    "  audienti setup play preflight --principal me --platform linkedin",
+    "  audienti setup play preflight --principal 42 --json",
+    "",
+    "API:",
+    "  GET /api/v1/accounts/:account_id/social_cookies.json"
+  ].join("\n")],
+
   ["users", [
     "Usage:",
     "  audienti users list [--json]",
@@ -8442,6 +8825,7 @@ const HELP_TOPICS = new Map([
     "Usage:",
     "  audienti analytics prospects [--window 24h] [--cohort-start YYYY-MM-DD --cohort-end YYYY-MM-DD] [--motion <motn_id>] [--list <list_id>] [--user <account_user_id|email|name|me>] [--json]",
     "  audienti analytics dashboard [--cohort-start YYYY-MM-DD --cohort-end YYYY-MM-DD] [--play-tag <tag>] [--motion <motn_id>] [--list <list_id>] [--json]",
+    "  audienti analytics stages [--interval weekly|monthly] [--cohort-start YYYY-MM-DD --cohort-end YYYY-MM-DD] [--play-tag <tag>] [--motion <motn_id>] [--list <list_id>] [--json]",
     "  audienti analytics cohorts create-list --name <text> --start YYYY-MM-DD --end YYYY-MM-DD [--note-mode <any|with_note|blank>] [--user <account_user_id|email|name|me>] [--json]",
     "  audienti analytics prospects cohort-analysis [--weeks <n>] [--window 24h] [--motion <motn_id>] [--list <list_id>] [--user <account_user_id|email|name|me>] [--json]",
     "  audienti analytics users [--user <account_user_id|email|name|me>] [--window 30d | --start YYYY-MM-DD --end YYYY-MM-DD] [--cohort-start YYYY-MM-DD --cohort-end YYYY-MM-DD] [--motion <motn_id>] [--list <list_id>] [--platform <linkedin|email|gmail>] [--json]",
@@ -8458,6 +8842,7 @@ const HELP_TOPICS = new Map([
     "  --motion <motn_id>  For prospect and user analytics, filter AccountProspect.motion_id to one motion/play.",
     "  --list <list_id>  Filter analytics to prospects in one list, including analytics cohort lists.",
     "  --play-tag <tag>  For dashboard analytics, filter to motions/lists tagged with a campaign tag.",
+    "  --interval <weekly|monthly>  For stages analytics, select the conversion cohort grain.",
     "  --provenance <source>  Optional lower-level AccountProspect.intake_source filter.",
     "  --platform <linkedin|email|gmail>  For user analytics, filter events.platform. --channel is accepted as an alias.",
     "  cohort-analysis loops over recent weekly AccountProspect.created_at cohorts and compares their current stages.",
@@ -8497,6 +8882,35 @@ const HELP_TOPICS = new Map([
     "  GET /api/v1/accounts/:account_id/analytics/dashboard.json"
   ].join("\n")],
 
+  ["analytics stages", [
+    "Usage:",
+    `  ${ANALYTICS_STAGES_USAGE.slice("Usage: ".length)}`,
+    "",
+    "Status: implemented",
+    "",
+    "Purpose:",
+    "  Return the stages dashboard read model through the CLI, including weekly or monthly conversion cohorts and current stage aging.",
+    "",
+    "Options:",
+    "  --interval <weekly|monthly>  Conversion cohort grain. Defaults to weekly.",
+    "  --cohort-start <YYYY-MM-DD> --cohort-end <YYYY-MM-DD>  Select the AccountProspect.created_at cohort.",
+    "  --play-tag <tag>  Filter to motions/lists tagged with a campaign tag. --tag is accepted as an alias.",
+    "  --motion <motn_id>  Filter to one motion/play.",
+    "  --list <list_id>  Filter to prospects in one list, including analytics cohort lists.",
+    "  --offer <offr_id>  Filter to one offer.",
+    "  --icp <icp_id>  Filter to one ICP.",
+    "  --user <account_user_id|email|name|me>  Filter to prospects assigned to one account user.",
+    "",
+    "Output shape:",
+    "  conversion_grid.rows[]: period label, date bounds, totals_by_stage, and values keyed by stage metric",
+    "  conversion_grid.stage_definitions[]: stable metric keys and numerator/denominator stage definitions",
+    "  stage_aging.rows[]: current, due soon, overdue, age, and idle counts by current pipeline stage",
+    "  stage_aging.totals: rollup current, due soon, overdue, overdue_rate, and oldest_idle_days",
+    "",
+    "API:",
+    "  GET /api/v1/accounts/:account_id/analytics/stages.json"
+  ].join("\n")],
+
   ["analytics prospects", [
     "Usage:",
     `  ${ANALYTICS_PROSPECTS_USAGE.slice("Usage: ".length)}`,
@@ -8661,15 +9075,17 @@ const HELP_TOPICS = new Map([
     "  Give a local coding agent the shortest safe path through the common Audienti production workflows.",
     "",
     "1. Authenticate and select an account",
-    "  audienti auth token <token>",
+    "  audienti auth login",
     "  audienti accounts list",
     "  audienti accounts select <acct_id>",
     "  audienti users list",
     "  audienti users select me",
+    "  audienti setup play preflight --principal me --platform linkedin",
     "  audienti offers list",
     "  audienti icps list",
     "",
     "2. Create a motion or play",
+    "  audienti setup play preflight --principal <account_user_id|me> --platform linkedin",
     "  audienti motions create --payload <file.json>",
     "  audienti motions clone <motn_id> --name \"New subset motion\"",
     "  audienti motions move-prospects <source_motn_id> --target <target_motn_id> <prsp_id> [prsp_id...]",
@@ -8725,6 +9141,7 @@ const HELP_TOPICS = new Map([
     "  audienti users activity me --window 7d",
     "  audienti analytics prospects --window 24h",
     "  audienti analytics dashboard --play-tag wine_campaign",
+    "  audienti analytics stages --interval weekly --play-tag wine_campaign",
     "  audienti analytics cohorts create-list --name \"Connection requests 2026-07-20\" --start 2026-07-20 --end 2026-07-20",
     "  audienti analytics users --user me --window 30d",
     "  audienti analytics visibility --window 24h --user me",

package/src/mcp.js

@@ -0,0 +1,103 @@
+import { ApiError, AudientiClient, DEFAULT_HOST } from "./api-client.js";
+import { readConfig } from "./config.js";
+
+export async function runMcpServer({
+  input = process.stdin,
+  output = process.stdout,
+  env = process.env,
+  fetchImpl = globalThis.fetch
+} = {}) {
+  input.setEncoding("utf8");
+
+  let buffer = "";
+  for await (const chunk of input) {
+    buffer += chunk;
+    const lines = buffer.split(/\r?\n/);
+    buffer = lines.pop() || "";
+
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      const response = await handleRawMessage(line, { env, fetchImpl });
+      if (response) output.write(`${JSON.stringify(response)}\n`);
+    }
+  }
+}
+
+export async function handleRawMessage(line, options = {}) {
+  try {
+    return handleMcpRequest(JSON.parse(line), options);
+  } catch (error) {
+    return errorResponse(null, -32700, error.message);
+  }
+}
+
+export async function handleMcpRequest(message, { env = process.env, fetchImpl = globalThis.fetch } = {}) {
+  if (!message || message.jsonrpc !== "2.0") {
+    return errorResponse(message?.id ?? null, -32600, "Invalid JSON-RPC request.");
+  }
+
+  if (message.id === undefined || message.id === null) return null;
+
+  try {
+    return await remoteMcpResponse(message, { env, fetchImpl });
+  } catch (error) {
+    return errorResponse(message.id, -32603, toolErrorMessage(error), toolErrorPayload(error));
+  }
+}
+
+async function remoteMcpResponse(message, { env = process.env, fetchImpl = globalThis.fetch } = {}) {
+  const config = await readConfig({ env });
+  if (!config.token) throw new Error("Not authenticated. Run `audienti auth login` or `audienti auth token <token>`.");
+
+  const client = new AudientiClient({
+    host: config.host || DEFAULT_HOST,
+    token: config.token,
+    fetchImpl
+  });
+
+  return client.mcp(withSelectedAccount(message, config));
+}
+
+function withSelectedAccount(message, config) {
+  if (message.method !== "tools/call" || !config.accountId) return message;
+
+  const params = message.params || {};
+  const args = params.arguments || {};
+  if (args.account_id) return message;
+
+  return {
+    ...message,
+    params: {
+      ...params,
+      arguments: {
+        ...args,
+        account_id: config.accountId
+      }
+    }
+  };
+}
+
+function errorResponse(id, code, message, data) {
+  return {
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code,
+      message,
+      ...(data === undefined ? {} : { data })
+    }
+  };
+}
+
+function toolErrorMessage(error) {
+  if (error instanceof ApiError && error.status) return `${error.message} (HTTP ${error.status})`;
+  return error.message;
+}
+
+function toolErrorPayload(error) {
+  return {
+    error: error.message,
+    status: error instanceof ApiError ? error.status || null : null,
+    body: error instanceof ApiError ? error.body || null : null
+  };
+}