@llmindset/hf-mcp 0.2.40 → 0.2.42

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

@@ -0,0 +1,204 @@
+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';
+
+/**
+ * Fetches space metadata and schema to discover parameters
+ */
+export async function viewParameters(spaceName: string, hfToken?: string): Promise<ToolResult> {
+	try {
+		// Step 1: Fetch space metadata to get subdomain
+		const metadata = await fetchSpaceMetadata(spaceName, hfToken);
+
+		// Step 2: Fetch schema from Gradio endpoint
+		const tools = await fetchGradioSchema(metadata.subdomain, metadata.private, hfToken);
+
+		// For simplicity, we'll work with the first tool
+		// (most Gradio spaces expose a single primary tool)
+		if (tools.length === 0) {
+			return {
+				formatted: `Error: No tools found for space '${spaceName}'.`,
+				totalResults: 0,
+				resultsShared: 0,
+				isError: true,
+			};
+		}
+
+		const tool = tools[0] as Tool;
+
+		// Step 3: Analyze schema complexity
+		const schemaResult = analyzeSchemaComplexity(tool);
+
+		if (!schemaResult.isSimple) {
+			return {
+				formatted: formatComplexSchemaError(spaceName, schemaResult.reason || 'Unknown reason'),
+				totalResults: 0,
+				resultsShared: 0,
+				isError: true,
+			};
+		}
+
+		// Step 4: Format parameters for display
+		const formatted = formatParameters(schemaResult, spaceName);
+
+		return {
+			formatted,
+			totalResults: schemaResult.parameters.length,
+			resultsShared: schemaResult.parameters.length,
+		};
+	} catch (error) {
+		const errorMessage = error instanceof Error ? error.message : String(error);
+
+		// Check if this is a 404 error (space not found)
+		const is404 = errorMessage.includes('404') || errorMessage.toLowerCase().includes('not found');
+
+		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.';
+		}
+
+		return {
+			formatted: formattedError,
+			totalResults: 0,
+			resultsShared: 0,
+			isError: true,
+		};
+	}
+}
+
+/**
+ * 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/space-tool.ts

@@ -0,0 +1,252 @@
+import type { ToolResult } from '../types/tool-result.js';
+import type { ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types.js';
+import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import { spaceArgsSchema, OPERATION_NAMES, type OperationName, type SpaceArgs, type InvokeResult } from './types.js';
+import { viewParameters } from './commands/view-parameters.js';
+import { invokeSpace } from './commands/invoke.js';
+
+// Re-export types (including InvokeResult for external use)
+export * from './types.js';
+
+/**
+ * Usage instructions when tool is called with no operation
+ */
+const USAGE_INSTRUCTIONS = `# Gradio Space Interaction
+
+Dynamically interact with any Gradio MCP Space. View parameter schemas or invoke spaces with custom parameters.
+
+## Supported Schema Types
+
+✅ **Simple types** (supported):
+- Strings, numbers, booleans
+- Enums (predefined value sets)
+- Arrays of primitives
+- Shallow objects (one level deep)
+- FileData (as URL strings)
+
+❌ **Complex types** (not supported):
+- Deeply nested objects (2+ levels)
+- Arrays of objects
+- Union types
+- Recursive schemas
+
+For spaces with complex schemas, direct the user to huggingface.co/settings/mcp to manage their settings.
+
+## Available Operations
+
+### view_parameters
+Display the parameter schema for a space's first tool.
+
+**Example:**
+\`\`\`json
+{
+  "operation": "view_parameters",
+  "space_name": "evalstate/FLUX1_schnell"
+}
+\`\`\`
+
+### invoke
+Execute a space's first tool with provided parameters.
+
+**Example:**
+\`\`\`json
+{
+  "operation": "invoke",
+  "space_name": "evalstate/FLUX1_schnell",
+  "parameters": "{\\"prompt\\": \\"a cute cat\\", \\"num_steps\\": 4}"
+}
+\`\`\`
+
+## Workflow
+
+1. **Discover parameters** - Use \`view_parameters\` to see what a space accepts
+2. **Invoke the space** - Use \`invoke\` with the required parameters
+3. **Review results** - Get formatted output (text, images, resources)
+
+## File Handling
+
+For parameters that accept files (FileData types):
+- Provide a publicly accessible URL (http:// or https://)
+- Example: \`{"image": "https://example.com/photo.jpg"}\`
+- To upload local files, use the dedicated gr_* prefixed tool for that space
+
+## Tips
+
+- The tool automatically applies default values for optional parameters
+- Unknown parameters generate warnings but are still passed through (permissive inputs)
+- Enum parameters show all allowed values in view_parameters
+- Required parameters are clearly marked and validated
+`;
+
+/**
+ * Space tool configuration
+ */
+export const DYNAMIC_SPACE_TOOL_CONFIG = {
+	name: 'dynamic_space',
+	description:
+		'Dynamically interact with Gradio MCP Spaces . View parameter schemas or invoke spaces with custom parameters. ' +
+		'Supports simple parameter types (strings, numbers, booleans, arrays, enums, shallow objects). ' +
+		'Call with no operation for full usage instructions.',
+	schema: spaceArgsSchema,
+	annotations: {
+		title: 'Gradio Space Interaction',
+		readOnlyHint: false,
+		openWorldHint: true,
+	},
+} as const;
+
+/**
+ * Space tool implementation
+ */
+export class SpaceTool {
+	private hfToken?: string;
+
+	constructor(hfToken?: string) {
+		this.hfToken = hfToken;
+	}
+
+	/**
+	 * Execute a space operation
+	 * Returns InvokeResult (with raw MCP content) for invoke operation,
+	 * or ToolResult (with formatted text) for other operations
+	 */
+	async execute(
+		params: SpaceArgs,
+		extra?: RequestHandlerExtra<ServerRequest, ServerNotification>
+	): Promise<InvokeResult | ToolResult> {
+		const requestedOperation = params.operation;
+
+		// If no operation provided, return usage instructions
+		if (!requestedOperation) {
+			return {
+				formatted: USAGE_INSTRUCTIONS,
+				totalResults: 1,
+				resultsShared: 1,
+			};
+		}
+
+		// Validate operation
+		const normalizedOperation = requestedOperation.toLowerCase();
+		if (!isOperationName(normalizedOperation)) {
+			return {
+				formatted: `Unknown operation: "${requestedOperation}"
+Available operations: ${OPERATION_NAMES.join(', ')}
+
+Call this tool with no operation for full usage instructions.`,
+				totalResults: 0,
+				resultsShared: 0,
+				isError: true,
+			};
+		}
+
+		// Execute operation
+		try {
+			switch (normalizedOperation) {
+				case 'view_parameters':
+					return await this.handleViewParameters(params);
+
+				case 'invoke':
+					return await this.handleInvoke(params, extra);
+
+				default:
+					return {
+						formatted: `Unknown operation: "${requestedOperation}"`,
+						totalResults: 0,
+						resultsShared: 0,
+						isError: true,
+					};
+			}
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			return {
+				formatted: `Error executing ${requestedOperation}: ${errorMessage}`,
+				totalResults: 0,
+				resultsShared: 0,
+				isError: true,
+			};
+		}
+	}
+
+	/**
+	 * Handle view_parameters operation
+	 */
+	private async handleViewParameters(params: SpaceArgs): Promise<ToolResult> {
+		if (!params.space_name) {
+			return {
+				formatted: `Error: Missing required parameter: "space_name"
+
+Example:
+\`\`\`json
+{
+  "operation": "view_parameters",
+  "space_name": "username/space-name"
+}
+\`\`\``,
+				totalResults: 0,
+				resultsShared: 0,
+				isError: true,
+			};
+		}
+
+		return await viewParameters(params.space_name, this.hfToken);
+	}
+
+	/**
+	 * Handle invoke operation
+	 * Returns either InvokeResult (with raw MCP content) or ToolResult (error messages)
+	 */
+	private async handleInvoke(
+		params: SpaceArgs,
+		extra?: RequestHandlerExtra<ServerRequest, ServerNotification>
+	): Promise<InvokeResult | ToolResult> {
+		// Validate required parameters
+		if (!params.space_name) {
+			return {
+				formatted: `Error: Missing required parameter: "space_name"
+
+Example:
+\`\`\`json
+{
+  "operation": "invoke",
+  "space_name": "username/space-name",
+  "parameters": "{\\"param1\\": \\"value1\\"}"
+}
+\`\`\``,
+				totalResults: 0,
+				resultsShared: 0,
+				isError: true,
+			};
+		}
+
+		if (!params.parameters) {
+			return {
+				formatted: `Error: Missing required parameter: "parameters"
+
+The "parameters" field must be a JSON object string containing the space parameters.
+
+Example:
+\`\`\`json
+{
+  "operation": "invoke",
+  "space_name": "${params.space_name}",
+  "parameters": "{\\"param1\\": \\"value1\\", \\"param2\\": 42}"
+}
+\`\`\`
+
+Use "view_parameters" to see what parameters this space accepts.`,
+				totalResults: 0,
+				resultsShared: 0,
+				isError: true,
+			};
+		}
+
+		return await invokeSpace(params.space_name, params.parameters, this.hfToken, extra);
+	}
+}
+
+/**
+ * Type guard for operation names
+ */
+function isOperationName(value: string): value is OperationName {
+	return (OPERATION_NAMES as readonly string[]).includes(value);
+}

