@llmindset/hf-mcp 0.1.16

package/src/space-files.ts

@@ -0,0 +1,325 @@
+import { z } from 'zod';
+import { listFiles, spaceInfo } from '@huggingface/hub';
+import { formatBytes, escapeMarkdown } from './utilities.js';
+import { HfApiError } from './hf-api-call.js';
+import { explain } from './error-messages.js';
+
+// Define the FileWithUrl interface
+export interface FileWithUrl {
+	path: string;
+	size: number;
+	type: 'file' | 'directory' | 'unknown';
+	url: string;
+	sizeFormatted: string;
+	lastModified?: string;
+	lfs: boolean;
+}
+
+// File type detection helpers
+const IMAGE_EXTENSIONS = new Set([
+	'.jpg',
+	'.jpeg',
+	'.png',
+	'.gif',
+	'.bmp',
+	'.tiff',
+	'.tif',
+	'.webp',
+	'.svg',
+	'.ico',
+	'.heic',
+	'.heif',
+]);
+
+const AUDIO_EXTENSIONS = new Set([
+	'.mp3',
+	'.wav',
+	'.flac',
+	'.aac',
+	'.ogg',
+	'.m4a',
+	'.wma',
+	'.opus',
+	'.aiff',
+	'.au',
+	'.ra',
+]);
+
+function getFileExtension(path: string): string {
+	const lastDot = path.lastIndexOf('.');
+	return lastDot === -1 ? '' : path.substring(lastDot).toLowerCase();
+}
+
+function isImageFile(path: string): boolean {
+	return IMAGE_EXTENSIONS.has(getFileExtension(path));
+}
+
+function isAudioFile(path: string): boolean {
+	return AUDIO_EXTENSIONS.has(getFileExtension(path));
+}
+
+function matchesFileType(file: FileWithUrl, fileType: 'all' | 'image' | 'audio'): boolean {
+	switch (fileType) {
+		case 'all':
+			return true;
+		case 'image':
+			return isImageFile(file.path);
+		case 'audio':
+			return isAudioFile(file.path);
+		default:
+			return true;
+	}
+}
+
+// Tool configuration
+export const SPACE_FILES_TOOL_CONFIG = {
+	name: 'space_files',
+	description: '', // This will be dynamically set with username
+	schema: z.object({
+		spaceName: z.string().optional().describe('Space identifier in format "username/spacename"'),
+		fileType: z
+			.enum(['all', 'image', 'audio'])
+			.optional()
+			.default('all')
+			.describe('Filter files by type: all (default), image, or audio files only'),
+	}),
+	annotations: {
+		title: 'Space Files List',
+		destructiveHint: false,
+		readOnlyHint: true,
+		openWorldHint: true,
+	},
+} as const;
+
+// Define parameter types
+export type SpaceFilesParams = z.infer<typeof SPACE_FILES_TOOL_CONFIG.schema>;
+
+/**
+ * Service for listing files in Hugging Face Spaces
+ */
+export class SpaceFilesTool {
+	private readonly accessToken?: string;
+	private readonly username?: string;
+
+	constructor(hfToken?: string, username?: string) {
+		this.accessToken = hfToken;
+		this.username = username;
+	}
+
+	static createToolConfig(username?: string): typeof SPACE_FILES_TOOL_CONFIG {
+		const description = username
+			? `Defaults to ${username}/filedrop. List files in a static Hugging Face Space. Use the URL for specifying Files inputs to Gradio endpoints or downloading files`
+			: `List all files in a static Hugging Face Space. Use the URL for specifying Files inputs to Gradio endpoints or downloading files.`;
+		return {
+			...SPACE_FILES_TOOL_CONFIG,
+			description: description as '',
+		};
+	}
+
+	/**
+	 * Get all files in a space with their URLs
+	 */
+	async getSpaceFilesWithUrls(spaceName: string): Promise<FileWithUrl[]> {
+		try {
+			// Get space info to determine subdomain
+			const space = await spaceInfo({
+				name: spaceName,
+				additionalFields: ['subdomain'],
+				...(this.accessToken && { accessToken: this.accessToken }),
+			});
+
+			// Check if it's a static space
+			if (space.sdk !== 'static') {
+				throw new Error(
+					`Space "${spaceName}" is not a static space (found: ${space.sdk}). This tool only works with static spaces.`
+				);
+			}
+
+			const files: FileWithUrl[] = [];
+
+			// List all files recursively
+			for await (const file of listFiles({
+				repo: { type: 'space', name: spaceName },
+				recursive: true,
+				expand: true, // Get last commit info
+				...(this.accessToken && { credentials: { accessToken: this.accessToken } }),
+			})) {
+				if (file.type === 'file') {
+					files.push({
+						path: file.path,
+						size: file.size,
+						type: file.type,
+						url: this.constructFileUrl(spaceName, file.path),
+						sizeFormatted: formatBytes(file.size),
+						lastModified: file.lastCommit?.date,
+						lfs: !!file.lfs,
+					});
+				}
+			}
+
+			return files.sort((a, b) => a.path.localeCompare(b.path));
+		} catch (error) {
+			if (error instanceof HfApiError) {
+				throw explain(error, `Failed to list files for space "${spaceName}"`);
+			}
+			throw error;
+		}
+	}
+
+	/**
+	 * Construct the URL for a file
+	 */
+	private constructFileUrl(spaceName: string, filePath: string): string {
+		return `https://huggingface.co/spaces/${spaceName}/resolve/main/${filePath}`;
+	}
+
+	/**
+	 * Generate detailed markdown report with files grouped by directory
+	 */
+	async generateDetailedMarkdown(spaceName: string, fileType: 'all' | 'image' | 'audio' = 'all'): Promise<string> {
+		const allFiles = await this.getSpaceFilesWithUrls(spaceName);
+		const files = allFiles.filter((file) => matchesFileType(file, fileType));
+
+		let markdown = `# Files in Space: ${spaceName}\n\n`;
+		if (fileType !== 'all') {
+			markdown += `**Filter**: ${fileType} files only\n`;
+		}
+		markdown += `**Total Files**: ${files.length}\n`;
+		markdown += `**Total Size**: ${formatBytes(files.reduce((sum, f) => sum + f.size, 0))}\n\n`;
+
+		// Handle empty results
+		if (files.length === 0) {
+			if (fileType !== 'all') {
+				markdown += `No ${fileType} files found in this space.\n`;
+			} else {
+				markdown += `No files found in this space.\n`;
+			}
+			return markdown;
+		}
+
+		// Group files by directory
+		const byDirectory = files.reduce(
+			(acc, file) => {
+				const dir = file.path.includes('/') ? file.path.substring(0, file.path.lastIndexOf('/')) : '/';
+				if (!acc[dir]) acc[dir] = [];
+				acc[dir].push(file);
+				return acc;
+			},
+			{} as Record<string, FileWithUrl[]>
+		);
+
+		// Generate table
+		markdown += `## All Files\n\n`;
+		markdown += `| File Path | Size | Type | Last Modified | URL |\n`;
+		markdown += `|-----------|------|------|---------------|-----|\n`;
+
+		// Sort directories and output files
+		const sortedDirs = Object.keys(byDirectory).sort();
+		for (const dir of sortedDirs) {
+			const dirFiles = byDirectory[dir];
+			if (!dirFiles) continue;
+
+			if (dir !== '/' && dirFiles.length > 0) {
+				markdown += `| **📁 ${escapeMarkdown(dir)}/** | | | | |\n`;
+			}
+
+			for (const file of dirFiles) {
+				const fileName = file.path.split('/').pop() || file.path;
+				const indent = dir === '/' ? '' : '&nbsp;&nbsp;&nbsp;&nbsp;';
+				const icon = this.getFileIcon(fileName);
+				const lastMod = file.lastModified ? new Date(file.lastModified).toLocaleDateString() : '-';
+
+				markdown += `| ${indent}${icon} ${escapeMarkdown(fileName)} | ${file.sizeFormatted} | ${file.lfs ? 'LFS' : 'Regular'} | ${lastMod} | ${file.url} |\n`;
+			}
+		}
+
+		// Add direct access examples
+		markdown += `\n## Direct Access Examples\n\n`;
+		markdown += `\`\`\`bash\n`;
+
+		// Show a few example URLs
+		const examples = files.slice(0, 2);
+		for (const file of examples) {
+			markdown += `# Download ${file.path}\n`;
+			markdown += `curl -L -O ${file.url}\n\n`;
+		}
+		markdown += `\`\`\`\n`;
+		markdown += '## Use the URL when specifying Files inputs for Gradio endpoints.\n\n';
+		markdown += 'This space is accessible via `git` with `git clone https://huggingface.co/spaces/' + spaceName + '`\n';
+		return markdown;
+	}
+
+	/**
+	 * Generate simple markdown table without grouping
+	 */
+	async generateSimpleMarkdown(spaceName: string, fileType: 'all' | 'image' | 'audio' = 'all'): Promise<string> {
+		const allFiles = await this.getSpaceFilesWithUrls(spaceName);
+		const files = allFiles.filter((file) => matchesFileType(file, fileType));
+
+		let markdown = `# Files in ${spaceName}\n\n`;
+		if (fileType !== 'all') {
+			markdown += `**Filter**: ${fileType} files only\n\n`;
+		}
+		markdown += `| File Name | Path | Size | URL |\n`;
+		markdown += `|-----------|------|------|-----|\n`;
+
+		for (const file of files) {
+			const fileName = file.path.split('/').pop() || file.path;
+			const icon = this.getFileIcon(fileName);
+			markdown += `| ${icon} ${escapeMarkdown(fileName)} | ${escapeMarkdown(file.path)} | ${file.sizeFormatted} | [Link](${file.url}) |\n`;
+		}
+
+		return markdown;
+	}
+
+	/**
+	 * List files with the specified format
+	 */
+	async listFiles(params: SpaceFilesParams): Promise<string> {
+		const { fileType = 'all' } = params;
+
+		// Use provided spaceName or default to username/filedrop
+		const spaceName = params.spaceName || (this.username ? `${this.username}/filedrop` : 'filedrop');
+
+		return this.generateDetailedMarkdown(spaceName, fileType);
+	}
+
+	/**
+	 * Get file icon based on extension
+	 */
+	private getFileIcon(filename: string): string {
+		const ext = filename.split('.').pop()?.toLowerCase();
+		const iconMap: Record<string, string> = {
+			py: '🐍',
+			js: '📜',
+			ts: '📘',
+			md: '📝',
+			txt: '📄',
+			json: '📊',
+			yaml: '⚙️',
+			yml: '⚙️',
+			png: '🖼️',
+			jpg: '🖼️',
+			jpeg: '🖼️',
+			gif: '🖼️',
+			svg: '🎨',
+			mp4: '🎬',
+			mp3: '🎵',
+			pdf: '📕',
+			zip: '📦',
+			tar: '📦',
+			gz: '📦',
+			html: '🌐',
+			css: '🎨',
+			ipynb: '📓',
+			csv: '📊',
+			parquet: '🗄️',
+			safetensors: '🤖',
+			bin: '💾',
+			pkl: '🥒',
+			h5: '🗃️',
+		};
+
+		return iconMap[ext || ''] || '📄';
+	}
+}

