@llmindset/hf-mcp 0.3.2 → 0.3.4

package/src/network/url-policy.ts

@@ -0,0 +1,304 @@
+export interface UrlPathRules {
+	requiredPrefix?: string;
+}
+
+export type UrlProtocol = 'https:' | 'http:';
+
+export interface UrlQueryRules {
+	allowAny?: boolean;
+	allowKeys?: ReadonlySet<string>;
+}
+
+export interface UrlPolicy {
+	allowedProtocols: ReadonlySet<UrlProtocol>;
+	allowedHosts?: ReadonlySet<string>;
+	allowSubdomainsOf?: readonly string[];
+	requireDefaultPort?: boolean;
+	pathRules?: UrlPathRules;
+	queryRules?: UrlQueryRules;
+	allowCredentials?: boolean;
+	customValidator?: (url: URL) => void;
+}
+
+const LOCALHOST_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+
+const ENCODED_SEPARATOR_RE = /%(?:2f|5c)/i;
+const ENCODED_BYTE_RE = /%[0-9a-f]{2}/i;
+const INVALID_PERCENT_ENCODING_RE = /%(?![0-9a-f]{2})/i;
+
+function normalizeHostname(hostname: string): string {
+	return hostname.toLowerCase().replace(/\.+$/, '');
+}
+
+function safeDecodeURIComponent(value: string): string {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		throw new Error('URL contains invalid percent-encoding');
+	}
+}
+
+function collectDecodedPathVariants(pathname: string): string[] {
+	const variants = [pathname];
+	let current = pathname;
+
+	for (let i = 0; i < 2; i += 1) {
+		if (!current.includes('%')) {
+			break;
+		}
+
+		const decoded = safeDecodeURIComponent(current);
+		if (decoded === current) {
+			break;
+		}
+
+		variants.push(decoded);
+		current = decoded;
+	}
+
+	return variants;
+}
+
+function hasDotSegments(pathname: string): boolean {
+	const normalized = pathname.replace(/\\/g, '/');
+	const segments = normalized.split('/');
+	return segments.some((segment) => segment === '.' || segment === '..');
+}
+
+function matchesRequiredPrefix(pathname: string, requiredPrefix: string): boolean {
+	const normalizedPath = pathname.replace(/\\/g, '/');
+	const normalizedPrefix = requiredPrefix.replace(/\\/g, '/');
+
+	if (normalizedPath === normalizedPrefix) {
+		return true;
+	}
+
+	if (normalizedPrefix.endsWith('/') && normalizedPath === normalizedPrefix.slice(0, -1)) {
+		return true;
+	}
+
+	return normalizedPath.startsWith(normalizedPrefix);
+}
+
+function assertHostAllowed(hostname: string, policy: UrlPolicy): void {
+	if (!policy.allowedHosts && (!policy.allowSubdomainsOf || policy.allowSubdomainsOf.length === 0)) {
+		return;
+	}
+
+	const normalized = normalizeHostname(hostname);
+
+	if (policy.allowedHosts) {
+		for (const host of policy.allowedHosts) {
+			if (normalizeHostname(host) === normalized) {
+				return;
+			}
+		}
+	}
+
+	if (policy.allowSubdomainsOf) {
+		for (const domain of policy.allowSubdomainsOf) {
+			const normalizedDomain = normalizeHostname(domain);
+			if (normalized === normalizedDomain || normalized.endsWith(`.${normalizedDomain}`)) {
+				return;
+			}
+		}
+	}
+
+	throw new Error(`URL hostname is not allowed: ${hostname}`);
+}
+
+function assertPathAllowed(url: URL, pathRules?: UrlPathRules): void {
+	const pathname = url.pathname;
+
+	if (pathname.includes('%') && INVALID_PERCENT_ENCODING_RE.test(pathname)) {
+		throw new Error('URL path contains invalid percent-encoding');
+	}
+
+	const variants = collectDecodedPathVariants(pathname);
+
+	const hasEncodedSeparators = variants.some((variant) => ENCODED_SEPARATOR_RE.test(variant));
+	if (hasEncodedSeparators) {
+		throw new Error('URL path contains encoded separators');
+	}
+
+	const hasUnsafeDotSegments = variants.some((variant) => hasDotSegments(variant));
+	if (hasUnsafeDotSegments) {
+		throw new Error('URL path contains dot-segments');
+	}
+
+	if (variants.length > 1) {
+		const decodedOnce = variants[1] ?? '';
+		if (ENCODED_BYTE_RE.test(decodedOnce)) {
+			throw new Error('URL path appears to use double-encoding');
+		}
+	}
+
+	if (pathRules?.requiredPrefix) {
+		const hasPrefix = variants.some((variant) => matchesRequiredPrefix(variant, pathRules.requiredPrefix ?? ''));
+		if (!hasPrefix) {
+			throw new Error(`URL path must start with ${pathRules.requiredPrefix}`);
+		}
+	}
+}
+
+function assertQueryAllowed(url: URL, policy: UrlPolicy): void {
+	const rules = policy.queryRules;
+	if (!rules || rules.allowAny === true) {
+		return;
+	}
+
+	if (!rules.allowKeys) {
+		if (url.search.length > 0) {
+			throw new Error('URL query string is not allowed');
+		}
+		return;
+	}
+
+	for (const key of url.searchParams.keys()) {
+		if (!rules.allowKeys.has(key)) {
+			throw new Error(`URL query parameter is not allowed: ${key}`);
+		}
+	}
+}
+
+function assertPortAllowed(url: URL, policy: UrlPolicy): void {
+	if (!policy.requireDefaultPort || url.port.length === 0) {
+		return;
+	}
+
+	const defaultPort = url.protocol === 'https:' ? '443' : url.protocol === 'http:' ? '80' : '';
+	if (!defaultPort || url.port !== defaultPort) {
+		throw new Error(`URL port is not allowed for protocol ${url.protocol}`);
+	}
+}
+
+export function validateUrlAgainstPolicy(url: URL, policy: UrlPolicy): void {
+	if (!policy.allowedProtocols.has(url.protocol as UrlProtocol)) {
+		throw new Error(`URL protocol is not allowed: ${url.protocol}`);
+	}
+
+	if (!policy.allowCredentials && (url.username.length > 0 || url.password.length > 0)) {
+		throw new Error('URL credentials are not allowed');
+	}
+
+	assertHostAllowed(url.hostname, policy);
+	assertPortAllowed(url, policy);
+	assertPathAllowed(url, policy.pathRules);
+	assertQueryAllowed(url, policy);
+
+	policy.customValidator?.(url);
+}
+
+export function parseAndValidateUrl(input: string | URL, policy: UrlPolicy): URL {
+	const parsed = input instanceof URL ? new URL(input.toString()) : new URL(input.trim());
+	validateUrlAgainstPolicy(parsed, policy);
+	return parsed;
+}
+
+export function createHfDocsPolicy(): UrlPolicy {
+	const hfHosts = new Set(['huggingface.co', 'www.huggingface.co']);
+
+	return {
+		allowedProtocols: new Set(['https:']),
+		allowedHosts: new Set(['huggingface.co', 'www.huggingface.co', 'gradio.app', 'www.gradio.app']),
+		allowCredentials: false,
+		queryRules: { allowAny: true },
+		customValidator: (url) => {
+			const host = normalizeHostname(url.hostname);
+			if (hfHosts.has(host) && !matchesRequiredPrefix(url.pathname, '/docs/')) {
+				throw new Error('Hugging Face docs URLs must remain under /docs/');
+			}
+		},
+	};
+}
+
+export function createGradioMcpPolicy(): UrlPolicy {
+	return {
+		allowedProtocols: new Set(['https:', 'http:']),
+		pathRules: {
+			requiredPrefix: '/gradio_api/mcp',
+		},
+		allowCredentials: false,
+		queryRules: { allowAny: true },
+		customValidator: (url) => {
+			const enforceLocalHttpOnly = process.env.NODE_ENV === 'production';
+			if (enforceLocalHttpOnly && url.protocol === 'http:' && !isLocalhostHostname(url.hostname)) {
+				throw new Error('HTTP is only allowed for localhost Gradio MCP endpoints');
+			}
+		},
+	};
+}
+
+export function isLocalhostHostname(hostname: string): boolean {
+	return LOCALHOST_HOSTS.has(normalizeHostname(hostname));
+}
+
+export function createExternalHttpsPolicy(): UrlPolicy {
+	return {
+		allowedProtocols: new Set(['https:']),
+		allowCredentials: false,
+		queryRules: { allowAny: true },
+	};
+}
+
+export function createHuggingFaceHubPolicy(): UrlPolicy {
+	return {
+		allowedProtocols: new Set(['https:']),
+		allowedHosts: new Set(['huggingface.co', 'www.huggingface.co', 'hf.co']),
+		allowCredentials: false,
+		queryRules: { allowAny: true },
+	};
+}
+
+export function createLocalhostHttpPolicy(): UrlPolicy {
+	return {
+		allowedProtocols: new Set(['https:', 'http:']),
+		allowedHosts: new Set(['localhost', '127.0.0.1', '[::1]']),
+		allowCredentials: false,
+		queryRules: { allowAny: true },
+	};
+}
+
+export function createExactHostPolicy(hostname: string, allowedProtocol: UrlProtocol): UrlPolicy {
+	return {
+		allowedProtocols: new Set([allowedProtocol]),
+		allowedHosts: new Set([hostname.toLowerCase()]),
+		allowCredentials: false,
+		queryRules: { allowAny: true },
+	};
+}
+
+export function createHostPrefixPolicy(
+	hostname: string,
+	requiredPrefix: string,
+	allowedProtocol: UrlProtocol = 'https:'
+): UrlPolicy {
+	return {
+		allowedProtocols: new Set([allowedProtocol]),
+		allowedHosts: new Set([hostname.toLowerCase()]),
+		pathRules: {
+			requiredPrefix,
+		},
+		allowCredentials: false,
+		queryRules: { allowAny: true },
+	};
+}
+
+export function createGradioMcpHostPolicy(
+	hostname: string,
+	allowedProtocol: UrlProtocol
+): UrlPolicy {
+	return createHostPrefixPolicy(hostname, '/gradio_api/mcp', allowedProtocol);
+}
+
+export function createGradioSchemaHostPolicy(hostname: string): UrlPolicy {
+	return createHostPrefixPolicy(hostname, '/gradio_api/mcp/schema');
+}
+
+export function createHttpOrHttpsPolicy(): UrlPolicy {
+	return {
+		allowedProtocols: new Set(['https:', 'http:']),
+		allowCredentials: false,
+		queryRules: { allowAny: true },
+	};
+}

