IP Geolocation MCP Server

Instructions

Implementation Reference

• src/tools/asn.ts:141-176 (handler)

  The handler function for the "lookup_asn" tool, which processes input parameters, handles caching, calls the ASN API, applies field projections, and formats the result.

  async (params) => {
    try {
      const effectiveInclude = buildEffectiveAsnInclude(params);
      const cacheKey = buildAsnCacheKey({
        ...params,
        include: effectiveInclude,
      });
      const cached = params.force_refresh ? undefined : getCachedValue(cacheKey);
  
      const baseResult =
        cached ??
        (await getAsn({
          asn: params.asn,
          ip: params.ip,
          include: effectiveInclude || undefined,
        }));
  
      if (cached === undefined) {
        setCachedValue(cacheKey, baseResult);
      }
  
      const result = applyFieldsAndExcludes(baseResult, {
        fields: params.fields,
        excludes: params.excludes,
        rootKey: "asn",
      });
  
      return {
        content: [
          { type: "text" as const, text: formatToolResult(result) },
        ],
      };
    } catch (error) {
      return errorToolResponse(error);
    }
  }

• src/tools/asn.ts:88-140 (registration)

  The registration of the "lookup_asn" tool, including its schema definition and documentation.

    server.registerTool(
      "lookup_asn",
      {
        title: "ASN Details",
        annotations: {
          readOnlyHint: true,
        },
        description: `Decision policy: call lookup_asn once per ASN/IP target with required include values decided up front. Hard rule: do not call lookup_asn a second time for the same target in the same answer unless the first call failed or required data is truly missing.
  
  If the first response already contains a superset of needed data, extract the requested subset locally and do not call lookup_asn again just to trim output.
  
  Detailed ASN lookup via GET /v3/asn. Paid only. Cost: 1 credit. Query by AS number or IP. Returns core ASN details and can include peers, downstreams, upstreams, routes, and WHOIS.
  
  Use lookup_ip for basic ASN data. Use this tool only when you need extended ASN datasets.
  
  Tool selection rule: if this tool is used, call it once per ASN/IP target and include set, then post-process locally. Do not re-call lookup_asn for the same target only to change fields/excludes or output shape.`,
        inputSchema: {
          asn: z
            .string()
            .optional()
            .describe(
              "AS number to look up (e.g. AS13335 or just 13335). Takes priority over ip if both are provided."
            ),
          ip: z
            .string()
            .optional()
            .describe(
              "IPv4 or IPv6 address to find the ASN for. Used only if asn is not provided."
            ),
          include: z
            .string()
            .optional()
            .describe(
              "Comma-separated extra data to include: peers, downstreams, upstreams, routes, whois_response. No additional credit cost."
            ),
          fields: z
            .string()
            .optional()
            .describe(
              "Comma-separated dot-path fields to return (e.g. asn.as_number,asn.organization or upstreams.as_number). Paths can be full (asn.upstreams.as_number) or relative to the asn root (upstreams.as_number). Use include for optional datasets (peers/downstreams/upstreams/routes/whois_response), then use fields to keep only required paths."
            ),
          excludes: z
            .string()
            .optional()
            .describe(
              "Comma-separated dot-path fields to exclude (e.g. asn.date_allocated,asn.rir or upstreams.description). Paths can be full or relative to the asn root."
            ),
          force_refresh: z
            .boolean()
            .optional()
            .describe("Default false. Leave unset unless the user asks to refresh or rerun."),
        },
      },