IP Geolocation MCP Server

Instructions

Implementation Reference

• src/tools/security.ts:150-168 (handler)

  The handler function for the bulk_security_check tool which fetches data via getSecurityBulk and handles caching/formatting.

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

• src/tools/security.ts:112-169 (registration)

  The registration of the bulk_security_check tool in the McpServer, including its schema definition.

    server.registerTool(
      "bulk_security_check",
      {
        title: "Bulk Security Check",
        annotations: {
          readOnlyHint: true,
        },
        description: `Decision policy: this is a single-domain bulk tool. Use it only when the user asks for security/threat data only. If each IP request also needs other domains (ownership, location, network, timezone, currency, or abuse), call bulk_lookup_ip once with include and targeted fields/excludes.
  
  Bulk IP security lookup via POST /v3/security-bulk for up to ${MAX_BULK_ITEMS.toLocaleString()} IPs per MCP request. Paid only. Cost: 2 credits per valid IP.
  
  Use bulk_lookup_ip with include=security when the same batch also needs geolocation or other IP domains. Tool selection rule: call this tool once per IP batch and post-process locally. Do not re-call bulk_security_check for the same batch only to change fields/excludes or output shape.`,
        inputSchema: {
          ips: z
            .array(z.string())
            .min(1)
            .max(MAX_BULK_ITEMS)
            .describe(
              `Array of IPv4 and/or IPv6 addresses to check. Minimum 1, maximum ${MAX_BULK_ITEMS.toLocaleString()} in this MCP server.`
            ),
          fields: z
            .string()
            .optional()
            .describe(
              "Comma-separated dot-path fields to return per IP (e.g. security.threat_score,security.is_vpn). Reduces response size."
            ),
          excludes: z
            .string()
            .optional()
            .describe(
              "Comma-separated dot-path fields to exclude per IP (e.g. security.is_tor,security.is_cloud_provider)."
            ),
          force_refresh: z
            .boolean()
            .optional()
            .describe("Default false. Leave unset unless the user asks to refresh or rerun."),
        },
      },
      async (params) => {
        try {
          const cacheKey = buildSecurityBulkCacheKey(params);
          const cached = params.force_refresh ? undefined : getCachedValue(cacheKey);
  
          const result = cached ?? (await getSecurityBulk(params));
          if (cached === undefined) {
            setCachedValue(cacheKey, result);
          }
  
          return {
            content: [
              { type: "text" as const, text: formatToolResult(result) },
            ],
          };
        } catch (error) {
          return errorToolResponse(error);
        }
      }
    );