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",
  	};
  }