@listo-ai/mcp-observability 0.2.0

package/dist/easy-setup.js

@@ -0,0 +1,75 @@
+import { createMcpObservability, InMemorySink, createConsoleSink, } from './index.js';
+import { createRemoteSink } from './remote-sink.js';
+import { TELEMETRY_SINK_KEY, OBSERVABILITY_KEY, setGlobal, } from './endpoints.js';
+/**
+ * Create an observability instance with environment-based defaults.
+ *
+ * This is the easiest way to get started with Listo Insights.
+ * It automatically:
+ * - Configures RemoteSink if INSIGHTS_API_KEY is provided
+ * - Configures InMemorySink + local dashboard in development
+ * - Applies sensible defaults (sampling, redaction, etc.)
+ * - Auto-detects tenant/user from common headers
+ *
+ * @example
+ * ```typescript
+ * const observability = createMcpObservabilityEasy({
+ *   serviceName: "my-mcp-server",
+ *   serviceVersion: "1.0.0",
+ * });
+ * ```
+ *
+ * Environment variables used:
+ * - INSIGHTS_API_URL: Insights API endpoint (default: https://api.listoai.co)
+ * - INSIGHTS_API_KEY: API key for authentication (generated in dashboard)
+ * - NODE_ENV: Determines if dev/production mode
+ */
+export function createMcpObservabilityEasy(config) {
+    const { serviceName, serviceVersion = '1.0.0', environment = process.env.NODE_ENV === 'production' ? 'production' : 'dev', insightsApiUrl = process.env.INSIGHTS_API_URL, insightsApiKey = process.env.INSIGHTS_API_KEY, enableLocalDashboard = environment === 'dev', sampleRate = environment === 'production' ? 0.1 : 1.0, } = config;
+    const sinks = [];
+    // Console logging in dev only
+    if (environment === 'dev') {
+        sinks.push(createConsoleSink({ logSuccess: false }));
+    }
+    // Local in-memory dashboard for development
+    if (enableLocalDashboard) {
+        const telemetrySink = new InMemorySink({ limit: 2000 });
+        sinks.push(telemetrySink);
+        // Export globally for telemetry endpoints to access
+        setGlobal(TELEMETRY_SINK_KEY, telemetrySink);
+    }
+    // Remote Listo Insights sink
+    if (insightsApiUrl && insightsApiKey) {
+        sinks.push(createRemoteSink({
+            endpoint: `${insightsApiUrl}/v1/events/batch`,
+            apiKey: insightsApiKey,
+            batchSize: 50,
+            flushIntervalMs: 5000,
+            maxRetries: 3,
+        }));
+    }
+    else if (environment !== 'dev') {
+        console.warn('[Listo Insights] No API key configured. ' +
+            'Set INSIGHTS_API_KEY environment variable to enable remote telemetry. ' +
+            'Generate a key at: https://app.listoai.co/settings');
+    }
+    // Create the observability instance
+    const options = {
+        serviceName,
+        serviceVersion,
+        environment,
+        sampleRate,
+        capturePayloads: true,
+        redactKeys: ['password', 'token', 'apiKey', 'secret', 'authorization'],
+        sinks: sinks.length > 0 ? sinks : [createConsoleSink({ logSuccess: false })],
+        // Auto-detect tenant from common headers
+        tenantResolver: (req) => req.headers['x-tenant-id'] ||
+            req.headers['x-tenant-slug'] ||
+            undefined,
+    };
+    const observability = createMcpObservability(options);
+    // Export globally for telemetry router's POST /event endpoint
+    setGlobal(OBSERVABILITY_KEY, observability);
+    return observability;
+}
+//# sourceMappingURL=easy-setup.js.map

package/dist/endpoints.d.ts

@@ -0,0 +1,34 @@
+import type { Request, Response, NextFunction } from 'express';
+import type { McpObservability } from './index.js';
+declare const TELEMETRY_SINK_KEY: unique symbol;
+declare const OBSERVABILITY_KEY: unique symbol;
+declare function setGlobal<T>(key: symbol, value: T): void;
+/**
+ * Express middleware for automatic HTTP request tracking
+ *
+ * @example
+ * ```typescript
+ * import { expressTelemetry } from '@listo-ai/mcp-observability';
+ *
+ * app.use(expressTelemetry(observability));
+ * ```
+ */
+export declare function expressTelemetry(observability: McpObservability): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+/**
+ * Express router for telemetry endpoints
+ *
+ * Provides:
+ * - GET /telemetry - JSON metrics
+ * - GET /telemetry/dashboard - HTML dashboard
+ * - POST /telemetry/event - UI event ingestion
+ *
+ * @example
+ * ```typescript
+ * import { createTelemetryRouter } from '@listo-ai/mcp-observability';
+ *
+ * app.use('/telemetry', createTelemetryRouter());
+ * ```
+ */
+export declare function createTelemetryRouter(): any;
+export { TELEMETRY_SINK_KEY, OBSERVABILITY_KEY, setGlobal };
+//# sourceMappingURL=endpoints.d.ts.map

