amplitude-cli 0.3.0

package/dist/mcp-client.js

@@ -0,0 +1,291 @@
+/**
+ * Amplitude MCP client.
+ * Calls Amplitude's MCP server tools (search, query_dataset, save_chart_edits,
+ * create_dashboard, etc.) using OAuth tokens.
+ *
+ * The MCP server exposes tools via JSON-RPC over HTTP (Streamable HTTP transport).
+ */
+import { getAccessToken, getMcpBaseUrl, getOAuthConfig } from "./utils/oauth.js";
+export class AmplitudeMcpClient {
+    region;
+    sessionId;
+    initialized = false;
+    constructor(region) {
+        const oauth = getOAuthConfig();
+        this.region =
+            region ||
+                process.env.AMPLITUDE_REGION ||
+                oauth?.region ||
+                "us";
+    }
+    /**
+     * Initialize MCP session. Must be called before any tool calls.
+     * Auto-called by callTool if not yet initialized.
+     */
+    async ensureSession() {
+        if (this.initialized && this.sessionId)
+            return;
+        const token = await getAccessToken(this.region);
+        const baseUrl = getMcpBaseUrl(this.region);
+        const body = {
+            jsonrpc: "2.0",
+            id: Date.now(),
+            method: "initialize",
+            params: {
+                protocolVersion: "2024-11-05",
+                capabilities: {},
+                clientInfo: { name: "amplitude-cli", version: "0.2.0" },
+            },
+        };
+        const res = await fetch(`${baseUrl}/mcp`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json, text/event-stream",
+                Authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(body),
+        });
+        const newSessionId = res.headers.get("mcp-session-id");
+        if (newSessionId) {
+            this.sessionId = newSessionId;
+        }
+        if (!res.ok) {
+            const text = await res.text();
+            throw new McpError(res.status, text, "initialize");
+        }
+        this.initialized = true;
+    }
+    /**
+     * Call an MCP tool on the Amplitude server.
+     */
+    async callTool(toolName, args = {}) {
+        try {
+            return await this._callToolOnce(toolName, args);
+        }
+        catch (err) {
+            // Auto-recover from session errors by re-initializing
+            if (err instanceof McpError && err.detail.toLowerCase().includes("session")) {
+                this.sessionId = undefined;
+                this.initialized = false;
+                return await this._callToolOnce(toolName, args);
+            }
+            throw err;
+        }
+    }
+    async _callToolOnce(toolName, args = {}) {
+        await this.ensureSession();
+        const token = await getAccessToken(this.region);
+        const baseUrl = getMcpBaseUrl(this.region);
+        const body = {
+            jsonrpc: "2.0",
+            id: Date.now(),
+            method: "tools/call",
+            params: {
+                name: toolName,
+                arguments: args,
+            },
+        };
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+            Authorization: `Bearer ${token}`,
+        };
+        // Include session ID for continuity if we have one
+        if (this.sessionId) {
+            headers["Mcp-Session-Id"] = this.sessionId;
+        }
+        const res = await fetch(`${baseUrl}/mcp`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        // Capture session ID from response
+        const newSessionId = res.headers.get("mcp-session-id");
+        if (newSessionId) {
+            this.sessionId = newSessionId;
+        }
+        if (!res.ok) {
+            const text = await res.text();
+            throw new McpError(res.status, text, toolName);
+        }
+        const contentType = res.headers.get("content-type") || "";
+        // Handle SSE (text/event-stream) response
+        if (contentType.includes("text/event-stream")) {
+            return this.parseSSEResponse(res);
+        }
+        // Handle direct JSON response
+        const result = (await res.json());
+        if (result.error) {
+            throw new McpError(result.error.code, result.error.message, toolName);
+        }
+        return result.result || { content: [] };
+    }
+    /**
+     * Parse SSE response from MCP server.
+     */
+    async parseSSEResponse(res) {
+        const text = await res.text();
+        const lines = text.split("\n");
+        let lastData = "";
+        for (const line of lines) {
+            if (line.startsWith("data: ")) {
+                lastData = line.slice(6);
+            }
+        }
+        if (!lastData) {
+            return { content: [] };
+        }
+        try {
+            const parsed = JSON.parse(lastData);
+            if (parsed.error) {
+                throw new McpError(parsed.error.code, parsed.error.message, "sse");
+            }
+            return parsed.result || { content: [] };
+        }
+        catch (err) {
+            if (err instanceof McpError)
+                throw err;
+            // Return raw text as content
+            return {
+                content: [{ type: "text", text: lastData }],
+            };
+        }
+    }
+    /**
+     * List available MCP tools.
+     */
+    async listTools() {
+        await this.ensureSession();
+        const token = await getAccessToken(this.region);
+        const baseUrl = getMcpBaseUrl(this.region);
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+            Authorization: `Bearer ${token}`,
+        };
+        if (this.sessionId) {
+            headers["Mcp-Session-Id"] = this.sessionId;
+        }
+        const res = await fetch(`${baseUrl}/mcp`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: Date.now(),
+                method: "tools/list",
+                params: {},
+            }),
+        });
+        const newSessionId = res.headers.get("mcp-session-id");
+        if (newSessionId) {
+            this.sessionId = newSessionId;
+        }
+        if (!res.ok) {
+            const text = await res.text();
+            throw new McpError(res.status, text, "tools/list");
+        }
+        const contentType = res.headers.get("content-type") || "";
+        if (contentType.includes("text/event-stream")) {
+            return this.parseSSEResponse(res);
+        }
+        return res.json();
+    }
+    // ─── Convenience methods for common MCP tools ─────────────────────────
+    /**
+     * Search for entities (charts, dashboards, events, cohorts, etc.)
+     */
+    async search(query, entityTypes, limit) {
+        return this.callTool("search", {
+            query,
+            ...(entityTypes && { entity_types: entityTypes }),
+            ...(limit && { limit }),
+        });
+    }
+    /**
+     * Get context (project info, user info).
+     */
+    async getContext() {
+        return this.callTool("get_context");
+    }
+    /**
+     * Get chart definitions by ID.
+     */
+    async getCharts(chartIds) {
+        return this.callTool("get_charts", { chart_ids: chartIds });
+    }
+    /**
+     * Get dashboard by ID.
+     */
+    async getDashboard(dashboardId) {
+        return this.callTool("get_dashboard", { dashboard_id: dashboardId });
+    }
+    /**
+     * Query a dataset (create/preview a chart).
+     * Returns data + an editId that can be saved.
+     */
+    async queryDataset(definition) {
+        return this.callTool("query_dataset", definition);
+    }
+    /**
+     * Save a chart from query_dataset results.
+     */
+    async saveChart(editId, name, description) {
+        return this.callTool("save_chart_edits", {
+            edit_id: editId,
+            name,
+            ...(description && { description }),
+        });
+    }
+    /**
+     * Create a dashboard with charts and layout.
+     */
+    async createDashboard(name, rows, description) {
+        return this.callTool("create_dashboard", {
+            name,
+            rows,
+            ...(description && { description }),
+        });
+    }
+    /**
+     * Get event properties for an event type.
+     */
+    async getEventProperties(eventType) {
+        return this.callTool("get_event_properties", { event_type: eventType });
+    }
+    /**
+     * Query an existing chart's data.
+     */
+    async queryChart(chartId) {
+        return this.callTool("query_chart", { chart_id: chartId });
+    }
+    /**
+     * Get experiment details.
+     */
+    async getExperiments(experimentIds) {
+        return this.callTool("get_experiments", {
+            experiment_ids: experimentIds,
+        });
+    }
+    /**
+     * Query experiment results.
+     */
+    async queryExperiment(experimentId) {
+        return this.callTool("query_experiment", {
+            experiment_id: experimentId,
+        });
+    }
+}
+export class McpError extends Error {
+    code;
+    detail;
+    tool;
+    constructor(code, detail, tool) {
+        super(`MCP error (${code}) calling ${tool}: ${detail}`);
+        this.code = code;
+        this.detail = detail;
+        this.tool = tool;
+        this.name = "McpError";
+    }
+}
+//# sourceMappingURL=mcp-client.js.map

