@llmindset/hf-mcp 0.1.16

package/src/model-detail.ts

@@ -0,0 +1,359 @@
+import { z } from 'zod';
+import { modelInfo } from '@huggingface/hub';
+import { formatDate, formatNumber } from './utilities.js';
+
+const SPACES_TO_INCLUDE = 12;
+// Model Detail Tool Configuration
+export const MODEL_DETAIL_TOOL_CONFIG = {
+	name: 'model_details',
+	description: 'Get detailed information about a specific model from the Hugging Face Hub.',
+	schema: z.object({
+		model_id: z.string().min(1, 'Model ID is required').describe('Model ID (e.g., microsoft/DialoGPT-large)'),
+	}),
+	annotations: {
+		title: 'Model Details',
+		destructiveHint: false,
+		readOnlyHint: true,
+		openWorldHint: false,
+	},
+} as const;
+
+export type ModelDetailParams = z.infer<typeof MODEL_DETAIL_TOOL_CONFIG.schema>;
+
+// Clean interface design with explicit data availability
+
+// Required core information that should always be available
+interface ModelBasicInfo {
+	id: string; // Model ID
+	name: string; // Model name
+	downloads: number;
+	likes: number;
+	private: boolean;
+	gated: false | 'auto' | 'manual';
+	updatedAt: Date;
+}
+
+// Optional but reliable information with simple types
+interface ModelExtendedInfo {
+	author?: string;
+	library_name?: string;
+	pipeline_tag?: string; // Task type
+	downloadsAllTime?: number;
+	tags?: string[];
+}
+
+// Technical details that need validation
+interface ModelTechnicalDetails {
+	modelType?: string; // From config.model_type if exists
+	vocabSize?: number; // From config.vocab_size if exists
+	parameters?: number; // From safetensors.total if exists
+	modelClass?: string; // From transformersInfo.auto_model if exists
+}
+
+// Metadata from cardData with careful extraction
+interface ModelMetadata {
+	language?: string | string[];
+	license?: string | string[];
+	datasets?: string | string[];
+	fineTunedFrom?: string;
+}
+
+// Complete model information structure
+interface ModelInformation extends ModelBasicInfo {
+	extended?: ModelExtendedInfo;
+	technical?: ModelTechnicalDetails;
+	metadata?: ModelMetadata;
+	spaces?: Array<{
+		id: string;
+		name: string;
+		title?: string;
+	}>;
+}
+
+/**
+ * Service for getting detailed model information using the official huggingface.js library
+ */
+export class ModelDetailTool {
+	private readonly hubUrl?: string;
+	private readonly accessToken?: string;
+
+	/**
+	 * Creates a new model 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 model
+	 *
+	 * @param modelId The model ID to get details for (e.g., microsoft/DialoGPT-large)
+	 * @returns Formatted string with model details
+	 */
+	async getDetails(modelId: string): Promise<string> {
+		try {
+			// Define additional fields we want to retrieve (only those available in the hub library)
+			const additionalFields = [
+				'author',
+				'downloadsAllTime',
+				'library_name',
+				'tags',
+				'config',
+				'transformersInfo',
+				'safetensors',
+				'cardData',
+				'spaces',
+			] as const;
+
+			const modelData = await modelInfo<(typeof additionalFields)[number]>({
+				name: modelId,
+				additionalFields: Array.from(additionalFields),
+				...(this.accessToken && { credentials: { accessToken: this.accessToken } }),
+				...(this.hubUrl && { hubUrl: this.hubUrl }),
+			});
+
+			// Build the structured model information
+			const modelDetails: ModelInformation = {
+				// Basic info (required fields)
+				id: modelId,
+				name: modelData.name,
+				downloads: modelData.downloads,
+				likes: modelData.likes,
+				private: modelData.private,
+				gated: modelData.gated,
+				updatedAt: modelData.updatedAt,
+
+				// Extended info (optional but reliable fields)
+				extended: {
+					author: modelData.author,
+					library_name: modelData.library_name,
+					pipeline_tag: modelData.task,
+					downloadsAllTime: modelData.downloadsAllTime,
+					tags: modelData.tags,
+				},
+			};
+
+			// Technical details (requires validation)
+			const technical: ModelTechnicalDetails = {};
+
+			// Extract config details safely if they exist
+			if (modelData.config && typeof modelData.config === 'object') {
+				const config = modelData.config as Record<string, unknown>;
+				if ('model_type' in config && typeof config.model_type === 'string') {
+					technical.modelType = config.model_type;
+				}
+				if ('vocab_size' in config && typeof config.vocab_size === 'number') {
+					technical.vocabSize = config.vocab_size;
+				}
+			}
+
+			// Extract safe tensors info
+			if (modelData.safetensors && typeof modelData.safetensors.total === 'number') {
+				technical.parameters = modelData.safetensors.total;
+			}
+
+			// Extract transformers info
+			if (modelData.transformersInfo && modelData.transformersInfo.auto_model) {
+				technical.modelClass = modelData.transformersInfo.auto_model;
+			}
+
+			// Only add technical section if we have data
+			if (Object.keys(technical).length > 0) {
+				modelDetails.technical = technical;
+			}
+
+			// Metadata from card data
+			if (modelData.cardData) {
+				const metadata: ModelMetadata = {};
+				const cardData = modelData.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 ('datasets' in cardData) {
+					metadata.datasets = cardData.datasets as string | string[];
+				}
+
+				if ('finetuned_from' in cardData) {
+					metadata.fineTunedFrom = cardData.finetuned_from as string;
+				}
+
+				// Only add metadata section if we have data
+				if (Object.keys(metadata).length > 0) {
+					modelDetails.metadata = metadata;
+				}
+			}
+
+			// Extract spaces information if available
+			const spaces = modelData.spaces;
+			if (Array.isArray(spaces) && spaces.length > 0) {
+				try {
+					modelDetails.spaces = spaces.map((spaceId) => {
+						// Format is typically username/spacename
+						const parts = spaceId.split('/');
+						const name = parts.length > 1 ? parts[1] : spaceId;
+						return {
+							id: spaceId,
+							name: name || spaceId, // Ensure name is always a string
+							title: name, // Default to name if title not available
+						};
+					});
+					// eslint-disable-next-line @typescript-eslint/no-unused-vars
+				} catch (ignoreUnformattedSpaces) {
+					console.error(`Error processing spaces for model ${modelId}:`);
+				}
+			}
+
+			return formatModelDetails(modelDetails);
+		} catch (error) {
+			if (error instanceof Error) {
+				throw new Error(`Failed to get model details: ${error.message}`);
+			}
+			throw error;
+		}
+	}
+}
+
+// Formatting Function
+function formatModelDetails(model: ModelInformation): string {
+	const r: string[] = [];
+	const [authorFromName] = model.name.includes('/') ? model.name.split('/') : ['', model.name];
+
+	r.push(`# ${model.name}`);
+	r.push('');
+
+	// Overview section - using only reliable fields
+	r.push('## Overview');
+
+	// Author - from extended info or parsed from name
+	if (model.extended?.author || authorFromName) {
+		r.push(`- **Author:** ${model.extended?.author || authorFromName || ''}`);
+	}
+
+	// Task type
+	if (model.extended?.pipeline_tag) {
+		r.push(`- **Task:** ${model.extended.pipeline_tag}`);
+	}
+
+	// Library
+	if (model.extended?.library_name) {
+		r.push(`- **Library:** ${model.extended.library_name}`);
+	}
+
+	// Statistics
+	const stats = [];
+	if (model.extended?.downloadsAllTime) {
+		stats.push(`**Downloads:** ${formatNumber(model.extended.downloadsAllTime)}`);
+	}
+	if (model.likes) {
+		stats.push(`**Likes:** ${model.likes.toString()}`);
+	}
+	if (stats.length > 0) {
+		r.push(`- ${stats.join(' | ')}`);
+	}
+
+	// Dates
+	r.push(`- **Updated:** ${formatDate(model.updatedAt)}`);
+
+	// Status indicators
+	const status = [];
+	if (model.gated) status.push('🔒 Gated');
+	if (model.private) status.push('🔐 Private');
+	if (status.length > 0) {
+		r.push(`- **Status:** ${status.join(' | ')}`);
+	}
+	r.push('');
+
+	// Technical Details - only if we have validated information
+	if (model.technical && Object.keys(model.technical).length > 0) {
+		r.push('## Technical Details');
+
+		if (model.technical.modelClass) {
+			r.push(`- **Model Class:** ${model.technical.modelClass}`);
+		}
+
+		if (model.technical.parameters) {
+			r.push(`- **Parameters:** ${formatNumber(model.technical.parameters)}`);
+		}
+
+		if (model.technical.modelType) {
+			r.push(`- **Architecture:** ${model.technical.modelType}`);
+		}
+
+		if (model.technical.vocabSize) {
+			r.push(`- **Vocab Size:** ${formatNumber(model.technical.vocabSize)}`);
+		}
+
+		r.push('');
+	}
+
+	// Tags - reliable field from extended info
+	if (model.extended?.tags && model.extended.tags.length > 0) {
+		r.push('## Tags');
+		r.push(model.extended.tags.map((tag) => `\`${tag}\``).join(' '));
+		r.push('');
+	}
+
+	// Metadata - carefully extracted and validated
+	if (model.metadata) {
+		const metadata = [];
+
+		if (model.metadata.language) {
+			const languages = Array.isArray(model.metadata.language)
+				? model.metadata.language.join(', ')
+				: model.metadata.language;
+			metadata.push(`- **Language:** ${languages}`);
+		}
+
+		if (model.metadata.license) {
+			const license = Array.isArray(model.metadata.license)
+				? model.metadata.license.join(', ')
+				: model.metadata.license;
+			metadata.push(`- **License:** ${license}`);
+		}
+
+		if (model.metadata.datasets) {
+			const datasets = Array.isArray(model.metadata.datasets)
+				? model.metadata.datasets.join(', ')
+				: model.metadata.datasets;
+			metadata.push(`- **Datasets:** ${datasets}`);
+		}
+
+		if (model.metadata.fineTunedFrom) {
+			metadata.push(`- **Fine-tuned from:** ${model.metadata.fineTunedFrom}`);
+		}
+
+		if (metadata.length > 0) {
+			r.push('## Metadata');
+			r.push(...metadata);
+			r.push('');
+		}
+	}
+
+	// Spaces - processed with validation
+	if (model.spaces && model.spaces.length > 0) {
+		r.push('## Demo Spaces');
+		for (const space of model.spaces.slice(0, SPACES_TO_INCLUDE)) {
+			const title = space.title || space.name;
+			r.push(`- [${title}](https://hf.co/spaces/${space.id})`);
+		}
+
+		if (model.spaces.length > SPACES_TO_INCLUDE) {
+			r.push(`- *... and ${(model.spaces.length - SPACES_TO_INCLUDE).toString()} more spaces*`);
+		}
+		r.push('');
+	}
+
+	// Link is reliable - based on model name which is required
+	r.push(`**Link:** [https://hf.co/${model.name}](https://hf.co/${model.name})`);
+
+	return r.join('\n');
+}

