@llmindset/hf-mcp 0.3.10 → 0.3.12

package/src/create-repo.test.ts

@@ -0,0 +1,182 @@
+import { createRepo } from '@huggingface/hub';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { CreateRepoTool, formatCreateRepoResult } from './create-repo.js';
+
+vi.mock('@huggingface/hub', () => ({
+	createRepo: vi.fn(),
+}));
+
+describe('CreateRepoTool', () => {
+	beforeEach(() => {
+		vi.mocked(createRepo).mockReset();
+		vi.mocked(createRepo).mockResolvedValue({
+			repoUrl: 'https://huggingface.co/alice/example-model',
+			id: '0123456789abcdef01234567',
+		});
+	});
+
+	it('creates a model repository with client-native repo params', async () => {
+		const tool = new CreateRepoTool('token');
+		const result = await tool.create({
+			name: 'alice/example-model',
+			repo_type: 'model',
+		});
+
+		expect(createRepo).toHaveBeenCalledWith({
+			accessToken: 'token',
+			repo: { name: 'alice/example-model', type: 'model' },
+			private: undefined,
+		});
+		expect(result).toEqual({
+			url: 'https://huggingface.co/alice/example-model',
+			name: 'alice/example-model',
+			repoType: 'model',
+			id: '0123456789abcdef01234567',
+		});
+	});
+
+	it('defaults to model repositories', async () => {
+		const tool = new CreateRepoTool('token');
+		await tool.create({
+			name: 'alice/default-model',
+		});
+
+		expect(createRepo).toHaveBeenCalledWith({
+			accessToken: 'token',
+			repo: { name: 'alice/default-model', type: 'model' },
+			private: undefined,
+		});
+	});
+
+	it('creates a dataset repository', async () => {
+		const tool = new CreateRepoTool('token');
+		await tool.create({
+			name: 'alice/example-dataset',
+			repo_type: 'dataset',
+			private: true,
+		});
+
+		expect(createRepo).toHaveBeenCalledWith({
+			accessToken: 'token',
+			repo: { name: 'alice/example-dataset', type: 'dataset' },
+			private: true,
+		});
+	});
+
+	it('creates a bucket repository', async () => {
+		vi.mocked(createRepo).mockResolvedValue({
+			repoUrl: 'https://huggingface.co/buckets/alice/example-bucket',
+			id: 'bucket-id',
+		});
+		const tool = new CreateRepoTool('token');
+		const result = await tool.create({
+			name: 'alice/example-bucket',
+			repo_type: 'bucket',
+			private: true,
+		});
+
+		expect(createRepo).toHaveBeenCalledWith({
+			accessToken: 'token',
+			repo: { name: 'alice/example-bucket', type: 'bucket' },
+			private: true,
+		});
+		expect(result).toEqual({
+			url: 'https://huggingface.co/buckets/alice/example-bucket',
+			name: 'alice/example-bucket',
+			repoType: 'bucket',
+			id: 'bucket-id',
+		});
+	});
+
+	it('creates a Space repository with sdk', async () => {
+		vi.mocked(createRepo).mockResolvedValue({
+			repoUrl: 'https://huggingface.co/spaces/alice/demo',
+			id: 'abcdefabcdefabcdefabcdef',
+		});
+		const tool = new CreateRepoTool('token');
+		await tool.create({
+			name: 'alice/demo',
+			repo_type: 'space',
+			sdk: 'gradio',
+		});
+
+		expect(createRepo).toHaveBeenCalledWith({
+			accessToken: 'token',
+			repo: { name: 'alice/demo', type: 'space' },
+			private: undefined,
+			sdk: 'gradio',
+		});
+	});
+
+	it('creates a Streamlit Space repository', async () => {
+		vi.mocked(createRepo).mockResolvedValue({
+			repoUrl: 'https://huggingface.co/spaces/alice/streamlit-demo',
+			id: 'streamlit-space-id',
+		});
+		const tool = new CreateRepoTool('token');
+		await tool.create({
+			name: 'alice/streamlit-demo',
+			repo_type: 'space',
+			sdk: 'streamlit',
+		});
+
+		expect(createRepo).toHaveBeenCalledWith({
+			accessToken: 'token',
+			repo: { name: 'alice/streamlit-demo', type: 'space' },
+			private: undefined,
+			sdk: 'streamlit',
+		});
+	});
+
+	it('requires sdk for Space repositories', async () => {
+		const tool = new CreateRepoTool('token');
+		await expect(
+			tool.create({
+				name: 'alice/demo',
+				repo_type: 'space',
+			})
+		).rejects.toThrow('sdk is required when repo_type is space');
+		expect(createRepo).not.toHaveBeenCalled();
+	});
+
+	it('requires fully-qualified repo names', async () => {
+		const tool = new CreateRepoTool('token');
+		await expect(
+			tool.create({
+				name: 'example-model',
+				repo_type: 'model',
+			})
+		).rejects.toThrow("name must be fully qualified in 'namespace/repo-name' format");
+		expect(createRepo).not.toHaveBeenCalled();
+	});
+
+	it('requires an auth token', async () => {
+		const tool = new CreateRepoTool(undefined);
+		await expect(
+			tool.create({
+				name: 'alice/example-model',
+				repo_type: 'model',
+			})
+		).rejects.toThrow('Requires Authentication');
+		expect(createRepo).not.toHaveBeenCalled();
+	});
+
+	it('formats the created repository result', () => {
+		expect(
+			formatCreateRepoResult({
+				url: 'https://huggingface.co/alice/example-model',
+				name: 'alice/example-model',
+				repoType: 'model',
+				id: '0123456789abcdef01234567',
+			})
+		).toBe(
+			[
+				'Repository created.',
+				'Name: alice/example-model',
+				'Type: model',
+				'URL: https://huggingface.co/alice/example-model',
+				'ID: 0123456789abcdef01234567',
+			].join('\n')
+		);
+	});
+});

