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