vikunja-mcp-ng 0.4.0

package/dist/utils/performance/performance-monitor.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * Performance monitoring and metrics collection for bulk operations
+ * Tracks throughput, latency, and efficiency metrics
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordPerformanceMetrics = exports.monitorBulkOperation = exports.performanceMonitor = exports.PerformanceMonitor = void 0;
+const logger_1 = require("../logger");
+class PerformanceMonitor {
+    operations = [];
+    alerts = [];
+    activeOperations = new Map();
+    // Configurable thresholds
+    thresholds = {
+        highLatencyMs: 5000, // 5 seconds
+        lowThroughputItemsPerSec: 2, // 2 items per second
+        highFailureRatePercent: 20, // 20% failure rate
+        lowCacheHitRatePercent: 30, // 30% cache hit rate
+    };
+    /**
+     * Start monitoring an operation
+     */
+    startOperation(operationId, operationType, itemCount, concurrencyLevel = 1, metadata) {
+        const metrics = {
+            operationType,
+            startTime: Date.now(),
+            itemCount,
+            successCount: 0,
+            failureCount: 0,
+            apiCallCount: 0,
+            cacheHits: 0,
+            cacheMisses: 0,
+            concurrencyLevel,
+            metadata: metadata || {},
+        };
+        this.activeOperations.set(operationId, metrics);
+        logger_1.logger.debug('Performance monitoring started', {
+            operationId,
+            operationType,
+            itemCount,
+            concurrencyLevel,
+        });
+    }
+    /**
+     * Update operation progress
+     */
+    updateOperation(operationId, updates) {
+        const operation = this.activeOperations.get(operationId);
+        if (!operation) {
+            logger_1.logger.warn('Attempted to update unknown operation', { operationId });
+            return;
+        }
+        // Type-safe assignment with validation
+        if (updates.successCount !== undefined)
+            operation.successCount = updates.successCount;
+        if (updates.failureCount !== undefined)
+            operation.failureCount = updates.failureCount;
+        if (updates.apiCallCount !== undefined)
+            operation.apiCallCount = updates.apiCallCount;
+        if (updates.cacheHits !== undefined)
+            operation.cacheHits = updates.cacheHits;
+        if (updates.cacheMisses !== undefined)
+            operation.cacheMisses = updates.cacheMisses;
+    }
+    /**
+     * Increment API call count for an operation
+     */
+    recordApiCall(operationId, count = 1) {
+        const operation = this.activeOperations.get(operationId);
+        if (operation) {
+            operation.apiCallCount += count;
+        }
+    }
+    /**
+     * Record cache hit for an operation
+     */
+    recordCacheHit(operationId, count = 1) {
+        const operation = this.activeOperations.get(operationId);
+        if (operation) {
+            operation.cacheHits += count;
+        }
+    }
+    /**
+     * Record cache miss for an operation
+     */
+    recordCacheMiss(operationId, count = 1) {
+        const operation = this.activeOperations.get(operationId);
+        if (operation) {
+            operation.cacheMisses += count;
+        }
+    }
+    /**
+     * Complete operation monitoring and analyze performance
+     */
+    completeOperation(operationId) {
+        const operation = this.activeOperations.get(operationId);
+        if (!operation) {
+            logger_1.logger.warn('Attempted to complete unknown operation', { operationId });
+            return undefined;
+        }
+        operation.endTime = Date.now();
+        operation.duration = operation.endTime - operation.startTime;
+        // Move to completed operations
+        this.operations.push(operation);
+        this.activeOperations.delete(operationId);
+        // Analyze performance and generate alerts if needed
+        this.analyzePerformance(operation);
+        // Keep only last 1000 operations to prevent memory growth
+        if (this.operations.length > 1000) {
+            this.operations = this.operations.slice(-1000);
+        }
+        logger_1.logger.debug('Performance monitoring completed', {
+            operationId,
+            operationType: operation.operationType,
+            duration: operation.duration,
+            itemCount: operation.itemCount,
+            apiCalls: operation.apiCallCount,
+            successRate: operation.itemCount > 0 ? (operation.successCount / operation.itemCount) * 100 : 0,
+        });
+        return operation;
+    }
+    /**
+     * Get comprehensive performance statistics
+     */
+    getStats() {
+        const totalOperations = this.operations.length;
+        if (totalOperations === 0) {
+            return this.getEmptyStats();
+        }
+        const totals = this.operations.reduce((acc, op) => ({
+            duration: acc.duration + (op.duration || 0),
+            items: acc.items + op.itemCount,
+            apiCalls: acc.apiCalls + op.apiCallCount,
+            cacheHits: acc.cacheHits + op.cacheHits,
+            cacheMisses: acc.cacheMisses + op.cacheMisses,
+            successes: acc.successes + op.successCount,
+            failures: acc.failures + op.failureCount,
+        }), { duration: 0, items: 0, apiCalls: 0, cacheHits: 0, cacheMisses: 0, successes: 0, failures: 0 });
+        const operationsByType = this.operations.reduce((acc, op) => {
+            acc[op.operationType] = (acc[op.operationType] || 0) + 1;
+            return acc;
+        }, {});
+        const peakConcurrency = Math.max(...this.operations.map(op => op.concurrencyLevel));
+        const last10Operations = this.operations.slice(-10);
+        const last10Duration = last10Operations.reduce((sum, op) => sum + (op.duration || 0), 0);
+        const last10Items = last10Operations.reduce((sum, op) => sum + op.itemCount, 0);
+        return {
+            totalOperations,
+            totalDuration: totals.duration,
+            totalItems: totals.items,
+            totalApiCalls: totals.apiCalls,
+            totalCacheHits: totals.cacheHits,
+            totalCacheMisses: totals.cacheMisses,
+            averageOperationDuration: totals.duration / totalOperations,
+            averageItemsPerSecond: totals.duration > 0 ? (totals.items / (totals.duration / 1000)) : 0,
+            averageApiCallsPerOperation: totals.apiCalls / totalOperations,
+            cacheHitRatio: (totals.cacheHits + totals.cacheMisses) > 0
+                ? totals.cacheHits / (totals.cacheHits + totals.cacheMisses)
+                : 0,
+            operationSuccessRate: totals.items > 0 ? (totals.successes / totals.items) : 0,
+            peakConcurrency,
+            operationsByType,
+            recentPerformance: {
+                last10Operations,
+                averageDurationLast10: last10Operations.length > 0 ? last10Duration / last10Operations.length : 0,
+                throughputLast10: last10Duration > 0 ? (last10Items / (last10Duration / 1000)) : 0,
+            },
+        };
+    }
+    /**
+     * Get recent performance alerts
+     */
+    getAlerts(maxAge) {
+        if (!maxAge) {
+            return [...this.alerts];
+        }
+        const cutoff = Date.now() - maxAge;
+        return this.alerts.filter(alert => alert.timestamp > cutoff);
+    }
+    /**
+     * Clear all alerts
+     */
+    clearAlerts() {
+        this.alerts = [];
+    }
+    /**
+     * Export performance data for analysis
+     */
+    exportData() {
+        return {
+            operations: [...this.operations],
+            alerts: [...this.alerts],
+            stats: this.getStats(),
+            exportTimestamp: Date.now(),
+        };
+    }
+    /**
+     * Reset all performance data
+     */
+    reset() {
+        this.operations = [];
+        this.alerts = [];
+        this.activeOperations.clear();
+        logger_1.logger.info('Performance monitor reset');
+    }
+    /**
+     * Analyze operation performance and generate alerts
+     */
+    analyzePerformance(operation) {
+        if (!operation.duration)
+            return;
+        // Check for high latency
+        if (operation.duration > this.thresholds.highLatencyMs) {
+            this.addAlert('high_latency', 'critical', `Operation took ${operation.duration}ms (threshold: ${this.thresholds.highLatencyMs}ms)`, operation);
+        }
+        // Check for low throughput
+        const throughput = operation.duration > 0 ? (operation.itemCount / (operation.duration / 1000)) : 0;
+        if (throughput < this.thresholds.lowThroughputItemsPerSec && operation.itemCount > 5) {
+            this.addAlert('low_throughput', 'warning', `Low throughput: ${throughput.toFixed(2)} items/sec (threshold: ${this.thresholds.lowThroughputItemsPerSec})`, operation);
+        }
+        // Check for high failure rate
+        const failureRate = operation.itemCount > 0 ? (operation.failureCount / operation.itemCount) * 100 : 0;
+        if (failureRate > this.thresholds.highFailureRatePercent && operation.itemCount > 1) {
+            this.addAlert('high_failure_rate', 'critical', `High failure rate: ${failureRate.toFixed(1)}% (threshold: ${this.thresholds.highFailureRatePercent}%)`, operation);
+        }
+        // Check for cache inefficiency
+        const totalCacheOps = operation.cacheHits + operation.cacheMisses;
+        const cacheHitRate = totalCacheOps > 0 ? (operation.cacheHits / totalCacheOps) * 100 : 100;
+        if (cacheHitRate < this.thresholds.lowCacheHitRatePercent && totalCacheOps > 5) {
+            this.addAlert('cache_inefficiency', 'warning', `Low cache hit rate: ${cacheHitRate.toFixed(1)}% (threshold: ${this.thresholds.lowCacheHitRatePercent}%)`, operation);
+        }
+    }
+    /**
+     * Add performance alert
+     */
+    addAlert(type, severity, message, operation) {
+        const alert = {
+            type,
+            severity,
+            message,
+            metrics: {
+                operationType: operation.operationType,
+                duration: operation.duration || 0,
+                itemCount: operation.itemCount,
+                apiCallCount: operation.apiCallCount,
+                cacheHits: operation.cacheHits,
+                cacheMisses: operation.cacheMisses,
+            },
+            timestamp: Date.now(),
+        };
+        this.alerts.push(alert);
+        // Keep only last 100 alerts
+        if (this.alerts.length > 100) {
+            this.alerts = this.alerts.slice(-100);
+        }
+        logger_1.logger.warn('Performance alert generated', alert);
+    }
+    /**
+     * Get empty stats structure
+     */
+    getEmptyStats() {
+        return {
+            totalOperations: 0,
+            totalDuration: 0,
+            totalItems: 0,
+            totalApiCalls: 0,
+            totalCacheHits: 0,
+            totalCacheMisses: 0,
+            averageOperationDuration: 0,
+            averageItemsPerSecond: 0,
+            averageApiCallsPerOperation: 0,
+            cacheHitRatio: 0,
+            operationSuccessRate: 0,
+            peakConcurrency: 0,
+            operationsByType: {},
+            recentPerformance: {
+                last10Operations: [],
+                averageDurationLast10: 0,
+                throughputLast10: 0,
+            },
+        };
+    }
+}
+exports.PerformanceMonitor = PerformanceMonitor;
+// Global performance monitor instance
+exports.performanceMonitor = new PerformanceMonitor();
+// Helper functions for common monitoring patterns
+const monitorBulkOperation = (operationType, itemCount, operation, concurrencyLevel) => {
+    const operationId = `${operationType}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    exports.performanceMonitor.startOperation(operationId, operationType, itemCount, concurrencyLevel);
+    return operation()
+        .then(result => {
+        exports.performanceMonitor.completeOperation(operationId);
+        return result;
+    })
+        .catch(error => {
+        exports.performanceMonitor.updateOperation(operationId, { failureCount: itemCount });
+        exports.performanceMonitor.completeOperation(operationId);
+        throw error;
+    });
+};
+exports.monitorBulkOperation = monitorBulkOperation;
+const recordPerformanceMetrics = (operationId, metrics) => {
+    exports.performanceMonitor.updateOperation(operationId, metrics);
+};
+exports.recordPerformanceMetrics = recordPerformanceMetrics;
+//# sourceMappingURL=performance-monitor.js.map

package/dist/utils/performance/performance-monitor.js.map

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

package/dist/utils/read-only.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Global Read-Only Safety Mode + MCP Tool Annotations
+ *
+ * Single source of truth for two related things, per
+ * docs/ENDPOINT-PLAYBOOK.md's "one classification table per tool" guidance:
+ *
+ *  1. **Read-only gating.** When the server's `readOnly` config flag is
+ *     active (`vikunja-mcp.config.json`'s `readOnly`, or the
+ *     `VIKUNJA_MCP_READ_ONLY` env var — env always wins, see
+ *     docs/CONFIGURATION.md), every write/destructive subcommand across
+ *     every tool is rejected at dispatch with a clear, consistent error.
+ *     Read subcommands continue to work normally. Each tool dispatcher
+ *     calls `assertWriteAllowed(toolName, subcommand)` exactly once, right
+ *     after its existing auth check — a single shared guard, not 24
+ *     copy-pasted `if (readOnly) throw` checks.
+ *
+ *  2. **MCP tool annotations.** `readOnlyHint` / `destructiveHint` /
+ *     `idempotentHint` (see the SDK's `ToolAnnotations`) are derived from
+ *     the same per-subcommand classification tables via
+ *     `getToolAnnotations(toolName)`, so the two features can never drift
+ *     out of sync with each other.
+ *
+ * Classification rubric (`SubcommandClassification`):
+ *  - 'read':        never mutates Vikunja server state. Always allowed;
+ *                    never contributes to `destructiveHint`.
+ *  - 'write':        creates or updates state (create, update, set-*,
+ *                    archive, move, duplicate, subscribe, ...). Rejected
+ *                    when `readOnly` is active.
+ *  - 'destructive':  removes/deletes a resource or relationship (delete,
+ *                    remove-*, unassign, unrelate, unsubscribe,
+ *                    bulk-delete, ...). Rejected when `readOnly` is
+ *                    active; any 'destructive' entry makes the whole tool's
+ *                    `destructiveHint` true.
+ *
+ * Annotation mapping rationale: annotations are per-TOOL, but our tools
+ * mix read/write/destructive subcommands behind one MCP tool name, so:
+ *  - `readOnlyHint` is true only for a tool whose *entire* subcommand
+ *    surface is 'read' (e.g. `vikunja_auth` — see below).
+ *  - `destructiveHint` is true if *any* subcommand is 'destructive'.
+ *  - `idempotentHint` is only ever set true via the explicit
+ *    `IDEMPOTENT_TOOLS` allowlist below, and only when every write
+ *    subcommand on that tool is genuinely idempotent — see its comment.
+ *
+ * `vikunja_auth` special case: connect/status/refresh/disconnect/info only
+ * manage the MCP server's local in-memory session — none of them mutate a
+ * Vikunja resource — so every subcommand is classified 'read' and
+ * read-only mode never blocks it (and `readOnlyHint` is honestly true).
+ */
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+export type SubcommandClassification = 'read' | 'write' | 'destructive';
+type ClassificationTable = Record<string, SubcommandClassification>;
+/** Tool name -> subcommand classification table. */
+export declare const TOOL_CLASSIFICATIONS: Record<string, ClassificationTable>;
+/**
+ * Classify a subcommand for a given tool. Unrecognized tool/subcommand
+ * pairs fail closed as 'write' (rather than 'read') so an entry missing
+ * from the table above is blocked while read-only mode is active instead
+ * of silently slipping through — a table-maintenance bug should surface as
+ * an over-eager rejection, never as a read-only bypass.
+ */
+export declare function classifySubcommand(toolName: string, subcommand: string): SubcommandClassification;
+/** True if every subcommand on this tool is classified 'read'. */
+export declare function isToolReadOnly(toolName: string): boolean;
+/** True if any subcommand on this tool is classified 'destructive'. */
+export declare function isToolDestructive(toolName: string): boolean;
+/**
+ * Derive this tool's MCP `ToolAnnotations` from its classification table —
+ * see the module doc comment for the readOnlyHint/destructiveHint/
+ * idempotentHint mapping rationale.
+ */
+export declare function getToolAnnotations(toolName: string): ToolAnnotations;
+/**
+ * Whether the server's global read-only safety mode is currently active.
+ *
+ * Fails safe the same way `resolveModulesConfig` (src/tools/index.ts) does:
+ * a broken/unreadable config file must not crash tool registration or
+ * dispatch, so a `loadConfiguration()` failure here falls back to the
+ * schema default (`readOnly: false`) rather than propagating. This mirrors
+ * module gating's fail-safe precedent, not a "fail closed on ambiguity"
+ * choice — a config-loading error is an operator misconfiguration to
+ * surface via logs, not a signal about write intent.
+ */
+export declare function isReadOnlyModeActive(): boolean;
+/**
+ * The single shared guard every tool dispatcher calls once — right after
+ * its existing auth check, before routing to a subcommand handler — instead
+ * of duplicating a read-only check per subcommand.
+ *
+ * @param toolName - the registered MCP tool name (e.g. `vikunja_tasks`).
+ * @param subcommand - the dispatch key for this call. For tools without a
+ *   `subcommand`/`operation`/`action` field (batch-import, the three export
+ *   tools), dispatchers pass the tool's single fixed key from its
+ *   classification table above (e.g. `'import'`).
+ * @param classificationOverride - for the handful of subcommands whose
+ *   classification depends on the call's arguments rather than being
+ *   static (the comment-or-list dual-purpose `comment` subcommand;
+ *   batch-import's `dryRun`), dispatchers compute and pass the effective
+ *   classification directly instead of relying on the static table lookup.
+ */
+export declare function assertWriteAllowed(toolName: string, subcommand: string, classificationOverride?: SubcommandClassification): void;
+/**
+ * Appends a short read-only note to a tool's description, but only when
+ * read-only mode is active AND the tool actually has write/destructive
+ * subcommands to warn about (a fully-exempt tool like `vikunja_auth` never
+ * gets the note — it would be noise, not information). Called once at
+ * registration time — cheap, since `isReadOnlyModeActive()` just reads the
+ * already-loaded, cached configuration.
+ */
+export declare function withReadOnlyNote(toolName: string, description: string): string;
+export {};
+//# sourceMappingURL=read-only.d.ts.map

package/dist/utils/read-only.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-only.d.ts","sourceRoot":"","sources":["../../src/utils/read-only.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAK1E,MAAM,MAAM,wBAAwB,GAAG,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;AAExE,KAAK,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;AA+TpE,oDAAoD;AACpD,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CA4BpE,CAAC;AAMF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,wBAAwB,CAEjG;AAED,kEAAkE;AAClE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMxD;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAO3D;AAeD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CASpE;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAU9C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,sBAAsB,CAAC,EAAE,wBAAwB,GAChD,IAAI,CAaN;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAQ9E"}