package/dist/mcp-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-client.js","sourceRoot":"","sources":["../src/mcp-client.ts"],"names":[],"mappings":"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"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Centralized error handling for CLI commands.
+ */
+export declare function handleError(err: unknown): never;

package/dist/utils/errors.js

@@ -0,0 +1,34 @@
+/**
+ * Centralized error handling for CLI commands.
+ */
+import { McpError } from "../mcp-client.js";
+export function handleError(err) {
+    if (err instanceof McpError) {
+        console.error(`\nAmplitude MCP Error (${err.code}) calling ${err.tool}`);
+        if (err.code === 401 || err.code === 403) {
+            console.error("OAuth token invalid or expired.\n" +
+                "If using Nango: check that AMPLITUDE_ACCESS_TOKEN is set.\n" +
+                "If interactive: run 'amp auth login' to re-authenticate.");
+        }
+        else if (err.code === 429) {
+            console.error("Rate limited. Try again in a few minutes.");
+        }
+        else if (err.code === -32601) {
+            console.error("Unknown MCP tool. Run 'amp auth tools' to list available tools.");
+        }
+        console.error(`Detail: ${err.detail.slice(0, 500)}`);
+        process.exit(1);
+    }
+    if (err instanceof Error) {
+        if (err.message.includes("Not logged in")) {
+            console.error(`\n${err.message}`);
+            console.error("Set AMPLITUDE_ACCESS_TOKEN env var, or run 'amp auth login'.");
+            process.exit(1);
+        }
+        console.error(`\nError: ${err.message}`);
+        process.exit(1);
+    }
+    console.error("\nUnknown error:", err);
+    process.exit(1);
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;QAC5B,OAAO,CAAC,KAAK,CAAC,0BAA0B,GAAG,CAAC,IAAI,aAAa,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QAEzE,IAAI,GAAG,CAAC,IAAI,KAAK,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,GAAG,EAAE,CAAC;YACzC,OAAO,CAAC,KAAK,CACX,mCAAmC;gBACnC,6DAA6D;gBAC7D,0DAA0D,CAC3D,CAAC;QACJ,CAAC;aAAM,IAAI,GAAG,CAAC,IAAI,KAAK,GAAG,EAAE,CAAC;YAC5B,OAAO,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;QAC7D,CAAC;aAAM,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAC/B,OAAO,CAAC,KAAK,CAAC,iEAAiE,CAAC,CAAC;QACnF,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,WAAW,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QACrD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;YAC1C,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YAClC,OAAO,CAAC,KAAK,CACX,8DAA8D,CAC/D,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACzC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;IACvC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/utils/format.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Output formatting utilities.
+ * Supports JSON (default), compact JSON, and CSV.
+ */
+export type OutputFormat = "json" | "compact" | "csv";
+export declare function formatOutput(data: unknown, format: OutputFormat): string;
+/**
+ * Print to stdout. Commands use this for consistent output.
+ */
+export declare function output(data: unknown, format?: OutputFormat): void;

package/dist/utils/format.js

@@ -0,0 +1,90 @@
+/**
+ * Output formatting utilities.
+ * Supports JSON (default), compact JSON, and CSV.
+ */
+export function formatOutput(data, format) {
+    switch (format) {
+        case "json":
+            return JSON.stringify(data, null, 2);
+        case "compact":
+            return JSON.stringify(data);
+        case "csv":
+            return toCSV(data);
+        default:
+            return JSON.stringify(data, null, 2);
+    }
+}
+/**
+ * Best-effort CSV conversion for tabular data.
+ * Handles arrays of objects and Amplitude's series format.
+ */
+function toCSV(data) {
+    if (!data || typeof data !== "object") {
+        return String(data);
+    }
+    // Array of objects → standard CSV
+    if (Array.isArray(data)) {
+        if (data.length === 0)
+            return "";
+        if (typeof data[0] !== "object" || data[0] === null) {
+            return data.map(String).join("\n");
+        }
+        const keys = Object.keys(data[0]);
+        const header = keys.map(escapeCSV).join(",");
+        const rows = data.map((row) => {
+            const r = row;
+            return keys.map((k) => escapeCSV(String(r[k] ?? ""))).join(",");
+        });
+        return [header, ...rows].join("\n");
+    }
+    // Amplitude API wraps data in a `data` key — unwrap it for CSV
+    const obj = data;
+    if (obj.data && typeof obj.data === "object" && !Array.isArray(obj.data)) {
+        const inner = obj.data;
+        if (inner.series && inner.xValues) {
+            return seriestoCSV(inner);
+        }
+        // Unwrap and try again
+        return toCSV(inner);
+    }
+    // Direct series format: { series: [...], xValues: [...] }
+    if (obj.series && obj.xValues) {
+        return seriestoCSV(obj);
+    }
+    // Fallback: key-value pairs
+    const entries = Object.entries(obj);
+    return entries.map(([k, v]) => `${escapeCSV(k)},${escapeCSV(String(v))}`).join("\n");
+}
+function seriestoCSV(data) {
+    const xValues = data.xValues;
+    const seriesLabels = data.seriesLabels;
+    const series = data.series;
+    if (!xValues || !series) {
+        return JSON.stringify(data, null, 2);
+    }
+    const headers = ["date"];
+    if (seriesLabels) {
+        headers.push(...seriesLabels.map((l) => escapeCSV(String(l))));
+    }
+    else {
+        series.forEach((_, i) => headers.push(`series_${i}`));
+    }
+    const rows = xValues.map((x, i) => {
+        const values = series.map((s) => String(s[i] ?? ""));
+        return [escapeCSV(x), ...values.map(escapeCSV)].join(",");
+    });
+    return [headers.join(","), ...rows].join("\n");
+}
+function escapeCSV(val) {
+    if (val.includes(",") || val.includes('"') || val.includes("\n")) {
+        return `"${val.replace(/"/g, '""')}"`;
+    }
+    return val;
+}
+/**
+ * Print to stdout. Commands use this for consistent output.
+ */
+export function output(data, format = "json") {
+    console.log(formatOutput(data, format));
+}
+//# sourceMappingURL=format.js.map

package/dist/utils/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"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"}

