@llmindset/hf-mcp 0.3.1 → 0.3.3

package/src/repo-search.test.ts

@@ -0,0 +1,155 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { RepoSearchTool } from './repo-search.js';
+
+interface MockFetchCall {
+	input: string;
+	init?: RequestInit;
+}
+
+describe('RepoSearchTool', () => {
+	const originalFetch = globalThis.fetch;
+	let calls: MockFetchCall[] = [];
+
+	beforeEach(() => {
+		calls = [];
+		vi.stubGlobal('fetch', (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+			const inputString = stringifyRequestInput(input);
+			calls.push({ input: inputString, init });
+
+			if (inputString.includes('/api/models')) {
+				return Promise.resolve(jsonResponse([
+					{
+						id: 'meta-llama/Llama-3.1-8B-Instruct',
+						pipeline_tag: 'text-generation',
+						library_name: 'transformers',
+						downloads: 123,
+						likes: 10,
+						tags: ['text-generation'],
+					},
+				]));
+			}
+
+			if (inputString.includes('/api/datasets')) {
+				return Promise.resolve(jsonResponse([
+					{
+						id: 'openbmb/UltraData-Math',
+						description: 'Large-scale mathematical dataset',
+						downloads: 50,
+						likes: 3,
+						tags: ['math'],
+					},
+				]));
+			}
+
+			if (inputString.includes('/api/spaces')) {
+				return Promise.resolve(jsonResponse([
+					{
+						id: 'mrfakename/Z-Image-Turbo',
+						title: 'Z Image Turbo',
+						sdk: 'gradio',
+						likes: 20,
+					},
+				]));
+			}
+
+			return Promise.resolve(jsonResponse([]));
+		});
+	});
+
+	afterEach(() => {
+		vi.unstubAllGlobals();
+		globalThis.fetch = originalFetch;
+	});
+
+	it('aggregates model and dataset results in one response', async () => {
+		const tool = new RepoSearchTool('token');
+		const result = await tool.searchWithParams({
+			query: 'llama',
+			repo_types: ['model', 'dataset'],
+			limit: 5,
+		});
+
+		expect(calls).toHaveLength(2);
+		expect(calls[0]?.input).toContain('/api/models');
+		expect(calls[1]?.input).toContain('/api/datasets');
+		expect(result.totalResults).toBe(2);
+		expect(result.formatted).toContain('## Models (1)');
+		expect(result.formatted).toContain('## Datasets (1)');
+		expect(result.formatted).toContain('[https://hf.co/meta-llama/Llama-3.1-8B-Instruct]');
+		expect(result.formatted).toContain('[https://hf.co/datasets/openbmb/UltraData-Math]');
+	});
+
+	it('supports searching spaces through the same interface', async () => {
+		const tool = new RepoSearchTool('token');
+		const result = await tool.searchWithParams({
+			query: 'image generation',
+			repo_types: ['space'],
+			limit: 3,
+		});
+
+		expect(calls).toHaveLength(1);
+		expect(calls[0]?.input).toContain('/api/spaces');
+		expect(result.totalResults).toBe(1);
+		expect(result.formatted).toContain('## Spaces (1)');
+		expect(result.formatted).toContain('[https://hf.co/spaces/mrfakename/Z-Image-Turbo]');
+	});
+
+	it('applies an overall output length guard with truncation notice', async () => {
+		vi.stubGlobal('fetch', (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+			const inputString = stringifyRequestInput(input);
+			calls.push({ input: inputString, init });
+
+			if (inputString.includes('/api/models')) {
+				const longTag = 'very-long-tag-name-for-output-growth';
+				const models = Array.from({ length: 100 }, (_, index) => ({
+					id: `org/super-long-model-name-${index.toString().padStart(3, '0')}-with-extra-context`,
+					pipeline_tag: 'text-generation',
+					library_name: 'transformers',
+					downloads: 100000 - index,
+					likes: 1000 - index,
+					tags: Array.from({ length: 30 }, (_unused, tagIndex) => `${longTag}-${tagIndex.toString()}`),
+				}));
+				return Promise.resolve(jsonResponse(models));
+			}
+
+			return Promise.resolve(jsonResponse([]));
+		});
+
+		const tool = new RepoSearchTool('token');
+		const result = await tool.searchWithParams({
+			repo_types: ['model'],
+			limit: 100,
+		});
+
+		expect(result.totalResults).toBe(100);
+		expect(result.resultsShared).toBeLessThan(result.totalResults);
+		expect(result.formatted.length).toBeLessThanOrEqual(12_500 * 3);
+		expect(result.formatted).toContain('Results truncated at approximately 12,500 tokens');
+		expect(result.formatted).toContain('Included');
+	});
+});
+
+function jsonResponse(payload: unknown): Response {
+	return new Response(JSON.stringify(payload), {
+		status: 200,
+		headers: {
+			'content-type': 'application/json',
+		},
+	});
+}
+
+function stringifyRequestInput(input: RequestInfo | URL): string {
+	if (typeof input === 'string') {
+		return input;
+	}
+
+	if (input instanceof URL) {
+		return input.toString();
+	}
+
+	if (input instanceof Request) {
+		return input.url;
+	}
+
+	return input;
+}

