FlixBridge

Instructions

Implementation Reference

• src/index.ts:134-145 (registration)

  MCP tool registration defining the 'queue_diagnostics' tool name, description, and input schema.
  { name: "queue_diagnostics", description: "Analyze and auto-fix stuck queue items", inputSchema: { type: "object", properties: { service: { type: "string" }, autoFix: { type: "boolean" }, }, required: ["service"], }, },
• src/index.ts:326-327 (handler)

  Tool dispatch handler in main CallToolRequestSchema that routes 'queue_diagnostics' calls to the service implementation.
  case "queue_diagnostics": return await service.queueDiagnostics(input.autoFix);
• src/services/shared.ts:533-596 (handler)

  Primary handler implementation in BaseArrService: fetches queue, analyzes issues, attempts auto-fixes if enabled, and returns diagnostics.
  async queueDiagnostics( autoFix = true, ): Promise<OperationResult<QueueDiagnosticsData>> { const operation = withMetrics( this.serviceName, "queueDiagnostics", async () => { debugOperation(this.serviceName, "queueDiagnostics"); // Get current queue with detailed status const queueResponse = await fetchJson(this.buildApiUrl("/queue")); const queueData = QueueSchema.parse(queueResponse); const allItems = queueData.records || []; const issuesAnalyzed: QueueIssueAnalysis[] = []; const fixesAttempted: QueueFixAction[] = []; for (const item of allItems) { const analysis = this.analyzeQueueItem(item); // Include all real issues - exclude only "unknown" type with "info" severity const isRealIssue = !( analysis.category.type === "unknown" && analysis.category.severity === "info" ); if (isRealIssue) { issuesAnalyzed.push(analysis); // Attempt auto-fix if possible and enabled if (autoFix && analysis.category.autoFixable) { const fixAction = await this.attemptAutoFix(item, analysis); fixesAttempted.push(fixAction); } } } const summary = { fixed: fixesAttempted.filter((f) => f.success === true).length, failed: fixesAttempted.filter((f) => f.success === false).length, requiresManual: issuesAnalyzed.filter((i) => !i.category.autoFixable) .length, }; return { ok: true, data: { service: this.serviceName, mediaKind: this.mediaKind, totalQueueItems: allItems.length, issuesFound: issuesAnalyzed.length, issuesAnalyzed, fixesAttempted, summary, }, }; }, ); try { return await operation(); } catch (error) { return handleError(error, this.serviceName); } }
• src/services/base.ts:211-223 (schema)

  TypeScript interface defining the structure of QueueDiagnosticsData returned by the tool.
  export interface QueueDiagnosticsData { service: string; mediaKind: "series" | "movie"; totalQueueItems: number; issuesFound: number; issuesAnalyzed: QueueIssueAnalysis[]; fixesAttempted: QueueFixAction[]; summary: { fixed: number; failed: number; requiresManual: number; }; }
• src/services/shared.ts:598-728 (helper)

  Helper method analyzeQueueItem categorizes queue issues based on status messages and error patterns.
  private analyzeQueueItem(item: QueueRecord): QueueIssueAnalysis { const status = item.status?.toLowerCase() || ""; const statusMessages = item.statusMessages || []; const errorMessage = item.errorMessage || ""; const allMessages = [ status, ...statusMessages.map((m: StatusMessage) => m.title || m.message || ""), ...statusMessages.flatMap((m: StatusMessage) => m.messages || []), errorMessage, ] .filter(Boolean) .join(" ") .toLowerCase(); // TheXEM mapping issues if (allMessages.includes("thexem") && allMessages.includes("mapping")) { return { id: item.id, title: item.title, status: item.status, category: { type: "mapping", severity: "warning", autoFixable: true }, message: "TheXEM mapping issue detected", suggestedAction: "Trigger manual import to bypass mapping requirements", }; } // Quality downgrade issues if ( allMessages.includes("not a custom format upgrade") || allMessages.includes("do not improve on existing") ) { return { id: item.id, title: item.title, status: item.status, category: { type: "quality_downgrade", severity: "warning", autoFixable: true, }, message: "Download is not an upgrade over existing file", suggestedAction: "Remove from queue as existing file is better quality", }; } // Network/connection errors if ( allMessages.includes("timeout") || allMessages.includes("connection") || allMessages.includes("network") || allMessages.includes("dns") ) { return { id: item.id, title: item.title, status: item.status, category: { type: "network_error", severity: "warning", autoFixable: true, }, message: "Network connectivity issue detected", suggestedAction: "Retry download after network issue resolution", }; } // Disk space issues if ( allMessages.includes("disk") && (allMessages.includes("space") || allMessages.includes("full")) ) { return { id: item.id, title: item.title, status: item.status, category: { type: "disk_space", severity: "critical", autoFixable: false, }, message: "Insufficient disk space", suggestedAction: "Free up disk space manually", }; } // Permission issues if ( allMessages.includes("permission") || allMessages.includes("access denied") ) { return { id: item.id, title: item.title, status: item.status, category: { type: "permissions", severity: "critical", autoFixable: false, }, message: "File system permission issue", suggestedAction: "Fix file permissions manually", }; } // Check if item appears stuck (downloading for too long) const isStuck = status.includes("warning") || status.includes("error") || statusMessages.length > 0; if (isStuck) { return { id: item.id, title: item.title, status: item.status, category: { type: "unknown", severity: "warning", autoFixable: false }, message: "Item appears stuck with unrecognized issue", suggestedAction: "Manual investigation required", }; } // No issues detected return { id: item.id, title: item.title, status: item.status, category: { type: "unknown", severity: "info", autoFixable: false }, message: "No issues detected", suggestedAction: "No action needed", }; }