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),
    };
  }