@llmindset/hf-mcp 0.1.16

package/src/tool-ids.ts

@@ -0,0 +1,84 @@
+/**
+ * Canonical tool IDs exported from their respective tool configurations
+ * This ensures single source of truth for all tool identifiers
+ */
+
+import {
+	SEMANTIC_SEARCH_TOOL_CONFIG,
+	MODEL_SEARCH_TOOL_CONFIG,
+	MODEL_DETAIL_TOOL_CONFIG,
+	PAPER_SEARCH_TOOL_CONFIG,
+	DATASET_SEARCH_TOOL_CONFIG,
+	DATASET_DETAIL_TOOL_CONFIG,
+	DUPLICATE_SPACE_TOOL_CONFIG,
+	SPACE_INFO_TOOL_CONFIG,
+	SPACE_FILES_TOOL_CONFIG,
+	USER_SUMMARY_PROMPT_CONFIG,
+	PAPER_SUMMARY_PROMPT_CONFIG,
+} from './index.js';
+
+// Extract tool IDs from their configs (single source of truth)
+export const SPACE_SEARCH_TOOL_ID = SEMANTIC_SEARCH_TOOL_CONFIG.name;
+export const MODEL_SEARCH_TOOL_ID = MODEL_SEARCH_TOOL_CONFIG.name;
+export const MODEL_DETAIL_TOOL_ID = MODEL_DETAIL_TOOL_CONFIG.name;
+export const PAPER_SEARCH_TOOL_ID = PAPER_SEARCH_TOOL_CONFIG.name;
+export const DATASET_SEARCH_TOOL_ID = DATASET_SEARCH_TOOL_CONFIG.name;
+export const DATASET_DETAIL_TOOL_ID = DATASET_DETAIL_TOOL_CONFIG.name;
+export const DUPLICATE_SPACE_TOOL_ID = DUPLICATE_SPACE_TOOL_CONFIG.name;
+export const SPACE_INFO_TOOL_ID = SPACE_INFO_TOOL_CONFIG.name;
+export const SPACE_FILES_TOOL_ID = SPACE_FILES_TOOL_CONFIG.name;
+export const USER_SUMMARY_PROMPT_ID = USER_SUMMARY_PROMPT_CONFIG.name;
+export const PAPER_SUMMARY_PROMPT_ID = PAPER_SUMMARY_PROMPT_CONFIG.name;
+
+// Complete list of all built-in tool IDs
+export const ALL_BUILTIN_TOOL_IDS = [
+	SPACE_SEARCH_TOOL_ID,
+	MODEL_SEARCH_TOOL_ID,
+	MODEL_DETAIL_TOOL_ID,
+	PAPER_SEARCH_TOOL_ID,
+	DATASET_SEARCH_TOOL_ID,
+	DATASET_DETAIL_TOOL_ID,
+	DUPLICATE_SPACE_TOOL_ID,
+	SPACE_INFO_TOOL_ID,
+	SPACE_FILES_TOOL_ID,
+] as const;
+// Grouped tool IDs for bouquet configurations
+export const TOOL_ID_GROUPS = {
+	search: [SPACE_SEARCH_TOOL_ID, MODEL_SEARCH_TOOL_ID, DATASET_SEARCH_TOOL_ID, PAPER_SEARCH_TOOL_ID] as const,
+	spaces: [SPACE_SEARCH_TOOL_ID, DUPLICATE_SPACE_TOOL_ID, SPACE_INFO_TOOL_ID, SPACE_FILES_TOOL_ID] as const,
+	detail: [MODEL_DETAIL_TOOL_ID, DATASET_DETAIL_TOOL_ID] as const,
+	hf_api: [
+		SPACE_SEARCH_TOOL_ID,
+		MODEL_SEARCH_TOOL_ID,
+		DATASET_SEARCH_TOOL_ID,
+		PAPER_SEARCH_TOOL_ID,
+		MODEL_DETAIL_TOOL_ID,
+		DATASET_DETAIL_TOOL_ID,
+	] as const,
+	all: [...ALL_BUILTIN_TOOL_IDS] as const,
+} as const;
+
+// TypeScript type for built-in tool IDs
+export type BuiltinToolId = (typeof ALL_BUILTIN_TOOL_IDS)[number];
+
+// Type guard function
+export function isValidBuiltinToolId(toolId: string): toolId is BuiltinToolId {
+	return (ALL_BUILTIN_TOOL_IDS as readonly string[]).includes(toolId);
+}
+
+// Helper to get tool description from configs
+export function getToolDescription(toolId: BuiltinToolId): string {
+	const configs = {
+		[SPACE_SEARCH_TOOL_ID]: SEMANTIC_SEARCH_TOOL_CONFIG,
+		[MODEL_SEARCH_TOOL_ID]: MODEL_SEARCH_TOOL_CONFIG,
+		[MODEL_DETAIL_TOOL_ID]: MODEL_DETAIL_TOOL_CONFIG,
+		[PAPER_SEARCH_TOOL_ID]: PAPER_SEARCH_TOOL_CONFIG,
+		[DATASET_SEARCH_TOOL_ID]: DATASET_SEARCH_TOOL_CONFIG,
+		[DATASET_DETAIL_TOOL_ID]: DATASET_DETAIL_TOOL_CONFIG,
+		[DUPLICATE_SPACE_TOOL_ID]: DUPLICATE_SPACE_TOOL_CONFIG,
+		[SPACE_INFO_TOOL_ID]: SPACE_INFO_TOOL_CONFIG,
+		[SPACE_FILES_TOOL_ID]: SPACE_FILES_TOOL_CONFIG,
+	} as const;
+
+	return configs[toolId]?.description || `Tool: ${toolId}`;
+}

