@llmindset/hf-mcp 0.1.16

package/src/dataset-detail.ts

@@ -0,0 +1,257 @@
+import { z } from 'zod';
+import { datasetInfo } from '@huggingface/hub';
+import { formatDate, formatNumber } from './utilities.js';
+
+// Dataset Detail Tool Configuration
+export const DATASET_DETAIL_TOOL_CONFIG = {
+	name: 'dataset_details',
+	description: 'Get detailed information about a specific dataset on Hugging Face Hub.',
+	schema: z.object({
+		dataset_id: z
+			.string()
+			.min(5, 'Dataset ID is required')
+			.describe('Dataset ID (e.g. institutional/institutional-books-1.0, Anthropic/hh-rlhf etc.)'),
+	}),
+	annotations: {
+		title: 'Dataset Details',
+		destructiveHint: false,
+		readOnlyHint: true,
+		openWorldHint: false,
+	},
+} as const;
+
+export type DatasetDetailParams = z.infer<typeof DATASET_DETAIL_TOOL_CONFIG.schema>;
+
+// Clean interface design with explicit data availability
+
+// Required core information that should always be available
+interface DatasetBasicInfo {
+	id: string; // Dataset ID
+	name: string; // Dataset name
+	downloads: number;
+	likes: number;
+	private: boolean;
+	gated: false | 'auto' | 'manual';
+	updatedAt: Date;
+}
+
+// Optional but reliable information with simple types
+interface DatasetExtendedInfo {
+	author?: string;
+	downloadsAllTime?: number;
+	tags?: string[];
+	description?: string;
+}
+
+// Dataset card data with careful extraction
+interface DatasetMetadata {
+	language?: string | string[];
+	license?: string | string[];
+	task_categories?: string | string[];
+	size_categories?: string | string[];
+	dataset_info?: Record<string, unknown>;
+}
+
+// Complete dataset information structure
+interface DatasetInformation extends DatasetBasicInfo {
+	extended?: DatasetExtendedInfo;
+	metadata?: DatasetMetadata;
+}
+
+/**
+ * Service for getting detailed dataset information using the official huggingface.js library
+ */
+export class DatasetDetailTool {
+	private readonly hubUrl?: string;
+	private readonly accessToken?: string;
+
+	/**
+	 * Creates a new dataset detail service
+	 * @param hfToken Optional Hugging Face token for API access
+	 * @param hubUrl Optional custom hub URL
+	 */
+	constructor(hfToken?: string, hubUrl?: string) {
+		this.accessToken = hfToken;
+		this.hubUrl = hubUrl;
+	}
+
+	/**
+	 * Get detailed information about a specific dataset
+	 *
+	 * @param datasetId The dataset ID to get details for (e.g., squad, glue, imdb)
+	 * @returns Formatted string with dataset details
+	 */
+	async getDetails(datasetId: string): Promise<string> {
+		try {
+			// Define additional fields we want to retrieve (only those available in the hub library)
+			const additionalFields = ['author', 'downloadsAllTime', 'tags', 'description', 'cardData'] as const;
+
+			const datasetData = await datasetInfo<(typeof additionalFields)[number]>({
+				name: datasetId,
+				additionalFields: Array.from(additionalFields),
+				...(this.accessToken && { credentials: { accessToken: this.accessToken } }),
+				...(this.hubUrl && { hubUrl: this.hubUrl }),
+			});
+
+			// Build the structured dataset information
+			const datasetDetails: DatasetInformation = {
+				// Basic info (required fields)
+				id: datasetId,
+				name: datasetData.name,
+				downloads: datasetData.downloads,
+				likes: datasetData.likes,
+				private: datasetData.private,
+				gated: datasetData.gated,
+				updatedAt: datasetData.updatedAt,
+
+				// Extended info (optional but reliable fields)
+				extended: {
+					author: datasetData.author,
+					downloadsAllTime: datasetData.downloadsAllTime,
+					tags: datasetData.tags,
+					description: datasetData.description,
+				},
+			};
+
+			// Metadata from card data
+			if (datasetData.cardData) {
+				const metadata: DatasetMetadata = {};
+				const cardData = datasetData.cardData as Record<string, unknown>;
+
+				if ('language' in cardData) {
+					metadata.language = cardData.language as string | string[];
+				}
+
+				if ('license' in cardData) {
+					metadata.license = cardData.license as string | string[];
+				}
+
+				if ('task_categories' in cardData) {
+					metadata.task_categories = cardData.task_categories as string | string[];
+				}
+
+				if ('size_categories' in cardData) {
+					metadata.size_categories = cardData.size_categories as string | string[];
+				}
+
+				if ('dataset_info' in cardData) {
+					metadata.dataset_info = cardData.dataset_info as Record<string, unknown>;
+				}
+
+				// Only add metadata section if we have data
+				if (Object.keys(metadata).length > 0) {
+					datasetDetails.metadata = metadata;
+				}
+			}
+
+			// Note: siblings information is not available through the additional fields API
+			// It would require a separate API call to list files
+
+			return formatDatasetDetails(datasetDetails);
+		} catch (error) {
+			if (error instanceof Error) {
+				throw new Error(`Failed to get dataset details: ${error.message}`);
+			}
+			throw error;
+		}
+	}
+}
+
+// Formatting Function
+function formatDatasetDetails(dataset: DatasetInformation): string {
+	const r: string[] = [];
+	const [authorFromName] = dataset.name.includes('/') ? dataset.name.split('/') : ['', dataset.name];
+
+	r.push(`# ${dataset.name}`);
+	r.push('');
+
+	// Description if available
+	if (dataset.extended?.description) {
+		r.push('## Description');
+		r.push(dataset.extended.description);
+		r.push('');
+	}
+
+	// Overview section - using only reliable fields
+	r.push('## Overview');
+
+	// Author - from extended info or parsed from name
+	if (dataset.extended?.author || authorFromName) {
+		r.push(`- **Author:** ${dataset.extended?.author || authorFromName || ''}`);
+	}
+
+	// Statistics
+	const stats = [];
+	if (dataset.extended?.downloadsAllTime) {
+		stats.push(`**Downloads:** ${formatNumber(dataset.extended.downloadsAllTime)}`);
+	}
+	if (dataset.likes) {
+		stats.push(`**Likes:** ${dataset.likes.toString()}`);
+	}
+	if (stats.length > 0) {
+		r.push(`- ${stats.join(' | ')}`);
+	}
+
+	// Dates
+	r.push(`- **Updated:** ${formatDate(dataset.updatedAt)}`);
+
+	// Status indicators
+	const status = [];
+	if (dataset.gated) status.push('🔒 Gated');
+	if (dataset.private) status.push('🔐 Private');
+	if (status.length > 0) {
+		r.push(`- **Status:** ${status.join(' | ')}`);
+	}
+	r.push('');
+
+	// Tags - reliable field from extended info
+	if (dataset.extended?.tags && dataset.extended.tags.length > 0) {
+		r.push('## Tags');
+		r.push(dataset.extended.tags.map((tag) => `\`${tag}\``).join(' '));
+		r.push('');
+	}
+
+	// Metadata - carefully extracted and validated
+	if (dataset.metadata) {
+		const metadata = [];
+
+		if (dataset.metadata.language) {
+			const languages = Array.isArray(dataset.metadata.language)
+				? dataset.metadata.language.join(', ')
+				: dataset.metadata.language;
+			metadata.push(`- **Language:** ${languages}`);
+		}
+
+		if (dataset.metadata.license) {
+			const license = Array.isArray(dataset.metadata.license)
+				? dataset.metadata.license.join(', ')
+				: dataset.metadata.license;
+			metadata.push(`- **License:** ${license}`);
+		}
+
+		if (dataset.metadata.task_categories) {
+			const tasks = Array.isArray(dataset.metadata.task_categories)
+				? dataset.metadata.task_categories.join(', ')
+				: dataset.metadata.task_categories;
+			metadata.push(`- **Task Categories:** ${tasks}`);
+		}
+
+		if (dataset.metadata.size_categories) {
+			const size = Array.isArray(dataset.metadata.size_categories)
+				? dataset.metadata.size_categories.join(', ')
+				: dataset.metadata.size_categories;
+			metadata.push(`- **Size Category:** ${size}`);
+		}
+
+		if (metadata.length > 0) {
+			r.push('## Metadata');
+			r.push(...metadata);
+			r.push('');
+		}
+	}
+
+	// Link is reliable - based on dataset name which is required
+	r.push(`**Link:** [https://hf.co/datasets/${dataset.name}](https://hf.co/datasets/${dataset.name})`);
+
+	return r.join('\n');
+}

