mcp-hfspace

Instructions

Implementation Reference

• src/endpoint_wrapper.ts:226-281 (handler)

  Core handler function that executes the Gradio client.submit to the /infer endpoint of FLUX.1-schnell space, processes events, progress, and converts results to MCP format.
  async handleToolCall( parameters: Record<string, unknown>, progressToken: string | undefined, server: Server, ): Promise<CallToolResult> { const events = []; try { let result = null; const submission: AsyncIterable<GradioEvent> = this.client.submit( this.endpointPath.endpoint, parameters, ) as AsyncIterable<GradioEvent>; const progressNotifier = createProgressNotifier(server); for await (const msg of submission) { if (config.debug) events.push(msg); if (msg.type === "data") { if (Array.isArray(msg.data)) { const hasContent = msg.data.some( (item: unknown) => typeof item !== "object", ); if (hasContent) result = msg.data; if (null === result) result = msg.data; } } else if (msg.type === "status") { if (msg.stage === "error") { throw new Error(`Gradio error: ${msg.message || "Unknown error"}`); } if (progressToken) await progressNotifier.notify(msg, progressToken); } } if (!result) { throw new Error("No data received from endpoint"); } return await this.convertPredictResults( this.endpoint.returns, result, this.endpointPath, ); } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); throw new Error(`Error calling endpoint: ${errorMessage}`); } finally { if (config.debug && events.length > 0) { await fs.writeFile( `${this.mcpToolName}_status_${crypto .randomUUID() .substring(0, 5)}.json`, JSON.stringify(events, null, 2), ); } } }
• src/endpoint_wrapper.ts:193-224 (handler)

  Entry point for tool execution, processes input arguments (handles files), normalizes progress token, and delegates to handleToolCall.
  async call( request: CallToolRequest, server: Server, ): Promise<CallToolResult> { const progressToken = request.params._meta?.progressToken as | string | number | undefined; const parameters = request.params.arguments as Record<string, unknown>; // Get the endpoint parameters to check against const endpointParams = this.endpoint.parameters; // Process each parameter, applying handle_file for file inputs for (const [key, value] of Object.entries(parameters)) { const param = endpointParams.find( (p) => p.parameter_name === key || p.label === key, ); if (param && isFileParameter(param) && typeof value === "string") { const file = await this.validatePath(value); parameters[key] = handle_file(file); } } const normalizedToken = typeof progressToken === "number" ? progressToken.toString() : progressToken; return this.handleToolCall(parameters, normalizedToken, server); }
• src/index.ts:56-71 (registration)

  Creates EndpointWrapper instances for each configured spacePath (including default 'black-forest-labs/FLUX.1-schnell'), sets mcpToolName to 'FLUX_1-schnell-infer', and stores in endpoints map used for registration.
  for (const spacePath of config.spacePaths) { try { const endpoint = await EndpointWrapper.createEndpoint( spacePath, workingDir, ); endpoints.set(endpoint.toolDefinition().name, endpoint); } catch (e) { if (e instanceof Error) { console.error(`Error loading ${spacePath}: ${e.message}`); } else { throw e; } continue; } }
• src/index.ts:77-115 (registration)

  Registers all endpoint tools (including FLUX_1-schnell-infer) in the MCP listTools handler by mapping endpoints to their toolDefinition().
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: AVAILABLE_FILES, description: "A list of available file and resources. " + "If the User requests things like 'most recent image' or 'the audio' use " + "this tool to identify the intended resource." + "This tool returns 'resource uri', 'name', 'size', 'last modified' and 'mime type' in a markdown table", inputSchema: { type: "object", properties: {}, }, }, { name: SEARCH_FOR_SPACE, description: "Use semantic search to find an endpoint on the `Hugging Face Spaces` service. The search term will usually " + "be 3-7 words describing a task or activity the Person is trying to accomplish. The results are returned in a markdown table. " + "Present all results to the Person. Await specific guidance from the Person before making further Tool calls.", inputSchema: { type: "object", properties: { query: { type: "string", // TODO description assumes user is using claude desktop which has knowledge of HF Spaces. // consider updating for not CLAUDE_DESKTOP mode. 3.7 sys prompt refers to Human as Person description: "The semantic search term to use.", }, }, }, }, ...Array.from(endpoints.values()).map((endpoint) => endpoint.toolDefinition(), ), ], }; });
• src/index.ts:167-188 (registration)

  Registers the callTool handler that dispatches calls to the specific EndpointWrapper.call() based on tool name.
  const endpoint = endpoints.get(request.params.name); if (!endpoint) { throw new Error(`Unknown tool: ${request.params.name}`); } try { return await endpoint.call(request, server); } catch (error) { if (error instanceof Error) { return { content: [ { type: `text`, text: `mcp-hfspace error: ${error.message}`, }, ], isError: true, }; } throw error; } });
• src/gradio_convert.ts:98-127 (schema)

  Generates the MCP inputSchema for the tool from the Gradio ApiEndpoint parameters (used by toolDefinition()).
  export function convertApiToSchema(endpoint: ApiEndpoint) { const properties: { [key: string]: ParameterSchema } = {}; const required: string[] = []; let propertyCounter = 1; const unnamedParameters: Record<string, number> = {}; endpoint.parameters.forEach((param: ApiParameter, index: number) => { // Get property name from parameter_name, label, or generate one const propertyName = param.parameter_name || param.label || `Unnamed Parameter ${propertyCounter++}`; if (!param.parameter_name) { unnamedParameters[propertyName] = index; } // Convert parameter using existing function properties[propertyName] = convertParameter(param); // Add to required if no default value if (!param.parameter_has_default) { required.push(propertyName); } }); return { type: "object", properties, required, }; }
• src/config.ts:32-38 (helper)

  Defines the default HuggingFace space path 'black-forest-labs/FLUX.1-schnell' used to create the FLUX_1-schnell-infer tool.
  spacePaths: (() => { const filtered = argv._.filter((arg) => arg.toString().trim().length > 0); return filtered.length > 0 ? filtered : ["black-forest-labs/FLUX.1-schnell"]; })(), };