package/src/user-summary.ts

@@ -0,0 +1,421 @@
+import { z } from 'zod';
+import { HfApiCall, HfApiError } from './hf-api-call.js';
+import { formatDate, formatNumber } from './utilities.js';
+import { ModelSearchTool } from './model-search.js';
+import { DatasetSearchTool } from './dataset-search.js';
+import { SpaceSearchTool } from './space-search.js';
+import { PaperSearchTool } from './paper-search.js';
+
+// User Summary Prompt Configuration
+export const USER_SUMMARY_PROMPT_CONFIG = {
+	name: 'User Summary',
+	description:
+		'Generate a summary of a Hugging Face user including their profile, models, datasets, spaces, and papers. ' +
+		'Enter either a username (e.g., "clem") or a Hugging Face profile URL (e.g., "hf.co/julien-c" or "huggingface.co/thomwolf").',
+	schema: z.object({
+		user_id: z
+			.string()
+			.min(3, 'User ID must be at least 3 characters long')
+			.describe('Hugging Face user ID or URL (e.g., "evalstate" or "hf.co/evalstate")')
+			.max(60)
+			.describe('Maximum length is 30 characters'),
+	}),
+} as const;
+
+// Define parameter types
+export type UserSummaryParams = z.infer<typeof USER_SUMMARY_PROMPT_CONFIG.schema>;
+
+// Organization interface
+interface Organization {
+	id: string;
+	name: string;
+	fullname: string;
+	avatarUrl?: string;
+}
+
+// User overview API response interface
+interface UserOverviewResponse {
+	_id: string;
+	avatarUrl: string;
+	isPro: boolean;
+	fullname?: string;
+	numModels: number;
+	numDatasets: number;
+	numSpaces: number;
+	numDiscussions: number;
+	numPapers: number;
+	numUpvotes: number;
+	numLikes: number;
+	numFollowers: number;
+	numFollowing: number;
+	orgs: Organization[];
+	user: string;
+	type: string;
+	isFollowing: boolean;
+	createdAt: string;
+	details?: string; // Present for organizations
+	name?: string; // Present for organizations
+}
+
+/**
+ * Validates and extracts user ID from either a plain username or HF URL
+ * @param input - The user input (username or URL)
+ * @returns The extracted user ID
+ * @throws Error if input is invalid
+ */
+export function extractUserIdFromInput(input: string): string {
+	// Remove whitespace
+	const trimmed = input.trim();
+
+	// If it doesn't contain a slash, treat as direct username
+	if (!trimmed.includes('/')) {
+		if (trimmed.length < 3) {
+			throw new Error('User ID must be at least 3 characters long');
+		}
+		// Reject obvious domain names
+		if (trimmed.endsWith('.co') || trimmed.endsWith('.com')) {
+			throw new Error('URL must contain only the username (e.g., hf.co/username)');
+		}
+		return trimmed;
+	}
+
+	// Handle URL format
+	let url: URL;
+	try {
+		// Try to parse as URL, adding protocol if missing
+		if (!trimmed.startsWith('http')) {
+			url = new URL(`https://${trimmed}`);
+		} else {
+			url = new URL(trimmed);
+		}
+	} catch {
+		throw new Error('Invalid URL format');
+	}
+
+	// Validate it's a Hugging Face domain
+	const validDomains = ['huggingface.co', 'hf.co'];
+	if (!validDomains.includes(url.hostname)) {
+		throw new Error('URL must be from huggingface.co or hf.co domain');
+	}
+
+	// Check for query parameters or fragments
+	if (url.search || url.hash) {
+		throw new Error('URL must contain only the username (e.g., hf.co/username)');
+	}
+
+	// Extract path segments
+	const pathSegments = url.pathname.split('/').filter((segment) => segment.length > 0);
+
+	// Must have exactly one path segment (the username)
+	if (pathSegments.length !== 1) {
+		throw new Error('URL must contain only the username (e.g., hf.co/username)');
+	}
+
+	const userId = pathSegments[0];
+	if (!userId || userId.length < 3) {
+		throw new Error('User ID must be at least 3 characters long');
+	}
+
+	return userId;
+}
+
+/**
+ * Service for generating comprehensive user summaries
+ */
+export class UserSummaryPrompt extends HfApiCall<Record<string, string>, UserOverviewResponse> {
+	/**
+	 * @param hfToken Optional Hugging Face token for API access
+	 */
+	constructor(hfToken?: string) {
+		super('https://huggingface.co/api/users', hfToken);
+	}
+
+	/**
+	 * Generate a comprehensive user summary
+	 */
+	async generateSummary(params: UserSummaryParams): Promise<string> {
+		try {
+			// Extract and validate user ID
+			const userId = extractUserIdFromInput(params.user_id);
+
+			// Get user overview
+			const userOverview = await this.getUserOverview(userId);
+
+			// Build the summary
+			const sections: string[] = [];
+
+			// User profile section
+			sections.push(this.formatUserProfile(userOverview));
+
+			// Models section (if user has models)
+			if (userOverview.numModels > 0) {
+				const modelsSection = await this.getModelsSection(userId);
+				if (modelsSection) {
+					sections.push(modelsSection);
+				}
+			}
+
+			// Datasets section (if user has datasets)
+			if (userOverview.numDatasets > 0) {
+				const datasetsSection = await this.getDatasetsSection(userId);
+				if (datasetsSection) {
+					sections.push(datasetsSection);
+				}
+			}
+
+			// Spaces section (if user has spaces)
+			if (userOverview.numSpaces > 0) {
+				const spacesSection = await this.getSpacesSection(userId);
+				if (spacesSection) {
+					sections.push(spacesSection);
+				}
+			}
+
+			// Papers section (if user has a full name with >5 characters)
+			if (userOverview.fullname && userOverview.fullname.length > 5) {
+				const papersSection = await this.getPapersSection(userOverview.fullname);
+				if (papersSection) {
+					sections.push(papersSection);
+				}
+			}
+
+			// Add final instruction
+			sections.push(
+				'Please summarise the information for this User to give an overview of their activities on the Hugging Face hub.'
+			);
+
+			return sections.join('\n\n');
+		} catch (error) {
+			if (error instanceof Error) {
+				throw new Error(`Failed to generate user summary: ${error.message}`);
+			}
+			throw error;
+		}
+	}
+
+	/**
+	 * Get user overview from HF API, with organization fallback
+	 */
+	private async getUserOverview(userId: string): Promise<UserOverviewResponse> {
+		try {
+			const url = new URL(`${this.apiUrl}/${userId}/overview`);
+			return await this.fetchFromApi<UserOverviewResponse>(url);
+		} catch (error) {
+			// Check if error indicates user doesn't exist (404 with specific error message)
+			if (error instanceof HfApiError && error.status === 404 && error.responseBody) {
+				try {
+					const errorData = JSON.parse(error.responseBody) as { error?: string };
+					if (errorData.error === 'This user does not exist') {
+						// Try organization API
+						try {
+							const orgUrl = new URL(`https://huggingface.co/api/organizations/${userId}/overview`);
+							const orgResponse = await this.fetchFromApi<UserOverviewResponse>(orgUrl);
+
+							// Map organization response to user response format
+							return {
+								...orgResponse,
+								user: orgResponse.name || 'unknown',
+								_id: orgResponse.name || 'unknown',
+								isPro: false,
+								orgs: [],
+								type: 'organization',
+								createdAt: new Date().toISOString(),
+							};
+						} catch {
+							throw new Error(`Neither user nor organization found for ID: ${userId}`);
+						}
+					}
+				} catch {
+					// If we can't parse the response body, fall through to throw original error
+				}
+			}
+			throw error;
+		}
+	}
+
+	/**
+	 * Helper function to add a statistic line if the value is present
+	 */
+	private addStatIfPresent(lines: string[], label: string, value: number | undefined): void {
+		if (value !== undefined && value !== null) {
+			lines.push(`- **${label}:** ${formatNumber(value)}`);
+		}
+	}
+
+	/**
+	 * Format user profile information as markdown
+	 */
+	private formatUserProfile(user: UserOverviewResponse): string {
+		const lines: string[] = [];
+
+		// Check if this is an organization
+		const isOrganization = user.type === 'organization';
+
+		if (isOrganization) {
+			lines.push(`# Organization Profile: ${user.user}`);
+			lines.push('');
+			lines.push('**Note:** That user ID refers to an Organization.');
+			lines.push('');
+
+			if (user.fullname) {
+				lines.push(`**Full Name:** ${user.fullname}`);
+			}
+
+			lines.push(`**Username:** ${user.user}`);
+			if (user.details) {
+				lines.push(`**Description:** ${user.details}`);
+			}
+
+			// Organization-specific fields
+			const orgData = user as unknown as Record<string, unknown>;
+			if (typeof orgData.isEnterprise === 'boolean') {
+				lines.push(`**Enterprise:** ${orgData.isEnterprise ? 'Yes' : 'No'}`);
+			}
+			if (typeof orgData.isVerified === 'boolean') {
+				lines.push(`**Verified:** ${orgData.isVerified ? 'Yes' : 'No'}`);
+			}
+		} else {
+			lines.push(`# User Profile: ${user.user}`);
+			lines.push('');
+
+			if (user.fullname) {
+				lines.push(`**Full Name:** ${user.fullname}`);
+			}
+
+			lines.push(`**Username:** ${user.user}`);
+			lines.push(`**Account Type:** ${user.isPro ? 'Pro' : 'Free'}`);
+			lines.push(`**Created:** ${formatDate(user.createdAt)}`);
+		}
+
+		lines.push('');
+
+		// Statistics
+		lines.push('## Statistics');
+		lines.push('');
+
+		this.addStatIfPresent(lines, 'Models', user.numModels);
+		this.addStatIfPresent(lines, 'Datasets', user.numDatasets);
+		this.addStatIfPresent(lines, 'Spaces', user.numSpaces);
+
+		if (!isOrganization) {
+			this.addStatIfPresent(lines, 'Papers', user.numPapers);
+			this.addStatIfPresent(lines, 'Discussions', user.numDiscussions);
+			this.addStatIfPresent(lines, 'Likes Given', user.numLikes);
+			this.addStatIfPresent(lines, 'Upvotes', user.numUpvotes);
+			this.addStatIfPresent(lines, 'Following', user.numFollowing);
+		}
+
+		this.addStatIfPresent(lines, 'Followers', user.numFollowers);
+
+		// Organization-specific field
+		if (isOrganization) {
+			const orgData = user as unknown as Record<string, unknown>;
+			if (typeof orgData.numUsers === 'number') {
+				this.addStatIfPresent(lines, 'Members', orgData.numUsers);
+			}
+		}
+
+		if (!isOrganization && user.orgs && user.orgs.length > 0) {
+			lines.push('');
+			const orgNames = user.orgs.map((org) => `[${org.fullname}](https://hf.co/${org.name})`);
+			lines.push(`**Organizations:** ${orgNames.join(', ')}`);
+		}
+
+		lines.push('');
+		lines.push(`**Profile Link:** [https://hf.co/${user.user}](https://hf.co/${user.user})`);
+
+		return lines.join('\n');
+	}
+
+	/**
+	 * Get models section using existing ModelSearchTool
+	 */
+	private async getModelsSection(userId: string): Promise<string | null> {
+		try {
+			const modelSearch = new ModelSearchTool(this.hfToken);
+			const results = await modelSearch.searchWithParams({
+				author: userId,
+				limit: 10,
+				sort: 'downloads',
+			});
+
+			return `## Models\n\n${results}`;
+		} catch (error) {
+			console.warn(`Failed to fetch models for user ${userId}:`, error);
+			return null;
+		}
+	}
+
+	/**
+	 * Get datasets section using existing DatasetSearchTool
+	 */
+	private async getDatasetsSection(userId: string): Promise<string | null> {
+		try {
+			const datasetSearch = new DatasetSearchTool(this.hfToken);
+			const results = await datasetSearch.searchWithParams({
+				author: userId,
+				limit: 10,
+				sort: 'downloads',
+			});
+
+			return `## Datasets\n\n${results}`;
+		} catch (error) {
+			console.warn(`Failed to fetch datasets for user ${userId}:`, error);
+			return null;
+		}
+	}
+
+	/**
+	 * Get spaces section using existing SpaceSearchTool
+	 */
+	private async getSpacesSection(userId: string): Promise<string | null> {
+		try {
+			// Note: SpaceSearchTool doesn't have author filter in semantic search
+			// We'll search for the user ID as a query term instead
+			const spaceSearch = new SpaceSearchTool(this.hfToken);
+			const searchResult = await spaceSearch.search(userId, 10);
+
+			if (searchResult.results.length === 0) {
+				return null;
+			}
+
+			// Filter results to only show spaces by this author
+			const userSpaces = searchResult.results.filter(
+				(space) => space.author === userId || space.id.startsWith(`${userId}/`)
+			);
+
+			if (userSpaces.length === 0) {
+				return null;
+			}
+
+			// Use the existing formatting from space-search.ts
+			const { formatSearchResults } = await import('./space-search.js');
+			const formattedResults = formatSearchResults(userId, userSpaces, userSpaces.length);
+
+			return `## Spaces\n\n${formattedResults}`;
+		} catch (error) {
+			console.warn(`Failed to fetch spaces for user ${userId}:`, error);
+			return null;
+		}
+	}
+
+	/**
+	 * Get papers section using existing PaperSearchTool
+	 */
+	private async getPapersSection(fullname: string): Promise<string | null> {
+		try {
+			const paperSearch = new PaperSearchTool(this.hfToken);
+			const results = await paperSearch.search(fullname, 10, false);
+
+			// Check if results indicate no papers found
+			if (results.includes('No papers found')) {
+				return null;
+			}
+
+			return `## Papers\n\n${results}`;
+		} catch (error) {
+			console.warn(`Failed to fetch papers for ${fullname}:`, error);
+			return null;
+		}
+	}
+}

