@llmindset/hf-mcp 0.1.16

package/src/duplicate-space.ts

@@ -0,0 +1,263 @@
+import { z } from 'zod';
+import { HfApiCall } from './hf-api-call.js';
+import { explain } from './error-messages.js';
+import { NO_TOKEN_INSTRUCTIONS } from './utilities.js';
+
+export interface SpaceInfo {
+	runtime?: {
+		hardware?:
+			| {
+					current?: string;
+					requested?: string;
+			  }
+			| string;
+	};
+	gated?: boolean;
+	models?: string[];
+}
+
+export interface SpaceVariable {
+	key: string;
+	value: string;
+	description?: string;
+}
+
+export interface DuplicateSpaceParams {
+	sourceSpaceId: string;
+	newSpaceName?: string;
+	hardware?: 'freecpu' | 'zerogpu';
+	private?: boolean;
+}
+
+export interface DuplicateSpaceResult {
+	url: string;
+	spaceId: string;
+	hardware: string;
+	private: boolean;
+	variablesCopied: number;
+	instructions: string;
+	hardwareWarning?: string;
+}
+
+export const DUPLICATE_SPACE_TOOL_CONFIG = {
+	name: 'duplicate_space',
+	description: '', // This will be dynamically set with username
+	schema: z.object({
+		sourceSpaceId: z.string().min(1).describe("Space ID to copy (e.g., 'username/space-name')"),
+		newSpaceId: z.string().optional().describe('Name for the new space (optional, defaults to source space-name)'),
+		hardware: z
+			.enum(['freecpu', 'zerogpu'])
+			.optional()
+			.describe('Either "freecpu" or "zerogpu" (defaults based on source). Both options are in the free tier.'),
+		private: z
+			.boolean()
+			.optional()
+			.default(true)
+			.describe('Check with User whether the new space should be public or private.'),
+	}),
+	annotations: {
+		title: 'Duplicate Hugging Face Space',
+		destructiveHint: false,
+		readOnlyHint: false,
+		openWorldHint: true,
+	},
+} as const;
+
+// Hardware mapping constants
+const HARDWARE_MAP = {
+	freecpu: 'cpu-basic',
+	zerogpu: 'zero-a10g',
+} as const;
+
+const FREE_HARDWARE = ['cpu-basic', 'zero-a10g'];
+
+export class DuplicateSpaceTool extends HfApiCall<DuplicateSpaceParams, DuplicateSpaceResult> {
+	private username?: string;
+
+	constructor(hfToken?: string, username?: string) {
+		super('https://huggingface.co/api', hfToken);
+		this.username = username;
+	}
+
+	static createToolConfig(
+		username?: string
+	): Omit<typeof DUPLICATE_SPACE_TOOL_CONFIG, 'description'> & { description: string } {
+		const description = username
+			? `Duplicate a Hugging Face Space. Target space will be created as ${username}/<new-space-name>.`
+			: NO_TOKEN_INSTRUCTIONS;
+		return {
+			...DUPLICATE_SPACE_TOOL_CONFIG,
+			description,
+		};
+	}
+
+	normalizeSpaceName(spaceName: string): string {
+		// If already has a slash, check if it's trying to use a different username
+		if (spaceName.includes('/')) {
+			const [providedUser, spaceNamePart] = spaceName.split('/');
+			if (providedUser !== this.username) {
+				throw new Error(
+					`Invalid space ID: ${spaceName}. You can only create spaces in your own namespace. Try "${this.username || 'your-username'}/${spaceNamePart || 'space-name'}"`
+				);
+			}
+			return spaceName;
+		}
+		// Otherwise, prepend with username
+		return `${this.username || 'unknown'}/${spaceName}`;
+	}
+
+	async getSpaceInfo(spaceId: string): Promise<SpaceInfo> {
+		const url = `${this.apiUrl}/spaces/${spaceId}`;
+		return this.fetchFromApi(url);
+	}
+
+	async getSpaceVariables(spaceId: string): Promise<Record<string, { value: string; description?: string }>> {
+		const url = `${this.apiUrl}/spaces/${spaceId}/variables`;
+		try {
+			return await this.fetchFromApi(url);
+		} catch {
+			// If we can't access variables (private space or no permissions), return empty
+			return {};
+		}
+	}
+
+	async duplicate(params: DuplicateSpaceParams): Promise<DuplicateSpaceResult> {
+		const { sourceSpaceId, newSpaceName, hardware, private: isPrivate = true } = params;
+
+		if (!this.username) throw new Error(NO_TOKEN_INSTRUCTIONS);
+
+		try {
+			// Step 1: Get source space info
+			let sourceInfo: SpaceInfo;
+			try {
+				sourceInfo = await this.getSpaceInfo(sourceSpaceId);
+			} catch (error) {
+				// Explain the error and rethrow
+				throw explain(error, `Could not access source space "${sourceSpaceId}"`);
+			}
+
+			// Step 2: Get variables from source space
+			const sourceVars = await this.getSpaceVariables(sourceSpaceId);
+			const variables: SpaceVariable[] = Object.entries(sourceVars).map(([key, varInfo]) => ({
+				key,
+				value: varInfo.value,
+				description: varInfo.description,
+			}));
+
+			// Step 3: Determine hardware
+			// Extract hardware string from either object or string format
+			let sourceHardwareStr: string | undefined;
+			if (typeof sourceInfo.runtime?.hardware === 'object') {
+				sourceHardwareStr = sourceInfo.runtime.hardware.current || sourceInfo.runtime.hardware.requested;
+			} else {
+				sourceHardwareStr = sourceInfo.runtime?.hardware;
+			}
+
+			let selectedHardware: string;
+			let hardwareKey: 'freecpu' | 'zerogpu';
+
+			if (hardware) {
+				selectedHardware = HARDWARE_MAP[hardware];
+				hardwareKey = hardware;
+			} else {
+				// Auto-detect based on source
+				if (sourceHardwareStr === 'zero-a10g') {
+					selectedHardware = 'zero-a10g';
+					hardwareKey = 'zerogpu';
+				} else if (sourceHardwareStr === 'cpu-basic' || !sourceHardwareStr) {
+					selectedHardware = 'cpu-basic';
+					hardwareKey = 'freecpu';
+				} else {
+					// For any paid hardware, default to ZeroGPU (free tier)
+					selectedHardware = 'zero-a10g';
+					hardwareKey = 'zerogpu';
+				}
+			}
+
+			// Step 4: Determine target space ID
+			let targetId: string;
+			if (newSpaceName) {
+				targetId = this.normalizeSpaceName(newSpaceName);
+			} else {
+				// Use same name as source
+				const sourceName = sourceSpaceId.split('/')[1];
+				targetId = `${this.username}/${sourceName || ''}`;
+			}
+
+			// Step 5: Check for warnings
+			let hardwareWarning: string | undefined;
+			if (sourceHardwareStr && !FREE_HARDWARE.includes(sourceHardwareStr)) {
+				hardwareWarning = `Note: The source space uses '${sourceHardwareStr}' which is paid hardware. Your duplicated space is set to '${hardwareKey}'. "+ 
+				"You may need to upgrade in Settings to run this space or achieve the same performance.`;
+			}
+
+			let gatedWarning: string | undefined;
+			if (sourceInfo.gated) {
+				gatedWarning = `🔐 The model in this space is 'gated' - you may need to accept the licensing conditions before  use.`;
+			}
+
+			// Step 6: Make the duplication request
+			const url = `${this.apiUrl}/spaces/${sourceSpaceId}/duplicate`;
+			const payload = {
+				repository: targetId,
+				private: isPrivate,
+				hardware: selectedHardware,
+				variables: variables.length > 0 ? variables : undefined,
+			};
+
+			const response = await this.fetchFromApi<{ url: string }>(url, {
+				method: 'POST',
+				body: JSON.stringify(payload),
+			});
+
+			// Step 7: Construct response
+			const warnings: string[] = [];
+			if (hardwareWarning) warnings.push(hardwareWarning);
+			if (gatedWarning) warnings.push(gatedWarning);
+
+			const result: DuplicateSpaceResult = {
+				url: response.url,
+				spaceId: targetId,
+				hardware: hardwareKey,
+				private: isPrivate,
+				variablesCopied: variables.length,
+				instructions: this.formatInstructions(response.url, hardwareKey, isPrivate, warnings),
+			};
+
+			if (hardwareWarning) {
+				result.hardwareWarning = hardwareWarning;
+			}
+
+			return result;
+		} catch (error) {
+			// Explain the error and rethrow
+			throw explain(error, 'Failed to duplicate space');
+		}
+	}
+
+	private formatInstructions(url: string, hardware: string, isPrivate: boolean, warnings: string[]): string {
+		let instructions = `✅ 🤗 Space successfully duplicated! 
+
+🔗 Your new space: ${url}
+
+⚙️ To configure your space:
+1. Go to ${url}
+2. Click on 'Settings' in the top right
+3. Configure any additional settings as needed
+
+Hardware: ${hardware} | Visibility: ${isPrivate ? 'Private' : 'Public'}`;
+
+		if (warnings.length > 0) {
+			instructions += '\n\n⚠️ Warnings:';
+			warnings.forEach((warning) => {
+				instructions += `\n- ${warning}`;
+			});
+		}
+
+		return instructions;
+	}
+}
+
+export const formatDuplicateResult = (result: DuplicateSpaceResult): string => {
+	return result.instructions;
+};