package/src/repo-search.ts

@@ -0,0 +1,414 @@
+import { z } from 'zod';
+import { HfApiCall } from './hf-api-call.js';
+import { formatDate, formatNumber } from './utilities.js';
+import type { ToolResult } from './types/tool-result.js';
+
+const TAGS_TO_RETURN = 20;
+const TOKEN_CAP = 12_500;
+const CHARS_PER_TOKEN = 3;
+const MAX_OUTPUT_CHARS = TOKEN_CAP * CHARS_PER_TOKEN;
+
+const REPO_TYPES = ['model', 'dataset', 'space'] as const;
+export type RepoType = (typeof REPO_TYPES)[number];
+
+const REPO_TYPE_LABELS: Record<RepoType, string> = {
+	model: 'Models',
+	dataset: 'Datasets',
+	space: 'Spaces',
+};
+
+const DEFAULT_REPO_TYPES: RepoType[] = ['model', 'dataset'];
+
+export const REPO_SEARCH_TOOL_CONFIG = {
+	name: 'hub_repo_search',
+	description:
+		'Search Hugging Face repositories with a shared query interface. ' +
+		'You can target models, datasets, spaces, or aggregate across multiple repo types in one call. ' +
+		'Use space_search for semantic-first discovery of Spaces. ' +
+		'Include links to repositories in your response.',
+	schema: z.object({
+		query: z
+			.string()
+			.optional()
+			.describe('Search term. Leave blank and specify sort + limit to browse trending or recent repositories.'),
+		repo_types: z
+			.array(z.enum(REPO_TYPES))
+			.min(1)
+			.max(3)
+			.optional()
+			.default(DEFAULT_REPO_TYPES)
+			.describe(
+				'Repository types to search. Defaults to ["model", "dataset"]. space uses keyword search via /api/spaces.'
+			),
+		author: z
+			.string()
+			.optional()
+			.describe("Organization or user namespace to filter by (e.g. 'google', 'meta-llama', 'huggingface')."),
+		filters: z
+			.array(z.string())
+			.optional()
+			.describe(
+				'Optional hub filter tags. Applied to each selected repo type (e.g. ["text-generation"], ["language:en"], ["mcp-server"]).'
+			),
+		sort: z
+			.enum(['trendingScore', 'downloads', 'likes', 'createdAt', 'lastModified'])
+			.optional()
+			.describe('Sort order (descending): trendingScore, downloads, likes, createdAt, lastModified'),
+		limit: z
+			.number()
+			.min(1)
+			.max(100)
+			.optional()
+			.default(20)
+			.describe('Maximum number of results to return per selected repo type'),
+	}),
+	annotations: {
+		title: 'Repo Search',
+		destructiveHint: false,
+		readOnlyHint: true,
+		openWorldHint: true,
+	},
+} as const;
+
+export type RepoSearchParams = z.infer<typeof REPO_SEARCH_TOOL_CONFIG.schema>;
+
+interface RepoApiParams {
+	search?: string;
+	author?: string;
+	filter?: string;
+	sort?: string;
+	direction?: string;
+	limit?: string;
+}
+
+interface RepoResultBase {
+	id: string;
+	author?: string | null;
+	likes?: number;
+	downloads?: number;
+	trendingScore?: number;
+	private?: boolean;
+	tags?: string[];
+	createdAt?: string;
+	lastModified?: string | null;
+}
+
+interface ModelRepoResult extends RepoResultBase {
+	pipeline_tag?: string;
+	library_name?: string;
+}
+
+interface DatasetRepoResult extends RepoResultBase {
+	description?: string;
+	gated?: boolean;
+}
+
+interface SpaceRepoResult extends RepoResultBase {
+	title?: string | null;
+	emoji?: string | null;
+	sdk?: string;
+	shortDescription?: string;
+	ai_short_description?: string;
+	disabled?: boolean | null;
+}
+
+type RepoSearchResult = ModelRepoResult | DatasetRepoResult | SpaceRepoResult;
+
+interface RepoSearchBatchResult {
+	repoType: RepoType;
+	results: RepoSearchResult[];
+}
+
+/**
+ * Service for searching Hugging Face repositories with shared parameters.
+ *
+ * Uses listing endpoints:
+ * - /api/models
+ * - /api/datasets
+ * - /api/spaces
+ */
+export class RepoSearchTool extends HfApiCall<Record<string, string>, unknown> {
+	constructor(hfToken?: string) {
+		super('https://huggingface.co/api', hfToken);
+	}
+
+	async searchWithParams(params: Partial<RepoSearchParams>): Promise<ToolResult> {
+		try {
+			const repoTypes = normalizeRepoTypes(params.repo_types);
+			const apiParams = this.toApiParams(params);
+
+			const searchBatches = await Promise.all(
+				repoTypes.map(async (repoType): Promise<RepoSearchBatchResult> => {
+					const results = await this.searchByType(repoType, apiParams);
+					return { repoType, results };
+				})
+			);
+
+			const totalResults = searchBatches.reduce((sum, batch) => sum + batch.results.length, 0);
+			if (totalResults === 0) {
+				return {
+					formatted: `No repositories found for the given criteria.`,
+					totalResults: 0,
+					resultsShared: 0,
+				};
+			}
+
+			return formatSearchResults(searchBatches, params, repoTypes);
+		} catch (error) {
+			if (error instanceof Error) {
+				throw new Error(`Failed to search repositories: ${error.message}`);
+			}
+			throw error;
+		}
+	}
+
+	private toApiParams(params: Partial<RepoSearchParams>): RepoApiParams {
+		const apiParams: RepoApiParams = {};
+
+		if (params.query) {
+			apiParams.search = params.query;
+		}
+		if (params.author) {
+			apiParams.author = params.author;
+		}
+		if (params.filters && params.filters.length > 0) {
+			apiParams.filter = params.filters.join(',');
+		}
+		if (params.sort) {
+			apiParams.sort = params.sort;
+			apiParams.direction = '-1';
+		}
+		if (params.limit) {
+			apiParams.limit = params.limit.toString();
+		}
+
+		return apiParams;
+	}
+
+	private async searchByType(repoType: RepoType, params: RepoApiParams): Promise<RepoSearchResult[]> {
+		const endpoint = repoType === 'model' ? 'models' : repoType === 'dataset' ? 'datasets' : 'spaces';
+		const url = new URL(`${this.apiUrl}/${endpoint}`);
+
+		if (params.search !== undefined) {
+			url.searchParams.set('search', params.search);
+		}
+		if (params.author !== undefined) {
+			url.searchParams.set('author', params.author);
+		}
+		if (params.filter !== undefined) {
+			url.searchParams.set('filter', params.filter);
+		}
+		if (params.sort !== undefined) {
+			url.searchParams.set('sort', params.sort);
+		}
+		if (params.direction !== undefined) {
+			url.searchParams.set('direction', params.direction);
+		}
+		if (params.limit !== undefined) {
+			url.searchParams.set('limit', params.limit);
+		}
+
+		return this.fetchFromApi<RepoSearchResult[]>(url);
+	}
+}
+
+function normalizeRepoTypes(repoTypes: RepoType[] | undefined): RepoType[] {
+	if (!repoTypes || repoTypes.length === 0) {
+		return [...DEFAULT_REPO_TYPES];
+	}
+
+	const seen = new Set<RepoType>();
+	const normalized: RepoType[] = [];
+
+	for (const repoType of repoTypes) {
+		if (!seen.has(repoType)) {
+			seen.add(repoType);
+			normalized.push(repoType);
+		}
+	}
+
+	return normalized.length > 0 ? normalized : [...DEFAULT_REPO_TYPES];
+}
+
+function formatSearchResults(
+	searchBatches: RepoSearchBatchResult[],
+	params: Partial<RepoSearchParams>,
+	repoTypes: RepoType[]
+): ToolResult {
+	const lines: string[] = [];
+	const totalResults = searchBatches.reduce((sum, batch) => sum + batch.results.length, 0);
+	let resultsShared = 0;
+	let truncated = false;
+
+	const tryAppendLines = (nextLines: string[]): boolean => {
+		const candidate = [...lines, ...nextLines].join('\n');
+		if (candidate.length > MAX_OUTPUT_CHARS) {
+			return false;
+		}
+
+		lines.push(...nextLines);
+		return true;
+	};
+
+	const searchTerms: string[] = [];
+	if (params.query) searchTerms.push(`query "${params.query}"`);
+	if (params.author) searchTerms.push(`author "${params.author}"`);
+	if (params.filters && params.filters.length > 0) searchTerms.push(`filters [${params.filters.join(', ')}]`);
+	if (params.sort) searchTerms.push(`sorted by ${params.sort} (descending)`);
+
+	const repoTypesText = repoTypes.map((repoType) => REPO_TYPE_LABELS[repoType].toLowerCase()).join(', ');
+	const searchDesc = searchTerms.length > 0 ? ` matching ${searchTerms.join(', ')}` : '';
+	if (!tryAppendLines([`Found ${totalResults.toString()} repositories across ${repoTypesText}${searchDesc}.`, ''])) {
+		truncated = true;
+	}
+
+	outer: for (const batch of searchBatches) {
+		if (truncated) {
+			break;
+		}
+
+		const sectionLabel = REPO_TYPE_LABELS[batch.repoType];
+		if (!tryAppendLines([`## ${sectionLabel} (${batch.results.length.toString()})`, ''])) {
+			truncated = true;
+			break;
+		}
+
+		if (batch.results.length === 0) {
+			if (!tryAppendLines([`No ${sectionLabel.toLowerCase()} matched this query.`, ''])) {
+				truncated = true;
+				break;
+			}
+			continue;
+		}
+
+		for (const result of batch.results) {
+			const repoLines: string[] = [];
+			appendRepoResult(repoLines, batch.repoType, result);
+
+			if (!tryAppendLines(repoLines)) {
+				truncated = true;
+				break outer;
+			}
+
+			resultsShared += 1;
+		}
+	}
+
+	if (truncated) {
+		const truncationLines = [
+			'',
+			`⚠️ Results truncated at approximately ${TOKEN_CAP.toLocaleString()} tokens (${MAX_OUTPUT_CHARS.toLocaleString()} characters).`,
+			`Included ${resultsShared.toString()} of ${totalResults.toString()} repositories. Narrow the query, reduce limit, or filter repo_types to see more.`,
+		];
+
+		while (lines.length > 0 && [...lines, ...truncationLines].join('\n').length > MAX_OUTPUT_CHARS) {
+			lines.pop();
+		}
+
+		if ([...lines, ...truncationLines].join('\n').length <= MAX_OUTPUT_CHARS) {
+			lines.push(...truncationLines);
+		}
+	}
+
+	return {
+		formatted: lines.join('\n'),
+		totalResults,
+		resultsShared,
+	};
+}
+
+function appendRepoResult(lines: string[], repoType: RepoType, result: RepoSearchResult): void {
+	const heading = repoType === 'space' ? getSpaceHeading(result) : result.id;
+	lines.push(`### ${heading}`);
+	lines.push('');
+
+	if (repoType === 'dataset') {
+		const dataset = result as DatasetRepoResult;
+		if (dataset.description) {
+			const trimmed = dataset.description.substring(0, 200);
+			lines.push(`${trimmed}${dataset.description.length > 200 ? '...' : ''}`);
+			lines.push('');
+		}
+	}
+
+	if (repoType === 'space') {
+		const space = result as SpaceRepoResult;
+		const description = space.shortDescription || space.ai_short_description;
+		if (description) {
+			lines.push(description);
+			lines.push('');
+		}
+	}
+
+	const info: string[] = [];
+	if (result.author) info.push(`**Author:** ${result.author}`);
+
+	if (repoType === 'model') {
+		const model = result as ModelRepoResult;
+		if (model.pipeline_tag) info.push(`**Task:** ${model.pipeline_tag}`);
+		if (model.library_name) info.push(`**Library:** ${model.library_name}`);
+	}
+
+	if (repoType === 'space') {
+		const space = result as SpaceRepoResult;
+		if (space.sdk) info.push(`**SDK:** ${space.sdk}`);
+	}
+
+	if (typeof result.downloads === 'number') info.push(`**Downloads:** ${formatNumber(result.downloads)}`);
+	if (typeof result.likes === 'number') info.push(`**Likes:** ${result.likes.toString()}`);
+	if (typeof result.trendingScore === 'number') info.push(`**Trending Score:** ${result.trendingScore.toString()}`);
+
+	if (info.length > 0) {
+		lines.push(info.join(' | '));
+		lines.push('');
+	}
+
+	if (result.tags && result.tags.length > 0) {
+		lines.push(`**Tags:** ${result.tags.slice(0, TAGS_TO_RETURN).join(', ')}`);
+		if (result.tags.length > TAGS_TO_RETURN) {
+			lines.push(`*and ${(result.tags.length - TAGS_TO_RETURN).toString()} more...*`);
+		}
+		lines.push('');
+	}
+
+	const status: string[] = [];
+	if (result.private) status.push('🔐 Private');
+	if (repoType === 'dataset' && (result as DatasetRepoResult).gated) status.push('🔒 Gated');
+	if (repoType === 'space' && (result as SpaceRepoResult).disabled) status.push('⛔ Disabled');
+
+	if (status.length > 0) {
+		lines.push(status.join(' | '));
+		lines.push('');
+	}
+
+	if (result.createdAt) {
+		lines.push(`**Created:** ${formatDate(result.createdAt)}`);
+	}
+	if (result.lastModified && result.lastModified !== result.createdAt) {
+		lines.push(`**Last Modified:** ${formatDate(result.lastModified)}`);
+	}
+
+	lines.push(`**Link:** [${getRepoLink(repoType, result.id)}](${getRepoLink(repoType, result.id)})`);
+	lines.push('');
+	lines.push('---');
+	lines.push('');
+}
+
+function getSpaceHeading(result: RepoSearchResult): string {
+	const space = result as SpaceRepoResult;
+	const title = space.title?.trim();
+	if (title && title.length > 0) {
+		return `${title} (\`${result.id}\`)`;
+	}
+	return result.id;
+}
+
+function getRepoLink(repoType: RepoType, id: string): string {
+	if (repoType === 'dataset') {
+		return `https://hf.co/datasets/${id}`;
+	}
+	if (repoType === 'space') {
+		return `https://hf.co/spaces/${id}`;
+	}
+	return `https://hf.co/${id}`;
+}