package/dist/utils/mcp-helpers.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared MCP response helpers.
+ */
+import type { McpToolResult } from "../mcp-client.js";
+/**
+ * Extract text content from MCP tool result.
+ * If the text is JSON, parse it; otherwise return the raw string.
+ */
+export declare function extractMcpText(result: McpToolResult): unknown;
+/**
+ * Try to extract an editId from MCP query_dataset result.
+ */
+export declare function extractEditId(data: unknown): string | null;

package/dist/utils/mcp-helpers.js

@@ -0,0 +1,49 @@
+/**
+ * Shared MCP response helpers.
+ */
+/**
+ * Extract text content from MCP tool result.
+ * If the text is JSON, parse it; otherwise return the raw string.
+ */
+export function extractMcpText(result) {
+    const texts = result.content
+        .filter((c) => c.type === "text" && c.text)
+        .map((c) => c.text);
+    if (texts.length === 0)
+        return result;
+    if (texts.length === 1) {
+        try {
+            return JSON.parse(texts[0]);
+        }
+        catch {
+            return texts[0];
+        }
+    }
+    return texts;
+}
+/**
+ * Try to extract an editId from MCP query_dataset result.
+ */
+export function extractEditId(data) {
+    if (typeof data === "string") {
+        const match = data.match(/editId["\s:]+["']?([a-zA-Z0-9_-]+)/);
+        return match?.[1] || null;
+    }
+    if (typeof data === "object" && data !== null) {
+        const obj = data;
+        if (typeof obj.editId === "string")
+            return obj.editId;
+        if (typeof obj.edit_id === "string")
+            return obj.edit_id;
+        for (const key of Object.keys(obj)) {
+            const val = obj[key];
+            if (typeof val === "object" && val !== null) {
+                const found = extractEditId(val);
+                if (found)
+                    return found;
+            }
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=mcp-helpers.js.map

package/dist/utils/mcp-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-helpers.js","sourceRoot":"","sources":["../../src/utils/mcp-helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,MAAqB;IAClD,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO;SACzB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC;SAC1C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAK,CAAC,CAAC;IAEvB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC;IACtC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;QAC/D,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IAC5B,CAAC;IACD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,MAAM,GAAG,GAAG,IAA+B,CAAC;QAC5C,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ;YAAE,OAAO,GAAG,CAAC,MAAM,CAAC;QACtD,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;YAAE,OAAO,GAAG,CAAC,OAAO,CAAC;QACxD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;YACrB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;gBAC5C,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;gBACjC,IAAI,KAAK;oBAAE,OAAO,KAAK,CAAC;YAC1B,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/utils/oauth.d.ts

@@ -0,0 +1,62 @@
+/**
+ * OAuth 2.0 utilities for Amplitude MCP server.
+ * Handles:
+ *   - Dynamic client registration
+ *   - Authorization code flow with PKCE (S256)
+ *   - Token storage and refresh
+ *   - Local callback server
+ */
+export interface OAuthTokens {
+    access_token: string;
+    refresh_token?: string;
+    token_type: string;
+    expires_in?: number;
+    expires_at?: number;
+    scope?: string;
+}
+export interface OAuthConfig {
+    client_id: string;
+    region: string;
+    tokens: OAuthTokens;
+}
+/**
+ * Read the full config file (may contain apiKey/secretKey AND/OR oauth).
+ */
+export declare function readConfig(): Record<string, unknown>;
+/**
+ * Write config, preserving existing fields.
+ */
+export declare function writeConfig(updates: Record<string, unknown>): void;
+/**
+ * Get stored OAuth tokens if they exist.
+ */
+export declare function getOAuthConfig(): OAuthConfig | null;
+/**
+ * Check if an OAuth token is available from any source.
+ * Does NOT throw — returns true/false.
+ */
+export declare function hasOAuthToken(): boolean;
+/**
+ * Get a valid access token. Checks sources in order:
+ *   1. AMPLITUDE_ACCESS_TOKEN (or AMPLITUDE_OAUTH_TOKEN) env var (injected by OpenClaw/Masterclaw via Nango)
+ *   2. AMPLITUDE_OAUTH_REFRESH_TOKEN env var (for auto-refresh via env)
+ *   3. ~/.amplituderc oauth config (from `amp auth login`)
+ *
+ * Env vars take priority — this is the managed-environment path where
+ * Masterclaw handles OAuth via Nango and injects tokens through
+ * openclaw.json → skills.entries.amplitude.env.
+ */
+export declare function getAccessToken(region?: string): Promise<string>;
+/**
+ * Get MCP base URL for region.
+ */
+export declare function getMcpBaseUrl(region?: string): string;
+/**
+ * Run the full OAuth login flow.
+ * Returns the stored OAuth config.
+ */
+export declare function login(region?: string): Promise<OAuthConfig>;
+/**
+ * Revoke tokens and clear OAuth config.
+ */
+export declare function logout(): Promise<void>;