package/src/error-messages.ts

@@ -0,0 +1,57 @@
+/**
+ * Common HTTP error messages for Hugging Face API operations
+ */
+
+import { HfApiError } from './hf-api-call.js';
+
+/**
+ * Friendly explanations for common HTTP error codes
+ */
+export const FRIENDLY_ERROR_EXPLANATIONS: Record<number, string> = {
+	400: 'The request was invalid. Check your HF_TOKEN permissions, or that you have not exceeded the maximum number of spaces allowed..',
+	401: 'Authentication failed. Please check that your Hugging Face token is valid. Check your Hugging Face token permissions.',
+	403: 'You do not have permission to access this resource. Check your Hugging Face token permissions.',
+	404: 'The requested resource does not exist.',
+	409: 'A resource with this name already exists.',
+	422: 'The provided configuration is invalid.',
+	429: 'Duplication failed due to rate limits.',
+	500: 'Hugging Face is experiencing issues. Please try again later.',
+	502: 'The server gateway is temporarily unavailable.',
+	503: 'The service is temporarily down for maintenance.',
+};
+
+/**
+ * Get friendly explanation for a given HTTP status code
+ */
+export function getFriendlyExplanation(status: number): string {
+	// Check for exact match first
+	if (FRIENDLY_ERROR_EXPLANATIONS[status]) {
+		return FRIENDLY_ERROR_EXPLANATIONS[status];
+	}
+
+	// Handle 5xx errors generically
+	if (status >= 500) {
+		return 'Hugging Face is experiencing issues. Please try again later.';
+	}
+
+	// Default for unknown errors
+	return 'An unexpected error occurred. Please try again.';
+}
+
+/**
+ * Explain an error by enhancing it with friendly explanation if it's an HfApiError
+ * Otherwise returns the original error unchanged
+ * @param error - The error to explain
+ * @param context - Optional context about what was being attempted
+ * @returns The enhanced HfApiError or original error
+ */
+export function explain(error: unknown, context?: string): unknown {
+	// Only enhance HfApiError instances
+	if (error instanceof HfApiError) {
+		const friendlyExplanation = getFriendlyExplanation(error.status);
+		return error.withImprovedMessage(friendlyExplanation, context);
+	}
+
+	// Return any other error unchanged
+	return error;
+}