package/src/space/types.ts

@@ -0,0 +1,127 @@
+import { z } from 'zod';
+
+/**
+ * Operations supported by the space tool
+ */
+export const OPERATION_NAMES = ['view_parameters', 'invoke'] as const;
+export type OperationName = (typeof OPERATION_NAMES)[number];
+
+/**
+ * Zod schema for operation arguments
+ */
+export const spaceArgsSchema = z.object({
+	operation: z
+		.enum(OPERATION_NAMES)
+		.optional()
+		.describe('Operation to execute. Valid values: "view_parameters", "invoke"'),
+	space_name: z.string().optional().describe('The Hugging Face space ID (format: "username/space-name")'),
+	parameters: z.string().optional().describe('For invoke operation: JSON object string of parameters'),
+});
+
+export type SpaceArgs = z.infer<typeof spaceArgsSchema>;
+
+/**
+ * Parameter information extracted from schema
+ */
+export interface ParameterInfo {
+	name: string;
+	type: string;
+	description?: string;
+	required: boolean;
+	default?: unknown;
+	enum?: unknown[];
+	isFileData?: boolean;
+	complexType?: string; // Reason why the type is complex
+}
+
+/**
+ * Result of schema complexity analysis
+ */
+export interface SchemaComplexityResult {
+	isSimple: boolean;
+	reason?: string; // Reason if not simple
+	parameters: ParameterInfo[];
+	toolName: string;
+	toolDescription?: string;
+}
+
+/**
+ * Result of parameter processing
+ */
+export interface ProcessParametersResult {
+	valid: boolean;
+	parameters?: Record<string, unknown>;
+	error?: string;
+	warnings?: string[];
+}
+
+/**
+ * JSON Schema property definition
+ */
+export interface JsonSchemaProperty {
+	type?: string;
+	title?: string;
+	description?: string;
+	default?: unknown;
+	enum?: unknown[];
+	format?: string;
+	properties?: Record<string, JsonSchemaProperty>;
+	items?: JsonSchemaProperty;
+	required?: string[];
+	[key: string]: unknown;
+}
+
+/**
+ * JSON Schema definition
+ */
+export interface JsonSchema {
+	type?: string;
+	properties?: Record<string, JsonSchemaProperty>;
+	required?: string[];
+	description?: string;
+	[key: string]: unknown;
+}
+
+/**
+ * File input help message constant
+ */
+export const FILE_INPUT_HELP_MESSAGE =
+	'Provide a publicly accessible URL (http:// or https://) pointing to the file. ' +
+	'To upload local files, use the dedicated gr_* prefixed tool for this space, which supports file upload.';
+
+/**
+ * Check if a property is a FileData type
+ */
+export function isFileDataProperty(prop: JsonSchemaProperty): boolean {
+	return (
+		prop.title === 'ImageData' ||
+		prop.title === 'FileData' ||
+		(prop.format?.includes('http') && prop.format?.includes('file')) ||
+		false
+	);
+}
+
+/**
+ * Check if a schema contains file data
+ */
+export function hasFileData(schema: JsonSchema): boolean {
+	if (!schema.properties) return false;
+
+	return Object.values(schema.properties).some((prop) => isFileDataProperty(prop));
+}
+
+/**
+ * Extended result type for invoke operation that includes raw MCP result
+ * This allows the space tool to return structured content blocks instead of formatted text
+ */
+export interface InvokeResult {
+	result: {
+		content: unknown[];
+		isError?: boolean;
+		[key: string]: unknown;
+	};
+	warnings: string[];
+	totalResults: number;
+	resultsShared: number;
+	isError?: boolean;
+}