package/src/readme-utils.ts

@@ -2,12 +2,14 @@
  * Utility functions for fetching and processing README files from Hugging Face repositories
  */
 
+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;
 
 /**
  * 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)
@@ -20,14 +22,13 @@ export async function fetchReadmeContent(
 ): Promise<string | null> {
 	try {
 		// Construct the URL based on repository type
-		const baseUrl = type === 'datasets' 
-			? `https://huggingface.co/datasets/${repoName}`
-			: `https://huggingface.co/${repoName}`;
-		
+		const baseUrl =
+			type === 'datasets' ? `https://huggingface.co/datasets/${repoName}` : `https://huggingface.co/${repoName}`;
+
 		const url = `${baseUrl}/resolve/main/README.md`;
 
-		const response = await fetch(url);
-		
+		const { response } = await fetchWithProfile(url, NETWORK_FETCH_PROFILES.hfHub());
+
 		if (!response.ok) {
 			if (response.status === 404) {
 				// README doesn't exist, return null silently
@@ -64,7 +65,7 @@ export async function fetchReadmeContent(
 
 /**
  * Strips YAML frontmatter from markdown content
- * 
+ *
  * @param content The full markdown content
  * @returns The content with YAML frontmatter removed
  */
@@ -72,12 +73,12 @@ 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;
 }

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);
-		}
-	}

