IP Geolocation MCP Server

Instructions

Implementation Reference

• src/tools/useragent.ts:42-62 (handler)

  The handler for the 'parse_user_agent' tool, which handles user-agent parsing with caching and error handling.

  async (params) => {
    try {
      const cacheKey = buildUserAgentCacheKey(params.uaString);
      const cached = params.force_refresh ? undefined : getCachedValue(cacheKey);
      const result =
        cached ??
        (await parseUserAgent({
          uaString: params.uaString,
        }));
      if (cached === undefined) {
        setCachedValue(cacheKey, result);
      }
      return {
        content: [
          { type: "text" as const, text: formatToolResult(result) },
        ],
      };
    } catch (error) {
      return errorToolResponse(error);
    }
  }

• src/tools/useragent.ts:20-41 (registration)

  Registration of the 'parse_user_agent' tool in the MCP server.

    server.registerTool(
      "parse_user_agent",
      {
        title: "User-Agent Parser",
        annotations: {
          readOnlyHint: true,
        },
        description: `Parse an explicit user-agent string via POST /v3/user-agent. Paid only. Cost: 1 credit. Returns browser, device, OS, and engine details.
  
  This MCP tool parses only the uaString you pass. It does not infer a caller user-agent from the MCP transport. For multiple strings, use bulk_parse_user_agent.`,
        inputSchema: {
          uaString: z
            .string()
            .describe(
              "The user-agent string to parse (e.g. Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36)."
            ),
          force_refresh: z
            .boolean()
            .optional()
            .describe("Default false. Leave unset unless the user asks to refresh or rerun."),
        },
      },

• src/client.ts:316-324 (helper)

  The API client helper function that performs the actual network request to parse a user-agent.

  export async function parseUserAgent(params: {
    uaString: string;
  }): Promise<unknown> {
    return request(
      "/v3/user-agent",
      {},
      { method: "POST", body: { uaString: params.uaString } }
    );
  }