mcp-api-tools

Instructions

Implementation Reference

• src/index.ts:230-259 (handler)

  The request handler for 'url_parse', which delegates to 'parseUrl' or 'buildUrl' based on the input arguments.

  case "url_parse": {
    if (args?.build_params) {
      const built = buildUrl(
        args.build_params as {
          protocol?: string;
          hostname: string;
          port?: string | number;
          pathname?: string;
          query_params?: Record<string, string | string[]>;
          hash?: string;
          username?: string;
          password?: string;
        }
      );
      return {
        content: [
          { type: "text", text: JSON.stringify({ built_url: built }, null, 2) },
        ],
      };
    }
    if (args?.url) {
      const parsed = parseUrl(args.url as string);
      return {
        content: [{ type: "text", text: JSON.stringify(parsed, null, 2) }],
      };
    }
    throw new Error("Provide either 'url' to parse or 'build_params' to build");
  }
  
  case "header_analyzer": {

• src/index.ts:125-162 (schema)

  Tool definition and input schema registration for 'url_parse'.

  {
    name: "url_parse",
    description:
      "Parse a URL into its component parts: protocol, host, port, path, query parameters, hash, and more. Can also build a URL from parts.",
    inputSchema: {
      type: "object" as const,
      properties: {
        url: {
          type: "string",
          description: "URL to parse (use this OR build_params, not both)",
        },
        build_params: {
          type: "object",
          description: "Build a URL from parts instead of parsing",
          properties: {
            protocol: { type: "string", description: "Protocol (default: https:)" },
            hostname: { type: "string", description: "Hostname (required)" },
            port: { type: "string", description: "Port number" },
            pathname: { type: "string", description: "Path (default: /)" },
            query_params: {
              type: "object",
              description: "Query parameters as key-value pairs",
              additionalProperties: {
                oneOf: [
                  { type: "string" },
                  { type: "array", items: { type: "string" } },
                ],
              },
            },
            hash: { type: "string", description: "Hash/fragment" },
            username: { type: "string", description: "URL username" },
            password: { type: "string", description: "URL password" },
          },
          required: ["hostname"],
        },
      },
    },
  },

• src/tools/url-parser.ts:27-108 (helper)

  The core implementation functions 'parseUrl' and 'buildUrl' used by the 'url_parse' tool.

  export function parseUrl(url: string): ParsedUrl {
    let parsed: URL;
    try {
      parsed = new URL(url);
    } catch {
      throw new Error(`Invalid URL: ${url}`);
    }
  
    const queryParams: Record<string, string | string[]> = {};
    parsed.searchParams.forEach((value, key) => {
      const existing = queryParams[key];
      if (existing === undefined) {
        queryParams[key] = value;
      } else if (Array.isArray(existing)) {
        existing.push(value);
      } else {
        queryParams[key] = [existing, value];
      }
    });
  
    return {
      href: parsed.href,
      protocol: parsed.protocol,
      host: parsed.host,
      hostname: parsed.hostname,
      port: parsed.port,
      pathname: parsed.pathname,
      search: parsed.search,
      query_params: queryParams,
      hash: parsed.hash,
      origin: parsed.origin,
      username: parsed.username,
      password: parsed.password,
    };
  }
  
  export function buildUrl(params: BuildUrlParams): string {
    const {
      protocol = "https:",
      hostname,
      port,
      pathname = "/",
      query_params,
      hash,
      username,
      password,
    } = params;
  
    if (!hostname) {
      throw new Error("hostname is required to build a URL");
    }
  
    const proto = protocol.endsWith(":") ? protocol : protocol + ":";
    const url = new URL(`${proto}//${hostname}`);
  
    if (port !== undefined && port !== "") {
      url.port = String(port);
    }
  
    url.pathname = pathname;
  
    if (query_params) {
      for (const [key, value] of Object.entries(query_params)) {
        if (Array.isArray(value)) {
          for (const v of value) {
            url.searchParams.append(key, v);
          }
        } else {
          url.searchParams.set(key, value);
        }
      }
    }
  
    if (hash) {
      url.hash = hash.startsWith("#") ? hash : `#${hash}`;
    }
  
    if (username) url.username = username;
    if (password) url.password = password;
  
    return url.href;
  }