package/src/dataset-search.ts

@@ -0,0 +1,237 @@
+import { z } from 'zod';
+import { HfApiCall } from './hf-api-call.js';
+import { formatDate, formatNumber } from './utilities.js';
+const TAGS_TO_RETURN = 20;
+// Dataset Search Tool Configuration
+export const DATASET_SEARCH_TOOL_CONFIG = {
+	name: 'dataset_search',
+	description:
+		'Find Datasets hosted on the Hugging Face hub. ' +
+		'Returns comprehensive information about matching datasets including downloads, likes, tags, and direct links. ' +
+		'Include links to the datasets in your response',
+	schema: z.object({
+		query: z
+			.string()
+			.optional()
+			.describe(
+				'Search term. Leave blank and specify "sort" and "limit" to get e.g. "Top 20 trending datasets", "Top 10 most recent datasets" etc" '
+			),
+		author: z
+			.string()
+			.optional()
+			.describe("Organization or user who created the dataset (e.g., 'google', 'facebook', 'allenai')"),
+		tags: z
+			.array(z.string())
+			.optional()
+			.describe(
+				"Tags to filter datasets (e.g., ['language:en', 'size_categories:1M<n<10M', 'task_categories:text-classification'])"
+			),
+		sort: z
+			.enum(['trendingScore', 'downloads', 'likes', 'createdAt', 'lastModified'])
+			.optional()
+			.describe('Sort order: trendingScore, downloads, likes, createdAt, lastModified'),
+		limit: z.number().min(1).max(100).optional().default(20).describe('Maximum number of results to return'),
+	}),
+	annotations: {
+		title: 'Dataset Search',
+		destructiveHint: false,
+		readOnlyHint: true,
+		openWorldHint: true,
+	},
+} as const;
+
+// Define search parameter types
+export type DatasetSearchParams = z.infer<typeof DATASET_SEARCH_TOOL_CONFIG.schema>;
+
+// API parameter interface for direct HF API calls
+interface DatasetApiParams {
+	search?: string;
+	author?: string;
+	filter?: string;
+	sort?: string;
+	direction?: string;
+	limit?: string;
+}
+
+// Dataset result interface matching HF API response
+interface DatasetApiResult {
+	_id: string;
+	id: string;
+	author: string;
+	likes: number;
+	downloads: number;
+	trendingScore?: number;
+	private: boolean;
+	gated: boolean;
+	tags: string[];
+	createdAt: string;
+	lastModified: string;
+	description?: string;
+	sha: string;
+}
+/**
+ * Service for searching Hugging Face Datasets using direct API calls
+ */
+export class DatasetSearchTool extends HfApiCall<DatasetApiParams, DatasetApiResult[]> {
+	/**
+	 * @param hfToken Optional Hugging Face token for API access
+	 */
+	constructor(hfToken?: string) {
+		super('https://huggingface.co/api/datasets', hfToken);
+	}
+
+	/**
+	 * Search for datasets with detailed parameters
+	 */
+	async searchWithParams(params: Partial<DatasetSearchParams>): Promise<string> {
+		try {
+			// Convert our params to the HF API format
+			const apiParams: DatasetApiParams = {};
+
+			// Handle search query
+			if (params.query) {
+				apiParams.search = params.query;
+			}
+
+			// Handle author filter
+			if (params.author) {
+				apiParams.author = params.author;
+			}
+
+			// Handle tags filter
+			if (params.tags && params.tags.length > 0) {
+				apiParams.filter = params.tags.join(',');
+			}
+
+			// Handle sorting (always descending)
+			if (params.sort) {
+				apiParams.sort = params.sort;
+				apiParams.direction = '-1';
+			}
+
+			// Handle limit
+			if (params.limit) {
+				apiParams.limit = params.limit.toString();
+			}
+
+			// Call the API
+			const datasets = await this.callApi<DatasetApiResult[]>(apiParams);
+
+			if (datasets.length === 0) {
+				return `No datasets found for the given criteria.`;
+			}
+
+			return formatSearchResults(datasets, params);
+		} catch (error) {
+			if (error instanceof Error) {
+				throw new Error(`Failed to search for datasets: ${error.message}`);
+			}
+			throw error;
+		}
+	}
+
+	/**
+	 * Search for datasets with a specific filter (e.g., arxiv:XXXX.XXXXX)
+	 */
+	async searchWithFilter(filter: string, limit: number = 10): Promise<string> {
+		try {
+			const apiParams: DatasetApiParams = {
+				filter: filter,
+				limit: limit.toString(),
+				sort: 'downloads',
+				direction: '-1',
+			};
+
+			// Call the API
+			const datasets = await this.callApi<DatasetApiResult[]>(apiParams);
+
+			if (datasets.length === 0) {
+				return `No datasets found referencing ${filter}.`;
+			}
+
+			return formatSearchResults(datasets, { limit });
+		} catch (error) {
+			if (error instanceof Error) {
+				throw new Error(`Failed to search for datasets: ${error.message}`);
+			}
+			throw error;
+		}
+	}
+}
+
+// Formatting Function
+function formatSearchResults(datasets: DatasetApiResult[], params: Partial<DatasetSearchParams>): string {
+	const r: string[] = [];
+
+	// Build search description
+	const searchTerms = [];
+	if (params.query) searchTerms.push(`query "${params.query}"`);
+	if (params.author) searchTerms.push(`author "${params.author}"`);
+	if (params.tags && params.tags.length > 0) searchTerms.push(`tags [${params.tags.join(', ')}]`);
+	if (params.sort) searchTerms.push(`sorted by ${params.sort} (descending)`);
+
+	const searchDesc = searchTerms.length > 0 ? ` matching ${searchTerms.join(', ')}` : '';
+
+	const resultText =
+		datasets.length === params.limit
+			? `Showing first ${datasets.length.toString()} datasets${searchDesc}:`
+			: `Found ${datasets.length.toString()} datasets${searchDesc}:`;
+	r.push(resultText);
+	r.push('');
+
+	for (const dataset of datasets) {
+		r.push(`## ${dataset.id}`);
+		r.push('');
+
+		// Description if available
+		if (dataset.description) {
+			r.push(`${dataset.description.substring(0, 200)}${dataset.description.length > 200 ? '...' : ''}`);
+			r.push('');
+		}
+
+		// Basic info line
+		const info = [];
+		if (dataset.downloads) info.push(`**Downloads:** ${formatNumber(dataset.downloads)}`);
+		if (dataset.likes) info.push(`**Likes:** ${dataset.likes.toString()}`);
+		if (dataset.trendingScore) info.push(`**Trending Score:** ${dataset.trendingScore.toString()}`);
+
+		if (info.length > 0) {
+			r.push(info.join(' | '));
+			r.push('');
+		}
+
+		// Tags
+		if (dataset.tags && dataset.tags.length > 0) {
+			r.push(`**Tags:** ${dataset.tags.slice(0, TAGS_TO_RETURN).join(', ')}`);
+			if (dataset.tags.length > TAGS_TO_RETURN) {
+				r.push(`*and ${(dataset.tags.length - TAGS_TO_RETURN).toString()} more...*`);
+			}
+			r.push('');
+		}
+
+		// Status indicators
+		const status = [];
+		if (dataset.gated) status.push('🔒 Gated');
+		if (dataset.private) status.push('🔐 Private');
+		if (status.length > 0) {
+			r.push(status.join(' | '));
+			r.push('');
+		}
+
+		// Dates
+		if (dataset.createdAt) {
+			r.push(`**Created:** ${formatDate(dataset.createdAt)}`);
+		}
+
+		if (dataset.lastModified && dataset.lastModified !== dataset.createdAt) {
+			r.push(`**Last Modified:** ${formatDate(dataset.lastModified)}`);
+		}
+
+		r.push(`**Link:** [https://hf.co/datasets/${dataset.id}](https://hf.co/datasets/${dataset.id})`);
+		r.push('');
+		r.push('---');
+		r.push('');
+	}
+
+	return r.join('\n');
+}