@llmindset/hf-mcp 0.3.2 → 0.3.4

package/src/docs-search/doc-fetch.test.ts

@@ -19,13 +19,13 @@ const createMockResponse = ({
 	});
 
 const stubFetch = (factory: () => Response) => {
-	const fetchMock = vi.fn().mockImplementation(() => Promise.resolve(factory()));
+	const fetchMock = vi.fn<typeof fetch>().mockImplementation(() => Promise.resolve(factory()));
 	vi.stubGlobal('fetch', fetchMock);
 	return fetchMock;
 };
 
 describe('DocFetchTool', () => {
-    const tool = new DocFetchTool();
+	const tool = new DocFetchTool();
 
 	afterEach(() => {
 		vi.clearAllMocks();
@@ -72,27 +72,28 @@ describe('DocFetchTool', () => {
 				createMockResponse({
 					content: markdown,
 					contentType: 'text/markdown',
-				}),
+				})
 			);
 
 			const result = await tool.fetch({ doc_url: 'https://huggingface.co/docs/test' });
-			expect(fetchMock).toHaveBeenCalledWith('https://huggingface.co/docs/test', {
-				headers: { accept: 'text/markdown' },
-			});
+			expect(fetchMock).toHaveBeenCalledTimes(1);
+			const [calledUrl, calledInit] = fetchMock.mock.calls[0] ?? [];
+			expect(calledUrl).toBe('https://huggingface.co/docs/test');
+			expect(calledInit?.redirect).toBe('manual');
+			expect(new Headers(calledInit?.headers).get('accept')).toBe('text/markdown');
 			expect(result).toBe(markdown);
 		});
 
 		it('should return small documents without chunking', async () => {
-			
 			// Mock fetch to return HTML that converts to short markdown
 			stubFetch(() =>
 				createMockResponse({
 					content: '<h1>Short Document</h1><p>This is a short document.</p>',
-				}),
+				})
 			);
 
 			const result = await tool.fetch({ doc_url: 'https://huggingface.co/docs/test' });
-			
+
 			expect(result).toContain('# Short Document');
 			expect(result).toContain('This is a short document');
 			expect(result).not.toContain('DOCUMENT TRUNCATED');
@@ -100,16 +101,20 @@ describe('DocFetchTool', () => {
 
 		it('should chunk large documents and show truncation message', async () => {
 			// Mock fetch to return HTML that converts to long markdown
-			const longHtml = '<h1>Long Document</h1>' + '<p>This is a very long sentence that will be repeated many times to create a document that exceeds the 7500 token limit for testing chunking functionality.</p>'.repeat(200);
-			
+			const longHtml =
+				'<h1>Long Document</h1>' +
+				'<p>This is a very long sentence that will be repeated many times to create a document that exceeds the 7500 token limit for testing chunking functionality.</p>'.repeat(
+					200
+				);
+
 			stubFetch(() =>
 				createMockResponse({
 					content: longHtml,
-				}),
+				})
 			);
 
 			const result = await tool.fetch({ doc_url: 'https://huggingface.co/docs/test' });
-			
+
 			expect(result).toContain('# Long Document');
 			expect(result).toContain('DOCUMENT TRUNCATED');
 			expect(result).toContain('CALL hf_doc_fetch WITH AN OFFSET OF');
@@ -133,13 +138,15 @@ describe('DocFetchTool', () => {
 			const fetchMock = stubFetch(() =>
 				createMockResponse({
 					content: '<h1>Title</h1><p>Body</p>',
-				}),
+				})
 			);
 
 			const result = await tool.fetch({ doc_url: '/docs/test' });
-			expect(fetchMock).toHaveBeenCalledWith('https://huggingface.co/docs/test', {
-				headers: { accept: 'text/markdown' },
-			});
+			expect(fetchMock).toHaveBeenCalledTimes(1);
+			const [calledUrl, calledInit] = fetchMock.mock.calls[0] ?? [];
+			expect(calledUrl).toBe('https://huggingface.co/docs/test');
+			expect(calledInit?.redirect).toBe('manual');
+			expect(new Headers(calledInit?.headers).get('accept')).toBe('text/markdown');
 			expect(result).toContain('# Title');
 		});
 
@@ -147,28 +154,34 @@ describe('DocFetchTool', () => {
 			const fetchMock = stubFetch(() =>
 				createMockResponse({
 					content: '<h1>Another Title</h1><p>Body</p>',
-				}),
+				})
 			);
 
 			await tool.fetch({ doc_url: './docs/another' });
-			expect(fetchMock).toHaveBeenCalledWith('https://huggingface.co/docs/another', {
-				headers: { accept: 'text/markdown' },
-			});
+			expect(fetchMock).toHaveBeenCalledTimes(1);
+			const [calledUrl, calledInit] = fetchMock.mock.calls[0] ?? [];
+			expect(calledUrl).toBe('https://huggingface.co/docs/another');
+			expect(calledInit?.redirect).toBe('manual');
+			expect(new Headers(calledInit?.headers).get('accept')).toBe('text/markdown');
 		});
 
 		it('should return subsequent chunks with offset', async () => {
 			// Mock fetch to return the same long HTML
-			const longHtml = '<h1>Long Document</h1>' + '<p>This is a very long sentence that will be repeated many times to create a document that exceeds the 7500 token limit for testing chunking functionality.</p>'.repeat(200);
-			
+			const longHtml =
+				'<h1>Long Document</h1>' +
+				'<p>This is a very long sentence that will be repeated many times to create a document that exceeds the 7500 token limit for testing chunking functionality.</p>'.repeat(
+					200
+				);
+
 			stubFetch(() =>
 				createMockResponse({
 					content: longHtml,
-				}),
+				})
 			);
 
 			// Get first chunk
 			const firstChunk = await tool.fetch({ doc_url: 'https://huggingface.co/docs/test' });