package/src/create-repo.ts

@@ -0,0 +1,103 @@
+import { createRepo, type RepoType as HubRepoType, type SpaceSdk } from '@huggingface/hub';
+import { z } from 'zod';
+import { NO_TOKEN_INSTRUCTIONS } from './utilities.js';
+
+const REPO_TYPES = ['model', 'dataset', 'space', 'bucket'] as const satisfies readonly HubRepoType[];
+const SPACE_SDKS = ['streamlit', 'gradio', 'docker', 'static'] as const satisfies readonly SpaceSdk[];
+
+export const CREATE_REPO_TOOL_CONFIG = {
+	name: 'create_repo',
+	description: '',
+	schema: z.object({
+		name: z.string().min(1).describe("Fully-qualified repository name in 'namespace/repo-name' format."),
+		repo_type: z.enum(REPO_TYPES).optional().default('bucket').describe('Repository type. Defaults to bucket.'),
+		private: z.boolean().optional().describe('Whether to create the repository as private.'),
+		sdk: z.enum(SPACE_SDKS).optional().default('static').describe("SDK type - only required for repo_type='space'."),
+	}),
+	annotations: {
+		title: 'Create Hugging Face Repository',
+		destructiveHint: false,
+		readOnlyHint: false,
+		openWorldHint: true,
+	},
+} as const;
+
+export type CreateRepoParams = z.input<typeof CREATE_REPO_TOOL_CONFIG.schema>;
+type RepoType = (typeof REPO_TYPES)[number];
+type SupportedSpaceSdk = (typeof SPACE_SDKS)[number];
+
+function assertExhaustiveUnion<T extends never>(_value?: T): void {
+	void _value;
+}
+
+assertExhaustiveUnion<Exclude<HubRepoType, RepoType>>();
+assertExhaustiveUnion<Exclude<RepoType, HubRepoType>>();
+assertExhaustiveUnion<Exclude<SpaceSdk, SupportedSpaceSdk>>();
+assertExhaustiveUnion<Exclude<SupportedSpaceSdk, SpaceSdk>>();
+
+export interface CreateRepoResult {
+	url: string;
+	name: string;
+	repoType: RepoType;
+	id: string;
+}
+
+export class CreateRepoTool {
+	constructor(private readonly hfToken?: string) {}
+
+	static createToolConfig(): Omit<typeof CREATE_REPO_TOOL_CONFIG, 'description'> & { description: string } {
+		return {
+			...CREATE_REPO_TOOL_CONFIG,
+			description: 'Create a Hugging Face model, dataset, space, or bucket repository.',
+		};
+	}
+
+	async create(params: CreateRepoParams): Promise<CreateRepoResult> {
+		if (!this.hfToken) throw new Error(NO_TOKEN_INSTRUCTIONS);
+
+		const repoType = params.repo_type ?? 'model';
+		validateParams(params, repoType);
+
+		const result = await createRepo({
+			accessToken: this.hfToken,
+			repo: {
+				name: params.name,
+				type: repoType,
+			},
+			private: params.private,
+			...(repoType === 'space' ? { sdk: params.sdk } : {}),
+		});
+
+		return {
+			url: result.repoUrl,
+			name: params.name,
+			repoType,
+			id: result.id,
+		};
+	}
+}
+
+function validateParams(params: CreateRepoParams, repoType: RepoType): void {
+	if (!isFullyQualifiedRepoName(params.name)) {
+		throw new Error("name must be fully qualified in 'namespace/repo-name' format.");
+	}
+
+	if (repoType === 'space' && !params.sdk) {
+		throw new Error('sdk is required when repo_type is space.');
+	}
+}
+
+function isFullyQualifiedRepoName(name: string): boolean {
+	const parts = name.split('/');
+	return parts.length === 2 && parts.every((part) => part.length > 0);
+}
+
+export const formatCreateRepoResult = (result: CreateRepoResult): string => {
+	return [
+		'Repository created.',
+		`Name: ${result.name}`,
+		`Type: ${result.repoType}`,
+		`URL: ${result.url}`,
+		`ID: ${result.id}`,
+	].join('\n');
+};

