navidrome-mcp 1.0.1

package/dist/utils/error-formatter.js

@@ -0,0 +1,161 @@
+/**
+ * Navidrome MCP Server - Error Formatting Utility
+ * Copyright (C) 2025
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+/**
+ * Standardized error message formatting utilities
+ * Provides consistent error messages across the MCP application
+ */
+export class ErrorFormatter {
+    /**
+     * Extract message from unknown error type
+     */
+    static extractMessage(error) {
+        return error instanceof Error ? error.message : 'Unknown error';
+    }
+    // === HTTP/API ERRORS ===
+    /**
+     * Format HTTP request failures (network issues, 404, 500, etc.)
+     */
+    static httpRequest(operation, response, errorText) {
+        const base = `API request failed: ${operation} - ${response.status} ${response.statusText}`;
+        return errorText ? `${base} - ${errorText}` : base;
+    }
+    /**
+     * Format Subsonic API specific errors
+     */
+    static subsonicApi(response) {
+        return `Subsonic API request failed: ${response.status} ${response.statusText}`;
+    }
+    /**
+     * Format Subsonic API response errors (when subsonic-response.status !== 'ok')
+     */
+    static subsonicResponse(errorMessage) {
+        return `Subsonic API error: ${errorMessage || 'Unknown error'}`;
+    }
+    // === MCP TOOL ERRORS ===
+    /**
+     * Format MCP tool execution failures
+     */
+    static toolExecution(toolName, error) {
+        const message = this.extractMessage(error);
+        return `Tool '${toolName}' failed: ${message}`;
+    }
+    /**
+     * Format tool parameter validation errors
+     */
+    static toolValidation(toolName, field, issue) {
+        return `Tool '${toolName}' validation error: ${field} ${issue}`;
+    }
+    /**
+     * Format tool resource not found errors
+     */
+    static toolNotFound(resourceType, identifier) {
+        const base = `${resourceType} not found`;
+        return identifier ? `${base}: ${identifier}` : base;
+    }
+    /**
+     * Format unknown tool errors
+     */
+    static toolUnknown(toolName) {
+        return `Unknown tool: ${toolName}`;
+    }
+    /**
+     * Format not found errors
+     */
+    static notFound(resourceType, identifier) {
+        return `${resourceType} not found: ${identifier}`;
+    }
+    // === AUTHENTICATION & AUTHORIZATION ===
+    /**
+     * Format authentication failures
+     */
+    static authentication(details) {
+        const base = 'Authentication failed';
+        return details ? `${base}: ${details}` : base;
+    }
+    /**
+     * Format authorization failures
+     */
+    static authorization(operation) {
+        return `Authorization failed: insufficient permissions for ${operation}`;
+    }
+    // === EXTERNAL SERVICE ERRORS ===
+    /**
+     * Format Last.fm API errors
+     */
+    static lastfmApi(response) {
+        return `Last.fm API error: ${response.status} ${response.statusText}`;
+    }
+    /**
+     * Format Last.fm API response errors
+     */
+    static lastfmResponse(message) {
+        return `Last.fm API error: ${message || 'Unknown error'}`;
+    }
+    /**
+     * Format Radio Browser API errors
+     */
+    static radioBrowserApi(response) {
+        return `Radio Browser API error: ${response.status} ${response.statusText}`;
+    }
+    /**
+     * Format generic API request errors
+     */
+    static apiRequest(apiName, response) {
+        return `${apiName} request failed: ${response.status} ${response.statusText}`;
+    }
+    /**
+     * Format generic API response errors
+     */
+    static apiResponse(apiName, message) {
+        return `${apiName} error: ${message || 'Unknown error'}`;
+    }
+    // === CONFIGURATION ERRORS ===
+    /**
+     * Format configuration validation failures
+     */
+    static configValidation(messages) {
+        return `Configuration validation failed:\n${messages.join('\n')}`;
+    }
+    /**
+     * Format missing configuration errors
+     */
+    static configMissing(service, configKey) {
+        return `${service} not configured: missing ${configKey}`;
+    }
+    // === GENERIC OPERATION ERRORS ===
+    /**
+     * Format general operation failures with context
+     */
+    static operationFailed(operation, error) {
+        const message = this.extractMessage(error);
+        return `Operation failed: ${operation} - ${message}`;
+    }
+    /**
+     * Format unknown resource errors (for MCP resources)
+     */
+    static unknownResource(resourceUri) {
+        return `Unknown resource: ${resourceUri}`;
+    }
+    /**
+     * Format validation stream/URL errors
+     */
+    static streamValidation(url, issue) {
+        return `Stream validation failed: ${url} - ${issue}`;
+    }
+}
+//# sourceMappingURL=error-formatter.js.map

