mcp-hfspace MCP Server

Instructions

Implementation Reference

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

  Core handler logic for executing the tool: submits parameters to the Gradio client for the /infer endpoint of FLUX.1-schnell space, handles progress and data events, converts results to MCP content.
  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/index.ts:97-134 (handler)

  MCP CallToolRequestSchema handler that looks up the endpoint by tool name ('FLUX_1-schnell-infer') and invokes endpoint.call().
  server.setRequestHandler(CallToolRequestSchema, async (request) => { if (AVAILABLE_FILES === request.params.name) { return { content: [ { type: `resource`, resource: { uri: `/available-files`, mimeType: `text/markdown`, text: await workingDir.generateResourceTable(), }, }, ], }; } 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/index.ts:75-95 (registration)

  Registers the ListToolsRequestSchema handler which includes tool definitions for all endpoints, exposing the 'FLUX_1-schnell-infer' tool.
  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: {}, }, }, ...Array.from(endpoints.values()).map((endpoint) => endpoint.toolDefinition(), ), ], }; });
• src/index.ts:54-69 (registration)

  Creates EndpointWrapper instances for configured spacePaths (defaults to 'evalstate/FLUX.1-schnell'), generates tool name 'FLUX_1-schnell-infer', and registers in endpoints Map by name.
  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 space path 'evalstate/FLUX.1-schnell/infer' and formats mcpToolName to 'FLUX_1-schnell-infer' by replacing invalid characters like '.' with '_'.
  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)

  Default spacePaths configuration to ['evalstate/FLUX.1-schnell'] if no args provided, which generates 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"]; })(), };
• src/endpoint_wrapper.ts:185-191 (schema)

  Generates the tool definition including name 'FLUX_1-schnell-infer', description, and inputSchema converted from the Gradio /infer endpoint API.
  toolDefinition() { return { name: this.mcpToolName, description: `Call the ${this.mcpDescriptionName()}`, inputSchema: convertApiToSchema(this.endpoint), }; }