mcp4openapi 0.1.0

package/dist/src/metrics.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Prometheus Metrics Collector
+ *
+ * Why: Observability for production deployments
+ *
+ * Tracks:
+ * - HTTP requests (status, method, path)
+ * - Session lifecycle (active, created, destroyed)
+ * - MCP operations (tool calls, duration, errors)
+ * - API calls to backend (operation, status, duration)
+ */
+import { Registry } from 'prom-client';
+export interface MetricsCollectorConfig {
+    enabled: boolean;
+    prefix?: string;
+}
+export declare class MetricsCollector {
+    private registry;
+    private enabled;
+    private httpRequestsTotal;
+    private httpRequestDuration;
+    private sessionsActive;
+    private sessionsCreatedTotal;
+    private sessionsDestroyedTotal;
+    private mcpToolCallsTotal;
+    private mcpToolCallDuration;
+    private mcpToolCallErrors;
+    private apiCallsTotal;
+    private apiCallDuration;
+    private apiCallErrors;
+    constructor(config: MetricsCollectorConfig);
+    /**
+     * Record HTTP request
+     */
+    recordHttpRequest(method: string, path: string, status: number, durationSeconds: number): void;
+    /**
+     * Record session created
+     */
+    recordSessionCreated(): void;
+    /**
+     * Record session destroyed
+     */
+    recordSessionDestroyed(): void;
+    /**
+     * Record MCP tool call
+     */
+    recordToolCall(tool: string, status: 'success' | 'error', durationSeconds: number): void;
+    /**
+     * Record MCP tool call error
+     */
+    recordToolCallError(tool: string, errorType: string): void;
+    /**
+     * Record API call to backend
+     */
+    recordApiCall(operation: string, status: number, durationSeconds: number): void;
+    /**
+     * Record API call error
+     */
+    recordApiCallError(operation: string, errorType: string): void;
+    /**
+     * Get metrics in Prometheus format
+     */
+    getMetrics(): Promise<string>;
+    /**
+     * Get registry (for testing)
+     */
+    getRegistry(): Registry;
+    /**
+     * Normalize path for metrics (remove dynamic segments)
+     *
+     * Why: Avoid high cardinality in metrics labels
+     *
+     * Examples:
+     * - /mcp?sessionId=abc123 -> /mcp
+     * - /metrics -> /metrics
+     * - /health -> /health
+     */
+    private normalizePath;
+    /**
+     * Get status label (2xx, 4xx, 5xx)
+     *
+     * Why: Group similar statuses to reduce cardinality
+     */
+    private getStatusLabel;
+}
+//# sourceMappingURL=metrics.d.ts.map

package/dist/src/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,EAA6B,MAAM,aAAa,CAAC;AAElE,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,OAAO,CAAU;IAGzB,OAAO,CAAC,iBAAiB,CAAU;IACnC,OAAO,CAAC,mBAAmB,CAAY;IAGvC,OAAO,CAAC,cAAc,CAAQ;IAC9B,OAAO,CAAC,oBAAoB,CAAU;IACtC,OAAO,CAAC,sBAAsB,CAAU;IAGxC,OAAO,CAAC,iBAAiB,CAAU;IACnC,OAAO,CAAC,mBAAmB,CAAY;IACvC,OAAO,CAAC,iBAAiB,CAAU;IAGnC,OAAO,CAAC,aAAa,CAAU;IAC/B,OAAO,CAAC,eAAe,CAAY;IACnC,OAAO,CAAC,aAAa,CAAU;gBAEnB,MAAM,EAAE,sBAAsB;IAwF1C;;OAEG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI;IAmB9F;;OAEG;IACH,oBAAoB,IAAI,IAAI;IAM5B;;OAEG;IACH,sBAAsB,IAAI,IAAI;IAM9B;;OAEG;IACH,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI;IAOxF;;OAEG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAK1D;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI;IAS/E;;OAEG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAK9D;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAOnC;;OAEG;IACH,WAAW,IAAI,QAAQ;IAIvB;;;;;;;;;OASG;IACH,OAAO,CAAC,aAAa;IAcrB;;;;OAIG;IACH,OAAO,CAAC,cAAc;CAOvB"}