-			
+
 			// Extract offset from truncation message
 			const offsetMatch = firstChunk.match(/OFFSET OF (\d+)/);
 			expect(offsetMatch).toBeTruthy();
@@ -176,7 +189,7 @@ describe('DocFetchTool', () => {
 
 			// Get second chunk
 			const secondChunk = await tool.fetch({ doc_url: 'https://huggingface.co/docs/test', offset });
-			
+
 			expect(secondChunk).not.toEqual(firstChunk);
 			expect(secondChunk.length).toBeGreaterThan(0);
 		});
@@ -185,12 +198,69 @@ describe('DocFetchTool', () => {
 			stubFetch(() =>
 				createMockResponse({
 					content: '<h1>Short Document</h1><p>This is short.</p>',
-				}),
+				})
 			);
 
 			const result = await tool.fetch({ doc_url: 'https://huggingface.co/docs/test', offset: 10000 });
-			
+
 			expect(result).toContain('Error: Offset 10000 is beyond');
 		});
 	});
+
+	describe('security hardening', () => {
+		it('rejects traversal payload variants', async () => {
+			const traversalUrls = [
+				'https://huggingface.co/docs/../x',
+				'https://huggingface.co/docs/%2e%2e/x',
+				'https://huggingface.co/docs/%2e%2e%2fx',
+				'https://huggingface.co/docs/..%2fx',
+				'https://huggingface.co/docs/%2e%2e%5cx',
+				'https://huggingface.co/docs/%252e%252e%252fx',
+			];
+
+			const fetchMock = stubFetch(() =>
+				createMockResponse({
+					content: 'should never be fetched',
+				})
+			);
+
+			for (const docUrl of traversalUrls) {
+				await expect(tool.fetch({ doc_url: docUrl })).rejects.toThrow('Failed to fetch document');
+			}
+
+			expect(fetchMock).not.toHaveBeenCalled();
+		});
+
+		it('rejects redirect to non-allowlisted host', async () => {
+			const fetchMock = vi.fn().mockResolvedValueOnce(
+				new Response('', {
+					status: 302,
+					headers: { location: 'https://example.com/evil' },
+				})
+			);
+			vi.stubGlobal('fetch', fetchMock);
+
+			await expect(tool.fetch({ doc_url: 'https://huggingface.co/docs/transformers' })).rejects.toThrow(
+				'Failed to fetch document'
+			);
+
+			expect(fetchMock).toHaveBeenCalledTimes(1);
+		});
+
+		it('rejects redirect to http downgrade', async () => {
+			const fetchMock = vi.fn().mockResolvedValueOnce(
+				new Response('', {
+					status: 302,
+					headers: { location: 'http://huggingface.co/docs/transformers' },
+				})
+			);
+			vi.stubGlobal('fetch', fetchMock);
+
+			await expect(tool.fetch({ doc_url: 'https://huggingface.co/docs/transformers' })).rejects.toThrow(
+				'Failed to fetch document'
+			);
+
+			expect(fetchMock).toHaveBeenCalledTimes(1);
+		});
+	});
 });

