@llmindset/hf-mcp 0.2.50 → 0.2.51

package/src/space/space-tool.ts

@@ -1,7 +1,16 @@
 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 type { z } from 'zod';
+import {
+	spaceArgsSchema,
+	type SpaceArgs,
+	type InvokeResult,
+	isDynamicSpaceMode,
+	getOperationNames,
+	getSpaceArgsSchema,
+} from './types.js';
+import { findSpaces } from './commands/dynamic-find.js';
 import { discoverSpaces } from './commands/discover.js';
 import { viewParameters } from './commands/view-parameters.js';
 import { invokeSpace } from './commands/invoke.js';
@@ -14,7 +23,7 @@ export * from './types.js';
  */
 const USAGE_INSTRUCTIONS = `# Gradio Space Interaction
 
-Dynamically interact with any Gradio MCP Space. Discover dynamic spaces, view space parameter schemas, and invoke spaces.
+Dynamically interact with any Gradio MCP Space. Find spaces, view space parameter schemas, and invoke spaces.
 
 ## Supported Schema Types
 
@@ -25,17 +34,17 @@ Dynamically interact with any Gradio MCP Space. Discover dynamic spaces, view sp
 - Shallow objects (one level deep)
 - FileData (as URL strings)
 
-To use spaces with complex schemas, add them from  huggingface.co/settings/mcp.
+To use spaces with complex schemas, add them from huggingface.co/settings/mcp.
 
 ## Available Operations
 
-### discover
+### Find
 Find MCP-enabled Spaces for available for invocation based on task-focused or semantic searches.
 
 **Example:**
 \`\`\`json
 {
-  "operation": "discover",
+  "operation": "find",
   "search_query": "image generation",
   "limit": 10
 }
@@ -66,7 +75,7 @@ Execute a space's first tool with provided parameters.
 
 ## Workflow
 
-1. **Discover Spaces** - Use \`discover\` to find MCP-enabled spaces for your task
+1. **Find Spaces** - Use \`find\` to find MCP-enabled spaces for your task
 2. **Inspect Parameters** - Use \`view_parameters\` to see what a space accepts
 3. **Invoke the Space** - Use \`invoke\` with the required parameters
 
@@ -86,17 +95,108 @@ For parameters that accept files (FileData types):
 - Required parameters are clearly marked and validated
 `;
 