package/src/dataset-detail.ts

@@ -163,7 +163,7 @@ export class DatasetDetailTool {
 
 			// Fetch and append README content if requested
 			if (includeReadme) {
-				const readmeContent = await fetchReadmeContent(datasetDetails.name, 'datasets', false);
+				const readmeContent = await fetchReadmeContent(datasetDetails.name, 'datasets');
 				if (readmeContent) {
 					const result = formatDatasetDetails(datasetDetails);
 					result.formatted +=

package/src/dataset-viewer-inspect.test.ts

@@ -0,0 +1,234 @@
+import { describe, expect, it } from 'vitest';
+import { DatasetViewerInspector } from './dataset-viewer-inspect.js';
+
+const squadSplits = {
+	splits: [
+		{ dataset: 'rajpurkar/squad', config: 'plain_text', split: 'validation' },
+		{ dataset: 'rajpurkar/squad', config: 'plain_text', split: 'train' },
+	],
+	pending: [],
+	failed: [],
+};
+
+const squadSize = {
+	size: {
+		dataset: {
+			dataset: 'rajpurkar/squad',
+			num_bytes_original_files: 16278203,
+			num_bytes_parquet_files: 16278203,
+			num_bytes_memory: 98346470,
+			num_rows: 98169,
+			estimated_num_rows: null,
+		},
+		configs: [
+			{
+				dataset: 'rajpurkar/squad',
+				config: 'plain_text',
+				num_bytes_original_files: 16278203,
+				num_bytes_parquet_files: 16278203,
+				num_bytes_memory: 98346470,
+				num_rows: 98169,
+				num_columns: 5,
+				estimated_num_rows: null,
+			},
+		],
+		splits: [
+			{
+				dataset: 'rajpurkar/squad',
+				config: 'plain_text',
+				split: 'train',
+				num_bytes_parquet_files: 14458314,
+				num_bytes_memory: 89338716,
+				num_rows: 87599,
+				num_columns: 5,
+				estimated_num_rows: null,
+			},
+			{
+				dataset: 'rajpurkar/squad',
+				config: 'plain_text',
+				split: 'validation',
+				num_bytes_parquet_files: 1819889,
+				num_bytes_memory: 9007754,
+				num_rows: 10570,
+				num_columns: 5,
+				estimated_num_rows: null,
+			},
+		],
+	},
+	pending: [],
+	failed: [],
+	partial: false,
+};
+
+const squadParquet = {
+	parquet_files: [
+		{
+			dataset: 'rajpurkar/squad',
+			config: 'plain_text',
+			split: 'train',
+			url: 'https://huggingface.co/datasets/rajpurkar/squad/resolve/refs%2Fconvert%2Fparquet/plain_text/train/0000.parquet',
+			filename: '0000.parquet',
+			size: 14458314,
+		},
+		{
+			dataset: 'rajpurkar/squad',
+			config: 'plain_text',
+			split: 'validation',
+			url: 'https://huggingface.co/datasets/rajpurkar/squad/resolve/refs%2Fconvert%2Fparquet/plain_text/validation/0000.parquet',
+			filename: '0000.parquet',
+			size: 1819889,
+		},
+	],
+	pending: [],
+	failed: [],
+	partial: false,
+};
+
+const squadRows = {
+	features: [
+		{ feature_idx: 0, name: 'id', type: { dtype: 'string', _type: 'Value' } },
+		{ feature_idx: 1, name: 'context', type: { dtype: 'string', _type: 'Value' } },
+		{
+			feature_idx: 2,
+			name: 'answers',
+			type: {
+				text: { feature: { dtype: 'string', _type: 'Value' }, _type: 'List' },
+				answer_start: { feature: { dtype: 'int32', _type: 'Value' }, _type: 'List' },
+			},
+		},
+	],
+	rows: [
+		{
+			row_idx: 0,
+			row: {
+				id: '5733be284776f41900661182',
+				context:
+					'Architecturally, the school has a Catholic character. Atop the Main Building gold dome is a golden statue of the Virgin Mary.',
+				answers: { text: ['Saint Bernadette Soubirous'], answer_start: [515] },
+			},
+			truncated_cells: [],
+		},
+	],
+	num_rows_total: 87599,
+	num_rows_per_page: 100,
+	partial: false,
+};
+
+class SimulatedDatasetViewerClient {
+	readonly calls: Array<{ path: string; params: Record<string, string | number | undefined> }> = [];
+
+	constructor(private readonly responses: Record<string, unknown>) {}
+
+	getJson<T>(path: string, params: Record<string, string | number | undefined>): Promise<T> {
+		this.calls.push({ path, params });
+		const response = this.responses[path];
+		if (response instanceof Error) return Promise.reject(response);
+		return Promise.resolve(response as T);
+	}
+}
+
+function createInspector(client: SimulatedDatasetViewerClient): DatasetViewerInspector {
+	return new DatasetViewerInspector(undefined, {
+		client,
+		metadataProvider: {
+			getMetadata() {
+				return Promise.resolve({
+					name: 'rajpurkar/squad',
+					author: 'rajpurkar',
+					downloadsAllTime: 123456,
+					likes: 42,
+					updatedAt: new Date('2025-01-02T00:00:00Z'),
+					cardData: { license: 'cc-by-sa-4.0', task_categories: ['question-answering'] },
+				});
+			},
+		},
+	});
+}
+
+describe('DatasetViewerInspector', () => {
+	it('formats structure from splits, size, parquet, and schema preview', async () => {
+		const client = new SimulatedDatasetViewerClient({
+			'/splits': squadSplits,
+			'/size': squadSize,
+			'/parquet': squadParquet,
+			'/rows': squadRows,
+		});
+		const result = await createInspector(client).getStructure('rajpurkar/squad');
+
+		expect(result).toContain('## Dataset Structure');
+		expect(result).toContain('### Hub Metadata');
+		expect(result).toContain('| plain\\_text | train | 87.6K | — | 5 | 14.5 MB |');
+		expect(result).toContain('| plain\\_text | validation | 10.6K | — | 5 | 1.8 MB |');
+		expect(result).toContain('### Parquet Exports');
+		expect(result).toContain('| plain\\_text | train | 1 | 14.5 MB |');
+		expect(result).toContain('Using `plain_text/train`.');
+		expect(result).toContain('| 1 | id | {"dtype":"string","\\_type":"Value"} |');
+		expect(result).toContain('| 3 | answers |');
+	});
+
+	it('requires config and split for multi-split previews', async () => {
+		const client = new SimulatedDatasetViewerClient({
+			'/splits': squadSplits,
+		});
+		const result = await createInspector(client).getPreview('rajpurkar/squad', {});
+
+		expect(result).toContain('requires `config` and `split`');
+		expect(result).toContain('- `plain_text` / `train`');
+		expect(result).toContain('- `plain_text` / `validation`');
+	});
+
+	it('infers config and split for single-split previews and clamps limit', async () => {
+		const client = new SimulatedDatasetViewerClient({
+			'/splits': { splits: [{ dataset: 'x/y', config: 'default', split: 'train' }], pending: [], failed: [] },
+			'/rows': squadRows,
+		});
+		const result = await createInspector(client).getPreview('x/y', { limit: 500 });
+
+		expect(result).toContain('- Config: `default`');
+		expect(result).toContain('- Split: `train`');
+		expect(result).toContain('- Requested limit: `100`');
+		expect(client.calls.find((call) => call.path === '/rows')?.params).toMatchObject({ length: 100 });
+	});
+
+	it('rejects negative offsets before fetching rows', async () => {
+		const client = new SimulatedDatasetViewerClient({
+			'/splits': squadSplits,
+			'/rows': squadRows,
+		});
+		const result = await createInspector(client).getPreview('rajpurkar/squad', { offset: -1 });
+
+		expect(result).toContain('`offset` must be a non-negative integer');
+		expect(client.calls.some((call) => call.path === '/rows')).toBe(false);
+	});
+
+	it('surfaces Dataset Viewer endpoint failures as section warnings', async () => {
+		const client = new SimulatedDatasetViewerClient({
+			'/splits': new Error('The dataset has been renamed. Please use the current dataset name.'),
+			'/size': new Error('The dataset has been renamed. Please use the current dataset name.'),
+			'/parquet': new Error('The dataset has been renamed. Please use the current dataset name.'),
+		});
+		const result = await createInspector(client).getStructure('beans');
+
+		expect(result).toContain('Could not fetch splits from Dataset Viewer');
+		expect(result).toContain('Could not fetch size information from Dataset Viewer');
+		expect(result).toContain('Could not fetch parquet export information from Dataset Viewer');
+		expect(result).toContain('No config/split target was available for schema preview');
+	});
+
+	it('truncates row preview by cumulative output size rather than per-cell formatting', async () => {
+		const client = new SimulatedDatasetViewerClient({
+			'/splits': { splits: [{ dataset: 'x/y', config: 'default', split: 'train' }], pending: [], failed: [] },
+			'/rows': {
+				features: [{ feature_idx: 0, name: 'text', type: { dtype: 'string', _type: 'Value' } }],
+				rows: [{ row_idx: 0, row: { text: 'x'.repeat(80_000) }, truncated_cells: [] }],
+				num_rows_total: 1,
+				num_rows_per_page: 100,
+				partial: false,
+			},
+		});
+		const result = await createInspector(client).getPreview('x/y', {});
+
+		expect(result).toContain('Row preview output was truncated after approximately');
+		expect(result.length).toBeLessThan(70_000);
+	});
+});