package/src/hf-api-call.ts

@@ -0,0 +1,182 @@
+/**
+ * Custom error class that includes HTTP status information
+ */
+export class HfApiError extends Error {
+	constructor(
+		message: string,
+		public readonly status: number,
+		public readonly statusText: string,
+		public readonly responseBody?: string
+	) {
+		super(message);
+		this.name = 'HfApiError';
+	}
+
+	/**
+	 * Format the error with a friendly explanation followed by the original error
+	 * @param friendlyExplanation - User-friendly explanation
+	 * @param context - Optional context about what was being attempted
+	 * @returns Formatted error message
+	 */
+	formatWithExplanation(friendlyExplanation: string, context?: string): string {
+		let formatted = '';
+
+		// Add context if provided
+		if (context) {
+			formatted = `${context}. `;
+		}
+
+		// Add friendly explanation
+		formatted += friendlyExplanation;
+
+		// Add original error message on new line
+		formatted += `\n\n${this.message}`;
+
+		// Add response body details if available and different from message
+		if (this.responseBody) {
+			try {
+				const parsed = JSON.parse(this.responseBody) as { error?: string; message?: string; detail?: string };
+				const errorDetail = parsed.error || parsed.message || parsed.detail;
+				if (errorDetail && !this.message.includes(errorDetail)) {
+					formatted += `\n${errorDetail}`;
+				}
+			} catch {
+				// If not JSON, add raw response if it's not too long and not already in message
+				if (this.responseBody.length < 200 && !this.message.includes(this.responseBody)) {
+					formatted += `\n${this.responseBody}`;
+				}
+			}
+		}
+
+		return formatted;
+	}
+
+	/**
+	 * Create a new HfApiError with an improved message while preserving all other properties
+	 * @param friendlyExplanation - User-friendly explanation
+	 * @param context - Optional context about what was being attempted
+	 * @returns New HfApiError with improved message
+	 */
+	withImprovedMessage(friendlyExplanation: string, context?: string): HfApiError {
+		const improvedMessage = this.formatWithExplanation(friendlyExplanation, context);
+		return new HfApiError(improvedMessage, this.status, this.statusText, this.responseBody);
+	}
+}
+
+/**
+ * Base API client for Hugging Face HTTP APIs
+ *
+ * @template TParams - Type for API parameters
+ * @template TResponse - Type for API response
+ */
+export class HfApiCall<TParams = Record<string, string | undefined>, TResponse = unknown> {
+	protected readonly apiUrl: string;
+	protected readonly hfToken: string | undefined;
+	protected readonly apiTimeout: number;
+
+	/** nb reversed order from superclasses on basis that hfToken is more likely to be configured */
+	constructor(apiUrl: string, hfToken?: string) {
+		this.apiUrl = apiUrl;
+		this.hfToken = hfToken;
+		// Default to 12.5 seconds if HF_API_TIMEOUT is not set
+		this.apiTimeout = process.env.HF_API_TIMEOUT ? parseInt(process.env.HF_API_TIMEOUT, 10) : 12500;
+	}
+
+	/**
+	 * Fetches data from the API with proper error handling and authentication
+	 *
+	 * @template T - Response type (defaults to TResponse)
+	 * @param url - The URL to fetch from
+	 * @param options - Fetch options
+	 * @returns The parsed JSON response
+	 */
+	protected async fetchFromApi<T = TResponse>(url: URL | string, options?: globalThis.RequestInit): Promise<T> {
+		try {
+			const headers: Record<string, string> = {
+				Accept: 'application/json',
+				...((options?.headers as Record<string, string>) || {}),
+			};
+			if (this.hfToken) {
+				headers['Authorization'] = `Bearer ${this.hfToken}`;
+			}
+
+			// Add timeout using AbortController
+			const controller = new AbortController();
+			const timeoutId = setTimeout(() => controller.abort(), this.apiTimeout);
+
+			const response = await fetch(url.toString(), {
+				...options,
+				headers,
+				signal: controller.signal,
+			});
+
+			clearTimeout(timeoutId);
+
+			if (!response.ok) {
+				// Try to get error details from response body
+				let responseBody: string | undefined;
+				try {
+					responseBody = await response.text();
+				} catch {
+					// Ignore if we can't read the body
+				}
+
+				throw new HfApiError(
+					`API request failed: ${response.status.toString()} ${response.statusText}`,
+					response.status,
+					response.statusText,
+					responseBody
+				);
+			}
+
+			return (await response.json()) as T;
+		} catch (error) {
+			// Re-throw HfApiError as-is to preserve status information
+			if (error instanceof HfApiError) {
+				throw error;
+			}
+			// Handle timeout errors
+			if (error instanceof Error && error.name === 'AbortError') {
+				throw new Error(`API request timed out after ${this.apiTimeout}ms`);
+			}
+			// Wrap other errors
+			if (error instanceof Error) {
+				throw new Error(`API request failed: ${error.message}`);
+			}
+			throw error;
+		}
+	}
+
+	/**
+	 * Builds a URL with query parameters
+	 *
+	 * @param params - Key-value pairs of query parameters
+	 * @returns A URL object with the query parameters appended
+	 */
+	protected buildUrl(params: TParams): URL {
+		const url = new URL(this.apiUrl);
+
+		// Iterate over params in a type-safe way
+		for (const key in params) {
+			const value = params[key as keyof TParams];
+			if (value !== undefined) {
+				url.searchParams.append(key, String(value));
+			}
+		}
+
+		return url;
+	}
+
+	/**
+	 * Builds a URL with the given parameters and makes an API request
+	 *
+	 * @template T - Response type (defaults to TResponse)
+	 * @param params - The parameters to include in the URL
+	 * @param options - Additional fetch options
+	 * @returns The parsed JSON response
+	 */
+	protected async callApi<T = TResponse>(params: TParams, options?: globalThis.RequestInit): Promise<T> {
+		const url = this.buildUrl(params);
+		return this.fetchFromApi<T>(url, options);
+	}
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+// Export all modules - types are included in each module
+export * from './hf-api-call.js';
+export * from './error-messages.js';
+export * from './space-search.js';
+export * from './model-search.js';
+export * from './model-detail.js';
+export * from './utilities.js';
+export * from './paper-search.js';
+export * from './dataset-search.js';
+export * from './dataset-detail.js';
+export * from './duplicate-space.js';
+export * from './space-info.js';
+export * from './space-files.js';
+export * from './user-summary.js';
+export * from './paper-summary.js';
+
+// Export tool IDs for external use - these are the canonical tool identifiers
+export * from './tool-ids.js';