@llmindset/hf-mcp 0.3.11 → 0.3.12

package/src/hub-inspect.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { HUB_REPO_DETAILS_TOOL_CONFIG } from './hub-inspect.js';
+
+describe('HUB_REPO_DETAILS_TOOL_CONFIG', () => {
+	it('defaults to overview and accepts dataset viewer operations', () => {
+		const parsed = HUB_REPO_DETAILS_TOOL_CONFIG.schema.parse({
+			repo_ids: ['rajpurkar/squad'],
+			repo_type: 'dataset',
+			operations: ['dataset_structure', 'dataset_preview'],
+			config: 'plain_text',
+			split: 'train',
+			offset: 0,
+			limit: 5,
+		});
+
+		expect(parsed.include_readme).toBe(false);
+		expect(parsed.operations).toEqual(['dataset_structure', 'dataset_preview']);
+	});
+
+	it('does not expose a redundant readme operation', () => {
+		expect(() =>
+			HUB_REPO_DETAILS_TOOL_CONFIG.schema.parse({
+				repo_ids: ['rajpurkar/squad'],
+				operations: ['readme'],
+			})
+		).toThrow();
+	});
+});

package/src/hub-inspect.ts

@@ -4,12 +4,17 @@ import { ModelDetailTool } from './model-detail.js';
 import { DatasetDetailTool } from './dataset-detail.js';
 import { spaceInfo } from '@huggingface/hub';
 import { formatDate } from './utilities.js';
