fetch_openapi_spec

Instructions

Implementation Reference

• src/tools/fetch_openapi_spec.ts:25-80 (handler)

  Core implementation of the fetch_openapi_spec tool handler. Normalizes input URLs, parses targets, checks domains, fetches content, and returns text contents.

  export const fetch_openapi_spec = async (
    input: UrlFetchInput,
    extra: RequestHandlerExtra<ServerRequest, ServerNotification>,
    allowedDomains: Set<string>
  ): Promise<CallToolResult> => {
    logger.debug("Processing fetch_openapi_spec request with input:", input);
  
    // Normalize input to always be an array of { url: string } objects
    const urlList = normalizeUrlInput(input);
    const results: TextContent[] = [];
  
    for (const urlItem of urlList) {
      const url = urlItem.url;
  
      try {
        logger.debug(`Processing OpenAPI spec URL: ${url}`);
  
        // Validate the URL and get target info using the library function
        const targetInfo = await parseFetchTarget(url);
        if (targetInfo.type === "unsupported") {
          const errorMsg = `Unsupported URL format: ${targetInfo.reason}`;
          logger.error(errorMsg);
          throw new Error(errorMsg);
        }
  
        logger.debug(`Target info:`, targetInfo);
  
        // Check domain access using the library function
        checkDomainAccess(targetInfo, allowedDomains);
  
        logger.debug(`Fetching OpenAPI spec from: ${url}`);
  
        // Fetch the content using the library function
        const fileContent = await fetchContent(targetInfo);
        results.push({
          type: "text",
          text: fileContent,
        });
  
        logger.debug(
          `Successfully fetched ${fileContent.length} bytes from ${url}`
        );
      } catch (error) {
        const errorMsg = `Failed to process OpenAPI spec request for ${url}: ${
          error instanceof Error ? error.message : String(error)
        }`;
        logger.error(errorMsg);
        throw new Error(errorMsg);
      }
    }
  
    logger.debug(`Successfully processed ${results.length} OpenAPI specs`);
    return {
      content: results,
    };
  };

• src/tools/tool_schemas.ts:9-32 (schema)

  Zod schema defining the input for URL fetch tools, supporting single URL string, URL object, or array. Used by both fetch_openapi_spec and fetch_llms_txt.

  export const UrlFetchInputSchema = z.union([
    z.string().url("Input must be a valid URL string"),
    z.object({
      url: z
        .string()
        .url("Input must contain a valid URL string under the 'url' key"),
    }),
    z.array(
      z.union([
        z.string().url("Each array item must be a valid URL string"),
        z.object({
          url: z
            .string()
            .url(
              "Each array item must contain a valid URL string under the 'url' key"
            ),
        }),
      ])
    ),
  ]);
  
  // Type exports for use in function parameters
  export type UrlFetchInput = z.infer<typeof UrlFetchInputSchema>;

• src/index.ts:90-101 (registration)

  Tool capabilities declaration including name, description, inputSchema reference, and annotations.

  fetch_openapi_spec: {
    name: "fetch_openapi_spec",
    description: "Fetches the content of a OpenAPI spec url.",
    inputSchema: UrlFetchInputSchema,
    annotations: {
      title: "Fetch OpenAPI spec content",
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true,
    },
  },

• src/index.ts:142-161 (registration)

  Actual server.tool registration that wraps the imported handler, handles params.input extraction, and passes extra and allowedDomains.

  server.tool(
    "fetch_openapi_spec",
    "Fetches the content of one or more OpenAPI spec URLs.",
    {
      input: UrlFetchInputSchema.describe(
        "URL string, URL object, or array of URL/objects to fetch OpenAPI specs from"
      ),
    },
    async (params, extra) => {
      const input = params?.input ?? params;
      if (!input) {
        throw new Error("No input provided to fetch_openapi_spec");
      }
      return fetch_openapi_spec(
        input,
        extra as RequestHandlerExtra<ServerRequest, ServerNotification>,
        allowedDomains
      );
    }
  );