package/dist/src/metrics.js

@@ -0,0 +1,229 @@
+/**
+ * Prometheus Metrics Collector
+ *
+ * Why: Observability for production deployments
+ *
+ * Tracks:
+ * - HTTP requests (status, method, path)
+ * - Session lifecycle (active, created, destroyed)
+ * - MCP operations (tool calls, duration, errors)
+ * - API calls to backend (operation, status, duration)
+ */
+import { Registry, Counter, Gauge, Histogram } from 'prom-client';
+export class MetricsCollector {
+    registry;
+    enabled;
+    // HTTP metrics
+    httpRequestsTotal;
+    httpRequestDuration;
+    // Session metrics
+    sessionsActive;
+    sessionsCreatedTotal;
+    sessionsDestroyedTotal;
+    // MCP operation metrics
+    mcpToolCallsTotal;
+    mcpToolCallDuration;
+    mcpToolCallErrors;
+    // API metrics (calls to backend API)
+    apiCallsTotal;
+    apiCallDuration;
+    apiCallErrors;
+    constructor(config) {
+        this.enabled = config.enabled;
+        this.registry = new Registry();
+        const prefix = config.prefix || 'mcp_';
+        // HTTP metrics
+        this.httpRequestsTotal = new Counter({
+            name: `${prefix}http_requests_total`,
+            help: 'Total number of HTTP requests',
+            labelNames: ['method', 'path', 'status'],
+            registers: [this.registry],
+        });
+        this.httpRequestDuration = new Histogram({
+            name: `${prefix}http_request_duration_seconds`,
+            help: 'HTTP request duration in seconds',
+            labelNames: ['method', 'path', 'status'],
+            buckets: [0.001, 0.01, 0.05, 0.1, 0.5, 1, 2, 5],
+            registers: [this.registry],
+        });
+        // Session metrics
+        this.sessionsActive = new Gauge({
+            name: `${prefix}sessions_active`,
+            help: 'Number of active sessions',
+            registers: [this.registry],
+        });
+        this.sessionsCreatedTotal = new Counter({
+            name: `${prefix}sessions_created_total`,
+            help: 'Total number of sessions created',
+            registers: [this.registry],
+        });
+        this.sessionsDestroyedTotal = new Counter({
+            name: `${prefix}sessions_destroyed_total`,
+            help: 'Total number of sessions destroyed',
+            registers: [this.registry],
+        });
+        // MCP operation metrics
+        this.mcpToolCallsTotal = new Counter({
+            name: `${prefix}tool_calls_total`,
+            help: 'Total number of MCP tool calls',
+            labelNames: ['tool', 'status'],
+            registers: [this.registry],
+        });
+        this.mcpToolCallDuration = new Histogram({
+            name: `${prefix}tool_call_duration_seconds`,
+            help: 'MCP tool call duration in seconds',
+            labelNames: ['tool', 'status'],
+            buckets: [0.01, 0.05, 0.1, 0.5, 1, 2, 5, 10, 30],
+            registers: [this.registry],
+        });
+        this.mcpToolCallErrors = new Counter({
+            name: `${prefix}tool_call_errors_total`,
+            help: 'Total number of MCP tool call errors',
+            labelNames: ['tool', 'error_type'],
+            registers: [this.registry],
+        });
+        // API metrics
+        this.apiCallsTotal = new Counter({
+            name: `${prefix}api_calls_total`,
+            help: 'Total number of API calls to backend',
+            labelNames: ['operation', 'status'],
+            registers: [this.registry],
+        });
+        this.apiCallDuration = new Histogram({
+            name: `${prefix}api_call_duration_seconds`,
+            help: 'API call duration in seconds',
+            labelNames: ['operation', 'status'],
+            buckets: [0.01, 0.05, 0.1, 0.5, 1, 2, 5, 10],
+            registers: [this.registry],
+        });
+        this.apiCallErrors = new Counter({
+            name: `${prefix}api_call_errors_total`,
+            help: 'Total number of API call errors',
+            labelNames: ['operation', 'error_type'],
+            registers: [this.registry],
+        });
+    }
+    /**
+     * Record HTTP request
+     */
+    recordHttpRequest(method, path, status, durationSeconds) {
+        if (!this.enabled)
+            return;
+        this.httpRequestsTotal.inc({
+            method,
+            path: this.normalizePath(path),
+            status: status.toString(),
+        });
+        this.httpRequestDuration.observe({
+            method,
+            path: this.normalizePath(path),
+            status: status.toString(),
+        }, durationSeconds);
+    }
+    /**
+     * Record session created
+     */
+    recordSessionCreated() {
+        if (!this.enabled)
+            return;
+        this.sessionsCreatedTotal.inc();
+        this.sessionsActive.inc();
+    }
+    /**
+     * Record session destroyed
+     */
+    recordSessionDestroyed() {
+        if (!this.enabled)
+            return;
+        this.sessionsDestroyedTotal.inc();
+        this.sessionsActive.dec();
+    }
+    /**
+     * Record MCP tool call
+     */
+    recordToolCall(tool, status, durationSeconds) {
+        if (!this.enabled)
+            return;
+        this.mcpToolCallsTotal.inc({ tool, status });
+        this.mcpToolCallDuration.observe({ tool, status }, durationSeconds);
+    }
+    /**
+     * Record MCP tool call error
+     */
+    recordToolCallError(tool, errorType) {
+        if (!this.enabled)
+            return;
+        this.mcpToolCallErrors.inc({ tool, error_type: errorType });
+    }
+    /**
+     * Record API call to backend
+     */
+    recordApiCall(operation, status, durationSeconds) {
+        if (!this.enabled)
+            return;
+        const statusLabel = this.getStatusLabel(status);
+        this.apiCallsTotal.inc({ operation, status: statusLabel });
+        this.apiCallDuration.observe({ operation, status: statusLabel }, durationSeconds);
+    }
+    /**
+     * Record API call error
+     */
+    recordApiCallError(operation, errorType) {
+        if (!this.enabled)
+            return;
+        this.apiCallErrors.inc({ operation, error_type: errorType });
+    }
+    /**
+     * Get metrics in Prometheus format
+     */
+    async getMetrics() {
+        if (!this.enabled) {
+            return '# Metrics disabled\n';
+        }
+        return this.registry.metrics();
+    }
+    /**
+     * Get registry (for testing)
+     */
+    getRegistry() {
+        return this.registry;
+    }
+    /**
+     * Normalize path for metrics (remove dynamic segments)
+     *
+     * Why: Avoid high cardinality in metrics labels
+     *
+     * Examples:
+     * - /mcp?sessionId=abc123 -> /mcp
+     * - /metrics -> /metrics
+     * - /health -> /health
+     */
+    normalizePath(path) {
+        // Remove query string
+        const pathWithoutQuery = path.split('?')[0];
+        // Known paths
+        if (pathWithoutQuery === '/mcp' ||
+            pathWithoutQuery === '/metrics' ||
+            pathWithoutQuery === '/health') {
+            return pathWithoutQuery;
+        }
+        return pathWithoutQuery;
+    }
+    /**
+     * Get status label (2xx, 4xx, 5xx)
+     *
+     * Why: Group similar statuses to reduce cardinality
+     */
+    getStatusLabel(status) {
+        if (status >= 200 && status < 300)
+            return '2xx';
+        if (status >= 300 && status < 400)
+            return '3xx';
+        if (status >= 400 && status < 500)
+            return '4xx';
+        if (status >= 500 && status < 600)
+            return '5xx';
+        return 'unknown';
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/src/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAOlE,MAAM,OAAO,gBAAgB;IACnB,QAAQ,CAAW;IACnB,OAAO,CAAU;IAEzB,eAAe;IACP,iBAAiB,CAAU;IAC3B,mBAAmB,CAAY;IAEvC,kBAAkB;IACV,cAAc,CAAQ;IACtB,oBAAoB,CAAU;IAC9B,sBAAsB,CAAU;IAExC,wBAAwB;IAChB,iBAAiB,CAAU;IAC3B,mBAAmB,CAAY;IAC/B,iBAAiB,CAAU;IAEnC,qCAAqC;IAC7B,aAAa,CAAU;IACvB,eAAe,CAAY;IAC3B,aAAa,CAAU;IAE/B,YAAY,MAA8B;QACxC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,IAAI,QAAQ,EAAE,CAAC;QAE/B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC;QAEvC,eAAe;QACf,IAAI,CAAC,iBAAiB,GAAG,IAAI,OAAO,CAAC;YACnC,IAAI,EAAE,GAAG,MAAM,qBAAqB;YACpC,IAAI,EAAE,+BAA+B;YACrC,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;YACxC,SAAS,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC;SAC3B,CAAC,CAAC;QAEH,IAAI,CAAC,mBAAmB,GAAG,IAAI,SAAS,CAAC;YACvC,IAAI,EAAE,GAAG,MAAM,+BAA+B;YAC9C,IAAI,EAAE,kCAAkC;YACxC,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;YACxC,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YAC/C,SAAS,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC;SAC3B,CAAC,CAAC;QAEH,kBAAkB;QAClB,IAAI,CAAC,cAAc,GAAG,IAAI,KAAK,CAAC;YAC9B,IAAI,EAAE,GAAG,MAAM,iBAAiB;YAChC,IAAI,EAAE,2BAA2B;YACjC,SAAS,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC;SAC3B,CAAC,CAAC;QAEH,IAAI,CAAC,oBAAoB,GAAG,IAAI,OAAO,CAAC;YACtC,IAAI,EAAE,GAAG,MAAM,wBAAwB;YACvC,IAAI,EAAE,kCAAkC;YACxC,SAAS,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC;SAC3B,CAAC,CAAC;QAEH,IAAI,CAAC,sBAAsB,GAAG,IAAI,OAAO,CAAC;YACxC,IAAI,EAAE,GAAG,MAAM,0BAA0B;YACzC,IAAI,EAAE,oCAAoC;YAC1C,SAAS,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC;SAC3B,CAAC,CAAC;QAEH,wBAAwB;QACxB,IAAI,CAAC,iBAAiB,GAAG,IAAI,OAAO,CAAC;YACnC,IAAI,EAAE,GAAG,MAAM,kBAAkB;YACjC,IAAI,EAAE,gCAAgC;YACtC,UAAU,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC;YAC9B,SAAS,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC;SAC3B,CAAC,CAAC;QAEH,IAAI,CAAC,mBAAmB,GAAG,IAAI,SAAS,CAAC;YACvC,IAAI,EAAE,GAAG,MAAM,4BAA4B;YAC3C,IAAI,EAAE,mCAAmC;YACzC,UAAU,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC;YAC9B,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC;YAChD,SAAS,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC;SAC3B,CAAC,CAAC;QAEH,IAAI,CAAC,iBAAiB,GAAG,IAAI,OAAO,CAAC;YACnC,IAAI,EAAE,GAAG,MAAM,wBAAwB;YACvC,IAAI,EAAE,sCAAsC;YAC5C,UAAU,EAAE,CAAC,MAAM,EAAE,YAAY,CAAC;YAClC,SAAS,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC;SAC3B,CAAC,CAAC;QAEH,cAAc;QACd,IAAI,CAAC,aAAa,GAAG,IAAI,OAAO,CAAC;YAC/B,IAAI,EAAE,GAAG,MAAM,iBAAiB;YAChC,IAAI,EAAE,sCAAsC;YAC5C,UAAU,EAAE,CAAC,WAAW,EAAE,QAAQ,CAAC;YACnC,SAAS,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC;SAC3B,CAAC,CAAC;QAEH,IAAI,CAAC,eAAe,GAAG,IAAI,SAAS,CAAC;YACnC,IAAI,EAAE,GAAG,MAAM,2BAA2B;YAC1C,IAAI,EAAE,8BAA8B;YACpC,UAAU,EAAE,CAAC,WAAW,EAAE,QAAQ,CAAC;YACnC,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC5C,SAAS,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC;SAC3B,CAAC,CAAC;QAEH,IAAI,CAAC,aAAa,GAAG,IAAI,OAAO,CAAC;YAC/B,IAAI,EAAE,GAAG,MAAM,uBAAuB;YACtC,IAAI,EAAE,iCAAiC;YACvC,UAAU,EAAE,CAAC,WAAW,EAAE,YAAY,CAAC;YACvC,SAAS,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC;SAC3B,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,iBAAiB,CAAC,MAAc,EAAE,IAAY,EAAE,MAAc,EAAE,eAAuB;QACrF,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAE1B,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC;YACzB,MAAM;YACN,IAAI,EAAE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;YAC9B,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE;SAC1B,CAAC,CAAC;QAEH,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAC9B;YACE,MAAM;YACN,IAAI,EAAE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;YAC9B,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE;SAC1B,EACD,eAAe,CAChB,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,oBAAoB;QAClB,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,IAAI,CAAC,oBAAoB,CAAC,GAAG,EAAE,CAAC;QAChC,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,sBAAsB;QACpB,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,IAAI,CAAC,sBAAsB,CAAC,GAAG,EAAE,CAAC;QAClC,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,IAAY,EAAE,MAA2B,EAAE,eAAuB;QAC/E,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAE1B,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QAC7C,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,eAAe,CAAC,CAAC;IACtE,CAAC;IAED;;OAEG;IACH,mBAAmB,CAAC,IAAY,EAAE,SAAiB;QACjD,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,SAAiB,EAAE,MAAc,EAAE,eAAuB;QACtE,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAE1B,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QAEhD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;QAC3D,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,eAAe,CAAC,CAAC;IACpF,CAAC;IAED;;OAEG;IACH,kBAAkB,CAAC,SAAiB,EAAE,SAAiB;QACrD,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU;QACd,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,OAAO,sBAAsB,CAAC;QAChC,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;;;;;;OASG;IACK,aAAa,CAAC,IAAY;QAChC,sBAAsB;QACtB,MAAM,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAE5C,cAAc;QACd,IAAI,gBAAgB,KAAK,MAAM;YAC3B,gBAAgB,KAAK,UAAU;YAC/B,gBAAgB,KAAK,SAAS,EAAE,CAAC;YACnC,OAAO,gBAAgB,CAAC;QAC1B,CAAC;QAED,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IAED;;;;OAIG;IACK,cAAc,CAAC,MAAc;QACnC,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;YAAE,OAAO,KAAK,CAAC;QAChD,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;YAAE,OAAO,KAAK,CAAC;QAChD,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;YAAE,OAAO,KAAK,CAAC;QAChD,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;YAAE,OAAO,KAAK,CAAC;QAChD,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}

package/dist/src/naming-warnings.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Tool name length warning and recommendations
+ *
+ * Why: Help users understand name length issues and choose appropriate strategy
+ */
+import type { Logger } from './logger.js';
+import { type OperationForNaming } from './naming.js';
+export interface NameWarningOptions {
+    maxLength: number;
+    similarTopN: number;
+    similarityThreshold: number;
+    minParts?: number;
+    minLength?: number;
+}
+/**
+ * Collect operations that exceed name length limit
+ */
+export declare function collectOffenders(operations: OperationForNaming[], maxLength: number): OperationForNaming[];
+/**
+ * Generate warnings and suggestions for long tool names
+ */
+export declare function generateNameWarnings(operations: OperationForNaming[], options: NameWarningOptions, logger: Logger): void;
+//# sourceMappingURL=naming-warnings.d.ts.map

package/dist/src/naming-warnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming-warnings.d.ts","sourceRoot":"","sources":["../../src/naming-warnings.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAKL,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,kBAAkB,EAAE,EAChC,SAAS,EAAE,MAAM,GAChB,kBAAkB,EAAE,CAEtB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,kBAAkB,EAAE,EAChC,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,MAAM,GACb,IAAI,CAiFN"}

package/dist/src/naming-warnings.js

@@ -0,0 +1,83 @@
+/**
+ * Tool name length warning and recommendations
+ *
+ * Why: Help users understand name length issues and choose appropriate strategy
+ */
+import { shortenToolName, pickMostSimilarPairs, detectCollisions, NamingStrategy } from './naming.js';
+/**
+ * Collect operations that exceed name length limit
+ */
+export function collectOffenders(operations, maxLength) {
+    return operations.filter(op => op.operationId.length > maxLength);
+}
+/**
+ * Generate warnings and suggestions for long tool names
+ */
+export function generateNameWarnings(operations, options, logger) {
+    const { maxLength, similarTopN, similarityThreshold } = options;
+    const offenders = collectOffenders(operations, maxLength);
+    if (offenders.length === 0) {
+        return; // No warnings needed
+    }
+    logger.warn(`\n${'='.repeat(80)}`);
+    logger.warn(`⚠️  Tool Name Length Warning`);
+    logger.warn(`${'='.repeat(80)}\n`);
+    logger.warn(`Detected ${offenders.length} tool names exceeding ${maxLength} characters.`);
+    logger.warn(`Long names may be truncated or cause issues in some MCP clients.\n`);
+    // Pick most similar pairs to show as examples
+    const similarPairs = pickMostSimilarPairs(offenders, similarTopN, similarityThreshold);
+    if (similarPairs.length > 0) {
+        logger.warn(`Showing ${similarPairs.length} most similar name pairs with shortening suggestions:\n`);
+        for (let i = 0; i < similarPairs.length; i++) {
+            const pair = similarPairs[i];
+            logger.warn(`${'-'.repeat(80)}`);
+            logger.warn(`Example ${i + 1}/${similarPairs.length}:`);
+            logger.warn(`  Operation A: ${pair.opA.operationId} (${pair.opA.operationId.length} chars)`);
+            logger.warn(`  Operation B: ${pair.opB.operationId} (${pair.opB.operationId.length} chars)`);
+            logger.warn(`  Similarity: ${(pair.similarity * 100).toFixed(1)}%\n`);
+            // Show all strategies
+            const strategies = [NamingStrategy.Balanced, NamingStrategy.Iterative, NamingStrategy.Hash];
+            for (const strategy of strategies) {
+                const resultA = shortenToolName(pair.opA, strategy, maxLength, operations, {
+                    minParts: options.minParts,
+                    minLength: options.minLength,
+                });
+                const resultB = shortenToolName(pair.opB, strategy, maxLength, operations, {
+                    minParts: options.minParts,
+                    minLength: options.minLength,
+                });
+                const collision = resultA.name === resultB.name ? '⚠️  COLLISION' : '✓ No collision';
+                logger.warn(`  Strategy: ${strategy}`);
+                logger.warn(`    A: ${resultA.name} (${resultA.name.length} chars)`);
+                logger.warn(`    B: ${resultB.name} (${resultB.name.length} chars)`);
+                logger.warn(`    ${collision}\n`);
+            }
+        }
+    }
+    // Show collision statistics for each strategy
+    logger.warn(`${'-'.repeat(80)}`);
+    logger.warn(`Collision Analysis:\n`);
+    const strategies = [NamingStrategy.Balanced, NamingStrategy.Iterative, NamingStrategy.Hash];
+    for (const strategy of strategies) {
+        const collisions = detectCollisions(offenders, strategy, maxLength, {
+            minParts: options.minParts,
+            minLength: options.minLength,
+        });
+        const collisionCount = Array.from(collisions.values()).reduce((sum, ops) => sum + ops.length - 1, 0);
+        logger.warn(`  ${strategy}: ${collisionCount} collision(s) among ${offenders.length} names`);
+    }
+    logger.warn(`\n${'-'.repeat(80)}`);
+    logger.warn(`How to Fix:\n`);
+    logger.warn(`  1. Choose a shortening strategy based on collision analysis above`);
+    logger.warn(`  2. Set environment variables:\n`);
+    logger.warn(`     export MCP_TOOLNAME_STRATEGY=balanced      # or: iterative, hash, auto`);
+    logger.warn(`     export MCP_TOOLNAME_WARN_ONLY=false       # Apply shortening`);
+    logger.warn(`     export MCP_TOOLNAME_MAX=45                # Optional: adjust limit`);
+    logger.warn(`     export MCP_TOOLNAME_MIN_PARTS=3           # Optional: min parts (for balanced)`);
+    logger.warn(`     export MCP_TOOLNAME_MIN_LENGTH=20         # Optional: min length (for balanced)\n`);
+    logger.warn(`  Example for balanced strategy:`);
+    logger.warn(`     export MCP_TOOLNAME_STRATEGY=balanced MCP_TOOLNAME_WARN_ONLY=false\n`);
+    logger.warn(`${'-'.repeat(80)}`);
+    logger.warn(`Summary: ${offenders.length} names need shortening. Choose strategy and restart.\n`);
+}
+//# sourceMappingURL=naming-warnings.js.map

package/dist/src/naming-warnings.js.map

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

package/dist/src/naming.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Tool name shortening strategies
+ *
+ * Why: MCP tool names combined with server name must stay under limits.
+ * Different strategies offer trade-offs between readability and compactness.
+ */
+export declare enum NamingStrategy {
+    None = "none",
+    Balanced = "balanced",
+    Iterative = "iterative",
+    Hash = "hash",
+    Auto = "auto"
+}
+export interface OperationForNaming {
+    operationId: string;
+    method: string;
+    path: string;
+    tags?: string[];
+}
+export interface ShortenResult {
+    name: string;
+    truncated: boolean;
+    strategy: NamingStrategy;
+    originalLength: number;
+    partsUsed?: number;
+}
+export interface SimilarPair {
+    opA: OperationForNaming;
+    opB: OperationForNaming;
+    similarity: number;
+}
+export interface ShorteningOptions {
+    maxLength: number;
+    minParts?: number;
+    minLength?: number;
+    allOperations?: OperationForNaming[];
+}
+/**
+ * Shorten tool name using specified strategy
+ */
+export declare function shortenToolName(op: OperationForNaming, strategy: NamingStrategy, maxLength: number, allOperations?: OperationForNaming[], options?: Partial<ShorteningOptions>): ShortenResult;
+/**
+ * Generate stable short hash from string
+ */
+export declare function stableHash(str: string, length?: number): string;
+/**
+ * Calculate Levenshtein distance between two strings
+ */
+export declare function levenshteinDistance(a: string, b: string): number;
+/**
+ * Pick most similar pairs of operations
+ */
+export declare function pickMostSimilarPairs(operations: OperationForNaming[], topN: number, threshold?: number): SimilarPair[];
+/**
+ * Detect potential collisions when shortening multiple operations
+ */
+export declare function detectCollisions(operations: OperationForNaming[], strategy: NamingStrategy, maxLength: number, options?: Partial<ShorteningOptions>): Map<string, OperationForNaming[]>;
+//# sourceMappingURL=naming.d.ts.map

package/dist/src/naming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../../src/naming.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,oBAAY,cAAc;IACxB,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,SAAS,cAAc;IACvB,IAAI,SAAS;IACb,IAAI,SAAS;CACd;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,cAAc,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,kBAAkB,CAAC;IACxB,GAAG,EAAE,kBAAkB,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,kBAAkB,EAAE,CAAC;CACtC;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,kBAAkB,EACtB,QAAQ,EAAE,cAAc,EACxB,SAAS,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE,kBAAkB,EAAE,EACpC,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GACnC,aAAa,CAoDf;AAiYD;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAU,GAAG,MAAM,CAUlE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAoBhE;AAaD;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,kBAAkB,EAAE,EAChC,IAAI,EAAE,MAAM,EACZ,SAAS,GAAE,MAAa,GACvB,WAAW,EAAE,CA4Df;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,kBAAkB,EAAE,EAChC,QAAQ,EAAE,cAAc,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,GACnC,GAAG,CAAC,MAAM,EAAE,kBAAkB,EAAE,CAAC,CAmBnC"}