package/src/space-info.ts

@@ -0,0 +1,190 @@
+import { z } from 'zod';
+import { HfApiCall } from './hf-api-call.js';
+import { listSpaces } from '@huggingface/hub';
+import type { SpaceEntry, SpaceRuntime, SpaceSdk } from '@huggingface/hub';
+import { formatDate, formatNumber, escapeMarkdown, NO_TOKEN_INSTRUCTIONS } from './utilities.js';
+
+interface SpaceReport {
+	user: string;
+	generatedAt: Date;
+	totalSpaces: number;
+	publicSpaces: number;
+	privateSpaces: number;
+	runningSpaces: number;
+	totalLikes: number;
+	sdkCounts: Record<string, number>;
+	spaces: SpaceDetails[];
+}
+
+interface SpaceDetails {
+	name: string;
+	url: string;
+	sdk: SpaceSdk | 'unknown'; // Allow 'unknown' in our internal type
+	status: SpaceRuntime['stage'] | 'UNKNOWN';
+	statusEmoji: string;
+	hardware: string;
+	storage: string;
+	visibility: string;
+	likes: number;
+	lastModified: string;
+}
+
+const STATUS_EMOJI: Record<string, string> = {
+	RUNNING: '🟢 Running',
+	RUNNING_BUILDING: '🔄 Building',
+	SLEEPING: '😴 Sleeping',
+	PAUSED: '⏸️ Paused',
+	STOPPED: '⏹️ Stopped',
+	RUNTIME_ERROR: '❌ Error',
+	BUILD_ERROR: '🚫 Build Error',
+	BUILDING: '🔨 Building',
+	NO_APP_FILE: '📄 No App',
+	CONFIG_ERROR: '⚙️ Config Error',
+	DELETING: '🗑️ Deleting',
+};
+
+export interface SpaceInfoParams {
+	username?: string;
+}
+
+export const SPACE_INFO_TOOL_CONFIG = {
+	name: 'space_info',
+	description: '', // This will be dynamically set based on auth
+	schema: z.object({
+		username: z.string().optional().describe('Username to get spaces for (defaults to authenticated user)'),
+	}),
+	annotations: {
+		title: 'Hugging Face Spaces Information',
+		destructiveHint: false,
+		readOnlyHint: true,
+		openWorldHint: false,
+	},
+} as const;
+
+export class SpaceInfoTool extends HfApiCall<SpaceInfoParams, SpaceReport> {
+	private authenticatedUsername?: string;
+
+	constructor(hfToken?: string, authenticatedUsername?: string) {
+		super('https://huggingface.co/api', hfToken);
+		this.authenticatedUsername = authenticatedUsername;
+	}
+
+	static createToolConfig(username?: string): typeof SPACE_INFO_TOOL_CONFIG {
+		const description = username
+			? `Tabluate Hugging Face Spaces information for ${username}, or another User.`
+			: `Tabluate public Hugging Face Spaces for a specific User. Supply a Hugging Face token or go to https://hf.co/join to create an account to view your own private Spaces.`;
+		return {
+			...SPACE_INFO_TOOL_CONFIG,
+			description: description as '',
+		};
+	}
+
+	async getSpacesReport(targetUsername?: string): Promise<string> {
+		// TODO -- think a bit more about this exact condition
+		if (!this.authenticatedUsername && !targetUsername) throw new Error(NO_TOKEN_INSTRUCTIONS);
+
+		const username = targetUsername || this.authenticatedUsername || 'error';
+		const spaces: SpaceEntry[] = [];
+		const spacesWithRuntime: SpaceDetails[] = [];
+
+		try {
+			// Fetch all spaces for the user with runtime info in a single request
+			for await (const space of listSpaces({
+				search: { owner: username },
+				additionalFields: ['runtime', 'subdomain'] as const,
+				accessToken: this.hfToken,
+			})) {
+				spaces.push(space);
+
+				// Use runtime data directly from listSpaces response
+				const runtime = space.runtime;
+				const hardware = runtime?.hardware?.current || 'cpu-basic';
+
+				spacesWithRuntime.push({
+					name: space.name.split('/')[1] || space.name,
+					url: `https://huggingface.co/spaces/${space.name}`,
+					sdk: space.sdk || 'unknown',
+					status: runtime?.stage || 'UNKNOWN',
+					statusEmoji: STATUS_EMOJI[runtime?.stage || 'STOPPED'] || '❓ Unknown',
+					hardware: hardware,
+					storage: runtime?.resources?.requests?.ephemeral || 'None',
+					visibility: space.private ? '🔒 Private' : '🌍 Public',
+					likes: space.likes,
+					lastModified: space.updatedAt ? formatDate(space.updatedAt) : 'Unknown',
+				});
+			}
+
+			// Calculate statistics
+			const report: SpaceReport = {
+				user: username,
+				generatedAt: new Date(),
+				totalSpaces: spaces.length,
+				publicSpaces: spaces.filter((s) => !s.private).length,
+				privateSpaces: spaces.filter((s) => s.private).length,
+				runningSpaces: spacesWithRuntime.filter((s) => s.status === 'RUNNING').length,
+				totalLikes: spaces.reduce((sum, s) => sum + s.likes, 0),
+				sdkCounts: spaces.reduce(
+					(acc, s) => {
+						const sdk = s.sdk || 'unknown';
+						acc[sdk] = (acc[sdk] || 0) + 1;
+						return acc;
+					},
+					{} as Record<string, number>
+				),
+				spaces: spacesWithRuntime.sort((a, b) => b.lastModified.localeCompare(a.lastModified)),
+			};
+
+			// Generate markdown report
+			return this.generateMarkdown(report);
+		} catch (error) {
+			if (error instanceof Error) {
+				throw new Error(`Failed to get spaces information: ${error.message}`);
+			}
+			throw error;
+		}
+	}
+
+	private generateMarkdown(report: SpaceReport): string {
+		// Handle case where user has no spaces
+		if (report.totalSpaces === 0) {
+			return `# Hugging Face Spaces Report
+**User**: ${report.user}
+**Generated**: ${formatDate(report.generatedAt)}
+
+No spaces were found for user '${report.user}'.
+
+You can create your first Space at [https://huggingface.co/new-space](https://huggingface.co/new-space).`;
+		}
+
+		const sdkSummary = Object.entries(report.sdkCounts)
+			.filter(([_, count]) => count > 0)
+			.map(([sdk, count]) => `${sdk} (${count})`)
+			.join(', ');
+
+		let markdown = `# Hugging Face Spaces Report
+**User**: ${report.user}
+**Generated**: ${formatDate(report.generatedAt)}
+
+## Summary
+- **Total Spaces**: ${report.totalSpaces}
+- **Public**: ${report.publicSpaces}${report.privateSpaces > 0 ? ` | **Private**: ${report.privateSpaces}` : ''}
+- **Currently Running**: ${report.runningSpaces}
+- **Total Likes**: ${formatNumber(report.totalLikes)}
+- **SDKs**: ${sdkSummary || 'None'}
+
+## All Spaces
+| Space | SDK | Status | Hardware | Storage | Visibility | Likes ❤️ | Last Modified |
+|-------|-----|--------|----------|---------|------------|----------|--------------|\n`;
+
+		// Add each space as a table row
+		for (const space of report.spaces) {
+			markdown += `| [${escapeMarkdown(space.name)}](${space.url}) | ${escapeMarkdown(space.sdk)} | ${space.statusEmoji} | ${escapeMarkdown(space.hardware)} | ${escapeMarkdown(space.storage)} | ${space.visibility} | ${space.likes} | ${space.lastModified} |\n`;
+		}
+
+		return markdown;
+	}
+}
+
+export const formatSpaceInfoResult = async (tool: SpaceInfoTool, params: SpaceInfoParams): Promise<string> => {
+	return tool.getSpacesReport(params.username);
+};

