@moda-ai/cli 1.0.0

package/.env.example

@@ -0,0 +1,8 @@
+# Moda API Key (required)
+# Get this from https://app.modaflows.com/settings
+MODA_API_KEY=moda_sk_...
+
+# Moda Backend URL (optional)
+# Defaults to production: https://modaflows.com
+# For local development, override with:
+# MODA_BASE_URL=http://localhost:3001

package/README.md

@@ -0,0 +1,124 @@
+# moda-cli
+
+CLI and MCP server for [Moda](https://modaflows.com) -- AI agent analytics and observability.
+
+Query your conversation analytics from the terminal or connect AI assistants (Claude Code, Cursor, etc.) to your Moda data via the Model Context Protocol.
+
+## Install
+
+```bash
+npm install -g moda-cli
+```
+
+Or use without installing:
+
+```bash
+npx moda-cli overview
+```
+
+## Setup
+
+Get your API key from [modaflows.com/settings](https://modaflows.com/settings), then:
+
+```bash
+export MODA_API_KEY="moda_sk_..."
+```
+
+## CLI Usage
+
+```bash
+moda overview                                    # Dashboard overview
+moda overview --days-back=30                     # Last 30 days
+
+moda clusters                                    # Browse topic clusters
+moda clusters --parent-id=node-abc               # Drill into a category
+
+moda cluster-conversations <node_id>             # Conversations in a cluster
+
+moda conversations --search="error"              # Search conversations
+moda conversations --time-range=24h              # Filter by time
+moda conversations --environment=production      # Filter by environment
+
+moda context <conversation_id>                   # Get conversation context
+moda context <conversation_id> --msg-index=5     # Center on message 5
+
+moda frustrations                                # User frustration detections
+moda frustrations --days-back=14 --limit=20
+
+moda tool-failures                               # Tool failure overview
+moda tool-failure-detail <tool_name>             # Per-tool failure detail
+```
+
+All commands output JSON. Pipe to `jq` for filtering:
+
+```bash
+moda overview | jq '.frustrations'
+moda frustrations | jq '.frustrations[].primary_cause'
+```
+
+## MCP Server
+
+### Claude Code
+
+```bash
+claude mcp add moda -- npx moda-cli
+```
+
+Or add manually to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "moda": {
+      "command": "npx",
+      "args": ["-y", "moda-cli"],
+      "env": {
+        "MODA_API_KEY": "moda_sk_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Other MCP Clients (Cursor, etc.)
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "moda-cli"],
+  "env": {
+    "MODA_API_KEY": "moda_sk_your_key_here"
+  }
+}
+```
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `moda_get_overview` | Dashboard overview with KPIs, top clusters, recent activity |
+| `moda_get_clusters` | Browse topic cluster hierarchy |
+| `moda_get_cluster_conversations` | List conversations in a specific cluster |
+| `moda_search_conversations` | Search and filter conversations |
+| `moda_get_conversation_context` | Get windowed conversation context (max 5 messages) |
+| `moda_get_frustrations` | User frustration detections with evidence |
+| `moda_get_tool_failures` | Tool failure overview |
+| `moda_get_tool_failure_detail` | Per-tool failure detail with examples |
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `MODA_API_KEY` | Yes | -- | Your Moda API key (`moda_sk_...`) |
+| `MODA_BASE_URL` | No | `https://modaflows.com` | Base URL for the Data API |
+
+## Documentation
+
+- [CLI Reference](https://docs.modaflows.com/data-api/cli)
+- [MCP Server Setup](https://docs.modaflows.com/data-api/mcp)
+- [Data API Overview](https://docs.modaflows.com/data-api/overview)
+- [Quickstart](https://docs.modaflows.com/quickstart)
+
+## License
+
+MIT

package/dist/api-client.d.ts

@@ -0,0 +1,7 @@
+export declare class ApiError extends Error {
+    readonly statusCode: number;
+    readonly responseBody: string;
+    constructor(message: string, statusCode: number, responseBody: string);
+}
+export declare function callDataAPI(endpoint: string): Promise<unknown>;
+//# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.js

@@ -0,0 +1,67 @@
+// src/api-client.ts
+import { MODA_API_KEY, MODA_BASE_URL } from './config.js';
+const REQUEST_TIMEOUT_MS = 30_000;
+const MAX_RETRIES = 3;
+const INITIAL_BACKOFF_MS = 500;
+export class ApiError extends Error {
+    statusCode;
+    responseBody;
+    constructor(message, statusCode, responseBody) {
+        super(message);
+        this.statusCode = statusCode;
+        this.responseBody = responseBody;
+        this.name = 'ApiError';
+    }
+}
+function isRetryable(status) {
+    return status === 429 || status >= 500;
+}
+export async function callDataAPI(endpoint) {
+    const url = `${MODA_BASE_URL}/api/v1/data${endpoint}`;
+    let lastError;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        if (attempt > 0) {
+            const backoff = INITIAL_BACKOFF_MS * Math.pow(2, attempt - 1);
+            await new Promise((resolve) => setTimeout(resolve, backoff));
+        }
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        try {
+            const response = await fetch(url, {
+                headers: {
+                    'x-api-key': MODA_API_KEY,
+                    'Content-Type': 'application/json',
+                },
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                const error = new ApiError(`API error (${response.status}): ${errorText}`, response.status, errorText);
+                if (isRetryable(response.status) && attempt < MAX_RETRIES) {
+                    lastError = error;
+                    continue;
+                }
+                throw error;
+            }
+            return response.json();
+        }
+        catch (error) {
+            if (error instanceof ApiError)
+                throw error;
+            const isAbort = error instanceof DOMException && error.name === 'AbortError';
+            const wrapped = new Error(isAbort
+                ? `Request timed out after ${REQUEST_TIMEOUT_MS}ms: ${url}`
+                : `Network error: ${error instanceof Error ? error.message : String(error)}`);
+            if (attempt < MAX_RETRIES) {
+                lastError = wrapped;
+                continue;
+            }
+            throw wrapped;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    throw lastError ?? new Error('Request failed after retries');
+}
+//# sourceMappingURL=api-client.js.map

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+interface ParsedArgs {
+    command: string;
+    positional: string | undefined;
+    flags: Record<string, string>;
+}
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function flagsToArgs(flags: Record<string, string>, positionalKey?: string, positionalValue?: string): Record<string, unknown>;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+import { z } from 'zod';
+import { validateConfig, VERSION } from './config.js';
+import { callDataAPI, ApiError } from './api-client.js';
+import { OverviewSchema, ClustersSchema, ClusterConversationsSchema, ConversationsSchema, ContextSchema, FrustrationsSchema, ToolFailuresSchema, ToolFailureDetailSchema, } from './schemas.js';
+export function parseArgs(argv) {
+    const args = argv.slice(2);
+    const command = args[0] || '';
+    const flags = {};
+    let positional;
+    let i = 1;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            const eqIndex = arg.indexOf('=');
+            if (eqIndex !== -1) {
+                // --key=value
+                const key = arg.slice(2, eqIndex);
+                flags[key] = arg.slice(eqIndex + 1);
+            }
+            else {
+                // --key value
+                const key = arg.slice(2);
+                const next = args[i + 1];
+                if (next !== undefined && !next.startsWith('--')) {
+                    flags[key] = next;
+                    i++;
+                }
+                else {
+                    flags[key] = 'true';
+                }
+            }
+        }
+        else if (positional === undefined) {
+            positional = arg;
+        }
+        i++;
+    }
+    return { command, positional, flags };
+}
+// Convert kebab-case flags to snake_case for Zod schema compatibility
+export function flagsToArgs(flags, positionalKey, positionalValue) {
+    const result = {};
+    if (positionalKey && positionalValue) {
+        result[positionalKey] = positionalValue;
+    }
+    for (const [key, value] of Object.entries(flags)) {
+        const snakeKey = key.replace(/-/g, '_');
+        // Try to parse as number for numeric fields
+        const num = Number(value);
+        result[snakeKey] = isNaN(num) || value === 'true' ? value : num;
+    }
+    return result;
+}
+// --- Help ---
+function printHelp() {
+    console.error(`Usage: moda <command> [options]
+
+Commands:
+  overview                         Dashboard overview with KPIs
+  clusters                         Browse topic cluster hierarchy
+  cluster-conversations <node_id>  List conversations in a cluster
+  conversations                    Search and filter conversations
+  context <conversation_id>        Get windowed conversation context
+  frustrations                     Get user frustration detections
+  tool-failures                    Get tool failure overview
+  tool-failure-detail <tool_name>  Get per-tool failure detail
+
+Options:
+  --help                           Show this help message
+  --version                        Show version number
+
+Common flags:
+  --days-back=N                    Number of days to look back (1-90)
+  --limit=N                        Maximum results to return
+  --offset=N                       Number of results to skip
+  --time-range=RANGE               Time range filter (all|1h|3d|7d|24h|30d|90d)
+
+Examples:
+  moda overview
+  moda overview --days-back=30
+  moda clusters --time-range=7d
+  moda conversations --search="error" --limit=5
+  moda frustrations --days-back=14 --limit=20
+  moda context <conversation_id> --window=3`);
+}
+// --- Command Handlers ---
+// Each handler replicates the URL construction from src/handlers.ts
+// but outputs JSON directly instead of wrapping in MCP envelope.
+async function runCommand(command, positional, flags) {
+    switch (command) {
+        case 'overview': {
+            const args = flagsToArgs(flags);
+            const params = OverviewSchema.parse(args);
+            const queryString = params.days_back ? `?days_back=${params.days_back}` : '';
+            const data = await callDataAPI(`/overview${queryString}`);
+            console.log(JSON.stringify(data, null, 2));
+            break;
+        }
+        case 'clusters': {
+            const args = flagsToArgs(flags);
+            const params = ClustersSchema.parse(args);
+            const query = new URLSearchParams();
+            if (params.parent_id)
+                query.set('parent_id', params.parent_id);
+            if (params.time_range)
+                query.set('time_range', params.time_range);
+            const queryString = query.toString() ? `?${query.toString()}` : '';
+            const data = await callDataAPI(`/clusters${queryString}`);
+            console.log(JSON.stringify(data, null, 2));
+            break;
+        }
+        case 'cluster-conversations': {
+            if (!positional) {
+                console.error('Error: <node_id> is required');
+                console.error('Usage: moda cluster-conversations <node_id> [--limit=N] [--offset=N]');
+                process.exit(1);
+            }
+            const args = flagsToArgs(flags, 'node_id', positional);
+            const params = ClusterConversationsSchema.parse(args);
+            const query = new URLSearchParams();
+            if (params.limit)
+                query.set('limit', params.limit.toString());
+            if (params.offset !== undefined)
+                query.set('offset', params.offset.toString());
+            const queryString = query.toString() ? `?${query.toString()}` : '';
+            const data = await callDataAPI(`/clusters/${params.node_id}/conversations${queryString}`);
+            console.log(JSON.stringify(data, null, 2));
+            break;
+        }
+        case 'conversations': {
+            const args = flagsToArgs(flags);
+            const params = ConversationsSchema.parse(args);
+            const query = new URLSearchParams();
+            if (params.search)
+                query.set('search', params.search);
+            if (params.cluster_id)
+                query.set('cluster_id', params.cluster_id);
+            if (params.user_id)
+                query.set('user_id', params.user_id);
+            if (params.time_range)
+                query.set('time_range', params.time_range);
+            if (params.environment)
+                query.set('environment', params.environment);
+            if (params.limit)
+                query.set('limit', params.limit.toString());
+            if (params.offset !== undefined)
+                query.set('offset', params.offset.toString());
+            const queryString = query.toString() ? `?${query.toString()}` : '';
+            const data = await callDataAPI(`/conversations${queryString}`);
+            console.log(JSON.stringify(data, null, 2));
+            break;
+        }
+        case 'context': {
+            if (!positional) {
+                console.error('Error: <conversation_id> is required');
+                console.error('Usage: moda context <conversation_id> [--msg-index=N] [--window=N]');
+                process.exit(1);
+            }
+            const args = flagsToArgs(flags, 'conversation_id', positional);
+            const params = ContextSchema.parse(args);
+            const query = new URLSearchParams();
+            if (params.msg_index !== undefined)
+                query.set('msg_index', params.msg_index.toString());
+            if (params.window)
+                query.set('window', params.window.toString());
+            const queryString = query.toString() ? `?${query.toString()}` : '';
+            const data = await callDataAPI(`/conversations/${params.conversation_id}/context${queryString}`);
+            console.log(JSON.stringify(data, null, 2));
+            break;
+        }
+        case 'frustrations': {
+            const args = flagsToArgs(flags);
+            const params = FrustrationsSchema.parse(args);
+            const query = new URLSearchParams();
+            if (params.days_back)
+                query.set('days_back', params.days_back.toString());
+            if (params.limit)
+                query.set('limit', params.limit.toString());
+            if (params.offset !== undefined)
+                query.set('offset', params.offset.toString());
+            const queryString = query.toString() ? `?${query.toString()}` : '';
+            const data = await callDataAPI(`/frustrations${queryString}`);
+            console.log(JSON.stringify(data, null, 2));
+            break;
+        }
+        case 'tool-failures': {
+            const args = flagsToArgs(flags);
+            const params = ToolFailuresSchema.parse(args);
+            const queryString = params.days_back ? `?days_back=${params.days_back}` : '';
+            const data = await callDataAPI(`/tool-failures${queryString}`);
+            console.log(JSON.stringify(data, null, 2));
+            break;
+        }
+        case 'tool-failure-detail': {
+            if (!positional) {
+                console.error('Error: <tool_name> is required');
+                console.error('Usage: moda tool-failure-detail <tool_name> [--subtype=S] [--days-back=N] [--limit=N] [--offset=N]');
+                process.exit(1);
+            }
+            const args = flagsToArgs(flags, 'tool_name', positional);
+            const params = ToolFailureDetailSchema.parse(args);
+            const query = new URLSearchParams();
+            if (params.subtype)
+                query.set('subtype', params.subtype);
+            if (params.days_back)
+                query.set('days_back', params.days_back.toString());
+            if (params.limit)
+                query.set('limit', params.limit.toString());
+            if (params.offset !== undefined)
+                query.set('offset', params.offset.toString());
+            const queryString = query.toString() ? `?${query.toString()}` : '';
+            const data = await callDataAPI(`/tool-failures/${params.tool_name}${queryString}`);
+            console.log(JSON.stringify(data, null, 2));
+            break;
+        }
+        default:
+            console.error(`Error: Unknown command '${command}'`);
+            console.error('Run "moda --help" for usage information.');
+            process.exit(1);
+    }
+}
+// --- Main ---
+async function main() {
+    const { command, positional, flags } = parseArgs(process.argv);
+    if (command === '--version' || command === '-V' || flags.version === 'true') {
+        console.log(`moda-cli ${VERSION}`);
+        process.exit(0);
+    }
+    if (!command || command === '--help' || command === '-h' || flags.help === 'true') {
+        printHelp();
+        process.exit(command ? 0 : 1);
+    }
+    validateConfig();
+    await runCommand(command, positional, flags);
+}
+// Only run main() when this file is executed directly (not when imported as a module).
+// In ESM, import.meta.url is the file URL of the current module; process.argv[1] is
+// the path of the entry-point script. Comparing them lets tests import parseArgs /
+// flagsToArgs without triggering the CLI bootstrap.
+import { fileURLToPath } from 'url';
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+if (isMain) {
+    main().catch((error) => {
+        if (error instanceof z.ZodError) {
+            const issues = error.errors.map((e) => {
+                const field = e.path.length ? e.path.join('.') : 'input';
+                return `  ${field}: ${e.message}`;
+            });
+            console.error(`Validation error:\n${issues.join('\n')}`);
+        }
+        else if (error instanceof ApiError) {
+            console.error(`API error (HTTP ${error.statusCode}): ${error.responseBody || error.message}`);
+        }
+        else if (error instanceof Error) {
+            console.error(`Error: ${error.message}`);
+        }
+        else {
+            console.error('Error:', error);
+        }
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+export declare const VERSION = "1.0.0";
+export declare const MODA_API_KEY: string | undefined;
+export declare const MODA_BASE_URL: string;
+export declare const PORT: number;
+export declare function validateConfig(): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,13 @@
+// src/config.ts
+export const VERSION = '1.0.0';
+export const MODA_API_KEY = process.env.MODA_API_KEY;
+export const MODA_BASE_URL = process.env.MODA_BASE_URL || 'https://modaflows.com';
+export const PORT = parseInt(process.env.PORT || '3003', 10);
+export function validateConfig() {
+    if (!MODA_API_KEY) {
+        console.error('Error: MODA_API_KEY environment variable is required');
+        console.error('Get your API key from https://modaflows.com/settings');
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/handlers.d.ts

@@ -0,0 +1,7 @@
+export declare function handleToolCall(name: string, args: unknown): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/handlers.js

@@ -0,0 +1,117 @@
+// src/handlers.ts
+import { z } from 'zod';
+import { callDataAPI } from './api-client.js';
+import { OverviewSchema, ClustersSchema, ClusterConversationsSchema, ConversationsSchema, ContextSchema, FrustrationsSchema, ToolFailuresSchema, ToolFailureDetailSchema, } from './schemas.js';
+export async function handleToolCall(name, args) {
+    try {
+        switch (name) {
+            case 'moda_get_overview': {
+                const params = OverviewSchema.parse(args);
+                const queryString = params.days_back ? `?days_back=${params.days_back}` : '';
+                const data = await callDataAPI(`/overview${queryString}`);
+                return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+            }
+            case 'moda_get_clusters': {
+                const params = ClustersSchema.parse(args);
+                const query = new URLSearchParams();
+                if (params.parent_id)
+                    query.set('parent_id', params.parent_id);
+                if (params.time_range)
+                    query.set('time_range', params.time_range);
+                const queryString = query.toString() ? `?${query.toString()}` : '';
+                const data = await callDataAPI(`/clusters${queryString}`);
+                return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+            }
+            case 'moda_get_cluster_conversations': {
+                const params = ClusterConversationsSchema.parse(args);
+                const query = new URLSearchParams();
+                if (params.limit)
+                    query.set('limit', params.limit.toString());
+                // FIX: use !== undefined instead of falsy check so offset=0 is included
+                if (params.offset !== undefined)
+                    query.set('offset', params.offset.toString());
+                const queryString = query.toString() ? `?${query.toString()}` : '';
+                const data = await callDataAPI(`/clusters/${params.node_id}/conversations${queryString}`);
+                return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+            }
+            case 'moda_search_conversations': {
+                const params = ConversationsSchema.parse(args);
+                const query = new URLSearchParams();
+                if (params.search)
+                    query.set('search', params.search);
+                if (params.cluster_id)
+                    query.set('cluster_id', params.cluster_id);
+                if (params.user_id)
+                    query.set('user_id', params.user_id);
+                if (params.time_range)
+                    query.set('time_range', params.time_range);
+                if (params.environment)
+                    query.set('environment', params.environment);
+                if (params.limit)
+                    query.set('limit', params.limit.toString());
+                // FIX: use !== undefined instead of falsy check
+                if (params.offset !== undefined)
+                    query.set('offset', params.offset.toString());
+                const queryString = query.toString() ? `?${query.toString()}` : '';
+                const data = await callDataAPI(`/conversations${queryString}`);
+                return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+            }
+            case 'moda_get_conversation_context': {
+                const params = ContextSchema.parse(args);
+                const query = new URLSearchParams();
+                if (params.msg_index !== undefined)
+                    query.set('msg_index', params.msg_index.toString());
+                if (params.window)
+                    query.set('window', params.window.toString());
+                const queryString = query.toString() ? `?${query.toString()}` : '';
+                const data = await callDataAPI(`/conversations/${params.conversation_id}/context${queryString}`);
+                return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+            }
+            case 'moda_get_frustrations': {
+                const params = FrustrationsSchema.parse(args);
+                const query = new URLSearchParams();
+                if (params.days_back)
+                    query.set('days_back', params.days_back.toString());
+                if (params.limit)
+                    query.set('limit', params.limit.toString());
+                // FIX: use !== undefined instead of falsy check
+                if (params.offset !== undefined)
+                    query.set('offset', params.offset.toString());
+                const queryString = query.toString() ? `?${query.toString()}` : '';
+                const data = await callDataAPI(`/frustrations${queryString}`);
+                return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+            }
+            case 'moda_get_tool_failures': {
+                const params = ToolFailuresSchema.parse(args);
+                const queryString = params.days_back ? `?days_back=${params.days_back}` : '';
+                const data = await callDataAPI(`/tool-failures${queryString}`);
+                return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+            }
+            case 'moda_get_tool_failure_detail': {
+                const params = ToolFailureDetailSchema.parse(args);
+                const query = new URLSearchParams();
+                if (params.subtype)
+                    query.set('subtype', params.subtype);
+                if (params.days_back)
+                    query.set('days_back', params.days_back.toString());
+                if (params.limit)
+                    query.set('limit', params.limit.toString());
+                // FIX: use !== undefined instead of falsy check
+                if (params.offset !== undefined)
+                    query.set('offset', params.offset.toString());
+                const queryString = query.toString() ? `?${query.toString()}` : '';
+                const data = await callDataAPI(`/tool-failures/${params.tool_name}${queryString}`);
+                return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            throw new Error(`Invalid arguments: ${JSON.stringify(error.errors)}`);
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=handlers.js.map

package/dist/http-server.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=http-server.d.ts.map