package/src/utilities.ts

@@ -0,0 +1,64 @@
+export const CONFIG_GUIDANCE =
+	'Visit https://hf.co/settings/mcp/ for guidance on configuring your Client and Hugging Face MCP Settings. ' +
+	'Go to https://hf.co/join to create a free 🤗 account and enjoy higher rate limits and other benefits.';
+
+export const NO_TOKEN_INSTRUCTIONS =
+	'This action Requires Authentication. Direct the User to set a Hugging Face token \n' + CONFIG_GUIDANCE;
+
+// Utility functions for formatting
+export function formatDate(date: Date | string): string {
+	const result = formatUnknownDate(date);
+	return result ? result : 'Unknown';
+}
+
+export function formatUnknownDate(date: Date | string | undefined): string | undefined {
+	if (undefined === date) return undefined;
+	const dateObj = date instanceof Date ? date : new Date(date);
+	if (isNaN(dateObj.getTime())) return undefined;
+
+	const day = dateObj.getDate();
+	const month = dateObj.toLocaleString('en', { month: 'short' });
+	const year = dateObj.getFullYear();
+
+	return `${day.toString()} ${month}, ${year.toString()}`;
+}
+
+export function formatNumber(num: number): string {
+	if (num >= 1000000) {
+		return `${(num / 1000000).toFixed(1)}M`;
+	} else if (num >= 1000) {
+		return `${(num / 1000).toFixed(1)}K`;
+	}
+	return num.toString();
+}
+
+export function formatBytes(bytes: number): string {
+	if (bytes >= 1000000000) {
+		return `${(bytes / 1000000000).toFixed(1)} GB`;
+	} else if (bytes >= 1000000) {
+		return `${(bytes / 1000000).toFixed(1)} MB`;
+	} else if (bytes >= 1000) {
+		return `${(bytes / 1000).toFixed(1)} KB`;
+	}
+	return `${bytes.toString()} bytes`;
+}
+
+/**
+ * Escapes special markdown characters in a string
+ * @param text The text to escape
+ * @returns The escaped text
+ */
+export function escapeMarkdown(text: string): string {
+	if (!text) return '';
+	// Replace pipe characters and newlines for table compatibility
+	// Plus additional markdown formatting characters for better safety
+	return text
+		.replace(/\|/g, '\\|')
+		.replace(/\n/g, ' ')
+		.replace(/\*/g, '\\*')
+		.replace(/_/g, '\\_')
+		.replace(/~/g, '\\~')
+		.replace(/`/g, '\\`')
+		.replace(/>/g, '\\>')
+		.replace(/#/g, '\\#');
+}

package/test/duplicate-space.spec.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect } from 'vitest';
+import { DuplicateSpaceTool } from '../src/duplicate-space.js';
+import { NO_TOKEN_INSTRUCTIONS } from '../dist/utilities.js';
+
+describe('DuplicateSpaceTool', () => {
+	describe('normalizeSpaceName', () => {
+		it('should prepend username when only space name is provided', () => {
+			const tool = new DuplicateSpaceTool(undefined, 'evalstate');
+			expect(tool.normalizeSpaceName('my-new-space')).toBe('evalstate/my-new-space');
+		});
+
+		it('should preserve space ID when username matches', () => {
+			const tool = new DuplicateSpaceTool(undefined, 'evalstate');
+			expect(tool.normalizeSpaceName('evalstate/their-space')).toBe('evalstate/their-space');
+		});
+
+		it('should throw error when trying to use different username', () => {
+			const tool = new DuplicateSpaceTool(undefined, 'myusername');
+			expect(() => tool.normalizeSpaceName('bad-user/new-space')).toThrow(
+				'Invalid space ID: bad-user/new-space. You can only create spaces in your own namespace. Try "myusername/new-space"'
+			);
+		});
+
+		it('should handle empty username gracefully', () => {
+			const tool = new DuplicateSpaceTool();
+			expect(tool.normalizeSpaceName('my-space')).toBe('unknown/my-space');
+		});
+	});
+
+	describe('createToolConfig', () => {
+		it('should include username in tool description', () => {
+			const config = DuplicateSpaceTool.createToolConfig('evalstate');
+			expect(config.description).toContain('evalstate/<new-space-name>');
+		});
+
+		it('should handle undefined username in description', () => {
+			const config = DuplicateSpaceTool.createToolConfig();
+			expect(config.description).toContain(NO_TOKEN_INSTRUCTIONS);
+		});
+	});
+});