package/src/docs-search/doc-fetch.ts

@@ -1,6 +1,8 @@
 import { z } from 'zod';
 import TurndownService from 'turndown';
 import { estimateTokens } from '../utilities.js';
+import { createHfDocsPolicy, parseAndValidateUrl } from '../network/url-policy.js';
+import { fetchWithProfile, NETWORK_FETCH_PROFILES } from '../network/fetch-profile.js';
 
 export const DOC_FETCH_CONFIG = {
 	name: 'hf_doc_fetch',
@@ -26,6 +28,7 @@ export type DocFetchParams = z.infer<typeof DOC_FETCH_CONFIG.schema>;
 
 export class DocFetchTool {
 	private turndownService: TurndownService;
+	private readonly docsPolicy = createHfDocsPolicy();
 
 	constructor() {
 		this.turndownService = new TurndownService({
@@ -120,19 +123,7 @@ export class DocFetchTool {
 	 */
 	validateUrl(hfUrl: string): void {
 		try {
-			const url = new URL(hfUrl);
-			if (url.protocol !== 'https:') {
-				throw new Error('That was not a valid documentation URL');
-			}
-
-			const hostname = url.hostname.toLowerCase();
-			const isHfDocs =
-				(hostname === 'huggingface.co' || hostname === 'www.huggingface.co') && url.pathname.startsWith('/docs/');
-			const isGradio = hostname === 'gradio.app' || hostname === 'www.gradio.app';
-
-			if (!isHfDocs && !isGradio) {
-				throw new Error('That was not a valid documentation URL');
-			}
+			parseAndValidateUrl(hfUrl, this.docsPolicy);
 		} catch {
 			throw new Error('That was not a valid documentation URL');
 		}
@@ -144,9 +135,11 @@ export class DocFetchTool {
 	async fetch(params: DocFetchParams): Promise<string> {
 		try {
 			const normalizedUrl = normalizeDocUrl(params.doc_url);
-			this.validateUrl(normalizedUrl);
-
-			const response = await fetch(normalizedUrl, { headers: { accept: 'text/markdown' } });
+			const { response } = await fetchWithProfile(normalizedUrl, NETWORK_FETCH_PROFILES.hfDocs(), {
+				requestInit: {
+					headers: { accept: 'text/markdown' },
+				},
+			});
 			if (!response.ok) {
 				throw new Error(`Failed to fetch document: ${response.status} ${response.statusText}`);
 			}

package/src/file-icons.ts

@@ -0,0 +1,39 @@
+export const FILE_ICON_BY_EXTENSION: Readonly<Record<string, string>> = {
+	py: '🐍',
+	js: '📜',
+	ts: '📘',
+	md: '📝',
+	txt: '📄',
+	json: '📊',
+	yaml: '⚙️',
+	yml: '⚙️',
+	png: '🖼️',
+	jpg: '🖼️',
+	jpeg: '🖼️',
+	gif: '🖼️',
+	svg: '🎨',
+	mp4: '🎬',
+	mp3: '🎵',
+	pdf: '📕',
+	zip: '📦',
+	tar: '📦',
+	gz: '📦',
+	html: '🌐',
+	css: '🎨',
+	ipynb: '📓',
+	csv: '📊',
+	parquet: '🗄️',
+	safetensors: '🤖',
+	bin: '💾',
+	pkl: '🥒',
+	h5: '🗃️',
+};
+
+export function getFileIcon(filename: string): string {
+	const extension = filename.split('.').pop()?.toLowerCase();
+	if (!extension) {
+		return '📄';
+	}
+
+	return FILE_ICON_BY_EXTENSION[extension] ?? '📄';
+}

package/src/gradio-files.ts

@@ -3,6 +3,7 @@ import { listFiles } from '@huggingface/hub';
 import { formatBytes, escapeMarkdown } from './utilities.js';
 import { HfApiError } from './hf-api-call.js';
 import { explain } from './error-messages.js';
+import { getFileIcon } from './file-icons.js';
 
 // Define the FileWithUrl interface
 interface FileWithUrl {
@@ -207,7 +208,7 @@ export class GradioFilesTool {
 
 		for (const file of files) {
 			const fileName = file.path.split('/').pop() || file.path;
-			const icon = this.getFileIcon(fileName);
+			const icon = getFileIcon(fileName);
 			const lastMod = file.lastModified ? new Date(file.lastModified).toLocaleDateString() : '-';
 
 			markdown += `| ${escapeMarkdown(fileName)} | ${file.sizeFormatted} | ${icon} ${file.type} | ${lastMod} | ${file.url} |\n`;
@@ -215,43 +216,4 @@ export class GradioFilesTool {
 
 		return markdown;
 	}
-
-	/**
-	 * Get file icon based on extension
-	 */
-	private getFileIcon(filename: string): string {
-		const ext = filename.split('.').pop()?.toLowerCase();
-		const iconMap: Record<string, string> = {
-			py: '🐍',
-			js: '📜',
-			ts: '📘',
-			md: '📝',
-			txt: '📄',
-			json: '📊',
-			yaml: '⚙️',
-			yml: '⚙️',
-			png: '🖼️',
-			jpg: '🖼️',
-			jpeg: '🖼️',
-			gif: '🖼️',
-			svg: '🎨',
-			mp4: '🎬',
-			mp3: '🎵',
-			pdf: '📕',
-			zip: '📦',
-			tar: '📦',
-			gz: '📦',
-			html: '🌐',
-			css: '🎨',
-			ipynb: '📓',
-			csv: '📊',
-			parquet: '🗄️',
-			safetensors: '🤖',
-			bin: '💾',
-			pkl: '🥒',
-			h5: '🗃️',
-		};
-
-		return iconMap[ext || ''] || '📄';
-	}
 }

package/src/hf-api-call.ts

@@ -1,3 +1,5 @@
+import { fetchWithProfile, NETWORK_FETCH_PROFILES } from './network/fetch-profile.js';
+
 /**
  * Custom error class that includes HTTP status information
  */
@@ -99,18 +101,14 @@ export class HfApiCall<TParams = Record<string, string | undefined>, TResponse =
 				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,
+			const { response } = await fetchWithProfile(url.toString(), NETWORK_FETCH_PROFILES.externalHttps(), {
+				timeoutMs: this.apiTimeout,
+				requestInit: {
+					...options,
+					headers,
+				},
 			});
 
-			clearTimeout(timeoutId);
-
 			const responseBodyText = await response.text();
 
 			if (!response.ok) {

package/src/index.browser.ts

@@ -0,0 +1,183 @@
+const KNOWLEDGE_DATE = new Intl.DateTimeFormat('en-GB', {
+	day: 'numeric',
+	month: 'long',
+	year: 'numeric',
+	timeZone: 'UTC',
+}).format(new Date());
+
+interface BrowserToolConfig {
+	name: string;
+	description: string;
+	annotations: {
+		title: string;
+		destructiveHint: boolean;
+		readOnlyHint: boolean;
+		openWorldHint: boolean;
+	};
+}
+
+export const SEMANTIC_SEARCH_TOOL_CONFIG: BrowserToolConfig = {
+	name: 'space_search',
+	description:
+		'Find Hugging Face Spaces using semantic search. IMPORTANT Only MCP Servers can be used with the dynamic_space tool' +
+		'Include links to the Space when presenting the results.',
+	annotations: {
+		title: 'Hugging Face Space Search',
+		destructiveHint: false,
+		readOnlyHint: true,
+		openWorldHint: true,
+	},
+};
+
+export const REPO_SEARCH_TOOL_CONFIG: BrowserToolConfig = {
+	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.',
+	annotations: {
+		title: 'Repo Search',
+		destructiveHint: false,
+		readOnlyHint: true,
+		openWorldHint: true,
+	},
+};
+
+export const PAPER_SEARCH_TOOL_CONFIG: BrowserToolConfig = {
+	name: 'paper_search',
+	description:
+		'Find Machine Learning research papers on the Hugging Face hub. ' +
+		"Include 'Link to paper' When presenting the results. " +
+		'Consider whether tabulating results matches user intent.',
+	annotations: {
+		title: 'Paper Search',
+		destructiveHint: false,
+		readOnlyHint: true,
+		openWorldHint: true,
+	},
+};
+
+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.',
+	annotations: {
+		title: 'Hub Repo Details',
+		destructiveHint: false,
+		readOnlyHint: true,
+		openWorldHint: false,
+	},
+};
+
+export const DUPLICATE_SPACE_TOOL_CONFIG: BrowserToolConfig = {
+	name: 'duplicate_space',
+	description: '',
+	annotations: {
+		title: 'Duplicate Hugging Face Space',
+		destructiveHint: false,
+		readOnlyHint: false,
+		openWorldHint: true,
+	},
+};
+
+export const SPACE_FILES_TOOL_CONFIG: BrowserToolConfig = {
+	name: 'space_files',
+	description: '',
+	annotations: {
+		title: 'Space Files List',
+		destructiveHint: false,
+		readOnlyHint: true,
+		openWorldHint: true,
+	},
+};
+
+export const DOCS_SEMANTIC_SEARCH_CONFIG: BrowserToolConfig = {
+	name: 'hf_doc_search',
+	description:
+		'Search and Discover Hugging Face Product and Library documentation. Send an empty query to discover structure and navigation instructions. ' +
+		`Knowledge up-to-date as at ${KNOWLEDGE_DATE}. Combine with the Product filter to focus results.`,
+	annotations: {
+		title: 'Hugging Face Documentation Search',
+		destructiveHint: false,
+		readOnlyHint: true,
+		openWorldHint: true,
+	},
+};
+
+export const DOC_FETCH_CONFIG: BrowserToolConfig = {
+	name: 'hf_doc_fetch',
+	description:
+		'Fetch a document from the Hugging Face or Gradio documentation library. For large documents, use offset to get subsequent chunks.',
+	annotations: {
+		title: 'Fetch a document from the Hugging Face documentation library',
+		destructiveHint: false,
+		readOnlyHint: true,
+		openWorldHint: true,
+	},
+};
+
+export const SPACE_SEARCH_TOOL_ID = SEMANTIC_SEARCH_TOOL_CONFIG.name;
+export const MODEL_SEARCH_TOOL_ID = 'model_search';
+export const REPO_SEARCH_TOOL_ID = REPO_SEARCH_TOOL_CONFIG.name;
+export const MODEL_DETAIL_TOOL_ID = 'model_details';
+export const PAPER_SEARCH_TOOL_ID = PAPER_SEARCH_TOOL_CONFIG.name;
+export const DATASET_SEARCH_TOOL_ID = 'dataset_search';
+export const DATASET_DETAIL_TOOL_ID = 'dataset_details';
+export const HUB_REPO_DETAILS_TOOL_ID = HUB_REPO_DETAILS_TOOL_CONFIG.name;
+export const DUPLICATE_SPACE_TOOL_ID = DUPLICATE_SPACE_TOOL_CONFIG.name;
+export const SPACE_INFO_TOOL_ID = 'space_info';
+export const SPACE_FILES_TOOL_ID = SPACE_FILES_TOOL_CONFIG.name;
+export const USE_SPACE_TOOL_ID = 'use_space';
+export const DOCS_SEMANTIC_SEARCH_TOOL_ID = DOCS_SEMANTIC_SEARCH_CONFIG.name;
+export const DOC_FETCH_TOOL_ID = DOC_FETCH_CONFIG.name;
+export const HF_JOBS_TOOL_ID = 'hf_jobs';
+export const DYNAMIC_SPACE_TOOL_ID = 'dynamic_space';
+
+export const ALL_BUILTIN_TOOL_IDS = [
+	SPACE_SEARCH_TOOL_ID,
+	MODEL_SEARCH_TOOL_ID,
+	REPO_SEARCH_TOOL_ID,
+	MODEL_DETAIL_TOOL_ID,
+	PAPER_SEARCH_TOOL_ID,
+	DATASET_SEARCH_TOOL_ID,
+	DATASET_DETAIL_TOOL_ID,
+	HUB_REPO_DETAILS_TOOL_ID,
+	DUPLICATE_SPACE_TOOL_ID,
+	SPACE_INFO_TOOL_ID,
+	SPACE_FILES_TOOL_ID,
+	DOCS_SEMANTIC_SEARCH_TOOL_ID,
+	DOC_FETCH_TOOL_ID,
+	USE_SPACE_TOOL_ID,
+	HF_JOBS_TOOL_ID,
+	DYNAMIC_SPACE_TOOL_ID,
+] as const;
+
+export const TOOL_ID_GROUPS = {
+	search: [SPACE_SEARCH_TOOL_ID, REPO_SEARCH_TOOL_ID, PAPER_SEARCH_TOOL_ID, DOCS_SEMANTIC_SEARCH_TOOL_ID] as const,
+	spaces: [
+		SPACE_SEARCH_TOOL_ID,
+		DUPLICATE_SPACE_TOOL_ID,
+		SPACE_INFO_TOOL_ID,
+		SPACE_FILES_TOOL_ID,
+		USE_SPACE_TOOL_ID,
+	] as const,
+	detail: [MODEL_DETAIL_TOOL_ID, DATASET_DETAIL_TOOL_ID, HUB_REPO_DETAILS_TOOL_ID] as const,
+	docs: [DOCS_SEMANTIC_SEARCH_TOOL_ID, DOC_FETCH_TOOL_ID] as const,
+	hf_api: [
+		SPACE_SEARCH_TOOL_ID,
+		REPO_SEARCH_TOOL_ID,
+		PAPER_SEARCH_TOOL_ID,
+		HUB_REPO_DETAILS_TOOL_ID,
+		DOCS_SEMANTIC_SEARCH_TOOL_ID,
+	] as const,
+	dynamic_space: [DYNAMIC_SPACE_TOOL_ID] as const,
+	all: [...ALL_BUILTIN_TOOL_IDS] as const,
+} as const;
+
+export type BuiltinToolId = (typeof ALL_BUILTIN_TOOL_IDS)[number];
+
+export function isValidBuiltinToolId(toolId: string): toolId is BuiltinToolId {
+	return (ALL_BUILTIN_TOOL_IDS as readonly string[]).includes(toolId);
+}

package/src/index.ts

@@ -24,6 +24,7 @@ export * from './jobs/jobs-tool.js';
 export * from './space/dynamic-space-tool.js';
 export * from './space/utils/gradio-caller.js';
 export * from './space/utils/gradio-schema.js';
+export * from './network/url-policy.js';
 
 // Export shared types
 export * from './types/tool-result.js';

package/src/jobs/commands/uv-utils.ts

@@ -6,7 +6,7 @@ export const UV_DEFAULT_IMAGE = 'ghcr.io/astral-sh/uv:python3.12-bookworm';
 type UvCommandOptions = Pick<UvArgs, 'with_deps' | 'python' | 'script_args'>;
 type UvCommandLikeArgs = Pick<UvArgs, 'script' | 'with_deps' | 'python' | 'script_args'>;
 
-export function buildUvCommand(script: string, args: UvCommandOptions): string[] {
+function buildUvCommand(script: string, args: UvCommandOptions): string[] {
 	const parts: string[] = ['uv', 'run'];
 
 	if (args.with_deps && args.with_deps.length > 0) {
@@ -28,7 +28,7 @@ export function buildUvCommand(script: string, args: UvCommandOptions): string[]
 	return parts;
 }
 
-export function wrapInlineScript(script: string, args: UvCommandOptions): string {
+function wrapInlineScript(script: string, args: UvCommandOptions): string {
 	const encoded = Buffer.from(script, 'utf-8').toString('base64');
 	const baseCommand = shellQuote(buildUvCommand('-', args));
 	return `echo "${encoded}" | base64 -d | ${baseCommand}`;

package/src/jobs/jobs-tool.ts

@@ -162,6 +162,17 @@ const HARDWARE_FLAVORS_SECTION = [
 	.filter((line): line is string => Boolean(line))
 	.join('\n');
 
+const UNKNOWN_OPERATION_INSTRUCTIONS = `Available operations:
+- run, uv, ps, logs, inspect, cancel
+- scheduled run, scheduled uv, scheduled ps, scheduled inspect, scheduled delete, scheduled suspend, scheduled resume
+
+Call this tool with no operation for full usage instructions.`;
+
+function formatUnknownOperationMessage(requestedOperation?: string): string {
+	return `Unknown operation: "${requestedOperation ?? 'unknown'}"
+${UNKNOWN_OPERATION_INSTRUCTIONS}`;
+}
+
 function isHelpRequested(args: Record<string, unknown> | undefined): boolean {
 	if (!args) {
 		return false;
@@ -426,12 +437,7 @@ export class HfJobsTool {
 		const normalizedOperation = requestedOperation.toLowerCase();
 		if (!isOperationName(normalizedOperation)) {
 			return {
-				formatted: `Unknown operation: "${requestedOperation}"
-Available operations:
-- run, uv, ps, logs, inspect, cancel
-- scheduled run, scheduled uv, scheduled ps, scheduled inspect, scheduled delete, scheduled suspend, scheduled resume
-
-Call this tool with no operation for full usage instructions.`,
+				formatted: formatUnknownOperationMessage(requestedOperation),
 				totalResults: 0,
 				resultsShared: 0,
 			};
@@ -540,12 +546,7 @@ Call this tool with no operation for full usage instructions.`,
 
 				default:
 					return {
-						formatted: `Unknown operation: "${requestedOperation ?? 'unknown'}"
-Available operations:
-- run, uv, ps, logs, inspect, cancel
-- scheduled run, scheduled uv, scheduled ps, scheduled inspect, scheduled delete, scheduled suspend, scheduled resume
-
-Call this tool with no operation for full usage instructions.`,
+						formatted: formatUnknownOperationMessage(requestedOperation),
 						totalResults: 0,
 						resultsShared: 0,
 					};