package/src/space/commands/discover.ts

@@ -1,12 +1,13 @@
 import type { ToolResult } from '../../types/tool-result.js';
 import { escapeMarkdown } from '../../utilities.js';
 import { VIEW_PARAMETERS } from '../types.js';
+import { fetchWithProfile, NETWORK_FETCH_PROFILES } from '../../network/fetch-profile.js';
 
 /**
  * Prompt configuration for discover operation (from DYNAMIC_SPACE_DATA)
  * These prompts can be easily tweaked to adjust behavior
  */
-export const DISCOVER_PROMPTS = {
+const DISCOVER_PROMPTS = {
 	// Header for results
 	RESULTS_HEADER: `**Available Spaces:**
 
@@ -90,7 +91,14 @@ export async function discoverSpaces(): Promise<ToolResult> {
 	}
 
 	try {
-		const response = await fetch(url);
+		const allowPermissiveUrls = process.env.ALLOW_PERMISSIVE_URLS === 'true';
+		const profile = allowPermissiveUrls
+			? NETWORK_FETCH_PROFILES.httpOrHttpsPermissive()
+			: NETWORK_FETCH_PROFILES.externalHttps();
+
+		const { response } = await fetchWithProfile(url, profile, {
+			timeoutMs: 10000,
+		});
 
 		if (!response.ok) {
 			return {

package/src/space/commands/invoke.ts

@@ -5,7 +5,7 @@ import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/proto
 import { analyzeSchemaComplexity, validateParameters, applyDefaults } from '../utils/schema-validator.js';
 import { formatComplexSchemaError, formatValidationError } from '../utils/parameter-formatter.js';
 import { callGradioToolWithHeaders } from '../utils/gradio-caller.js';
-import { parseGradioSchemaResponse, normalizeParsedTools } from '../utils/gradio-schema.js';
+import { fetchGradioSchema, fetchSpaceMetadata } from '../utils/space-http.js';
 
 /**
  * Invokes a Gradio space with provided parameters
@@ -112,90 +112,3 @@ export async function invokeSpace(
 		};
 	}
 }
-
-/**
- * Fetches space metadata from HuggingFace API
- */
-async function fetchSpaceMetadata(
-	spaceName: string,
-	hfToken?: string
-): Promise<{ subdomain: string; private: boolean }> {
-	const url = `https://huggingface.co/api/spaces/${spaceName}`;
-	const headers: Record<string, string> = {};
-
-	if (hfToken) {
-		headers['Authorization'] = `Bearer ${hfToken}`;
-	}
-
-	const controller = new AbortController();
-	const timeoutId = setTimeout(() => controller.abort(), 10000);
-
-	try {
-		const response = await fetch(url, {
-			headers,
-			signal: controller.signal,
-		});
-
-		clearTimeout(timeoutId);
-
-		if (!response.ok) {
-			throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-		}
-
-		const info = (await response.json()) as {
-			subdomain?: string;
-			private?: boolean;
-		};
-
-		if (!info.subdomain) {
-			throw new Error('Space does not have a subdomain');
-		}
-
-		return {
-			subdomain: info.subdomain,
-			private: info.private || false,
-		};
-	} finally {
-		clearTimeout(timeoutId);
-	}
-}
-
-/**
- * Fetches schema from Gradio endpoint
- */
-async function fetchGradioSchema(subdomain: string, isPrivate: boolean, hfToken?: string): Promise<Tool[]> {
-	const schemaUrl = `https://${subdomain}.hf.space/gradio_api/mcp/schema`;
-
-	const headers: Record<string, string> = {
-		'Content-Type': 'application/json',
-	};
-
-	if (isPrivate && hfToken) {
-		headers['X-HF-Authorization'] = `Bearer ${hfToken}`;
-	}
-
-	const controller = new AbortController();
-	const timeoutId = setTimeout(() => controller.abort(), 10000);
-
-	try {
-		const response = await fetch(schemaUrl, {
-			method: 'GET',
-			headers,
-			signal: controller.signal,
-		});
-
-		clearTimeout(timeoutId);
-
-		if (!response.ok) {
-			throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-		}
-
-		const schemaResponse = (await response.json()) as unknown;
-
-			// Parse schema response (handle both array and object formats)
-			const parsed = parseGradioSchemaResponse(schemaResponse);
-			return normalizeParsedTools(parsed);
-		} finally {
-			clearTimeout(timeoutId);
-		}
-	}