mcp-hfspace MCP Server

Instructions

Implementation Reference

• src/endpoint_wrapper.ts:193-304 (handler)

  Main execution logic for the tool: processes input arguments (handles file uploads), submits to the Gradio /infer endpoint of the FLUX.1-schnell space, reports progress, handles errors, and converts outputs to MCP content using GradioConverter.
  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); } 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), ); } } } private async convertPredictResults( returns: ApiReturn[], predictResults: unknown[], endpointPath: EndpointPath, ): Promise<CallToolResult> { const content: (TextContent | ImageContent | EmbeddedResource)[] = []; for (const [index, output] of returns.entries()) { const value = predictResults[index]; const converted = await this.converter.convert( output, value as GradioResourceValue, endpointPath, ); content.push(converted); } return { content, isError: false, }; }
• src/gradio_convert.ts:98-127 (schema)

  Converts the Gradio ApiEndpoint parameters to the MCP tool inputSchema used by 'FLUX_1-schnell-infer'.
  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/index.ts:54-69 (registration)

  Creates and registers the EndpointWrapper instance for the default spacePath 'evalstate/FLUX.1-schnell' (generating tool name 'FLUX_1-schnell-infer') in the endpoints map, which is used by the MCP CallToolRequestHandler.
  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/endpoint_wrapper.ts:41-68 (helper)

  Parses the configured path 'evalstate/FLUX.1-schnell/infer' to compute mcpToolName 'FLUX_1-schnell-infer' (replaces . with _). Called during EndpointWrapper creation.
  export function parsePath(path: string): EndpointPath { const parts = path.replace(/^\//, "").split("/"); if (parts.length != 3) { throw new Error( `Invalid Endpoint path format [${path}]. Use or vendor/space/endpoint`, ); } const [owner, space, rawEndpoint] = parts; return { owner, space, endpoint: isNaN(Number(rawEndpoint)) ? `/${rawEndpoint}` : parseInt(rawEndpoint), mcpToolName: formatMcpToolName(space, rawEndpoint), mcpDisplayName: formatMcpDisplayName(space, rawEndpoint), }; function formatMcpToolName(space: string, endpoint: string | number) { return `${space}-${endpoint}`.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64); } function formatMcpDisplayName(space: string, endpoint: string | number) { return `${space} endpoint /${endpoint}`; } }
• src/config.ts:32-36 (helper)

  Defines the default HF Space path 'evalstate/FLUX.1-schnell', leading to creation of the 'FLUX_1-schnell-infer' tool.
  spacePaths: (() => { const filtered = argv._.filter((arg) => arg.toString().trim().length > 0); return filtered.length > 0 ? filtered : ["evalstate/FLUX.1-schnell"]; })(), };