package/src/model-search.ts

@@ -0,0 +1,231 @@
+import { z } from 'zod';
+import { HfApiCall } from './hf-api-call.js';
+import { formatDate, formatNumber } from './utilities.js';
+
+export const TAGS_TO_RETURN = 20;
+// Model Search Tool Configuration
+export const MODEL_SEARCH_TOOL_CONFIG = {
+	name: 'model_search',
+	description:
+		'Find Machine Learning models hosted on Hugging Face. ' +
+		'Returns comprehensive information about matching models including downloads, likes, tags, and direct links. ' +
+		'Include links to the models 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 models", "Top 10 most recent models" etc" '
+			),
+		author: z
+			.string()
+			.optional()
+			.describe("Organization or user who created the model (e.g., 'google', 'meta-llama', 'microsoft')"),
+		task: z
+			.string()
+			.optional()
+			.describe("Model task type (e.g., 'text-generation', 'image-classification', 'translation')"),
+		library: z.string().optional().describe("Framework the model uses (e.g., 'transformers', 'diffusers', 'timm')"),
+		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: 'Model Search',
+		destructiveHint: false,
+		readOnlyHint: true,
+		openWorldHint: true,
+	},
+} as const;
+
+// Define search parameter types
+export type ModelSearchParams = z.infer<typeof MODEL_SEARCH_TOOL_CONFIG.schema>;
+
+// API parameter interface for direct HF API calls
+interface ModelApiParams {
+	search?: string;
+	author?: string;
+	filter?: string;
+	sort?: string;
+	direction?: string;
+	limit?: string;
+}
+
+// Model result interface matching HF API response
+interface ModelApiResult {
+	_id: string;
+	id: string;
+	modelId: string;
+	likes: number;
+	downloads: number;
+	trendingScore?: number;
+	private: boolean;
+	tags: string[];
+	pipeline_tag?: string;
+	library_name?: string;
+	createdAt: string;
+}
+
+/**
+ * Service for searching Hugging Face Models using direct API calls
+ */
+export class ModelSearchTool extends HfApiCall<ModelApiParams, ModelApiResult[]> {
+	/**
+	 * @param hfToken Optional Hugging Face token for API access
+	 */
+	constructor(hfToken?: string) {
+		super('https://huggingface.co/api/models', hfToken);
+	}
+
+	/**
+	 * Search for models with detailed parameters
+	 */
+	async searchWithParams(params: Partial<ModelSearchParams>): Promise<string> {
+		try {
+			// Convert our params to the HF API format
+			const apiParams: ModelApiParams = {};
+
+			// Handle search query
+			if (params.query) {
+				apiParams.search = params.query;
+			}
+
+			// Handle author filter
+			if (params.author) {
+				apiParams.author = params.author;
+			}
+
+			// Handle task and library filters
+			const filters = [];
+			if (params.task) filters.push(params.task);
+			if (params.library) filters.push(params.library);
+			if (filters.length > 0) {
+				apiParams.filter = filters.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 models = await this.callApi<ModelApiResult[]>(apiParams);
+
+			if (models.length === 0) {
+				return `No models found for the given criteria.`;
+			}
+
+			return formatSearchResults(models, params);
+		} catch (error) {
+			if (error instanceof Error) {
+				throw new Error(`Failed to search for models: ${error.message}`);
+			}
+			throw error;
+		}
+	}
+
+	/**
+	 * Search for models with a specific filter (e.g., arxiv:XXXX.XXXXX)
+	 */
+	async searchWithFilter(filter: string, limit: number = 10): Promise<string> {
+		try {
+			const apiParams: ModelApiParams = {
+				filter: filter,
+				limit: limit.toString(),
+				sort: 'downloads',
+				direction: '-1',
+			};
+
+			// Call the API
+			const models = await this.callApi<ModelApiResult[]>(apiParams);
+
+			if (models.length === 0) {
+				return `No models found referencing ${filter}.`;
+			}
+
+			return formatSearchResults(models, { limit });
+		} catch (error) {
+			if (error instanceof Error) {
+				throw new Error(`Failed to search for models: ${error.message}`);
+			}
+			throw error;
+		}
+	}
+}
+
+// Formatting Function
+function formatSearchResults(models: ModelApiResult[], params: Partial<ModelSearchParams>): 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.task) searchTerms.push(`task "${params.task}"`);
+	if (params.library) searchTerms.push(`library "${params.library}"`);
+	if (params.sort) searchTerms.push(`sorted by ${params.sort} (descending)`);
+
+	const searchDesc = searchTerms.length > 0 ? ` matching ${searchTerms.join(', ')}` : '';
+
+	const resultText =
+		models.length === params.limit
+			? `Showing first ${models.length.toString()} models${searchDesc}:`
+			: `Found ${models.length.toString()} models${searchDesc}:`;
+	r.push(resultText);
+	r.push('');
+
+	for (const model of models) {
+		r.push(`## ${model.id}`);
+		r.push('');
+
+		// Basic info line
+		const info = [];
+		if (model.pipeline_tag) info.push(`**Task:** ${model.pipeline_tag}`);
+		if (model.library_name) info.push(`**Library:** ${model.library_name}`);
+		if (model.downloads) info.push(`**Downloads:** ${formatNumber(model.downloads)}`);
+		if (model.likes) info.push(`**Likes:** ${model.likes.toString()}`);
+		if (model.trendingScore) info.push(`**Trending Score:** ${model.trendingScore.toString()}`);
+
+		if (info.length > 0) {
+			r.push(info.join(' | '));
+			r.push('');
+		}
+
+		// Tags
+		if (model.tags && model.tags.length > 0) {
+			r.push(`**Tags:** ${model.tags.slice(0, TAGS_TO_RETURN).join(', ')}`);
+			if (model.tags.length > TAGS_TO_RETURN) {
+				r.push(`*and ${(model.tags.length - TAGS_TO_RETURN).toString()} more...*`);
+			}
+			r.push('');
+		}
+
+		// Status indicators
+		const status = [];
+		if (model.private) status.push('🔐 Private');
+		if (status.length > 0) {
+			r.push(status.join(' | '));
+			r.push('');
+		}
+
+		// Dates
+		if (model.createdAt) {
+			r.push(`**Created:** ${formatDate(model.createdAt)}`);
+		}
+
+		r.push(`**Link:** [https://hf.co/${model.id}](https://hf.co/${model.id})`);
+		r.push('');
+		r.push('---');
+		r.push('');
+	}
+
+	return r.join('\n');
+}