package/src/space-search.ts

@@ -0,0 +1,177 @@
+import { z } from 'zod';
+import { HfApiCall } from './hf-api-call.js';
+import { escapeMarkdown } from './utilities.js';
+
+// Define the SearchResult interface
+export interface SpaceSearchResult {
+	id: string;
+	emoji?: string; // Emoji for the space
+	likes?: number;
+	title?: string;
+	author: string;
+	runtime: {
+		stage?: string; // always seems to be "RUNNING"
+	};
+	ai_category?: string;
+	ai_short_description?: string;
+	shortDescription?: string;
+	semanticRelevancyScore?: number; // Score from semantic search API
+	trendingScore?: number;
+	lastModified?: Date;
+}
+
+// Define input types for space search
+interface SpaceSearchParams {
+	q: string;
+	sdk: string;
+	filter?: string;
+}
+
+// Default number of results to return
+const RESULTS_TO_RETURN = 10;
+
+export const SEMANTIC_SEARCH_TOOL_CONFIG = {
+	name: 'space_search',
+	description:
+		'Find Hugging Face Spaces using semantic search. ' + 'Include links to the Space when presenting the results.',
+	schema: z.object({
+		query: z.string().min(1, 'Query is required').max(100, 'Query too long').describe('Semantic Search Query'),
+		limit: z.number().optional().default(RESULTS_TO_RETURN).describe('Number of results to return'),
+		mcp: z.boolean().optional().default(false).describe('Only return MCP Server enabled Spaces'),
+	}),
+	annotations: {
+		title: 'Hugging Face Space Search',
+		destructiveHint: false,
+		readOnlyHint: true,
+		openWorldHint: true,
+	},
+} as const;
+
+/**
+ * Service for searching Hugging Face Spaces semantically
+ */
+export class SpaceSearchTool extends HfApiCall<SpaceSearchParams, SpaceSearchResult[]> {
+	/**
+	 * Creates a new semantic search service
+	 * @param apiUrl The URL of the Hugging Face semantic search API
+	 * @param hfToken Optional Hugging Face token for API access
+	 */
+	constructor(hfToken?: string, apiUrl = 'https://huggingface.co/api/spaces/semantic-search') {
+		super(apiUrl, hfToken);
+	}
+
+	/**
+	 * Performs a semantic search on Hugging Face Spaces
+	 * @param query The search query
+	 * @param limit Maximum number of results to return
+	 * @returns An array of search results
+	 */
+	async search(
+		query: string,
+		limit: number = RESULTS_TO_RETURN,
+		mcp: boolean = false
+	): Promise<{ results: SpaceSearchResult[]; totalCount: number }> {
+		try {
+			// Validate input before making API call
+			if (!query) {
+				return { results: [], totalCount: 0 };
+			}
+
+			// Prepare API parameters, adding the filter if mcp is true
+			const params: SpaceSearchParams = { q: query, sdk: 'gradio' };
+
+			if (mcp) {
+				params.filter = 'mcp-server';
+			}
+
+			const results = await this.callApi<SpaceSearchResult[]>(params);
+
+			return { results: results.slice(0, limit), totalCount: results.length };
+		} catch (error) {
+			if (error instanceof Error) {
+				throw new Error(`Failed to search for spaces: ${error.message}`);
+			}
+			throw error;
+		}
+	}
+
+	/**
+	 * Search for spaces with a specific filter (e.g., arxiv:XXXX.XXXXX)
+	 * Note: For spaces, we need to use the regular API endpoint with filter parameter
+	 */
+	async searchWithFilter(filter: string, limit: number = 10, headerLevel: number = 1): Promise<string> {
+		try {
+			// For spaces, we need to use the regular spaces API endpoint with filter
+			const url = new URL('https://huggingface.co/api/spaces');
+			url.searchParams.append('filter', filter);
+			url.searchParams.append('limit', limit.toString());
+			url.searchParams.append('sort', 'likes');
+			url.searchParams.append('direction', '-1');
+
+			const results = await this.fetchFromApi<SpaceSearchResult[]>(url);
+
+			if (results.length === 0) {
+				return `No matching Hugging Face Spaces found referencing ${filter}.`;
+			}
+
+			// Format results using the existing formatter
+			return formatSearchResults(filter, results, results.length, headerLevel);
+		} catch (error) {
+			if (error instanceof Error) {
+				throw new Error(`Failed to search for spaces: ${error.message}`);
+			}
+			throw error;
+		}
+	}
+}
+
+// Create a schema validator for search parameters
+export const SearchParamsSchema = SEMANTIC_SEARCH_TOOL_CONFIG.schema;
+
+export type SearchParams = z.infer<typeof SEMANTIC_SEARCH_TOOL_CONFIG.schema>;
+
+/**
+ * Formats search results as a markdown table for MCP friendly output
+ * @param results The search results to format
+ * @returns A markdown formatted string with the search results
+ */
+export const formatSearchResults = (
+	query: string,
+	results: SpaceSearchResult[],
+	totalCount: number,
+	headerLevel: number = 1
+): string => {
+	if (results.length === 0) {
+		return `No matching Hugging Face Spaces found for the query '${query}'. Try a different query.`;
+	}
+
+	const showingText =
+		results.length < totalCount
+			? `Showing ${results.length.toString()} of ${totalCount.toString()} results`
+			: `All ${results.length.toString()} results`;
+	const headerPrefix = '#'.repeat(headerLevel);
+	let markdown = `${headerPrefix} Space Search Results for the query '${query}' (${showingText})\n\n`;
+	markdown += '| Space | Description | Author | ID | Category |  Likes | Trending Score | Relevance |\n';
+	markdown += '|-------|-------------|--------|----|----------|--------|----------------|-----------|\n';
+
+	for (const result of results) {
+		const title = result.title || 'Untitled';
+		const description = result.shortDescription || result.ai_short_description || 'No description';
+		const author = result.author || 'Unknown';
+		const id = result.id || '';
+		const emoji = result.emoji ? escapeMarkdown(result.emoji) + ' ' : '';
+		const relevance = result.semanticRelevancyScore ? (result.semanticRelevancyScore * 100).toFixed(1) + '%' : 'N/A';
+
+		markdown +=
+			`| ${emoji}[${escapeMarkdown(title)}](https://hf.co/spaces/${id}) ` +
+			`| ${escapeMarkdown(description)} ` +
+			`| ${escapeMarkdown(author)} ` +
+			`| \`${escapeMarkdown(id)}\` ` +
+			`| \`${escapeMarkdown(result.ai_category ?? '-')}\` ` +
+			`| ${escapeMarkdown(result.likes?.toString() ?? '-')} ` +
+			`| ${escapeMarkdown(result.trendingScore?.toString() ?? '-')} ` +
+			`| ${relevance} |\n`;
+	}
+
+	return markdown;
+};