package/dist/endpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoints.d.ts","sourceRoot":"","sources":["../src/endpoints.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,YAAY,CAAC;AAEjE,QAAA,MAAM,kBAAkB,eAAoC,CAAC;AAC7D,QAAA,MAAM,iBAAiB,eAAoC,CAAC;AAe5D,iBAAS,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAEjD;AA4BD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,gBAAgB,IAChD,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,mBAW9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,QAqQpC;AAED,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,SAAS,EAAE,CAAC"}

package/dist/endpoints.js

@@ -0,0 +1,307 @@
+const TELEMETRY_SINK_KEY = Symbol.for('listo.telemetrySink');
+const OBSERVABILITY_KEY = Symbol.for('listo.observability');
+function escapeHtml(str) {
+    return str
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+function getGlobal(key) {
+    return globalThis[key];
+}
+function setGlobal(key, value) {
+    globalThis[key] = value;
+}
+const UI_EVENT_FIELDS = new Set([
+    'name',
+    'action',
+    'widgetId',
+    'toolName',
+    'sessionId',
+    'tenantId',
+    'locale',
+    'properties',
+]);
+const MAX_EVENT_BODY_SIZE = 8192;
+function validateUiEventBody(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return null;
+    const raw = body;
+    if (typeof raw.name !== 'string' || raw.name.length === 0)
+        return null;
+    const cleaned = {};
+    for (const key of UI_EVENT_FIELDS) {
+        if (key in raw) {
+            cleaned[key] = raw[key];
+        }
+    }
+    return cleaned;
+}
+/**
+ * Express middleware for automatic HTTP request tracking
+ *
+ * @example
+ * ```typescript
+ * import { expressTelemetry } from '@listo-ai/mcp-observability';
+ *
+ * app.use(expressTelemetry(observability));
+ * ```
+ */
+export function expressTelemetry(observability) {
+    return async (req, res, next) => {
+        const route = req.route?.path || req.path;
+        try {
+            await observability.trackHttpRequest(req, res, async (tracking) => {
+                tracking.setRoute(route);
+                next();
+            });
+        }
+        catch (error) {
+            next(error);
+        }
+    };
+}
+/**
+ * Express router for telemetry endpoints
+ *
+ * Provides:
+ * - GET /telemetry - JSON metrics
+ * - GET /telemetry/dashboard - HTML dashboard
+ * - POST /telemetry/event - UI event ingestion
+ *
+ * @example
+ * ```typescript
+ * import { createTelemetryRouter } from '@listo-ai/mcp-observability';
+ *
+ * app.use('/telemetry', createTelemetryRouter());
+ * ```
+ */
+export function createTelemetryRouter() {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const express = require('express');
+    const router = express.Router();
+    const getTelemetrySink = () => {
+        return getGlobal(TELEMETRY_SINK_KEY);
+    };
+    // JSON metrics endpoint
+    router.get('/', (req, res) => {
+        const sink = getTelemetrySink();
+        if (!sink) {
+            return res.status(404).json({
+                error: 'Local telemetry not enabled',
+                hint: 'Set enableLocalDashboard: true in createMcpObservabilityEasy config',
+            });
+        }
+        res.json({
+            events: sink.getEvents(),
+            metrics: sink.getMetrics(),
+        });
+    });
+    // HTML dashboard endpoint
+    router.get('/dashboard', (req, res) => {
+        const sink = getTelemetrySink();
+        if (!sink) {
+            return res
+                .status(404)
+                .type('text/html')
+                .set('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'").send(`
+        <!DOCTYPE html>
+        <html>
+          <head>
+            <title>Listo Telemetry</title>
+            <style>
+              body { font-family: system-ui, sans-serif; padding: 20px; }
+              .error { color: #d32f2f; }
+            </style>
+          </head>
+          <body>
+            <h1>Listo Telemetry Dashboard</h1>
+            <p class="error">Local telemetry is not enabled.</p>
+            <p>To enable, set enableLocalDashboard: true in createMcpObservabilityEasy config.</p>
+          </body>
+        </html>
+      `);
+        }
+        const metrics = sink.getMetrics();
+        const html = `
+      <!DOCTYPE html>
+      <html>
+        <head>
+          <meta charset="UTF-8">
+          <meta name="viewport" content="width=device-width, initial-scale=1.0">
+          <title>Listo Telemetry Dashboard</title>
+          <style>
+            * { margin: 0; padding: 0; box-sizing: border-box; }
+            body {
+              font-family: system-ui, -apple-system, sans-serif;
+              background: #f5f5f5;
+              color: #333;
+            }
+            .container { max-width: 1200px; margin: 0 auto; padding: 20px; }
+            h1 { font-size: 28px; margin-bottom: 20px; }
+            h2 { font-size: 18px; margin-top: 30px; margin-bottom: 10px; }
+            .grid {
+              display: grid;
+              grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+              gap: 15px;
+              margin-bottom: 20px;
+            }
+            .card {
+              background: white;
+              border-radius: 8px;
+              padding: 20px;
+              box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+            }
+            .metric-value { font-size: 32px; font-weight: bold; margin-top: 10px; }
+            .metric-label { font-size: 12px; color: #666; text-transform: uppercase; }
+            table {
+              width: 100%;
+              border-collapse: collapse;
+              background: white;
+              border-radius: 8px;
+              overflow: hidden;
+            }
+            th, td { padding: 12px; text-align: left; }
+            th { background: #f5f5f5; font-weight: 600; }
+            tr:hover { background: #fafafa; }
+            .refresh { margin-bottom: 20px; }
+            button {
+              padding: 10px 15px;
+              background: #1976d2;
+              color: white;
+              border: none;
+              border-radius: 4px;
+              cursor: pointer;
+              font-size: 14px;
+            }
+            button:hover { background: #1565c0; }
+          </style>
+        </head>
+        <body>
+          <div class="container">
+            <div class="refresh">
+              <button onclick="location.reload()">⟲ Refresh</button>
+              <small style="margin-left: 10px; color: #666;">Auto-refreshes every 5 seconds</small>
+            </div>
+
+            <h1>📊 Listo Telemetry Dashboard</h1>
+
+            <div class="grid">
+              <div class="card">
+                <div class="metric-label">Total Events</div>
+                <div class="metric-value">${metrics.totals.events}</div>
+              </div>
+              <div class="card">
+                <div class="metric-label">HTTP Requests</div>
+                <div class="metric-value">${metrics.totals.http}</div>
+              </div>
+              <div class="card">
+                <div class="metric-label">MCP Requests</div>
+                <div class="metric-value">${metrics.totals.mcp}</div>
+              </div>
+              <div class="card">
+                <div class="metric-label">Sessions</div>
+                <div class="metric-value">${metrics.totals.sessions}</div>
+              </div>
+            </div>
+
+            ${metrics.http.overall.count > 0
+            ? `
+              <h2>HTTP Performance</h2>
+              <table>
+                <tr>
+                  <th>Route</th>
+                  <th>Requests</th>
+                  <th>Errors</th>
+                  <th>Avg (ms)</th>
+                  <th>P95 (ms)</th>
+                  <th>P99 (ms)</th>
+                </tr>
+                ${Object.entries(metrics.http.byRoute)
+                .map(([route, stats]) => {
+                const s = stats;
+                return `
+                  <tr>
+                    <td><code>${escapeHtml(route)}</code></td>
+                    <td>${s.count}</td>
+                    <td style="color: ${s.errors > 0 ? '#d32f2f' : '#4caf50'}">${s.errors}</td>
+                    <td>${(s.avgMs || 0).toFixed(1)}</td>
+                    <td>${(s.p95 || 0).toFixed(1)}</td>
+                    <td>${(s.p99 || 0).toFixed(1)}</td>
+                  </tr>
+                `;
+            })
+                .join('')}
+              </table>
+            `
+            : ''}
+
+            ${metrics.mcp.tools && Object.keys(metrics.mcp.tools).length > 0
+            ? `
+              <h2>MCP Tools</h2>
+              <table>
+                <tr>
+                  <th>Tool</th>
+                  <th>Calls</th>
+                  <th>Errors</th>
+                  <th>Avg (ms)</th>
+                  <th>P95 (ms)</th>
+                  <th>P99 (ms)</th>
+                </tr>
+                ${Object.entries(metrics.mcp.tools)
+                .map(([tool, stats]) => {
+                const s = stats;
+                return `
+                  <tr>
+                    <td><code>${escapeHtml(tool)}</code></td>
+                    <td>${s.count}</td>
+                    <td style="color: ${s.errors > 0 ? '#d32f2f' : '#4caf50'}">${s.errors}</td>
+                    <td>${(s.avgMs || 0).toFixed(1)}</td>
+                    <td>${(s.p95 || 0).toFixed(1)}</td>
+                    <td>${(s.p99 || 0).toFixed(1)}</td>
+                  </tr>
+                `;
+            })
+                .join('')}
+              </table>
+            `
+            : ''}
+
+            <p style="margin-top: 40px; color: #999; font-size: 12px;">
+              Last updated: ${new Date().toLocaleTimeString()} |
+              View in <a href="https://app.listoai.co" target="_blank" style="color: #1976d2;">Listo</a>
+            </p>
+          </div>
+
+          <script>
+            setTimeout(() => location.reload(), 5000);
+          </script>
+        </body>
+      </html>
+    `;
+        res
+            .type('text/html')
+            .set('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'; script-src 'unsafe-inline'")
+            .send(html);
+    });
+    // UI event ingestion endpoint
+    router.post('/event', express.json({ limit: MAX_EVENT_BODY_SIZE }), (req, res) => {
+        const validated = validateUiEventBody(req.body);
+        if (!validated) {
+            res
+                .status(400)
+                .json({ error: 'Invalid event: "name" string required' });
+            return;
+        }
+        const observability = getGlobal(OBSERVABILITY_KEY);
+        if (observability) {
+            observability.recordUiEvent(validated);
+        }
+        res.status(201).json({ ok: true });
+    });
+    return router;
+}
+export { TELEMETRY_SINK_KEY, OBSERVABILITY_KEY, setGlobal };
+//# sourceMappingURL=endpoints.js.map