+/**
+ * Usage instructions for dynamic mode (when DYNAMIC_SPACE_DATA is set)
+ * Simplified instructions focusing on discover/view_parameters/invoke workflow
+ */
+const DYNAMIC_USAGE_INSTRUCTIONS = `# Gradio Space Interaction
+
+Dynamically use Gradio MCP Spaces. Discover available spaces, view their parameter schemas, and invoke them. Use "discover" to find recommended spaces for tasks.
+
+## Available Operations
+
+### discover
+List recommended spaces and their categories.
+
+**Example:**
+\`\`\`json
+{
+  "operation": "discover"
+}
+\`\`\`
+
+### 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 Spaces** - Use \`discover\` to see available spaces
+2. **Inspect Parameters** - Use \`view_parameters\` to see what a space accepts
+3. **Invoke the Space** - Use \`invoke\` with the required parameters
+
+## File Handling
+
+For parameters that accept files (FileData types):
+- Provide a publicly accessible URL (http:// or https://)
+- Example: \`{"image": "https://example.com/photo.jpg"}\`
+- Output url's from one tool may be used as inputs to another.
+`;
+
+/**
+ * Get the appropriate usage instructions based on mode
+ */
+function getUsageInstructions(): string {
+	return isDynamicSpaceMode() ? DYNAMIC_USAGE_INSTRUCTIONS : USAGE_INSTRUCTIONS;
+}
+
 /**
  * Space tool configuration
+ * Returns dynamic config based on environment
+ */
+export function getDynamicSpaceToolConfig(): {
+	name: string;
+	description: string;
+	schema: z.ZodObject<z.ZodRawShape>;
+	annotations: { title: string; readOnlyHint: boolean; openWorldHint: boolean };
+} {
+	const dynamicMode = isDynamicSpaceMode();
+	return {
+		name: 'dynamic_space',
+		description: dynamicMode
+			? 'Discover, inspect (view parameter schema) and dynamically invoke Gradio MCP Spaces to conduct ML Tasks including Image Generation, Background Removal, Text to Speech and more ' +
+				'Call with no operation for full usage instructions.'
+			: 'Find (semantic/task search), inspect (view parameter schema) and dynamically invoke Gradio MCP Spaces. ' +
+				'Call with no operation for full usage instructions.',
+		schema: getSpaceArgsSchema(),
+		annotations: {
+			title: 'Dynamically use Gradio Applications',
+			readOnlyHint: false,
+			openWorldHint: true,
+		},
+	};
+}
+
+/**
+ * Space tool configuration (static, for backward compatibility)
  */
 export const DYNAMIC_SPACE_TOOL_CONFIG = {
 	name: 'dynamic_space',
 	description:
-		'Discover (semantic/task search), inspect (view parameter schema) and dynamically invoke Gradio MCP Spaces to perform various ML Tasks. ' +
+		'Find (semantic/task search), inspect (view parameter schema) and dynamically invoke Gradio MCP Spaces. ' +
 		'Call with no operation for full usage instructions.',
 	schema: spaceArgsSchema,
 	annotations: {
-		title: 'Gradio Space Interaction',
+		title: 'Dynamically use Gradio Applications',
 		readOnlyHint: false,
 		openWorldHint: true,
 	},
@@ -126,7 +226,7 @@ export class SpaceTool {
 		// If no operation provided, return usage instructions
 		if (!requestedOperation) {
 			return {
-				formatted: USAGE_INSTRUCTIONS,
+				formatted: getUsageInstructions(),
 				totalResults: 1,
 				resultsShared: 1,
 			};
@@ -134,10 +234,11 @@ export class SpaceTool {
 
 		// Validate operation
 		const normalizedOperation = requestedOperation.toLowerCase();
-		if (!isOperationName(normalizedOperation)) {
+		const validOperations = getOperationNames();
+		if (!validOperations.includes(normalizedOperation)) {
 			return {
 				formatted: `Unknown operation: "${requestedOperation}"
-Available operations: ${OPERATION_NAMES.join(', ')}
+Available operations: ${validOperations.join(', ')}
 
 Call this tool with no operation for full usage instructions.`,
 				totalResults: 0,
@@ -149,8 +250,11 @@ Call this tool with no operation for full usage instructions.`,
 		// Execute operation
 		try {
 			switch (normalizedOperation) {
+				case 'find':
+					return await this.handleFind(params);
+
 				case 'discover':
-					return await this.handleDiscover(params);
+					return await this.handleDiscover();
 
 				case 'view_parameters':
 					return await this.handleViewParameters(params);
@@ -178,10 +282,17 @@ Call this tool with no operation for full usage instructions.`,
 	}
 
 	/**
-	 * Handle discover operation
+	 * Handle find operation
 	 */
-	private async handleDiscover(params: SpaceArgs): Promise<ToolResult> {
-		return await discoverSpaces(params.search_query, params.limit, this.hfToken);
+	private async handleFind(params: SpaceArgs): Promise<ToolResult> {
+		return await findSpaces(params.search_query, params.limit, this.hfToken);
+	}
+
+	/**
+	 * Handle discover operation (for dynamic space mode)
+	 */
+	private async handleDiscover(): Promise<ToolResult> {
+		return await discoverSpaces();
 	}
 
 	/**
@@ -260,10 +371,3 @@ Use "view_parameters" to see what parameters this space accepts.`,
 		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

@@ -2,12 +2,30 @@ import { z } from 'zod';
 
 /**
  * Operations supported by the space tool
+ * Standard mode: find, view_parameters, invoke
+ * Dynamic mode (DYNAMIC_SPACE_DATA): discover, view_parameters, invoke
  */
-export const OPERATION_NAMES = ['discover', 'view_parameters', 'invoke'] as const;
+export const OPERATION_NAMES = ['find', 'view_parameters', 'invoke'] as const;
+export const DYNAMIC_OPERATION_NAMES = ['discover', 'view_parameters', 'invoke'] as const;
 export type OperationName = (typeof OPERATION_NAMES)[number];
+export type DynamicOperationName = (typeof DYNAMIC_OPERATION_NAMES)[number];
 
 /**
- * Zod schema for operation arguments
+ * Check if dynamic space mode is enabled
+ */
+export function isDynamicSpaceMode(): boolean {
+	return !!process.env.DYNAMIC_SPACE_DATA;
+}
+
+/**
+ * Get the appropriate operation names based on mode
+ */
+export function getOperationNames(): readonly string[] {
+	return isDynamicSpaceMode() ? DYNAMIC_OPERATION_NAMES : OPERATION_NAMES;
+}
+
+/**
+ * Zod schema for operation arguments (standard mode)
  */
 export const spaceArgsSchema = z.object({
 	operation: z.enum(OPERATION_NAMES).optional().describe('Operation to execute.'),
@@ -22,11 +40,32 @@ export const spaceArgsSchema = z.object({
 		.string()
 		.optional()
 		.describe(
-			'For discover operation: Search query or task category (e.g. "Image Generation", "OCR", "FLUX image generation") to find MCP-enabled Spaces. Call with blank query to see task hints.'
+			'For find operation: Search query or task category (e.g. "Image Generation", "OCR", "FLUX image generation") to find MCP-enabled Spaces. Call with blank query to see task hints.'
 		),
-	limit: z.number().optional().describe('For discover operation: Maximum number of results to return (default: 10)'),
+	limit: z.number().optional().describe('For find operation: Maximum number of results to return (default: 10)'),
 });
 
+/**
+ * Zod schema for operation arguments (dynamic mode with DYNAMIC_SPACE_DATA)
+ */
+export const dynamicSpaceArgsSchema = z.object({
+	operation: z.enum(DYNAMIC_OPERATION_NAMES).optional().describe('Operation to execute.'),
+	space_name: z
+		.string()
+		.optional()
+		.describe(
+			'The Hugging Face space ID (format: "username/space-name"). Required for view_parameters and invoke operations.'
+		),
+	parameters: z.string().optional().describe('For invoke operation: JSON object string of parameters'),
+});
+
+/**
+ * Get the appropriate schema based on mode
+ */
+export function getSpaceArgsSchema(): z.ZodObject<z.ZodRawShape> {
+	return isDynamicSpaceMode() ? dynamicSpaceArgsSchema : spaceArgsSchema;
+}
+
 export type SpaceArgs = z.infer<typeof spaceArgsSchema>;
 
 /**
@@ -96,7 +135,7 @@ export interface JsonSchema {
  */
 export const FILE_INPUT_HELP_MESSAGE =
 	'Provide a publicly accessible URL (http:// or https://) for the Gradio file input. ' +
-	"Content previuosly generated by 'invoke' is usable, as well as Hub Repository URLs. ";
+	"Content previously generated by 'invoke' is usable, as well as Hub Repository URLs. ";
 
 /**
  * Check if a property is a FileData type