@powerfm/libretime-mcp 0.1.8 → 0.3.0

package/dist/http/admin.js

@@ -1,47 +1,34 @@
 #!/usr/bin/env node
 // HTTP MCP server — full admin access (shows + analytics + file/user management).
 // Exposes POST /mcp using MCP Streamable HTTP transport.
-// Requires Authorization: Bearer <MCP_API_KEY> on every request.
+// Requires Authorization: Bearer <MCP_API_KEY> on every MCP request.
 // Intended for network clients (e.g. powerfm-agent). For Claude Desktop use stdio/admin.ts.
 import '../env.js';
-import { createRequire } from 'module';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
-import cors from 'cors';
-const { version } = createRequire(import.meta.url)('../../package.json');
+import crypto from 'node:crypto';
 import { register as registerShows } from '../tools/shows/index.js';
 import { register as registerAnalytics } from '../tools/analytics/index.js';
 import { register as registerAdmin } from '../tools/admin/index.js';
+import { register as registerFiles } from '../tools/files/index.js';
+import { registerUploadEndpoint } from './upload.js';
+import { createHttpServer } from './server.js';
 const PORT = parseInt(process.env.MCP_PORT ?? '3000', 10);
-const API_KEY = process.env.MCP_API_KEY;
-if (!API_KEY) {
-    console.error('ERROR: MCP_API_KEY environment variable is required');
-    process.exit(1);
-}
-const app = createMcpExpressApp({ host: '0.0.0.0' });
-app.use(cors({ origin: process.env.CORS_ORIGIN ?? true, credentials: true }));
-// Simple API key middleware — checks Authorization: Bearer <key>
-app.use('/mcp', (req, res, next) => {
-    const auth = req.headers['authorization'];
-    if (!auth || auth !== `Bearer ${API_KEY}`) {
-        res.status(401).json({ error: 'Unauthorized' });
-        return;
-    }
-    next();
-});
-// Stateless transport — a fresh McpServer per request keeps things simple
-// and avoids session management complexity for now
-app.all('/mcp', async (req, res) => {
-    const server = new McpServer({ name: 'libretime-mcp-admin', version });
-    registerShows(server);
-    registerAnalytics(server);
-    registerAdmin(server);
-    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-    await server.connect(transport);
-    await transport.handleRequest(req, res, req.body);
-});
-app.listen(PORT, '0.0.0.0', () => {
-    console.error(`LibreTime MCP admin HTTP server listening on port ${PORT}`);
-    console.error('Endpoint: POST /mcp  (Authorization: Bearer <MCP_API_KEY>)');
+const PUBLIC_URL = process.env.MCP_PUBLIC_URL ?? `http://localhost:${PORT}`;
+// Scoped upload token — generated once at startup, rotates on restart.
+const UPLOAD_TOKEN = crypto.randomBytes(32).toString('hex');
+// uploadUrl is set by setupRoutes (which runs at startup) and read by register
+// (which runs per-request). setupRoutes always runs first, so this is safe.
+let uploadUrl;
+createHttpServer({
+    name: 'libretime-mcp-admin',
+    defaultPort: 3000,
+    setupRoutes: (app) => {
+        uploadUrl = registerUploadEndpoint(app, PUBLIC_URL, UPLOAD_TOKEN);
+        console.error(`Upload:   POST /upload  (X-Upload-Token: <per-startup token>)`);
+    },
+    register: (server) => {
+        registerShows(server);
+        registerAnalytics(server);
+        registerAdmin(server);
+        registerFiles(server, uploadUrl, UPLOAD_TOKEN);
+    },
 });

package/dist/http/client.js

@@ -4,40 +4,12 @@
 // Requires Authorization: Bearer <MCP_API_KEY> on every request.
 // Intended for network clients. For Claude Desktop use stdio/client.ts.
 import '../env.js';
-import { createRequire } from 'module';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
-import cors from 'cors';
 import { register as registerShows } from '../tools/shows/index.js';
-const { version } = createRequire(import.meta.url)('../../package.json');
-const PORT = parseInt(process.env.MCP_PORT ?? '3001', 10);
-const API_KEY = process.env.MCP_API_KEY;
-if (!API_KEY) {
-    console.error('ERROR: MCP_API_KEY environment variable is required');
-    process.exit(1);
-}
-const app = createMcpExpressApp({ host: '0.0.0.0' });
-app.use(cors({ origin: process.env.CORS_ORIGIN ?? true, credentials: true }));
-// Simple API key middleware — checks Authorization: Bearer <key>
-app.use('/mcp', (req, res, next) => {
-    const auth = req.headers['authorization'];
-    if (!auth || auth !== `Bearer ${API_KEY}`) {
-        res.status(401).json({ error: 'Unauthorized' });
-        return;
-    }
-    next();
-});
-// Stateless transport — a fresh McpServer per request keeps things simple
-// and avoids session management complexity for now
-app.all('/mcp', async (req, res) => {
-    const server = new McpServer({ name: 'libretime-mcp-client', version });
-    registerShows(server);
-    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
-    await server.connect(transport);
-    await transport.handleRequest(req, res, req.body);
-});
-app.listen(PORT, '0.0.0.0', () => {
-    console.error(`LibreTime MCP client HTTP server listening on port ${PORT}`);
-    console.error('Endpoint: POST /mcp  (Authorization: Bearer <MCP_API_KEY>)');
+import { createHttpServer } from './server.js';
+createHttpServer({
+    name: 'libretime-mcp-client',
+    defaultPort: 3001,
+    register: (server) => {
+        registerShows(server);
+    },
 });

package/dist/http/server.js

@@ -0,0 +1,72 @@
+import { createRequire } from 'module';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
+import cors from 'cors';
+import helmet from 'helmet';
+import rateLimit from 'express-rate-limit';
+import morgan from 'morgan';
+const { version } = createRequire(import.meta.url)('../../package.json');
+export function createHttpServer({ name, defaultPort, register, setupRoutes }) {
+    const PORT = parseInt(process.env.MCP_PORT ?? String(defaultPort), 10);
+    const API_KEY = process.env.MCP_API_KEY;
+    const AUTH_DISABLED = process.env.DISABLE_AUTH === 'true';
+    if (!AUTH_DISABLED && !API_KEY) {
+        console.error('ERROR: MCP_API_KEY environment variable is required');
+        process.exit(1);
+    }
+    const app = createMcpExpressApp({ host: '0.0.0.0' });
+    // Request logging — 'dev' in development (coloured, concise),
+    // 'combined' in production (Apache format: IP, method, path, status, size, user-agent).
+    // Runs first so every request is logged regardless of auth outcome.
+    const logFormat = process.env.NODE_ENV === 'production' ? 'combined' : 'dev';
+    app.use(morgan(logFormat));
+    // Security headers — sets ~14 protective HTTP headers automatically.
+    // contentSecurityPolicy disabled: the MCP SDK sets its own and they'd conflict.
+    app.use(helmet({ contentSecurityPolicy: false }));
+    app.use(cors({ origin: process.env.CORS_ORIGIN ?? true, credentials: true }));
+    // Rate limiting — max 120 requests per IP per minute.
+    // Protects against runaway clients and accidental hammering.
+    // /ping is excluded so uptime monitors never get blocked.
+    app.use(/^\/(mcp|upload)/, rateLimit({ windowMs: 60_000, max: 120 }));
+    // Rate limiting — max 120 requests per IP per minute.
+    // Protects against runaway clients and accidental hammering.
+    // /ping is excluded so uptime monitors never get blocked.
+    app.use(/^\/(mcp|upload)/, rateLimit({ windowMs: 60_000, max: 120 }));
+    // Health check — no auth required, used by uptime monitors and load balancers
+    app.get('/ping', (_req, res) => {
+        res.json({ status: 'ok' });
+    });
+    // Extra routes (e.g. /upload) with their own auth — must come before the MCP auth guard
+    setupRoutes?.(app);
+    // API key guard — protects all /mcp requests
+    app.use('/mcp', (req, res, next) => {
+        if (AUTH_DISABLED)
+            return next();
+        const auth = req.headers['authorization'];
+        if (!auth || auth !== `Bearer ${API_KEY}`) {
+            res.status(401).json({ error: 'Unauthorized' });
+            return;
+        }
+        next();
+    });
+    // Stateless transport — a fresh McpServer per request keeps things simple
+    // and avoids session management complexity for now.
+    app.all('/mcp', async (req, res) => {
+        // Log which MCP method and tool was called — morgan only sees POST /mcp
+        const method = req.body?.method;
+        const toolName = req.body?.params?.name;
+        if (method)
+            console.error(`[mcp] ${method}${toolName ? ` tool=${toolName}` : ''}`);
+        const server = new McpServer({ name, version });
+        register(server);
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+    });
+    app.listen(PORT, '0.0.0.0', () => {
+        console.error(`LibreTime MCP ${name} HTTP server listening on port ${PORT}`);
+        console.error(`Health:   GET  /ping`);
+        console.error(`Endpoint: POST /mcp  (Authorization: Bearer <MCP_API_KEY>)`);
+    });
+}

package/dist/http/upload.js

@@ -0,0 +1,75 @@
+import cors from 'cors';
+/**
+ * Registers POST /upload on the given Express app.
+ *
+ * The React UI posts audio files here directly (bypassing the MCP protocol).
+ * The body is buffered in memory before forwarding to LibreTime.
+ *
+ * TODO: switch back to streaming (Readable.toWeb) for large show files once
+ * the basic flow is confirmed working end-to-end.
+ *
+ * Auth: X-Upload-Token header must match the provided uploadToken.
+ *
+ * Returns the full upload URL so callers can pass it to registerFiles().
+ */
+export function registerUploadEndpoint(app, publicUrl, uploadToken) {
+    // Explicit CORS for the upload route — must allow X-Upload-Token so the
+    // browser's preflight passes before sending the actual file.
+    const uploadCors = cors({
+        origin: process.env.CORS_ORIGIN ?? true,
+        credentials: true,
+        allowedHeaders: ['Content-Type', 'X-Upload-Token'],
+    });
+    app.options('/upload', uploadCors);
+    app.post('/upload', uploadCors, async (req, res) => {
+        const totalStart = Date.now();
+        const token = req.headers['x-upload-token'];
+        if (!token || token !== uploadToken) {
+            console.error(`[upload] status=401 total_ms=${Date.now() - totalStart}`);
+            res.status(401).json({ error: 'Unauthorized' });
+            return;
+        }
+        const BASE_URL = process.env.LIBRETIME_URL ?? '';
+        // /rest/media is the legacy PHP upload endpoint — the only path that writes
+        // files to disk and queues the analyzer. Auth uses the LibreTime API key
+        // (from config.yml general.api_key) as the Basic Auth username with no password.
+        const API_KEY = process.env.LIBRETIME_API_KEY ?? '';
+        const libreAuth = 'Basic ' + Buffer.from(`${API_KEY}:`).toString('base64');
+        const libreUrl = new URL('/rest/media', BASE_URL).toString();
+        try {
+            const body = await new Promise((resolve, reject) => {
+                const chunks = [];
+                req.on('data', (chunk) => chunks.push(chunk));
+                req.on('end', () => resolve(Buffer.concat(chunks)));
+                req.on('error', reject);
+            });
+            const sizeMb = (body.length / 1024 / 1024).toFixed(2);
+            const libreStart = Date.now();
+            const response = await fetch(libreUrl, {
+                method: 'POST',
+                headers: {
+                    Authorization: libreAuth,
+                    Accept: 'application/json',
+                    'Content-Type': req.headers['content-type'],
+                    'Content-Length': String(body.length),
+                },
+                body: new Uint8Array(body),
+            });
+            const libreMs = Date.now() - libreStart;
+            const totalMs = Date.now() - totalStart;
+            if (!response.ok) {
+                const detail = await response.text();
+                console.error(`[upload] size=${sizeMb}mb libretime_ms=${libreMs} total_ms=${totalMs} status=${response.status} error="${detail}"`);
+                res.status(502).json({ error: `LibreTime error: ${response.status}`, detail });
+                return;
+            }
+            console.error(`[upload] size=${sizeMb}mb libretime_ms=${libreMs} total_ms=${totalMs} status=${response.status}`);
+            res.json(await response.json());
+        }
+        catch (err) {
+            console.error(`[upload] total_ms=${Date.now() - totalStart} status=500 error="${err instanceof Error ? err.message : String(err)}"`);
+            res.status(500).json({ error: err instanceof Error ? err.message : String(err) });
+        }
+    });
+    return `${publicUrl}/upload`;
+}

package/dist/libretime.js

@@ -1,6 +1,7 @@
 const BASE_URL = process.env.LIBRETIME_URL ?? '';
 const USER = process.env.LIBRETIME_USER ?? '';
 const PASS = process.env.LIBRETIME_PASS ?? '';
+const API_KEY = process.env.LIBRETIME_API_KEY ?? '';
 // Basic Auth header value, base64-encoded as the HTTP spec requires
 const authHeader = 'Basic ' + Buffer.from(`${USER}:${PASS}`).toString('base64');
 /**
@@ -46,8 +47,11 @@ export async function librePost(path, body) {
     return response.json();
 }
 /**
- * Make an authenticated multipart POST request to the LibreTime API.
- * Used for file uploads. Returns the parsed JSON response as unknown.
+ * BENCHED: multipart POST to /api/v2/files (DRF).
+ * Creates a DB record but never writes to disk or queues the analyzer —
+ * filepath stays null and import_status stays 1 forever.
+ * Kept here for when the DRF endpoint gets the analyzer wiring fixed upstream.
+ * See: PLAN.md → Open source contributions → LibreTime file upload
  */
 export async function libreUpload(path, formData) {
     const url = new URL(path, BASE_URL);
@@ -56,8 +60,6 @@ export async function libreUpload(path, formData) {
         headers: {
             Authorization: authHeader,
             Accept: 'application/json',
-            // Note: do NOT set Content-Type here — fetch sets it automatically
-            // with the correct multipart boundary when given a FormData body
         },
         body: formData,
     });
@@ -66,6 +68,32 @@ export async function libreUpload(path, formData) {
     }
     return response.json();
 }
+/**
+ * Upload a file to /rest/media — the legacy PHP endpoint that triggers the full
+ * import workflow (writes to disk, queues the analyzer). The DRF /api/v2/files
+ * endpoint creates a DB record but never writes to disk, so this is the only
+ * working upload path.
+ *
+ * Auth uses LIBRETIME_API_KEY (general.api_key from LibreTime config.yml) as
+ * Basic Auth username with no password, which is what /rest/media expects.
+ */
+export async function libreRestMedia(formData) {
+    const url = new URL('/rest/media', BASE_URL);
+    const apiKeyAuth = 'Basic ' + Buffer.from(`${API_KEY}:`).toString('base64');
+    const response = await fetch(url.toString(), {
+        method: 'POST',
+        headers: {
+            Authorization: apiKeyAuth,
+            Accept: 'application/json',
+            // Do NOT set Content-Type — fetch sets it with the correct multipart boundary
+        },
+        body: formData,
+    });
+    if (!response.ok) {
+        throw new Error(`LibreTime upload error: ${response.status} ${response.statusText} — ${url.toString()}`);
+    }
+    return response.json();
+}
 /**
  * Make an authenticated PATCH request to the LibreTime API with a JSON body.
  * Returns the parsed JSON response as unknown — callers are responsible for validation.

package/dist/stdio/admin.js

@@ -1,12 +1,26 @@
 #!/usr/bin/env node
 import { createRequire } from 'module';
+import crypto from 'node:crypto';
+import express from 'express';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { register as registerShows } from '../tools/shows/index.js';
 import { register as registerAnalytics } from '../tools/analytics/index.js';
 import { register as registerAdmin } from '../tools/admin/index.js';
 import { register as registerFiles } from '../tools/files/index.js';
+import { registerUploadEndpoint } from '../http/upload.js';
 const { version } = createRequire(import.meta.url)('../../package.json');
+// Spin up a local HTTP server solely for the file upload endpoint.
+// The MCP protocol runs over stdio — this is a side-channel so the
+// iframe UI can POST files without going through the MCP protocol.
+const UPLOAD_PORT = parseInt(process.env.UPLOAD_PORT ?? '4000', 10);
+const PUBLIC_URL = `http://localhost:${UPLOAD_PORT}`;
+const UPLOAD_TOKEN = crypto.randomBytes(32).toString('hex');
+const app = express();
+const uploadUrl = registerUploadEndpoint(app, PUBLIC_URL, UPLOAD_TOKEN);
+app.listen(UPLOAD_PORT, () => {
+    console.error(`Upload:   POST /upload on port ${UPLOAD_PORT}`);
+});
 const server = new McpServer({
     name: 'libretime-mcp-admin',
     version,
@@ -14,7 +28,7 @@ const server = new McpServer({
 registerShows(server);
 registerAnalytics(server);
 registerAdmin(server);
-registerFiles(server);
+registerFiles(server, uploadUrl, UPLOAD_TOKEN);
 const transport = new StdioServerTransport();
 await server.connect(transport);
 console.error('LibreTime MCP admin server running (shows + analytics + admin)');

package/dist/tools/files/index.js

@@ -1,10 +1,10 @@
-import { register as registerSearchFiles } from '../files/search_files.js';
-import { register as registerUploadFile } from '../files/upload_file.js';
-import { register as registerUpdateFileMetadata } from '../files/update_file_metadata.js';
-import { register as registerDeleteFile } from '../files/delete_file.js';
-export function register(server) {
+import { register as registerSearchFiles } from './search_files.js';
+import { register as registerUploadFile } from './upload_file_legacy.js';
+import { register as registerUpdateFileMetadata } from './update_file_metadata.js';
+import { register as registerDeleteFile } from './delete_file.js';
+export function register(server, uploadUrl, uploadToken) {
     registerSearchFiles(server);
-    registerUploadFile(server);
+    registerUploadFile(server, uploadUrl, uploadToken);
     registerUpdateFileMetadata(server);
     registerDeleteFile(server);
 }

package/dist/tools/files/types.js

@@ -1,4 +1,10 @@
 import { z } from 'zod';
+export const LibrarySchema = z.object({
+    id: z.number(),
+    name: z.string().nullable(),
+    code: z.string(),
+    enabled: z.boolean(),
+});
 export const LibreFileSchema = z.object({
     id: z.number(),
     name: z.string(),

package/dist/tools/files/upload_file.js

@@ -1,50 +1,175 @@
+// ON HOLD — waiting on LibreTime to wire the analyzer in the DRF /api/v2/files endpoint.
+//
+// Current behaviour of /api/v2/files (POST):
+//   - Creates a DB record (import_status = 1)
+//   - Does NOT write the file to disk
+//   - Does NOT queue the RabbitMQ analyzer job
+//   - filepath stays null; import_status never transitions to 0
+//
+// The working upload path is in upload_file_legacy.ts (/rest/media, legacy PHP endpoint).
+// index.ts imports from upload_file_legacy.ts until this is resolved upstream.
+//
+// To switch back once the DRF endpoint is fixed:
+//   1. Update index.ts to import from './upload_file.js' instead of './upload_file_legacy.js'
+//   2. Delete upload_file_legacy.ts
+//
+// Upstream context: PLAN.md → Open source contributions → LibreTime file upload
 import { z } from 'zod';
-import { libreUpload } from '../../libretime.js';
+import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE, } from '@modelcontextprotocol/ext-apps/server';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { libreGet, libreUpload } from '../../libretime.js';
 import { toolText } from '../../tool-response.js';
-import { LibreFileSchema } from './types.js';
-export function register(server) {
-    server.registerTool('upload_file', {
-        description: 'Upload an audio file to the LibreTime media library from a URL. If no URL is provided, returns an action signal so the client can trigger a local file upload workflow. Optionally provide metadata such as track title, artist, album, and genre.',
+import { LibreFileSchema, LibrarySchema } from './types.js';
+const HTML_PATH = import.meta.filename.endsWith('.ts')
+    ? path.join(import.meta.dirname, '../../../dist/apps/upload-file.html')
+    : path.join(import.meta.dirname, '../../apps/upload-file.html');
+const resourceUri = 'ui://libretime/upload-file.html';
+const metadataFields = {
+    track_title: z.string().optional().describe('Track title'),
+    artist_name: z.string().optional().describe('Artist name'),
+    album_title: z.string().optional().describe('Album title'),
+    genre: z.string().optional().describe('Genre'),
+    library: z.number().optional().describe('Track type / library ID'),
+};
+const MIME_MAP = {
+    mp3: 'audio/mpeg',
+    flac: 'audio/flac',
+    wav: 'audio/wav',
+    ogg: 'audio/ogg',
+    aac: 'audio/aac',
+    m4a: 'audio/mp4',
+    opus: 'audio/opus',
+};
+function inferMime(filePath) {
+    const ext = filePath.split('.').pop()?.toLowerCase() ?? '';
+    return MIME_MAP[ext] ?? 'audio/mpeg';
+}
+function appendMetadata(formData, fields) {
+    if (fields.track_title)
+        formData.append('track_title', fields.track_title);
+    if (fields.artist_name)
+        formData.append('artist_name', fields.artist_name);
+    if (fields.album_title)
+        formData.append('album_title', fields.album_title);
+    if (fields.genre)
+        formData.append('genre', fields.genre);
+    if (fields.library)
+        formData.append('library', String(fields.library));
+}
+export function register(server, uploadUrl, uploadToken) {
+    registerAppTool(server, 'upload_file', {
+        description: 'Upload an audio file to the LibreTime media library. Provide a URL to fetch the file from, or a local file path when running in stdio mode. When neither is given, opens a file picker. Optionally pre-fill metadata such as track title, artist, album, and genre.',
         inputSchema: {
             url: z.string().optional().describe('Publicly accessible URL of the audio file to upload'),
-            track_title: z.string().optional().describe('Track title'),
-            artist_name: z.string().optional().describe('Artist name'),
-            album_title: z.string().optional().describe('Album title'),
-            genre: z.string().optional().describe('Genre'),
+            file_path: z.string().optional().describe('Absolute path to a local audio file — use when running stdio mode'),
+            ...metadataFields,
         },
-    }, async ({ url, track_title, artist_name, album_title, genre }) => {
-        if (!url) {
-            return toolText({ status: 'upload_required', action: 'file_upload' });
-        }
-        let fileResponse;
-        try {
-            fileResponse = await fetch(url);
-            if (!fileResponse.ok) {
-                return toolText({ status: 'error', reason: `Could not fetch file: ${fileResponse.status} ${fileResponse.statusText}` });
+        _meta: { ui: { resourceUri } },
+    }, async ({ url, file_path, track_title, artist_name, album_title, genre, library }) => {
+        const meta = { track_title, artist_name, album_title, genre, library };
+        // Priority 1: local file path (stdio mode — server runs on the user's machine)
+        if (file_path) {
+            let fileBuffer;
+            try {
+                fileBuffer = await fs.readFile(file_path);
+            }
+            catch (err) {
+                return toolText({
+                    status: 'error',
+                    reason: `Could not read file: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+            const fileName = path.basename(file_path);
+            const mime = inferMime(file_path);
+            const formData = new FormData();
+            formData.append('file', new Blob([new Uint8Array(fileBuffer)], { type: mime }), fileName);
+            formData.append('name', fileName);
+            formData.append('size', String(fileBuffer.byteLength));
+            formData.append('mime', mime);
+            formData.append('accessed', String(Math.floor(Date.now() / 1000)));
+            appendMetadata(formData, meta);
+            try {
+                const raw = await libreUpload('/api/v2/files', formData);
+                const file = LibreFileSchema.parse(raw);
+                return toolText({ status: 'success', file });
+            }
+            catch (err) {
+                return toolText({
+                    status: 'error',
+                    reason: `LibreTime upload failed: ${err instanceof Error ? err.message : String(err)}`,
+                });
             }
         }
-        catch (err) {
-            return toolText({ status: 'error', reason: `Failed to reach URL: ${err instanceof Error ? err.message : String(err)}` });
+        // Priority 2: remote URL — fetch then forward to LibreTime
+        if (url) {
+            let fileResponse;
+            try {
+                fileResponse = await fetch(url);
+                if (!fileResponse.ok) {
+                    return toolText({
+                        status: 'error',
+                        reason: `Could not fetch file: ${fileResponse.status} ${fileResponse.statusText}`,
+                    });
+                }
+            }
+            catch (err) {
+                return toolText({
+                    status: 'error',
+                    reason: `Failed to reach URL: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+            const fileName = url.split('/').pop()?.split('?')[0] || 'upload';
+            const blob = await fileResponse.blob();
+            const mime = blob.type || inferMime(fileName);
+            const formData = new FormData();
+            formData.append('file', blob, fileName);
+            formData.append('name', fileName);
+            formData.append('size', String(blob.size));
+            formData.append('mime', mime);
+            formData.append('accessed', String(Math.floor(Date.now() / 1000)));
+            appendMetadata(formData, meta);
+            try {
+                const raw = await libreUpload('/api/v2/files', formData);
+                const file = LibreFileSchema.parse(raw);
+                return toolText({ status: 'success', file });
+            }
+            catch (err) {
+                return toolText({
+                    status: 'error',
+                    reason: `LibreTime upload failed: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
         }
-        const fileName = url.split('/').pop()?.split('?')[0] || 'upload';
-        const blob = await fileResponse.blob();
-        const formData = new FormData();
-        formData.append('file', blob, fileName);
-        if (track_title)
-            formData.append('track_title', track_title);
-        if (artist_name)
-            formData.append('artist_name', artist_name);
-        if (album_title)
-            formData.append('album_title', album_title);
-        if (genre)
-            formData.append('genre', genre);
+        // Priority 3: no input — hand off to the file picker UI
+        let libraries = [];
         try {
-            const raw = await libreUpload('/api/v2/files', formData);
-            const file = LibreFileSchema.parse(raw);
-            return toolText({ status: 'success', file });
+            const raw = await libreGet('/api/v2/libraries');
+            libraries = LibrarySchema.array().parse(raw);
         }
-        catch (err) {
-            return toolText({ status: 'error', reason: `LibreTime upload failed: ${err instanceof Error ? err.message : String(err)}` });
+        catch {
+            // Non-fatal — UI will just show no dropdown
         }
+        return toolText({
+            status: uploadUrl ? 'upload_ready' : 'upload_required',
+            upload_url: uploadUrl ?? null,
+            upload_token: uploadToken ?? null,
+            libraries,
+        });
+    });
+    registerAppResource(server, resourceUri, resourceUri, { mimeType: RESOURCE_MIME_TYPE }, async () => {
+        const html = await fs.readFile(HTML_PATH, 'utf-8');
+        return {
+            contents: [
+                {
+                    uri: resourceUri,
+                    mimeType: RESOURCE_MIME_TYPE,
+                    text: html,
+                    ...(uploadUrl && {
+                        _meta: { ui: { csp: { connectDomains: [uploadUrl] } } },
+                    }),
+                },
+            ],
+        };
     });
 }