package/dist/utils/error-formatter.js.map

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

package/dist/utils/logger.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Navidrome MCP Server - Logger Utility
+ * Copyright (C) 2025
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+declare class Logger {
+    private debugMode;
+    setDebug(enabled: boolean): void;
+    /**
+     * Sanitize URLs and other sensitive data from log messages
+     * Removes credentials from URLs to prevent accidental exposure
+     */
+    private sanitizeArgs;
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+export declare const logger: Logger;
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,cAAM,MAAM;IACV,OAAO,CAAC,SAAS,CAAS;IAE1B,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAIhC;;;OAGG;IACH,OAAO,CAAC,YAAY;IAgBpB,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAM/B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAI9B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAI9B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;CAGhC;AAED,eAAO,MAAM,MAAM,QAAe,CAAC"}

package/dist/utils/logger.js

@@ -0,0 +1,52 @@
+/**
+ * Navidrome MCP Server - Logger Utility
+ * Copyright (C) 2025
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+class Logger {
+    debugMode = false;
+    setDebug(enabled) {
+        this.debugMode = enabled;
+    }
+    /**
+     * Sanitize URLs and other sensitive data from log messages
+     * Removes credentials from URLs to prevent accidental exposure
+     */
+    sanitizeArgs(args) {
+        return args.map(arg => {
+            if (typeof arg === 'string' && arg.includes('://')) {
+                // Check if string contains URL with potential credentials
+                return arg.replace(/(https?:\/\/)[^:/\s]*:[^@/\s]*@/g, '$1[CREDENTIALS_REDACTED]@').replace(/([?&])[up]=[^&\s]*/g, '$1[CREDENTIAL_REDACTED]');
+            }
+            return arg;
+        });
+    }
+    debug(...args) {
+        if (this.debugMode) {
+            console.error('[DEBUG]', ...this.sanitizeArgs(args));
+        }
+    }
+    info(...args) {
+        console.error('[INFO]', ...this.sanitizeArgs(args));
+    }
+    warn(...args) {
+        console.error('[WARN]', ...this.sanitizeArgs(args));
+    }
+    error(...args) {
+        console.error('[ERROR]', ...this.sanitizeArgs(args));
+    }
+}
+export const logger = new Logger();
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM;IACF,SAAS,GAAG,KAAK,CAAC;IAE1B,QAAQ,CAAC,OAAgB;QACvB,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC;IAC3B,CAAC;IAED;;;OAGG;IACK,YAAY,CAAC,IAAe;QAClC,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;YACpB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnD,0DAA0D;gBAC1D,OAAO,GAAG,CAAC,OAAO,CAChB,kCAAkC,EAClC,2BAA2B,CAC5B,CAAC,OAAO,CACP,qBAAqB,EACrB,yBAAyB,CAC1B,CAAC;YACJ,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,GAAG,IAAe;QACtB,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IAED,IAAI,CAAC,GAAG,IAAe;QACrB,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,IAAI,CAAC,GAAG,IAAe;QACrB,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;IACtD,CAAC;IAED,KAAK,CAAC,GAAG,IAAe;QACtB,OAAO,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;IACvD,CAAC;CACF;AAED,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC"}