+import { DatasetViewerInspector } from './dataset-viewer-inspect.js';
+
+const HUB_INSPECT_OPERATIONS = ['overview', 'dataset_structure', 'dataset_preview'] as const;
 
 export const HUB_REPO_DETAILS_TOOL_CONFIG = {
 	name: 'hub_repo_details',
 	description:
 		'Get details for one or more Hugging Face repos (model, dataset, or space). ' +
-		'Auto-detects type unless specified.',
+		'Auto-detects type unless specified. For datasets, use operations: overview, dataset_structure, dataset_preview. ' +
+		'Use dataset_structure first to discover configs, splits, sizes, and schema. Use dataset_preview only when ' +
+		'config and split are known, unless the dataset has a single config/split.',
 	schema: z.object({
 		repo_ids: z
 			.array(z.string().min(1))
@@ -18,6 +23,26 @@ export const HUB_REPO_DETAILS_TOOL_CONFIG = {
 			.describe('Repo IDs for (models|dataset/space) - usually in author/name format (e.g. openai/gpt-oss-120b)'),
 		repo_type: z.enum(['model', 'dataset', 'space']).optional().describe('Specify lookup type; otherwise auto-detects'),
 		include_readme: z.boolean().default(false).describe('Include README from the repo'),
+		operations: z
+			.array(z.enum(HUB_INSPECT_OPERATIONS))
+			.optional()
+			.describe(
+				'Details to return. Defaults to ["overview"]. For datasets, prefer ["overview", "dataset_structure"] first; then call ["dataset_preview"] with config and split.'
+			),
+		config: z
+			.string()
+			.optional()
+			.describe(
+				'Dataset Viewer config. Required for dataset_preview when the dataset has multiple config/split options. Discover via dataset_structure.'
+			),
+		split: z
+			.string()
+			.optional()
+			.describe(
+				'Dataset Viewer split. Required for dataset_preview when the dataset has multiple config/split options. Discover via dataset_structure.'
+			),
+		offset: z.number().int().nonnegative().optional().describe('Row offset for dataset_preview. Defaults to 0.'),
+		limit: z.number().int().optional().describe('Row count for dataset_preview. Defaults to 5 and is clamped to 1-100.'),
 	}),
 	annotations: {
 		title: 'Hub Repo Details',
@@ -32,11 +57,13 @@ export type HubInspectParams = z.infer<typeof HUB_REPO_DETAILS_TOOL_CONFIG.schem
 export class HubInspectTool {
 	private readonly modelDetail: ModelDetailTool;
 	private readonly datasetDetail: DatasetDetailTool;
+	private readonly datasetViewer: DatasetViewerInspector;
 	private readonly hubUrl?: string;
 
 	constructor(hfToken?: string, hubUrl?: string) {
 		this.modelDetail = new ModelDetailTool(hfToken, hubUrl);
 		this.datasetDetail = new DatasetDetailTool(hfToken, hubUrl);
+		this.datasetViewer = new DatasetViewerInspector(hfToken, { hubUrl });
 		this.hubUrl = hubUrl;
 	}
 
@@ -46,7 +73,7 @@ export class HubInspectTool {
 
 		for (const id of params.repo_ids) {
 			try {
-				const section = await this.inspectSingle(id, params.repo_type, includeReadme);
+				const section = await this.inspectSingle(id, params, includeReadme);
 				parts.push(section);
 				successCount += 1;
 			} catch (err) {
@@ -66,20 +93,30 @@ export class HubInspectTool {
 
 	private async inspectSingle(
 		repoId: string,
-		type: 'model' | 'dataset' | 'space' | undefined,
+		params: HubInspectParams,
 		includeReadme: boolean
 	): Promise<string> {
+		const type = params.repo_type;
+		const operations = normalizeOperations(params.operations);
+		const hasDatasetOperation = operations.some((operation) => operation === 'dataset_structure' || operation === 'dataset_preview');
+
 		// If caller constrained the type, do only that
 		if (type === 'model') {
+			if (hasDatasetOperation) return operationMismatch(repoId, 'model', operations);
 			return (await this.modelDetail.getDetails(repoId, includeReadme)).formatted;
 		}
 		if (type === 'dataset') {
-			return (await this.datasetDetail.getDetails(repoId, includeReadme)).formatted;
+			return await this.getDatasetDetails(repoId, params, includeReadme, operations);
 		}
 		if (type === 'space') {
+			if (hasDatasetOperation) return operationMismatch(repoId, 'space', operations);
 			return await this.getSpaceDetails(repoId);
 		}
 
+		if (hasDatasetOperation) {
+			return await this.getDatasetDetails(repoId, params, includeReadme, operations);
+		}
+
 		// Auto-detect: attempt all three and aggregate. The same id may exist for multiple types.
 		const matches: string[] = [];
 
@@ -111,6 +148,33 @@ export class HubInspectTool {
 		return matches.join('\n\n---\n\n');
 	}
 
+	private async getDatasetDetails(
+		repoId: string,
+		params: HubInspectParams,
+		includeReadme: boolean,
+		operations: HubInspectOperation[]
+	): Promise<string> {
+		const sections: string[] = [];
+		if (operations.includes('overview')) {
+			const overview = (await this.datasetDetail.getDetails(repoId, includeReadme)).formatted;
+			sections.push(`${overview}\n\n${datasetDrillDownHint()}`);
+		}
+		if (operations.includes('dataset_structure')) {
+			sections.push(await this.datasetViewer.getStructure(repoId, { config: params.config, split: params.split }));
+		}
+		if (operations.includes('dataset_preview')) {
+			sections.push(
+				await this.datasetViewer.getPreview(repoId, {
+					config: params.config,
+					split: params.split,
+					offset: params.offset,
+					limit: params.limit,
+				})
+			);
+		}
+		return sections.join('\n\n');
+	}
+
 	private async getSpaceDetails(spaceId: string): Promise<string> {
 		const additionalFields = ['author', 'tags', 'runtime', 'subdomain', 'sha'] as const;
 		const info = await spaceInfo<(typeof additionalFields)[number]>({
@@ -142,3 +206,23 @@ export class HubInspectTool {
 		return lines.join('\n');
 	}
 }
+
+type HubInspectOperation = (typeof HUB_INSPECT_OPERATIONS)[number];
+
+function normalizeOperations(operations: readonly HubInspectOperation[] | undefined): HubInspectOperation[] {
+	return operations && operations.length > 0 ? [...new Set(operations)] : ['overview'];
+}
+
+function operationMismatch(repoId: string, type: 'model' | 'space', operations: HubInspectOperation[]): string {
+	const requested = operations.filter((operation) => operation.startsWith('dataset_')).join(', ');
+	return `# ${repoId}\n\nRequested dataset operation(s) \`${requested}\`, but this repo was requested as a ${type}. Dataset Viewer operations only apply to dataset repos.`;
+}
+
+function datasetDrillDownHint(): string {
+	return [
+		'## Available deeper inspections',
+		'Call `hub_repo_details` with:',
+		'- `operations: ["dataset_structure"]` for configs, splits, sizes, parquet exports, and schema.',
+		'- `operations: ["dataset_preview"]` with `config` and `split` for sample rows.',
+	].join('\n');
+}

package/src/index.browser.ts

@@ -75,7 +75,8 @@ export const HUB_REPO_DETAILS_TOOL_CONFIG: BrowserToolConfig = {
 	name: 'hub_repo_details',
 	description:
 		'Get details for one or more Hugging Face repos (model, dataset, or space). ' +
-		'Auto-detects type unless specified.',
+		'Auto-detects type unless specified. For datasets, use dataset_structure first to discover configs, splits, ' +
+		'sizes, and schema. Use dataset_preview only when config and split are known, unless the dataset has a single config/split.',
 	annotations: {
 		title: 'Hub Repo Details',
 		destructiveHint: false,

package/src/index.ts

@@ -10,6 +10,7 @@ export * from './dataset-search.js';
 export * from './repo-search.js';
 export * from './create-repo.js';
 export * from './dataset-detail.js';
+export * from './dataset-viewer-inspect.js';
 export * from './hub-inspect.js';
 export * from './duplicate-space.js';
 export * from './space-info.js';

package/src/model-detail.ts

@@ -259,7 +259,7 @@ export class ModelDetailTool {
 
 			// Fetch and append README content if requested
 			if (includeReadme) {
-				const readmeContent = await fetchReadmeContent(modelDetails.name, 'models', false);
+				const readmeContent = await fetchReadmeContent(modelDetails.name, 'models');
 				if (readmeContent) {
 					const result = formatModelDetails(modelDetails);
 					result.formatted += '\n\n## README\n<modelcard-readme>\n\n' + readmeContent.trim() + '\n</modelcard-readme>';

package/src/readme-utils.ts

@@ -5,21 +5,16 @@
 import { fetchWithProfile, NETWORK_FETCH_PROFILES } from './network/fetch-profile.js';
 
 // Maximum number of characters to include from a README
-const DEFAULT_MAX_README_CHARS = 10_000;
+const DEFAULT_MAX_README_CHARS = 40_000;
 
 /**
  * Fetches README content from a Hugging Face repository
  *
  * @param repoName The resolved repository name (e.g., 'rajpurkar/squad', 'openai-community/gpt2')
  * @param type The repository type ('models' or 'datasets')
- * @param includeYaml Whether to include YAML frontmatter (default: false)
  * @returns Promise<string | null> The README content or null if not found/error
  */
-export async function fetchReadmeContent(
-	repoName: string,
-	type: 'models' | 'datasets',
-	includeYaml: boolean = false
-): Promise<string | null> {
+export async function fetchReadmeContent(repoName: string, type: 'models' | 'datasets'): Promise<string | null> {
 	try {
 		// Construct the URL based on repository type
 		const baseUrl =
@@ -39,11 +34,6 @@ export async function fetchReadmeContent(
 
 		let content = await response.text();
 
-		// If includeYaml is false, strip YAML frontmatter
-		if (!includeYaml) {
-			content = stripYamlFrontmatter(content);
-		}
-
 		// Truncate overly long READMEs to a sensible default size
 		if (content.length > DEFAULT_MAX_README_CHARS) {
 			const truncated = content.slice(0, DEFAULT_MAX_README_CHARS);
@@ -62,23 +52,3 @@ export async function fetchReadmeContent(
 		return null;
 	}
 }
-
-/**
- * Strips YAML frontmatter from markdown content
- *
- * @param content The full markdown content
- * @returns The content with YAML frontmatter removed
- */
-function stripYamlFrontmatter(content: string): string {
-	// Match YAML frontmatter: starts with ---, ends with ---
-	const yamlPattern = /^(\s*---[\r\n]+)([\S\s]*?)([\r\n]+---(\r\n|\n|$))/;
-	const match = content.match(yamlPattern);
-
-	if (match) {
-		// Return everything after the closing ---
-		return content.substring(match[0].length);
-	}
-
-	// No YAML frontmatter found, return original content
-	return content;
-}