@mikado-ai/cli 0.1.0

package/README.md

@@ -0,0 +1,229 @@
+# @mikado-ai/cli
+
+Command-line interface and MCP server for [Mikado AI](https://mikadoai.app) — submit conversation transcripts, extract structured insights, and integrate with AI agents.
+
+## Install
+
+```bash
+npx @mikado-ai/cli
+```
+
+Or install globally:
+
+```bash
+npm install -g @mikado-ai/cli
+```
+
+## Quick Start
+
+```bash
+# 1. Authenticate (get your API key from Mikado AI → Settings → API Keys)
+mikado auth
+
+# 2. See available campaigns
+mikado campaigns
+
+# 3. Submit a transcript
+mikado submit transcript.txt --campaign abcd1234
+```
+
+## Authentication
+
+### Interactive
+
+```bash
+mikado auth
+```
+
+You'll be prompted for your API key and server URL.
+
+### Non-Interactive
+
+```bash
+mikado auth --key mkd_your_api_key --url https://mikadoai.app
+```
+
+### Environment Variable
+
+```bash
+export MIKADO_API_KEY=mkd_your_api_key
+export MIKADO_URL=https://mikadoai.app
+```
+
+Environment variables take precedence over the config file.
+
+### Config File
+
+Credentials are stored in `~/.mikado/config.json`. The file is created with restricted permissions (owner-only read/write).
+
+## Commands
+
+### `mikado submit <file>`
+
+Submit a conversation transcript for processing. By default, waits for results.
+
+```bash
+# Submit and wait for results (default)
+mikado submit transcript.txt --campaign abcd1234
+
+# Submit without waiting
+mikado submit transcript.txt --campaign abcd1234 --no-wait
+
+# Read from stdin
+cat transcript.txt | mikado submit -
+
+# JSON output for scripting
+mikado submit transcript.txt --campaign abcd1234 --json
+
+# Custom timeout (default: 300s)
+mikado submit transcript.txt --timeout 60
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-c, --campaign <id>` | Campaign short ID, UUID, or name |
+| `--no-wait` | Return immediately with job ID |
+| `--timeout <seconds>` | Max wait time (default: 300) |
+| `--json` | Output JSON to stdout |
+
+### `mikado campaigns`
+
+List available campaigns in your organization.
+
+```bash
+mikado campaigns
+```
+
+```
+  ID        Name              Status    Templates Conversations
+  abcd1234  Sales Calls       ACTIVE    2         142
+  efgh5678  Support Tickets   ACTIVE    1         89
+```
+
+### `mikado status <job-id>`
+
+Check the processing status of a submitted transcript.
+
+```bash
+mikado status 3f8a2b1c-...
+```
+
+```
+  Job:      3f8a2b1c-...
+  Status:   ✓ SUCCESS
+  Duration: 11.2s
+  Insights: 1 generated
+  Sentiment: positive (0.82)
+```
+
+### `mikado result <conversation-id>`
+
+Retrieve full results for a processed conversation.
+
+```bash
+mikado result 550e8400-...
+```
+
+### `mikado auth`
+
+Set up or update authentication credentials.
+
+```bash
+mikado auth
+mikado auth --key mkd_... --url https://api.mikado.ai
+```
+
+## JSON Output
+
+All commands support `--json` for machine-readable output. Errors go to stderr, data goes to stdout.
+
+```bash
+# Pipe to jq
+mikado submit transcript.txt --campaign abcd1234 --json | jq '.insights[0]'
+
+# Batch processing
+for f in transcripts/*.txt; do
+  mikado submit "$f" --campaign abcd1234 --json >> results.jsonl
+done
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | General error (auth failure, network error) |
+| `2` | Invalid arguments |
+| `3` | Processing failed (pipeline error) |
+| `4` | Timeout (polling exceeded `--timeout`) |
+
+## MCP Server
+
+Use Mikado AI as a tool in AI agents via the [Model Context Protocol](https://modelcontextprotocol.io/).
+
+### Configuration
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "mikado": {
+      "command": "npx",
+      "args": ["@mikado-ai/cli", "mcp"],
+      "env": {
+        "MIKADO_API_KEY": "mkd_your_api_key",
+        "MIKADO_URL": "https://mikadoai.app"
+      }
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add mikado -- npx @mikado-ai/cli mcp
+```
+
+### Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `mikado_submit_and_wait` | Submit a transcript and wait for full results. Primary tool for AI agents. |
+| `mikado_submit` | Submit a transcript, return immediately with job ID. |
+| `mikado_status` | Check processing status of a job. |
+| `mikado_result` | Get results for a completed conversation. |
+| `mikado_campaigns` | List available campaigns. |
+
+### Example Agent Workflow
+
+```
+1. Call mikado_campaigns to see available campaigns
+2. Call mikado_submit_and_wait with transcript + campaign
+3. Use the returned insights (scores, labels, extracted data) in your response
+```
+
+## Local Development
+
+```bash
+cd cli
+npm install
+npm run build      # Build to dist/
+npm run dev        # Watch mode
+
+# Test locally
+node dist/index.js --help
+node dist/index.js auth --key mkd_... --url http://localhost:8100
+```
+
+## Requirements
+
+- Node.js 18 or later
+- A [Mikado AI](https://mikadoai.app) account with an API key
+
+## License
+
+MIT

package/dist/chunk-5RICPX62.js

@@ -0,0 +1,94 @@
+// src/core/client.ts
+var MikadoClient = class {
+  apiKey;
+  baseUrl;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+  }
+  async request(path, options = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "Authorization": `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      ...options.headers
+    };
+    const response = await fetch(url, {
+      ...options,
+      headers
+    });
+    if (!response.ok) {
+      let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+      try {
+        const errorBody = await response.json();
+        if (errorBody.message) {
+          errorMessage = errorBody.message;
+        } else if (errorBody.detail) {
+          errorMessage = errorBody.detail;
+        }
+      } catch {
+      }
+      throw new Error(errorMessage);
+    }
+    return response.json();
+  }
+  async whoami() {
+    return this.request("/api/cli/whoami");
+  }
+  async submit(content, options) {
+    const body = { content };
+    if (options?.campaign) {
+      body.campaign = options.campaign;
+    }
+    if (options?.filename) {
+      body.filename = options.filename;
+    }
+    return this.request("/api/cli/submit", {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  async getJobStatus(jobId) {
+    return this.request(`/api/cli/jobs/${jobId}`);
+  }
+  async getConversation(conversationId) {
+    return this.request(
+      `/api/cli/conversations/${conversationId}`
+    );
+  }
+  async listCampaigns() {
+    return this.request("/api/cli/campaigns");
+  }
+};
+
+// src/core/poller.ts
+async function pollJob(client, jobId, options = {}) {
+  const {
+    interval = 1e3,
+    timeout = 3e5,
+    onUpdate
+  } = options;
+  const startTime = Date.now();
+  let currentInterval = interval;
+  const maxInterval = 5e3;
+  while (true) {
+    const elapsed = Date.now() - startTime;
+    if (elapsed > timeout) {
+      throw new Error(`Job polling timed out after ${timeout}ms`);
+    }
+    const status = await client.getJobStatus(jobId);
+    if (onUpdate) {
+      onUpdate(status);
+    }
+    if (status.status === "SUCCESS" || status.status === "FAILED") {
+      return status;
+    }
+    await new Promise((resolve) => setTimeout(resolve, currentInterval));
+    currentInterval = Math.min(currentInterval * 2, maxInterval);
+  }
+}
+
+export {
+  MikadoClient,
+  pollJob
+};

package/dist/chunk-6RKQ24OP.js

@@ -0,0 +1,94 @@
+// src/core/client.ts
+var MikadoClient = class {
+  apiKey;
+  baseUrl;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+  }
+  async request(path, options = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "Authorization": `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      ...options.headers
+    };
+    const response = await fetch(url, {
+      ...options,
+      headers
+    });
+    if (!response.ok) {
+      let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+      try {
+        const errorBody = await response.json();
+        if (errorBody.message) {
+          errorMessage = errorBody.message;
+        } else if (errorBody.detail) {
+          errorMessage = errorBody.detail;
+        }
+      } catch {
+      }
+      throw new Error(errorMessage);
+    }
+    return response.json();
+  }
+  async whoami() {
+    return this.request("/api/cli/whoami");
+  }
+  async submit(content, options) {
+    const body = { content };
+    if (options?.campaign) {
+      body.campaign_id = options.campaign;
+    }
+    if (options?.filename) {
+      body.filename = options.filename;
+    }
+    return this.request("/api/cli/submit", {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  async getJobStatus(jobId) {
+    return this.request(`/api/cli/jobs/${jobId}`);
+  }
+  async getConversation(conversationId) {
+    return this.request(
+      `/api/cli/conversations/${conversationId}`
+    );
+  }
+  async listCampaigns() {
+    return this.request("/api/cli/campaigns");
+  }
+};
+
+// src/core/poller.ts
+async function pollJob(client, jobId, options = {}) {
+  const {
+    interval = 1e3,
+    timeout = 3e5,
+    onUpdate
+  } = options;
+  const startTime = Date.now();
+  let currentInterval = interval;
+  const maxInterval = 5e3;
+  while (true) {
+    const elapsed = Date.now() - startTime;
+    if (elapsed > timeout) {
+      throw new Error(`Job polling timed out after ${timeout}ms`);
+    }
+    const status = await client.getJobStatus(jobId);
+    if (onUpdate) {
+      onUpdate(status);
+    }
+    if (status.status === "COMPLETED" || status.status === "FAILED") {
+      return status;
+    }
+    await new Promise((resolve) => setTimeout(resolve, currentInterval));
+    currentInterval = Math.min(currentInterval * 2, maxInterval);
+  }
+}
+
+export {
+  MikadoClient,
+  pollJob
+};

package/dist/chunk-DC4BEVL3.js

@@ -0,0 +1,94 @@
+// src/core/client.ts
+var MikadoClient = class {
+  apiKey;
+  baseUrl;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+  }
+  async request(path, options = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "Authorization": `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      ...options.headers
+    };
+    const response = await fetch(url, {
+      ...options,
+      headers
+    });
+    if (!response.ok) {
+      let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+      try {
+        const errorBody = await response.json();
+        if (errorBody.message) {
+          errorMessage = errorBody.message;
+        } else if (errorBody.detail) {
+          errorMessage = errorBody.detail;
+        }
+      } catch {
+      }
+      throw new Error(errorMessage);
+    }
+    return response.json();
+  }
+  async whoami() {
+    return this.request("/api/v1/cli/whoami");
+  }
+  async submit(content, options) {
+    const body = { content };
+    if (options?.campaign) {
+      body.campaign = options.campaign;
+    }
+    if (options?.filename) {
+      body.filename = options.filename;
+    }
+    return this.request("/api/v1/cli/submit", {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  async getJobStatus(jobId) {
+    return this.request(`/api/v1/cli/jobs/${jobId}`);
+  }
+  async getConversation(conversationId) {
+    return this.request(
+      `/api/v1/cli/conversations/${conversationId}`
+    );
+  }
+  async listCampaigns() {
+    return this.request("/api/v1/cli/campaigns");
+  }
+};
+
+// src/core/poller.ts
+async function pollJob(client, jobId, options = {}) {
+  const {
+    interval = 1e3,
+    timeout = 3e5,
+    onUpdate
+  } = options;
+  const startTime = Date.now();
+  let currentInterval = interval;
+  const maxInterval = 5e3;
+  while (true) {
+    const elapsed = Date.now() - startTime;
+    if (elapsed > timeout) {
+      throw new Error(`Job polling timed out after ${timeout}ms`);
+    }
+    const status = await client.getJobStatus(jobId);
+    if (onUpdate) {
+      onUpdate(status);
+    }
+    if (status.status === "SUCCESS" || status.status === "FAILED") {
+      return status;
+    }
+    await new Promise((resolve) => setTimeout(resolve, currentInterval));
+    currentInterval = Math.min(currentInterval * 2, maxInterval);
+  }
+}
+
+export {
+  MikadoClient,
+  pollJob
+};

package/dist/chunk-L27HHHAB.js

@@ -0,0 +1,95 @@
+// src/core/client.ts
+var MikadoClient = class {
+  apiKey;
+  baseUrl;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+  }
+  async request(path, options = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "Authorization": `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      ...options.headers
+    };
+    const response = await fetch(url, {
+      ...options,
+      headers
+    });
+    if (!response.ok) {
+      let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+      try {
+        const errorBody = await response.json();
+        if (errorBody.message) {
+          errorMessage = errorBody.message;
+        } else if (errorBody.detail) {
+          errorMessage = errorBody.detail;
+        }
+      } catch {
+      }
+      throw new Error(errorMessage);
+    }
+    return response.json();
+  }
+  // All /api/v1/* routes go via nginx directly to FastAPI (see nginx/nginx.conf)
+  async whoami() {
+    return this.request("/api/v1/cli/whoami");
+  }
+  async submit(content, options) {
+    const body = { content };
+    if (options?.campaign) {
+      body.campaign = options.campaign;
+    }
+    if (options?.filename) {
+      body.filename = options.filename;
+    }
+    return this.request("/api/v1/cli/submit", {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  async getJobStatus(jobId) {
+    return this.request(`/api/v1/cli/jobs/${jobId}`);
+  }
+  async getConversation(conversationId) {
+    return this.request(
+      `/api/v1/cli/conversations/${conversationId}`
+    );
+  }
+  async listCampaigns() {
+    return this.request("/api/v1/cli/campaigns");
+  }
+};
+
+// src/core/poller.ts
+async function pollJob(client, jobId, options = {}) {
+  const {
+    interval = 1e3,
+    timeout = 3e5,
+    onUpdate
+  } = options;
+  const startTime = Date.now();
+  let currentInterval = interval;
+  const maxInterval = 5e3;
+  while (true) {
+    const elapsed = Date.now() - startTime;
+    if (elapsed > timeout) {
+      throw new Error(`Job polling timed out after ${timeout}ms`);
+    }
+    const status = await client.getJobStatus(jobId);
+    if (onUpdate) {
+      onUpdate(status);
+    }
+    if (status.status === "SUCCESS" || status.status === "FAILED") {
+      return status;
+    }
+    await new Promise((resolve) => setTimeout(resolve, currentInterval));
+    currentInterval = Math.min(currentInterval * 2, maxInterval);
+  }
+}
+
+export {
+  MikadoClient,
+  pollJob
+};

package/dist/chunk-TJ7OWJIM.js

@@ -0,0 +1,94 @@
+// src/core/client.ts
+var MikadoClient = class {
+  apiKey;
+  baseUrl;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+  }
+  async request(path, options = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const headers = {
+      "Authorization": `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      ...options.headers
+    };
+    const response = await fetch(url, {
+      ...options,
+      headers
+    });
+    if (!response.ok) {
+      let errorMessage = `HTTP ${response.status}: ${response.statusText}`;
+      try {
+        const errorBody = await response.json();
+        if (errorBody.message) {
+          errorMessage = errorBody.message;
+        } else if (errorBody.detail) {
+          errorMessage = errorBody.detail;
+        }
+      } catch {
+      }
+      throw new Error(errorMessage);
+    }
+    return response.json();
+  }
+  async whoami() {
+    return this.request("/api/cli/whoami");
+  }
+  async submit(content, options) {
+    const body = { content };
+    if (options?.campaign) {
+      body.campaign = options.campaign;
+    }
+    if (options?.filename) {
+      body.filename = options.filename;
+    }
+    return this.request("/api/cli/submit", {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+  }
+  async getJobStatus(jobId) {
+    return this.request(`/api/cli/jobs/${jobId}`);
+  }
+  async getConversation(conversationId) {
+    return this.request(
+      `/api/cli/conversations/${conversationId}`
+    );
+  }
+  async listCampaigns() {
+    return this.request("/api/cli/campaigns");
+  }
+};
+
+// src/core/poller.ts
+async function pollJob(client, jobId, options = {}) {
+  const {
+    interval = 1e3,
+    timeout = 3e5,
+    onUpdate
+  } = options;
+  const startTime = Date.now();
+  let currentInterval = interval;
+  const maxInterval = 5e3;
+  while (true) {
+    const elapsed = Date.now() - startTime;
+    if (elapsed > timeout) {
+      throw new Error(`Job polling timed out after ${timeout}ms`);
+    }
+    const status = await client.getJobStatus(jobId);
+    if (onUpdate) {
+      onUpdate(status);
+    }
+    if (status.status === "COMPLETED" || status.status === "FAILED") {
+      return status;
+    }
+    await new Promise((resolve) => setTimeout(resolve, currentInterval));
+    currentInterval = Math.min(currentInterval * 2, maxInterval);
+  }
+}
+
+export {
+  MikadoClient,
+  pollJob
+};

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node