package/dist/utils/message-manager.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Navidrome MCP Server - One-Time Message Manager
+ * Copyright (C) 2025
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+/**
+ * Manages one-time messages for LLM assistants
+ * Ensures tips, reminders, and helpful messages are shown only once per session
+ */
+export declare class MessageManager {
+    private static instance;
+    private shownMessages;
+    private messageTemplates;
+    private constructor();
+    /**
+     * Get the singleton instance of MessageManager
+     */
+    static getInstance(): MessageManager;
+    /**
+     * Initialize predefined message templates
+     */
+    private initializeMessages;
+    /**
+     * Get a message if it hasn't been shown yet
+     * @param messageKey The unique key for the message
+     * @param customMessage Optional custom message to use instead of template
+     * @returns The message if not shown before, null otherwise
+     */
+    getMessage(messageKey: string, customMessage?: string): string | null;
+    /**
+     * Check if a message has been shown
+     * @param messageKey The unique key for the message
+     */
+    hasShownMessage(messageKey: string): boolean;
+    /**
+     * Manually mark a message as shown without returning it
+     * @param messageKey The unique key for the message
+     */
+    markAsShown(messageKey: string): void;
+    /**
+     * Reset all shown messages (useful for testing)
+     */
+    reset(): void;
+    /**
+     * Get all available message keys (for debugging)
+     */
+    getAvailableMessageKeys(): string[];
+    /**
+     * Add a new message template at runtime
+     * @param key The unique key for the message
+     * @param message The message content
+     */
+    addMessageTemplate(key: string, message: string): void;
+    /**
+     * Format a message with dynamic values
+     * @param messageKey The message key
+     * @param values Object with key-value pairs to replace in message
+     */
+    getFormattedMessage(messageKey: string, values: Record<string, string | number>, customMessage?: string): string | null;
+}
+export declare function getMessageManager(): MessageManager;
+//# sourceMappingURL=message-manager.d.ts.map

package/dist/utils/message-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-manager.d.ts","sourceRoot":"","sources":["../../src/utils/message-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA+B;IACtD,OAAO,CAAC,aAAa,CAAc;IACnC,OAAO,CAAC,gBAAgB,CAAsB;IAE9C,OAAO;IAMP;;OAEG;WACW,WAAW,IAAI,cAAc;IAO3C;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA2B1B;;;;;OAKG;IACI,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAiB5E;;;OAGG;IACI,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAInD;;;OAGG;IACI,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAI5C;;OAEG;IACI,KAAK,IAAI,IAAI;IAIpB;;OAEG;IACI,uBAAuB,IAAI,MAAM,EAAE;IAI1C;;;;OAIG;IACI,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAI7D;;;;OAIG;IACI,mBAAmB,CACxB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,EACvC,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,GAAG,IAAI;CAUjB;AAGD,wBAAgB,iBAAiB,IAAI,cAAc,CAElD"}

package/dist/utils/message-manager.js

@@ -0,0 +1,134 @@
+/**
+ * Navidrome MCP Server - One-Time Message Manager
+ * Copyright (C) 2025
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+/**
+ * Manages one-time messages for LLM assistants
+ * Ensures tips, reminders, and helpful messages are shown only once per session
+ */
+export class MessageManager {
+    static instance = null;
+    shownMessages;
+    messageTemplates;
+    constructor() {
+        this.shownMessages = new Set();
+        this.messageTemplates = new Map();
+        this.initializeMessages();
+    }
+    /**
+     * Get the singleton instance of MessageManager
+     */
+    static getInstance() {
+        if (!MessageManager.instance) {
+            MessageManager.instance = new MessageManager();
+        }
+        return MessageManager.instance;
+    }
+    /**
+     * Initialize predefined message templates
+     */
+    initializeMessages() {
+        // Radio validation reminder
+        this.messageTemplates.set('radio.validation_reminder', `
+🎵 STREAM VALIDATION RECOMMENDED
+   Use 'validate_radio_stream' tool first to test your URL
+   Many internet radio URLs change frequently
+   Validation checks: accessibility, audio format, streaming headers
+   
+   💡 TIP: Find reliable streams at radio-browser.info or somafm.com`);
+        // Radio list tip
+        this.messageTemplates.set('radio.list_tip', "💡 TIP: Use 'validate_radio_stream' to test station URLs if playback issues occur");
+        // Radio creation success
+        this.messageTemplates.set('radio.creation_success', "✅ Station created successfully! Remember to validate streams periodically as URLs may change.");
+        // General validation advice
+        this.messageTemplates.set('radio.validation_advice', "🔍 Pro tip: Radio streams can go offline. Validate regularly for best experience.");
+        // Add more message templates as needed
+        this.messageTemplates.set('general.welcome', "🎶 Welcome to Navidrome MCP! Type 'test_connection' to verify your setup.");
+    }
+    /**
+     * Get a message if it hasn't been shown yet
+     * @param messageKey The unique key for the message
+     * @param customMessage Optional custom message to use instead of template
+     * @returns The message if not shown before, null otherwise
+     */
+    getMessage(messageKey, customMessage) {
+        // Check if message was already shown
+        if (this.shownMessages.has(messageKey)) {
+            return null;
+        }
+        // Mark as shown
+        this.shownMessages.add(messageKey);
+        // Return custom message or template
+        if (customMessage) {
+            return customMessage;
+        }
+        return this.messageTemplates.get(messageKey) || null;
+    }
+    /**
+     * Check if a message has been shown
+     * @param messageKey The unique key for the message
+     */
+    hasShownMessage(messageKey) {
+        return this.shownMessages.has(messageKey);
+    }
+    /**
+     * Manually mark a message as shown without returning it
+     * @param messageKey The unique key for the message
+     */
+    markAsShown(messageKey) {
+        this.shownMessages.add(messageKey);
+    }
+    /**
+     * Reset all shown messages (useful for testing)
+     */
+    reset() {
+        this.shownMessages.clear();
+    }
+    /**
+     * Get all available message keys (for debugging)
+     */
+    getAvailableMessageKeys() {
+        return Array.from(this.messageTemplates.keys());
+    }
+    /**
+     * Add a new message template at runtime
+     * @param key The unique key for the message
+     * @param message The message content
+     */
+    addMessageTemplate(key, message) {
+        this.messageTemplates.set(key, message);
+    }
+    /**
+     * Format a message with dynamic values
+     * @param messageKey The message key
+     * @param values Object with key-value pairs to replace in message
+     */
+    getFormattedMessage(messageKey, values, customMessage) {
+        const message = this.getMessage(messageKey, customMessage);
+        if (!message)
+            return null;
+        let formatted = message;
+        for (const [key, value] of Object.entries(values)) {
+            formatted = formatted.replace(new RegExp(`{{${key}}}`, 'g'), String(value));
+        }
+        return formatted;
+    }
+}
+// Export singleton getter for convenience
+export function getMessageManager() {
+    return MessageManager.getInstance();
+}
+//# sourceMappingURL=message-manager.js.map