package/src/space/commands/view-parameters.ts

@@ -2,6 +2,7 @@ import type { ToolResult } from '../../types/tool-result.js';
 import type { Tool } from '@modelcontextprotocol/sdk/types.js';
 import { analyzeSchemaComplexity } from '../utils/schema-validator.js';
 import { formatParameters, formatComplexSchemaError } from '../utils/parameter-formatter.js';
+import { fetchGradioSchema, fetchSpaceMetadata } from '../utils/space-http.js';
 
 /**
  * Fetches space metadata and schema to discover parameters
@@ -56,7 +57,8 @@ export async function viewParameters(spaceName: string, hfToken?: string): Promi
 		let formattedError = `Error fetching parameters for space '${spaceName}': ${errorMessage}`;
 
 		if (is404) {
-			formattedError += '\n\nNote: The space MUST be an MCP enabled space. Use the `space_search` tool to find MCP enabled spaces.';
+			formattedError +=
+				'\n\nNote: The space MUST be an MCP enabled space. Use the `space_search` tool to find MCP enabled spaces.';
 		}
 
 		return {
@@ -67,138 +69,3 @@ export async function viewParameters(spaceName: string, hfToken?: string): Promi
 		};
 	}
 }
-
-/**
- * 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)
-		return parseSchemaResponse(schemaResponse);
-	} finally {
-		clearTimeout(timeoutId);
-	}
-}
-
-/**
- * Parses schema response and extracts tools
- */
-function parseSchemaResponse(schemaResponse: unknown): Tool[] {
-	const tools: Tool[] = [];
-
-	if (Array.isArray(schemaResponse)) {
-		// Array format: [{ name: "toolName", description: "...", inputSchema: {...} }, ...]
-		for (const item of schemaResponse) {
-			if (
-				typeof item === 'object' &&
-				item !== null &&
-				'name' in item &&
-				'inputSchema' in item
-			) {
-				const itemRecord = item as Record<string, unknown>;
-				if (typeof itemRecord.name === 'string') {
-					const tool = itemRecord as { name: string; description?: string; inputSchema: unknown };
-					tools.push({
-						name: tool.name,
-						description: tool.description || `${tool.name} tool`,
-						inputSchema: {
-							type: 'object',
-							...(tool.inputSchema as Record<string, unknown>),
-						},
-					});
-				}
-			}
-		}
-	} else if (typeof schemaResponse === 'object' && schemaResponse !== null) {
-		// Object format: { "toolName": { properties: {...}, required: [...] }, ... }
-		for (const [name, toolSchema] of Object.entries(schemaResponse)) {
-			if (typeof toolSchema === 'object' && toolSchema !== null) {
-				const schema = toolSchema as { description?: string };
-				tools.push({
-					name,
-					description: schema.description || `${name} tool`,
-					inputSchema: {
-						type: 'object',
-						...(toolSchema as Record<string, unknown>),
-					},
-				});
-			}
-		}
-	}
-
-	return tools.filter((tool) => !tool.name.toLowerCase().includes('<lambda'));
-}

package/src/space/dynamic-space-tool.ts

@@ -144,6 +144,10 @@ function getUsageInstructions(): string {
 	return isDynamicSpaceMode() ? DYNAMIC_USAGE_INSTRUCTIONS : USAGE_INSTRUCTIONS;
 }
 
+function formatUnknownOperationLine(requestedOperation?: string): string {
+	return `Unknown operation: "${requestedOperation ?? 'unknown'}"`;
+}
+
 /**
  * Space tool configuration
  * Returns dynamic config based on environment
@@ -222,7 +226,7 @@ export class SpaceTool {
 		const validOperations = getOperationNames();
 		if (!validOperations.includes(normalizedOperation)) {
 			return {
-				formatted: `Unknown operation: "${requestedOperation}"
+				formatted: `${formatUnknownOperationLine(requestedOperation)}
 Available operations: ${validOperations.join(', ')}
 
 Call this tool with no operation for full usage instructions.`,
@@ -249,7 +253,7 @@ Call this tool with no operation for full usage instructions.`,
 
 				default:
 					return {
-						formatted: `Unknown operation: "${requestedOperation}"`,
+						formatted: formatUnknownOperationLine(requestedOperation),
 						totalResults: 0,
 						resultsShared: 0,
 						isError: true,