package/dist/utils/message-manager.js.map

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

package/dist/utils/version.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Version utility to read version from package.json
+ */
+export declare function getPackageVersion(): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/utils/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,wBAAgB,iBAAiB,IAAI,MAAM,CAS1C"}

package/dist/utils/version.js

@@ -0,0 +1,19 @@
+/**
+ * Version utility to read version from package.json
+ */
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export function getPackageVersion() {
+    try {
+        const packageJsonPath = join(__dirname, '../../package.json');
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+        return packageJson.version;
+    }
+    catch {
+        // Fallback version if package.json can't be read
+        return '1.0.1';
+    }
+}
+//# sourceMappingURL=version.js.map

package/dist/utils/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAEpC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE1D,MAAM,UAAU,iBAAiB;IAC/B,IAAI,CAAC;QACH,MAAM,eAAe,GAAG,IAAI,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC;QAC9D,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC,CAAC;QACtE,OAAO,WAAW,CAAC,OAAO,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,iDAAiD;QACjD,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "navidrome-mcp",
+  "version": "1.0.1",
+  "description": "MCP server for interacting with Navidrome music server",
+  "type": "module",
+  "main": "dist/index.js",
+  "keywords": [
+    "mcp",
+    "navidrome",
+    "music",
+    "subsonic",
+    "api",
+    "server"
+  ],
+  "author": "",
+  "license": "AGPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Blakeem/Navidrome-MCP.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Blakeem/Navidrome-MCP/issues"
+  },
+  "homepage": "https://github.com/Blakeem/Navidrome-MCP#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "bin": {
+    "navidrome-mcp": "./dist/index.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.4",
+    "dotenv": "^16.4.7",
+    "file-type": "^19.5.0",
+    "zod": "^4.1.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.34.0",
+    "@types/node": "^24.3.0",
+    "@typescript-eslint/eslint-plugin": "^8.41.0",
+    "@typescript-eslint/parser": "^8.41.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "eslint": "^9.34.0",
+    "eslint-config-prettier": "^9.1.0",
+    "nodemon": "^3.1.10",
+    "prettier": "^3.6.2",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:ci": "SKIP_INTEGRATION_TESTS=true MOCK_ONLY_TESTS=true NAVIDROME_URL=http://ci-dummy:4533 NAVIDROME_USERNAME=ci-user NAVIDROME_PASSWORD=ci-pass vitest run",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "inspector": "npx @modelcontextprotocol/inspector node dist/index.js",
+    "inspector:dev": "npx @modelcontextprotocol/inspector tsx src/index.ts"
+  }
+}