serper-toolkit 0.0.4__py3-none-any.whl

serper_toolkit/__init__.py

@@ -0,0 +1,4 @@
+# serper/__init__.py
+from .server import main
+
+__all__ = ["main"]

serper_toolkit/__main__.py

@@ -0,0 +1,10 @@
+# serper_toolkit/__main__.py
+
+from . import server
+
+def main():
+    """Package entry point."""
+    server.main()
+
+if __name__ == "__main__":
+    main()

serper_toolkit/data/country_aliases.json

@@ -0,0 +1,248 @@
+{
+  "AF": ["AF", "Afghanistan", "Islamic Republic of Afghanistan", "AFG", "阿富汗", "阿富汗伊斯兰共和国"],
+  "AL": ["AL", "Albania", "Republic of Albania", "ALB", "阿尔巴尼亚"],
+  "DZ": ["DZ", "Algeria", "People's Democratic Republic of Algeria", "DZA", "阿尔及利亚"],
+  "AS": ["AS", "American Samoa", "AS", "美属萨摩亚"],
+  "AD": ["AD", "Andorra", "Principality of Andorra", "AND", "安道尔"],
+  "AO": ["AO", "Angola", "Republic of Angola", "AGO", "安哥拉"],
+  "AI": ["AI", "Anguilla", "AI", "安圭拉"],
+  "AQ": ["AQ", "Antarctica", "AQ", "南极洲"],
+  "AG": ["AG", "Antigua and Barbuda", "Antigua & Barbuda", "ATG", "安提瓜和巴布达"],
+  "AR": ["AR", "Argentina", "Argentine Republic", "ARG", "阿根廷"],
+  "AM": ["AM", "Armenia", "Republic of Armenia", "ARM", "亚美尼亚"],
+  "AW": ["AW", "Aruba", "AW", "阿鲁巴"],
+  "AU": ["AU", "Australia", "Commonwealth of Australia", "AUS", "澳大利亚", "Australia", "Down Under", "Oz"],
+  "AT": ["AT", "Austria", "Republic of Austria", "AUT", "奥地利"],
+  "AZ": ["AZ", "Azerbaijan", "Republic of Azerbaijan", "AZE", "阿塞拜疆"],
+  "BS": ["BS", "Bahamas", "Commonwealth of The Bahamas", "BHS", "巴哈马", "The Bahamas"],
+  "BH": ["BH", "Bahrain", "Kingdom of Bahrain", "BHR", "巴林"],
+  "BD": ["BD", "Bangladesh", "People's Republic of Bangladesh", "BGD", "孟加拉国", "孟加拉"],
+  "BB": ["BB", "Barbados", "BB", "巴巴多斯"],
+  "BY": ["BY", "Belarus", "Republic of Belarus", "BLR", "白俄罗斯"],
+  "BE": ["BE", "Belgium", "Kingdom of Belgium", "BEL", "比利时"],
+  "BZ": ["BZ", "Belize", "BZE", "伯利兹"],
+  "BJ": ["BJ", "Benin", "Republic of Benin", "BEN", "贝宁"],
+  "BM": ["BM", "Bermuda", "BM", "百慕大"],
+  "BT": ["BT", "Bhutan", "Kingdom of Bhutan", "BTN", "不丹"],
+  "BO": ["BO", "Bolivia", "Plurinational State of Bolivia", "BOL", "玻利维亚"],
+  "BA": ["BA", "Bosnia and Herzegovina", "BiH", "BA", "波黑", "波斯尼亚和黑塞哥维那"],
+  "BW": ["BW", "Botswana", "Republic of Botswana", "BWA", "博茨瓦纳"],
+  "BV": ["BV", "Bouvet Island", "Bouvetøya", "BV", "布韦岛"],
+  "BR": ["BR", "Brazil", "Federative Republic of Brazil", "BRA", "巴西"],
+  "IO": ["IO", "British Indian Ocean Territory", "BIOT", "英属印度洋领地"],
+  "BN": ["BN", "Brunei", "Brunei Darussalam", "BRN", "文莱", "文莱达鲁萨兰国"],
+  "BG": ["BG", "Bulgaria", "Republic of Bulgaria", "BGR", "保加利亚"],
+  "BF": ["BF", "Burkina Faso", "BFA", "布基纳法索"],
+  "BI": ["BI", "Burundi", "Republic of Burundi", "BDI", "布隆迪"],
+  "KH": ["KH", "Cambodia", "Kingdom of Cambodia", "KHM", "柬埔寨"],
+  "CM": ["CM", "Cameroon", "Republic of Cameroon", "CMR", "喀麦隆"],
+  "CA": ["CA", "Canada", "CA", "加拿大"],
+  "CV": ["CV", "Cape Verde", "Cabo Verde", "CPV", "佛得角", "开普绿洲"],
+  "KY": ["KY", "Cayman Islands", "KY", "开曼群岛"],
+  "CF": ["CF", "Central African Republic", "CAR", "中非共和国", "中非"],
+  "TD": ["TD", "Chad", "TCD", "乍得"],
+  "CL": ["CL", "Chile", "Republic of Chile", "CHL", "智利"],
+  "CN": ["CN", "China", "People's Republic of China", "PRC", "CHN", "中国", "中华人民共和国", "Mainland China", "大陆"],
+  "CX": ["CX", "Christmas Island", "CX", "圣诞岛"],
+  "CC": ["CC", "Cocos (Keeling) Islands", "CC", "科科斯（基林）群岛"],
+  "CO": ["CO", "Colombia", "Republic of Colombia", "COL", "哥伦比亚"],
+  "KM": ["KM", "Comoros", "Union of the Comoros", "COM", "科摩罗"],
+  "CG": ["CG", "Congo", "Republic of the Congo", "COG", "刚果（布）", "Congo-Brazzaville"],
+  "CD": ["CD", "Congo (Democratic Republic)", "DRC", "COD", "刚果（金）", "Democratic Republic of the Congo"],
+  "CK": ["CK", "Cook Islands", "CK", "库克群岛"],
+  "CR": ["CR", "Costa Rica", "Republic of Costa Rica", "CRI", "哥斯达黎加"],
+  "CI": ["CI", "Ivory Coast", "Côte d'Ivoire", "CIV", "科特迪瓦", "象牙海岸"],
+  "HR": ["HR", "Croatia", "Republic of Croatia", "HRV", "克罗地亚"],
+  "CU": ["CU", "Cuba", "Republic of Cuba", "CUB", "古巴"],
+  "CY": ["CY", "Cyprus", "Republic of Cyprus", "CYP", "塞浦路斯"],
+  "CZ": ["CZ", "Czechia", "Czech Republic", "CZE", "捷克", "捷克共和国"],
+  "DK": ["DK", "Denmark", "Kingdom of Denmark", "DNK", "丹麦"],
+  "DJ": ["DJ", "Djibouti", "Republic of Djibouti", "DJI", "吉布提"],
+  "DM": ["DM", "Dominica", "DM", "多米尼克"],
+  "DO": ["DO", "Dominican Republic", "DOM", "多米尼加共和国"],
+  "EC": ["EC", "Ecuador", "ECU", "厄瓜多尔"],
+  "EG": ["EG", "Egypt", "Arab Republic of Egypt", "EGY", "埃及"],
+  "SV": ["SV", "El Salvador", "SLV", "萨尔瓦多"],
+  "GQ": ["GQ", "Equatorial Guinea", "GNQ", "赤道几内亚"],
+  "ER": ["ER", "Eritrea", "ERI", "厄立特里亚"],
+  "EE": ["EE", "Estonia", "EST", "爱沙尼亚"],
+  "SZ": ["SZ", "Eswatini", "Kingdom of Eswatini", "SWZ", "斯威士兰", "埃斯瓦蒂尼"],
+  "ET": ["ET", "Ethiopia", "Federal Democratic Republic of Ethiopia", "ETH", "埃塞俄比亚"],
+  "FK": ["FK", "Falkland Islands", "FK", "福克兰群岛", "马尔维纳斯"],
+  "FO": ["FO", "Faroe Islands", "FO", "法罗群岛"],
+  "FJ": ["FJ", "Fiji", "FJI", "斐济"],
+  "FI": ["FI", "Finland", "Republic of Finland", "FIN", "芬兰"],
+  "FR": ["FR", "France", "French Republic", "FRA", "法国"],
+  "GF": ["GF", "French Guiana", "FG", "法属圭亚那"],
+  "PF": ["PF", "French Polynesia", "PF", "法属玻利尼西亚"],
+  "TF": ["TF", "French Southern Territories", "TF", "法属南部领地"],
+  "GA": ["GA", "Gabon", "Gabonese Republic", "GAB", "加蓬"],
+  "GM": ["GM", "Gambia", "The Gambia", "GMB", "冈比亚"],
+  "GE": ["GE", "Georgia", "GE", "格鲁吉亚"],
+  "DE": ["DE", "Germany", "Federal Republic of Germany", "DEU", "德国", "Deutschland"],
+  "GH": ["GH", "Ghana", "GHA", "加纳"],
+  "GI": ["GI", "Gibraltar", "GI", "直布罗陀"],
+  "GR": ["GR", "Greece", "Hellenic Republic", "GRC", "希腊"],
+  "GL": ["GL", "Greenland", "GL", "格陵兰"],
+  "GD": ["GD", "Grenada", "GRD", "格林纳达"],
+  "GP": ["GP", "Guadeloupe", "GP", "瓜德罗普"],
+  "GU": ["GU", "Guam", "GU", "关岛"],
+  "GT": ["GT", "Guatemala", "GTM", "危地马拉"],
+  "GG": ["GG", "Guernsey", "GG", "根西岛"],
+  "GN": ["GN", "Guinea", "GIN", "几内亚"],
+  "GW": ["GW", "Guinea-Bissau", "GNB", "几内亚比绍"],
+  "GY": ["GY", "Guyana", "GUY", "圭亚那"],
+  "HT": ["HT", "Haiti", "HTI", "海地"],
+  "HM": ["HM", "Heard Island and McDonald Islands", "HM", "赫德岛和麦克唐纳群岛"],
+  "VA": ["VA", "Holy See", "Vatican City", "VAT", "梵蒂冈", "教廷"],
+  "HN": ["HN", "Honduras", "HND", "洪都拉斯"],
+  "HK": ["HK", "Hong Kong", "Hong Kong SAR", "HK", "香港", "香港特别行政区"],
+  "HU": ["HU", "Hungary", "HUN", "匈牙利"],
+  "IS": ["IS", "Iceland", "ISL", "冰岛"],
+  "IN": ["IN", "India", "Republic of India", "IND", "印度"],
+  "ID": ["ID", "Indonesia", "Republic of Indonesia", "IDN", "印尼", "印度尼西亚"],
+  "IR": ["IR", "Iran", "Islamic Republic of Iran", "IRN", "伊朗"],
+  "IQ": ["IQ", "Iraq", "IRQ", "伊拉克"],
+  "IE": ["IE", "Ireland", "Republic of Ireland", "IRL", "爱尔兰"],
+  "IM": ["IM", "Isle of Man", "IM", "马恩岛"],
+  "IL": ["IL", "Israel", "State of Israel", "ISR", "以色列"],
+  "IT": ["IT", "Italy", "Italian Republic", "ITA", "意大利"],
+  "JM": ["JM", "Jamaica", "JAM", "牙买加"],
+  "JP": ["JP", "Japan", "JPN", "日本", "Nippon"],
+  "JE": ["JE", "Jersey", "JE", "泽西岛"],
+  "JO": ["JO", "Jordan", "JOR", "约旦"],
+  "KZ": ["KZ", "Kazakhstan", "Republic of Kazakhstan", "KAZ", "哈萨克斯坦"],
+  "KE": ["KE", "Kenya", "KEN", "肯尼亚"],
+  "KI": ["KI", "Kiribati", "KIR", "基里巴斯"],
+  "KP": ["KP", "North Korea", "Democratic People's Republic of Korea", "PRK", "朝鲜", "朝鲜民主主义人民共和国"],
+  "KR": ["KR", "South Korea", "Republic of Korea", "KOR", "韩国", "大韩民国", "Republic of Korea", "Korea, Republic of"],
+  "KW": ["KW", "Kuwait", "KWT", "科威特"],
+  "KG": ["KG", "Kyrgyzstan", "Kyrgyz Republic", "KGZ", "吉尔吉斯斯坦", "吉尔吉斯"],
+  "LA": ["LA", "Laos", "Lao People's Democratic Republic", "LAO", "老挝", "老挝人民民主共和国"],
+  "LV": ["LV", "Latvia", "LVA", "拉脱维亚"],
+  "LB": ["LB", "Lebanon", "LBN", "黎巴嫩"],
+  "LS": ["LS", "Lesotho", "LSO", "莱索托"],
+  "LR": ["LR", "Liberia", "LBR", "利比里亚"],
+  "LY": ["LY", "Libya", "Libyan Arab Jamahiriya", "LBY", "利比亚"],
+  "LI": ["LI", "Liechtenstein", "LIE", "列支敦士登"],
+  "LT": ["LT", "Lithuania", "LTU", "立陶宛"],
+  "LU": ["LU", "Luxembourg", "LUX", "卢森堡"],
+  "MO": ["MO", "Macau", "Macau SAR", "MO", "澳门", "澳门特别行政区"],
+  "MG": ["MG", "Madagascar", "MDG", "马达加斯加"],
+  "MW": ["MW", "Malawi", "MWI", "马拉维"],
+  "MY": ["MY", "Malaysia", "MYS", "马来西亚"],
+  "MV": ["MV", "Maldives", "MDV", "马尔代夫"],
+  "ML": ["ML", "Mali", "MLI", "马里"],
+  "MT": ["MT", "Malta", "MLT", "马耳他"],
+  "MH": ["MH", "Marshall Islands", "MHL", "马绍尔群岛"],
+  "MQ": ["MQ", "Martinique", "MQ", "马提尼克"],
+  "MR": ["MR", "Mauritania", "MRT", "毛里塔尼亚"],
+  "MU": ["MU", "Mauritius", "MUS", "毛里求斯"],
+  "YT": ["YT", "Mayotte", "YT", "马约特"],
+  "MX": ["MX", "Mexico", "United Mexican States", "MEX", "墨西哥"],
+  "FM": ["FM", "Micronesia", "Federated States of Micronesia", "FSM", "密克罗尼西亚"],
+  "MD": ["MD", "Moldova", "Republic of Moldova", "MDA", "摩尔多瓦"],
+  "MC": ["MC", "Monaco", "Principality of Monaco", "MCO", "摩纳哥"],
+  "MN": ["MN", "Mongolia", "MNG", "蒙古", "蒙古国"],
+  "ME": ["ME", "Montenegro", "MNE", "黑山"],
+  "MS": ["MS", "Montserrat", "MSR", "蒙特塞拉特"],
+  "MA": ["MA", "Morocco", "Kingdom of Morocco", "MAR", "摩洛哥"],
+  "MZ": ["MZ", "Mozambique", "MOZ", "莫桑比克"],
+  "MM": ["MM", "Myanmar", "Burma", "MMR", "缅甸", "缅甸联邦"],
+  "NA": ["NA", "Namibia", "NAM", "纳米比亚"],
+  "NR": ["NR", "Nauru", "NRU", "瑙鲁"],
+  "NP": ["NP", "Nepal", "NPL", "尼泊尔"],
+  "NL": ["NL", "Netherlands", "Holland", "NLD", "荷兰", "尼德兰"],
+  "NC": ["NC", "New Caledonia", "NC", "新喀里多尼亚"],
+  "NZ": ["NZ", "New Zealand", "NZ", "新西兰"],
+  "NI": ["NI", "Nicaragua", "NIC", "尼加拉瓜"],
+  "NE": ["NE", "Niger", "Niger Republic", "NER", "尼日尔"],
+  "NG": ["NG", "Nigeria", "NGA", "尼日利亚"],
+  "NU": ["NU", "Niue", "NIU", "纽埃"],
+  "NF": ["NF", "Norfolk Island", "NF", "诺福克岛"],
+  "MK": ["MK", "North Macedonia", "Republic of North Macedonia", "MKD", "北马其顿", "马其顿"],
+  "MP": ["MP", "Northern Mariana Islands", "MP", "北马里亚纳群岛"],
+  "NO": ["NO", "Norway", "NOR", "挪威"],
+  "OM": ["OM", "Oman", "OMN", "阿曼"],
+  "PK": ["PK", "Pakistan", "Islamic Republic of Pakistan", "PAK", "巴基斯坦"],
+  "PW": ["PW", "Palau", "PLW", "帕劳"],
+  "PS": ["PS", "Palestine", "State of Palestine", "PSE", "巴勒斯坦"],
+  "PA": ["PA", "Panama", "PAN", "巴拿马"],
+  "PG": ["PG", "Papua New Guinea", "PNG", "巴布亚新几内亚"],
+  "PY": ["PY", "Paraguay", "PRY", "巴拉圭"],
+  "PE": ["PE", "Peru", "PER", "秘鲁"],
+  "PH": ["PH", "Philippines", "PHL", "菲律宾"],
+  "PN": ["PN", "Pitcairn", "PN", "皮特凯恩群岛"],
+  "PL": ["PL", "Poland", "POL", "波兰"],
+  "PT": ["PT", "Portugal", "PRT", "葡萄牙"],
+  "PR": ["PR", "Puerto Rico", "PR", "波多黎各"],
+  "QA": ["QA", "Qatar", "QAT", "卡塔尔"],
+  "RE": ["RE", "Réunion", "REU", "留尼汪"],
+  "RO": ["RO", "Romania", "ROU", "罗马尼亚"],
+  "RU": ["RU", "Russia", "Russian Federation", "RUS", "俄罗斯", "俄国"],
+  "RW": ["RW", "Rwanda", "RWA", "卢旺达"],
+  "BL": ["BL", "Saint Barthélemy", "BL", "圣巴泰勒米"],
+  "SH": ["SH", "Saint Helena", "Saint Helena, Ascension and Tristan da Cunha", "SH", "圣赫勒拿"],
+  "KN": ["KN", "Saint Kitts and Nevis", "KNA", "圣基茨和尼维斯"],
+  "LC": ["LC", "Saint Lucia", "LCA", "圣卢西亚"],
+  "MF": ["MF", "Saint Martin", "MF", "圣马丁"],
+  "PM": ["PM", "Saint Pierre and Miquelon", "PM", "圣皮埃尔和密克隆"],
+  "VC": ["VC", "Saint Vincent and the Grenadines", "VCT", "圣文森特和格林纳丁斯"],
+  "WS": ["WS", "Samoa", "WSM", "萨摩亚"],
+  "SM": ["SM", "San Marino", "SMR", "圣马力诺"],
+  "ST": ["ST", "Sao Tome and Principe", "STP", "圣多美和普林西比"],
+  "SA": ["SA", "Saudi Arabia", "Kingdom of Saudi Arabia", "SAU", "沙特阿拉伯"],
+  "SN": ["SN", "Senegal", "SEN", "塞内加尔"],
+  "RS": ["RS", "Serbia", "SRB", "塞尔维亚"],
+  "SC": ["SC", "Seychelles", "SYC", "塞舌尔"],
+  "SL": ["SL", "Sierra Leone", "SLE", "塞拉利昂"],
+  "SG": ["SG", "Singapore", "SGP", "新加坡"],
+  "SX": ["SX", "Sint Maarten", "SX", "荷属圣马丁"],
+  "SK": ["SK", "Slovakia", "Slovak Republic", "SVK", "斯洛伐克"],
+  "SI": ["SI", "Slovenia", "SVN", "斯洛文尼亚"],
+  "SB": ["SB", "Solomon Islands", "SLB", "所罗门群岛"],
+  "SO": ["SO", "Somalia", "SOM", "索马里"],
+  "ZA": ["ZA", "South Africa", "Republic of South Africa", "ZAF", "南非"],
+  "GS": ["GS", "South Georgia and the South Sandwich Islands", "GS", "南乔治亚和南桑威奇群岛"],
+  "SS": ["SS", "South Sudan", "SSD", "南苏丹"],
+  "ES": ["ES", "Spain", "Kingdom of Spain", "ESP", "西班牙"],
+  "LK": ["LK", "Sri Lanka", "LKA", "斯里兰卡"],
+  "SD": ["SD", "Sudan", "SDN", "苏丹"],
+  "SR": ["SR", "Suriname", "SUR", "苏里南"],
+  "SJ": ["SJ", "Svalbard and Jan Mayen", "SJ", "斯瓦尔巴和扬马延"],
+  "SE": ["SE", "Sweden", "SWE", "瑞典"],
+  "CH": ["CH", "Switzerland", "Swiss Confederation", "CHE", "瑞士", "Swiss"],
+  "SY": ["SY", "Syria", "Syrian Arab Republic", "SYR", "叙利亚"],
+  "TW": ["TW", "Taiwan", "Taiwan, Province of China", "TWN", "台湾", "中华民国", "ROC"],
+  "TJ": ["TJ", "Tajikistan", "TJK", "塔吉克斯坦"],
+  "TZ": ["TZ", "Tanzania", "United Republic of Tanzania", "TZA", "坦桑尼亚"],
+  "TH": ["TH", "Thailand", "THA", "泰国"],
+  "TL": ["TL", "Timor-Leste", "East Timor", "TLS", "东帝汶", "蒂莫尔"],
+  "TG": ["TG", "Togo", "TGO", "多哥"],
+  "TK": ["TK", "Tokelau", "TKL", "托克劳"],
+  "TO": ["TO", "Tonga", "TON", "汤加"],
+  "TT": ["TT", "Trinidad and Tobago", "TTO", "特立尼达和多巴哥"],
+  "TN": ["TN", "Tunisia", "TUN", "突尼斯"],
+  "TR": ["TR", "Turkey", "Republic of Turkey", "TUR", "土耳其"],
+  "TM": ["TM", "Turkmenistan", "TKM", "土库曼斯坦"],
+  "TC": ["TC", "Turks and Caicos Islands", "TCA", "特克斯和凯科斯群岛"],
+  "TV": ["TV", "Tuvalu", "TUV", "图瓦卢"],
+  "UG": ["UG", "Uganda", "UGA", "乌干达"],
+  "UA": ["UA", "Ukraine", "UKR", "乌克兰"],
+  "AE": ["AE", "United Arab Emirates", "UAE", "阿拉伯联合酋长国", "阿联酋"],
+  "GB": ["GB", "United Kingdom", "United Kingdom of Great Britain and Northern Ireland", "UK", "GBR", "英国", "Britain", "Great Britain", "England", "UK"],
+  "US": ["US", "United States", "United States of America", "USA", "US", "America", "美利坚合众国", "美国"],
+  "UM": ["UM", "United States Minor Outlying Islands", "UM", "美国本土外小岛屿"],
+  "UY": ["UY", "Uruguay", "URY", "乌拉圭"],
+  "UZ": ["UZ", "Uzbekistan", "UZB", "乌兹别克斯坦"],
+  "VU": ["VU", "Vanuatu", "VUT", "瓦努阿图"],
+  "VE": ["VE", "Venezuela", "Bolivarian Republic of Venezuela", "VEN", "委内瑞拉"],
+  "VN": ["VN", "Vietnam", "Socialist Republic of Vietnam", "VNM", "越南"],
+  "VG": ["VG", "British Virgin Islands", "VG", "英属维尔京群岛"],
+  "VI": ["VI", "United States Virgin Islands", "VI", "美属维尔京群岛"],
+  "WF": ["WF", "Wallis and Futuna", "WF", "瓦利斯和富图纳"],
+  "EH": ["EH", "Western Sahara", "ESH", "西撒哈拉"],
+  "YE": ["YE", "Yemen", "YEM", "也门"],
+  "ZM": ["ZM", "Zambia", "ZMB", "赞比亚"],
+  "ZW": ["ZW", "Zimbabwe", "ZWE", "津巴布韦"]
+}

serper_toolkit/server.py

@@ -0,0 +1,668 @@
+import os
+import httpx
+import asyncio
+import json
+import logging
+import re
+import unicodedata
+import random
+from typing import Optional, Dict, Any, Union
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+from concurrent.futures import ThreadPoolExecutor
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+load_dotenv()
+
+API_KEY: Optional[str] = os.getenv("SERPER_API_KEY")
+mcp = FastMCP("serper-mcp")
+
+# 加载本地国家别名字典 (data/country_aliases.json)
+# 简化索引：仅使用别名字典 ALIAS_MAP，并生成按字母序排列的别名列表 ALIAS_KEYS_SORTED。
+# 使用自实现的 Quick Sort 对别名键进行排序，并用二分查找(binary search)做匹配查找。
+ALIAS_MAP: Dict[str, str] = {}
+ALIAS_KEYS_SORTED: list = []
+
+_aliases_path = os.path.join(os.path.dirname(__file__), "data", "country_aliases.json")
+
+# Quick Sort 实现（用于对别名字典键排序）
+def quick_sort(arr: list) -> list:
+    if len(arr) <= 1:
+        return arr
+    pivot = arr[len(arr) // 2]
+    left = [x for x in arr if x < pivot]
+    middle = [x for x in arr if x == pivot]
+    right = [x for x in arr if x > pivot]
+    return quick_sort(left) + middle + quick_sort(right)
+
+# 二分查找（在已排序的列表中查找精确匹配）
+def binary_search(arr: list, target: str) -> Optional[int]:
+    lo, hi = 0, len(arr) - 1
+    while lo <= hi:
+        mid = (lo + hi) // 2
+        if arr[mid] == target:
+            return mid
+        if arr[mid] < target:
+            lo = mid + 1
+        else:
+            hi = mid - 1
+    return None
+
+def normalize(text: str) -> str:
+    """归一化国家/地区名称：NFKD、去重音、转小写、去标点、折叠空白"""
+    if not text:
+        return ""
+    # Unicode normalize
+    s = unicodedata.normalize("NFKD", text)
+    # remove diacritics
+    s = "".join(ch for ch in s if not unicodedata.combining(ch))
+    # convert full-width to half-width and normalize spaces
+    s = s.replace("\u3000", " ")
+    s = s.strip().lower()
+    # remove punctuation except spaces
+    s = re.sub(r"[^\w\s'-]", " ", s, flags=re.UNICODE)
+    # replace underscores and multiple spaces with single space
+    s = re.sub(r"[_\s]+", " ", s).strip()
+    return s
+
+def _generate_variants(alias: str) -> set:
+    """为 alias 生成若干变体以提高命中率（去标点、逗号重排等）"""
+    variants = set()
+    base = alias.strip()
+    variants.add(base)
+    # normalized base
+    n = normalize(base)
+    variants.add(n)
+    # remove punctuation version
+    variants.add(re.sub(r"[^\w\s]", "", n))
+    # if contains comma, try reorder segments: "Korea, South" -> "south korea"
+    if "," in base:
+        parts = [p.strip() for p in base.split(",") if p.strip()]
+        if len(parts) >= 2:
+            reordered = " ".join(reversed(parts))
+            variants.add(reordered)
+            variants.add(normalize(reordered))
+    # also add word-reordered variants for simple two-word names
+    parts = n.split()
+    if len(parts) == 2:
+        variants.add(" ".join(reversed(parts)))
+    return {v for v in variants if v}
+
+try:
+    with open(_aliases_path, "r", encoding="utf-8") as f:
+        _forward = json.load(f)
+
+    # 仅基于别名字典构建 ALIAS_MAP（normalized alias -> alpha2）
+    for code, names in _forward.items():
+        code_up = code.upper()
+        if isinstance(names, list):
+            iter_names = names
+        else:
+            iter_names = [names]
+        for name in iter_names:
+            if not isinstance(name, str):
+                continue
+            for variant in _generate_variants(name):
+                key = normalize(variant)
+                if not key:
+                    continue
+                # 后来的同名别名以最后一个为准（覆盖），保持简单明了
+                ALIAS_MAP[key] = code_up
+
+    # 使用 Quick Sort 对别名字典的键进行排序，供二分查找使用
+    ALIAS_KEYS_SORTED = quick_sort(list(ALIAS_MAP.keys()))
+
+except FileNotFoundError:
+    logger.warning("国家别名字典未找到: %s", _aliases_path)
+except Exception as e:
+    logger.warning("加载国家别名字典失败: %s", e)
+
+USER_AGENT = "serper_client/1.0"
+API_ENDPOINTS = {
+    "search": "https://google.serper.dev/search",
+    "image_search": "https://google.serper.dev/images",
+    "video_search": "https://google.serper.dev/videos",
+    "place_search": "https://google.serper.dev/places",
+    "news_search": "https://google.serper.dev/news",
+    "lens_search": "https://google.serper.dev/lens",
+    "scholar_search": "https://google.serper.dev/scholar",
+    "scrape": "https://scrape.serper.dev",
+}
+HTTP_TIMEOUT = 30.0
+
+# 并发与重试相关配置（可通过环境变量调整）
+SERPER_MAX_CONNECTIONS = int(os.getenv("SERPER_MAX_CONNECTIONS", "200"))
+SERPER_KEEPALIVE = int(os.getenv("SERPER_KEEPALIVE", "20"))
+SERPER_HTTP2 = os.getenv("SERPER_HTTP2", "0") == "1"
+# 如果启用了 HTTP/2，确保环境中安装了 h2；否则回退为 False，避免 httpx 抛出 ImportError
+if SERPER_HTTP2:
+    try:
+        import h2  # noqa: F401
+    except Exception:
+        logger.warning("SERPER_HTTP2 设置为启用，但未检测到 'h2' 包。将自动禁用 HTTP/2（请安装 httpx[http2] 以启用）。")
+        SERPER_HTTP2 = False
+
+# Serper 后端总体并发上限为每秒 300 请求；将默认全局并发上限适当调高为 200（可通过环境变量调整）
+SERPER_MAX_CONCURRENT_REQUESTS = int(os.getenv("SERPER_MAX_CONCURRENT_REQUESTS", "200"))
+SERPER_MAX_WORKERS = int(os.getenv("SERPER_MAX_WORKERS", "10"))
+SERPER_RETRY_COUNT = int(os.getenv("SERPER_RETRY_COUNT", "3"))
+SERPER_RETRY_BASE_DELAY = float(os.getenv("SERPER_RETRY_BASE_DELAY", "0.5"))
+
+# per-endpoint 配置（通过环境变量传入 JSON 字符串，示例: '{"search":10,"scrape":2}'）
+try:
+    PER_ENDPOINT_MAX_CONCURRENT = json.loads(os.getenv("SERPER_ENDPOINT_CONCURRENCY", "{}"))
+except Exception:
+    PER_ENDPOINT_MAX_CONCURRENT = {}
+
+# per-endpoint 是否允许重试，默认允许（用于避免对非幂等接口重试）
+try:
+    PER_ENDPOINT_ALLOW_RETRY = json.loads(os.getenv("SERPER_ENDPOINT_RETRYABLE", '{"search": true, "scrape": false}'))
+except Exception:
+    PER_ENDPOINT_ALLOW_RETRY = {}
+
+# 请求并发信号量（在 startup_all 时初始化）
+REQUEST_SEMAPHORE = None
+
+# endpoint -> asyncio.Semaphore 映射（在 startup_all 中根据 PER_ENDPOINT_MAX_CONCURRENT 初始化）
+ENDPOINT_SEMAPHORES: Dict[str, asyncio.Semaphore] = {}
+
+# 全局 httpx AsyncClient 管理类
+class AsyncHttpClientManager:
+    _client: Optional[httpx.AsyncClient] = None
+    _lock = asyncio.Lock()
+
+    @classmethod
+    async def startup(cls):
+        async with cls._lock:
+            if cls._client is None:
+                limits = httpx.Limits(
+                    max_connections=SERPER_MAX_CONNECTIONS,
+                    max_keepalive_connections=SERPER_KEEPALIVE
+                )
+                timeout_obj = httpx.Timeout(
+                    connect=5.0,
+                    read=20.0,
+                    write=10.0,
+                    pool=30.0,
+                    timeout=HTTP_TIMEOUT
+                )
+                cls._client = httpx.AsyncClient(
+                    timeout=timeout_obj,
+                    headers={"User-Agent": USER_AGENT},
+                    limits=limits,
+                    http2=SERPER_HTTP2
+                )
+                logger.info("httpx AsyncClient 已启动 (max_connections=%d, keepalive=%d, http2=%s, timeout=%s)",
+                            SERPER_MAX_CONNECTIONS, SERPER_KEEPALIVE, SERPER_HTTP2, HTTP_TIMEOUT)
+
+    @classmethod
+    def get_client(cls) -> httpx.AsyncClient:
+        if cls._client is None:
+            raise RuntimeError("AsyncHttpClientManager 未启动，请先调用startup()")
+        return cls._client
+
+    @classmethod
+    async def shutdown(cls):
+        async with cls._lock:
+            if cls._client:
+                await cls._client.aclose()
+                logger.info("httpx AsyncClient 已关闭")
+                cls._client = None
+
+
+# 全局线程池执行器管理
+class ThreadPoolManager:
+    _executor: Optional[ThreadPoolExecutor] = None
+    _max_workers = SERPER_MAX_WORKERS
+
+    @classmethod
+    def startup(cls, max_workers: int = 10):
+        if cls._executor is None:
+            cls._executor = ThreadPoolExecutor(max_workers=cls._max_workers)
+            logger.info(f"线程池启动，最大工作线程数: {cls._max_workers}")
+
+    @classmethod
+    def get_executor(cls) -> ThreadPoolExecutor:
+        if cls._executor is None:
+            raise RuntimeError("ThreadPoolManager 未启动，请先调用startup()")
+        return cls._executor
+
+    @classmethod
+    def shutdown(cls):
+        if cls._executor:
+            cls._executor.shutdown(wait=True)
+            logger.info("线程池已关闭")
+            cls._executor = None
+
+
+def error_response(message: str, status_code: Optional[int] = None, extra: Optional[Dict[str, Any]] = None) -> str:
+    result: Dict[str, Any] = {
+        "success": False,
+        "error": True,
+        "message": message,
+    }
+    if status_code is not None:
+        result["status_code"] = status_code
+    if extra:
+        result.update(extra)
+    return json.dumps(result, ensure_ascii=False, indent=4)
+
+
+def success_response(query_details: Dict[str, Any], results: Dict[str, Any]) -> str:
+    return json.dumps({
+        "success": True,
+        "query_details": query_details,
+        "results": results,
+    }, ensure_ascii=False, indent=4)
+
+
+def get_country_code_alpha2(country_name: Optional[str]) -> str:
+    """
+    国家代码解析（已简化）：
+    - 仅基于别名字典 ALIAS_MAP 进行查找，使用 ALIAS_KEYS_SORTED + 二分查找匹配别名键。
+    - 优先在别名字典中查找传入参数（归一化后）；若命中则返回对应 alpha2。
+    - 如果传入为两字母 ISO2 则作为后备直接返回大写。
+    - 未找到则默认返回 'US'。
+    """
+    # 处理空输入：直接使用默认 US
+    if not country_name:
+        return "US"
+
+    name = country_name.strip()
+    if not name:
+        return "US"
+
+    # 归一化并首先在 ALIAS_MAP 中查找（O(1)）
+    norm = normalize(name)
+    if norm in ALIAS_MAP:
+        return ALIAS_MAP[norm]
+
+    # 对大规模别名列表，使用已排序键列表 + 二分查找
+    if ALIAS_KEYS_SORTED:
+        idx = binary_search(ALIAS_KEYS_SORTED, norm)
+        if idx is not None:
+            return ALIAS_MAP.get(ALIAS_KEYS_SORTED[idx], "US")
+
+    # 如果已经是两字母 ISO2，作为后备直接返回大写
+    if len(name) == 2 and name.isalpha():
+        return name.upper()
+
+    # 再尝试归一化的大写形式（例如传入 'USA'）
+    u_norm = normalize(name.upper())
+    if u_norm in ALIAS_MAP:
+        return ALIAS_MAP[u_norm]
+    if ALIAS_KEYS_SORTED:
+        idx = binary_search(ALIAS_KEYS_SORTED, u_norm)
+        if idx is not None:
+            return ALIAS_MAP.get(ALIAS_KEYS_SORTED[idx], "US")
+
+    logger.info("未找到国家名称 '%s'，使用默认国家码 US。", country_name)
+    return "US"
+
+
+def validate_search_num(num_val: int) -> int:
+    if 1 <= num_val <= 100:
+        return num_val
+    logger.warning("搜索数量 %d 超出范围(1-100)，使用默认值10。", num_val)
+    return 10
+
+
+def map_search_time_to_tbs_param(time_period_str: Optional[str]) -> Optional[str]:
+    if not time_period_str:
+        return None
+    s = time_period_str.strip().lower()
+    mapping = {
+        "小时": "qdr:h", "hour": "qdr:h",
+        "天": "qdr:d", "day": "qdr:d",
+        "周": "qdr:w", "week": "qdr:w",
+        "月": "qdr:m", "month": "qdr:m",
+        "年": "qdr:y", "year": "qdr:y",
+    }
+    for k, v in mapping.items():
+        if k in s:
+            return v
+    logger.info("未识别的时间偏好 '%s'，忽略时间过滤。", time_period_str)
+    return None
+
+
+async def execute_serper_request(
+    api_url: str,
+    payload: Dict[str, Any],
+    api_name: str
+) -> Union[Dict[str, Any], None]:
+    """
+    执行对 Serper API 的异步请求，包含并发控制与重试策略。
+    返回解析后的 JSON 或错误描述字典，或 None（当缺少 API_KEY 时）。
+    """
+    if not API_KEY:
+        logger.error("未配置SERPER_API_KEY，无法调用 %s 接口。", api_name)
+        return None
+
+    headers = {
+        "X-API-KEY": API_KEY,
+        "Content-Type": "application/json",
+    }
+
+    try:
+        client = AsyncHttpClientManager.get_client()
+    except RuntimeError as e:
+        logger.error("HTTP客户端未启动: %s", e)
+        return {"error": True, "message": f"{api_name}接口请求失败，HTTP客户端未启动。"}
+
+    logger.info("准备调用 %s 接口，payload: %s", api_name, payload)
+
+    # 选择用于该端点的 semaphore（优先 per-endpoint，其次全局 REQUEST_SEMAPHORE）
+    sem = ENDPOINT_SEMAPHORES.get(api_name, REQUEST_SEMAPHORE)
+    # 该端点是否允许重试（默认 True）
+    retry_allowed = PER_ENDPOINT_ALLOW_RETRY.get(api_name, True)
+
+    attempt = 0
+    while True:
+        try:
+            # 并发控制（如果已在 startup_all 中初始化）
+            if REQUEST_SEMAPHORE:
+                async with REQUEST_SEMAPHORE:
+                    response = await client.post(api_url, json=payload, headers=headers)
+            else:
+                response = await client.post(api_url, json=payload, headers=headers)
+
+            # 检查 HTTP 状态
+            response.raise_for_status()
+
+            # 解析返回 JSON
+            try:
+                result = response.json()
+            except Exception as e:
+                logger.error("%s接口JSON解析错误: %s", api_name, e)
+                return {"error": True, "message": f"{api_name}接口响应解析失败: {e}"}
+
+            return result
+
+        except httpx.HTTPStatusError as e:
+            status = e.response.status_code if e.response is not None else None
+            logger.warning("%s 接口返回 HTTP 错误 %s (尝试 %d/%d)", api_name, status, attempt + 1, SERPER_RETRY_COUNT)
+            # 对 5xx 做重试（仅在端点允许重试时）
+            if retry_allowed and status and 500 <= status < 600 and attempt < SERPER_RETRY_COUNT:
+                attempt += 1
+                delay = SERPER_RETRY_BASE_DELAY * (2 ** (attempt - 1)) + random.uniform(0, 0.1)
+                logger.info("对 %s 接口在 %s 秒后重试 (HTTP %s)", api_name, round(delay, 2), status)
+                await asyncio.sleep(delay)
+                continue
+            logger.error("%s接口HTTP错误 %s %s: %s", api_name, status, e.request.url if e.request else "", e)
+            return {
+                "error": True,
+                "message": f"{api_name}接口HTTP状态错误: {status}",
+                "status_code": status
+            }
+
+        except httpx.RequestError as e:
+            logger.warning("%s 接口请求错误 (尝试 %d/%d): %s", api_name, attempt + 1, SERPER_RETRY_COUNT, e)
+            if retry_allowed and attempt < SERPER_RETRY_COUNT:
+                attempt += 1
+                delay = SERPER_RETRY_BASE_DELAY * (2 ** (attempt - 1)) + random.uniform(0, 0.1)
+                logger.info("对 %s 接口在 %s 秒后重试 (请求错误)", api_name, round(delay, 2))
+                await asyncio.sleep(delay)
+                continue
+            logger.error("%s接口请求错误: %s", api_name, e)
+            return {"error": True, "message": f"{api_name}接口请求错误: {e}"}
+
+        except Exception as e:
+            logger.exception("%s接口未知错误: %s", api_name, e)
+            return {"error": True, "message": f"{api_name}接口未知错误: {e}"}
+
+
+async def generic_serper_search(
+    api_name_key: str,
+    q: Optional[str] = None,
+    url: Optional[str] = None,
+    num: Optional[int] = None,
+    country: Optional[str] = None,
+    time: Optional[str] = None,
+    include_markdown: Optional[bool] = None,
+    extra_params: Optional[Dict[str, Any]] = None
+) -> str:
+    if not API_KEY:
+        return error_response("环境变量SERPER_API_KEY未设置，接口无法调用。")
+    api_url = API_ENDPOINTS.get(api_name_key)
+    if not api_url:
+        return error_response(f"未知API_KEY '{api_name_key}'，无法处理请求。")
+    payload: Dict[str, Any] = {}
+    if q is not None:
+        payload["q"] = q
+    if url is not None:
+        if api_name_key in {"lens_search", "scrape"}:
+            payload["url"] = url
+        else:
+            logger.warning("url参数在接口%s中未使用", api_name_key)
+    if num is not None:
+        payload["num"] = validate_search_num(num)
+    country_code = get_country_code_alpha2(country)
+    if country_code:
+        payload["gl"] = country_code
+    logger.info("country param '%s' -> resolved country_code: %s", country, country_code)
+
+    tbs_val = map_search_time_to_tbs_param(time)
+    if tbs_val:
+        payload["tbs"] = tbs_val
+    if include_markdown is not None and api_name_key == "scrape":
+        if include_markdown:
+            payload["includeMarkdown"] = True
+    if extra_params:
+        # 不允许 extra_params 覆盖或设置 gl 参数（防止外部传入非 ISO2 值覆盖解析结果）
+        sanitized = {k: v for k, v in extra_params.items() if k.lower() != "gl"}
+        payload.update(sanitized)
+
+    # 最终验证 gl，确保为合法的 ISO2 大写字符串；使用 get_country_code_alpha2 进行规范化或移除
+    gl_val = payload.get("gl")
+    if gl_val is not None:
+        resolved = None
+        # 如果已经是 ASCII 两字母代码，直接规范为大写
+        if isinstance(gl_val, str) and re.fullmatch(r"[A-Za-z]{2}", gl_val):
+            resolved = gl_val.upper()
+        else:
+            # 否则尝试用别名字典解析（支持中文/英文/ISO3等）
+            resolved = get_country_code_alpha2(str(gl_val))
+        if resolved:
+            payload["gl"] = resolved
+        else:
+            logger.warning("无效的 gl 值 '%s'，已移除（无法解析为 ISO2）", gl_val)
+            payload.pop("gl", None)
+
+    if api_name_key == "scrape" and ("url" not in payload or not payload["url"].strip()):
+        return error_response("参数 url 必填且不能为空字符串。")
+    result = await execute_serper_request(api_url, payload, api_name_key)
+    if result is None:
+        return error_response(f"{api_name_key}请求失败，接口响应为空。")
+    if isinstance(result, dict) and result.get("error"):
+        return json.dumps({
+            "success": False,
+            "query_details": payload,
+            "error": result.get("error"),
+            "message": result.get("message", "未知错误"),
+            "status_code": result.get("status_code", None),
+        }, ensure_ascii=False, indent=4)
+    return success_response(payload, result)
+
+
+@mcp.tool(name="serper-general-search")
+async def serper_general_search(
+    search_key_words: str,
+    search_country: Optional[str] = None,
+    search_num: int = 10,
+    search_time: Optional[str] = None,
+) -> str:
+    """
+    通用搜索接口。
+    参数:
+        search_key_words: 搜索关键词（必填）
+        search_country: 国家名称（可选），支持中文或英文国家名
+        search_num: 返回结果数量，1~100，默认10
+        search_time: 时间过滤，如“小时”，“天”，“周”，“月”，“年”，可选
+    返回:
+        JSON格式字符串，包含查询参数和搜索结果。
+    """
+    return await generic_serper_search("search", q=search_key_words, country=search_country, num=search_num, time=search_time)
+
+
+@mcp.tool(name="serper-image-search")
+async def serper_image_search(
+    search_key_words: str,
+    search_country: Optional[str] = None,
+    search_num: int = 10,
+    search_time: Optional[str] = None,
+) -> str:
+    """
+    图片搜索接口。
+    参数含义与通用搜索接口相同。
+    """
+    return await generic_serper_search("image_search", q=search_key_words, country=search_country, num=search_num, time=search_time)
+
+
+@mcp.tool(name="serper-video-search")
+async def serper_video_search(
+    search_key_words: str,
+    search_country: Optional[str] = None,
+    search_num: int = 10,
+    search_time: Optional[str] = None,
+) -> str:
+    """
+    视频搜索接口。
+    参数含义与通用搜索接口相同。
+    """
+    return await generic_serper_search("video_search", q=search_key_words, country=search_country, num=search_num, time=search_time)
+
+
+@mcp.tool(name="serper-place-search")
+async def serper_place_search(
+    search_key_words: str,
+    search_country: Optional[str] = None,
+) -> str:
+    """
+    地点搜索接口。
+    参数:
+        search_key_words: 搜索关键词
+        search_country: 国家名称（可选）
+    """
+    return await generic_serper_search("place_search", q=search_key_words, country=search_country)
+
+
+@mcp.tool(name="serper-news-search")
+async def serper_news_search(
+    search_key_words: str,
+    search_country: Optional[str] = None,
+    search_num: int = 10,
+    search_time: Optional[str] = None,
+) -> str:
+    """
+    新闻搜索接口。
+    参数同通用搜索接口。
+    """
+    return await generic_serper_search("news_search", q=search_key_words, country=search_country, num=search_num, time=search_time)
+
+
+@mcp.tool(name="serper-lens-search")
+async def serper_lens_search(
+    image_url: str,
+    search_country: Optional[str] = None,
+) -> str:
+    """
+    Lens图片搜索接口。
+    参数:
+        image_url: 图片URL（必填）
+        search_country: 国家名称（可选）
+    """
+    return await generic_serper_search("lens_search", url=image_url, country=search_country)
+
+
+@mcp.tool(name="serper-scholar-search")
+async def serper_scholar_search(
+    search_key_words: str,
+    search_country: Optional[str] = None,
+) -> str:
+    """
+    学术搜索接口。
+    参数:
+        search_key_words: 查询关键词
+        search_country: 国家名称（可选）
+    """
+    return await generic_serper_search("scholar_search", q=search_key_words, country=search_country)
+
+
+@mcp.tool(name="serper-scrape")
+async def serper_scrape(
+    url: str,
+    include_markdown: bool = False,
+) -> str:
+    """
+    网页内容抓取接口。
+    参数:
+        url: 目标网页URL（必填）
+        include_markdown: 是否返回Markdown格式内容（默认为False）
+    返回:
+        JSON字符串，包含网页内容和（可选）Markdown文本。
+    """
+    return await generic_serper_search("scrape", url=url, include_markdown=include_markdown)
+
+
+# 示例：同步阻塞函数，通过线程池异步调用
+async def run_blocking_task_in_threadpool(blocking_func, *args, **kwargs):
+    loop = asyncio.get_running_loop()
+    executor = ThreadPoolManager.get_executor()
+    return await loop.run_in_executor(executor, lambda: blocking_func(*args, **kwargs))
+
+
+async def startup_all():
+    global REQUEST_SEMAPHORE
+    await AsyncHttpClientManager.startup()
+    ThreadPoolManager.startup(max_workers=SERPER_MAX_WORKERS)
+    # 初始化请求并发信号量
+    REQUEST_SEMAPHORE = asyncio.Semaphore(SERPER_MAX_CONCURRENT_REQUESTS)
+    logger.info("已初始化请求并发控制，最大并发请求数: %d，线程池最大工作线程: %d", SERPER_MAX_CONCURRENT_REQUESTS, SERPER_MAX_WORKERS)
+    # 可以扩展这里做更多初始化
+
+
+async def shutdown_all():
+    await AsyncHttpClientManager.shutdown()
+    ThreadPoolManager.shutdown()
+    # 可以扩展这里做更多清理
+
+
+def main():
+    """
+    The main synchronous entry point for the MCP server.
+    Manages the asyncio event loop to run async setup/teardown around the blocking mcp.run() call.
+    """
+    if not API_KEY:
+        logger.error(
+            "警告：环境变量SERPER_API_KEY未设置，启动后所有接口调用均不可用。"
+            "请在.env文件或环境变量中配置。"
+        )
+    else:
+        logger.info("加载到SERPER_API_KEY，准备启动Serper MCP工具接口服务。")
+
+    # Manually manage the event loop
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+
+    try:
+        # Run the async startup tasks
+        loop.run_until_complete(startup_all())
+        logger.info("Serper MCP 工具服务已启动。")
+
+        # Now, run the blocking MCP server loop
+        mcp.run(transport="stdio")
+
+    except KeyboardInterrupt:
+        logger.info("接收到中断信号，正在关闭服务...")
+    finally:
+        logger.info("开始关闭异步资源...")
+        # Run the async shutdown tasks
+        loop.run_until_complete(shutdown_all())
+        loop.close()
+        logger.info("Serper MCP工具接口服务已安全关闭。")
+
+# This block is for direct execution via 'python -m serper_toolkit.server'
+if __name__ == "__main__":
+    main()

serper_toolkit-0.0.4.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: serper-toolkit
+Version: 0.0.4
+Summary: A high-performance, asynchronous MCP server for Serper Google Search, featuring connection pooling, request retries, and intelligent input parsing.
+Author-email: "Joey.Kot" <joey.kot.x@gmail.com>
+Keywords: serper,mcp,server,google,search
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: h2>=4.2.0
+Requires-Dist: dotenv>=0.9.9
+Requires-Dist: mcp>=1.9.4
+
+# Serper MCP Toolkit
+
+A high-performance, asynchronous MCP server that provides comprehensive Google search and web content scraping capabilities through the Serper API (excluding some rarely used interfaces).
+
+This project is built on `httpx`, utilizing asynchronous clients and connection pool management to offer LLMs a stable and efficient external information retrieval tool.
+
+## Key Features
+
+- **Asynchronous Architecture**: Fully based on `asyncio` and `httpx`, ensuring high throughput and non-blocking I/O operations.
+- **HTTP Connection Pool**: Manages and reuses TCP connections through a global `httpx.AsyncClient` instance, significantly improving performance under high concurrency.
+- **Concurrency Control**: Built-in global and per-API endpoint concurrency semaphores effectively manage API request rates to prevent exceeding rate limits.
+- **Automatic Retry Mechanism**: Integrated request retry functionality with exponential backoff strategy automatically handles temporary network fluctuations or server errors, enhancing service stability.
+- **Intelligent Country Code Parsing**: Includes a comprehensive country name dictionary supporting inputs in Chinese, English, ISO Alpha-2/3, and other formats, with automatic normalization.
+- **Flexible Environment Variable Configuration**: Supports fine-tuned service configuration via environment variables.
+
+## Available Tools
+
+This service provides the following tools:
+
+| Tool Name                | Description                                  |
+| ------------------------ | -------------------------------------------- |
+| `serper-general-search`  | Performs general Google web searches.        |
+| `serper-image-search`    | Performs Google image searches.               |
+| `serper-video-search`    | Performs Google video searches.               |
+| `serper-place-search`    | Performs Google place searches.               |
+| `serper-news-search`     | Performs Google news searches.                |
+| `serper-lens-search`     | Performs Google Lens reverse image searches via image URL. |
+| `serper-scholar-search`  | Performs Google Scholar searches.             |
+| `serper-scrape`          | Scrapes and returns the content of a specified URL. |
+
+## Installation Guide
+
+It is recommended to install using `pip` or `uv`.
+
+```bash
+# Using pip
+pip install serper-toolkit
+
+# Or using uv
+uv pip install serper-toolkit
+```
+
+## Quick Start
+
+### Set Environment Variables
+
+Create a `.env` file in the project root directory and enter your Serper API key:
+
+```bash
+SERPER_API_KEY="your-serper-api-key-here"
+```
+
+### Configure MCP Client
+
+Add the following server configuration in the MCP client configuration file:
+
+```json
+{
+  "mcpServers": {
+    "serper": {
+      "command": "python3",
+      "args": ["-m", "serper-toolkit"],
+      "env": {
+        "SERPER_API_KEY": "<Your Serper API key>"
+      }
+    }
+  }
+}
+```
+
+```json
+{
+  "mcpServers": {
+    "serper-toolkit": {
+      "command": "uvx",
+      "args": ["serper-toolkit"],
+      "env": {
+        "SERPER_API_KEY": "<Your Serper API key>"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+- `SERPER_MAX_CONNECTIONS`: Maximum number of HTTP client connections (default: 200).
+- `SERPER_KEEPALIVE`: Maximum number of keep-alive HTTP client connections (default: 20).
+- `SERPER_HTTP2`: Enable HTTP/2 (default: "0", set to "1" to enable).
+- `SERPER_MAX_CONCURRENT_REQUESTS`: Global maximum concurrent requests (default: 200).
+- `SERPER_RETRY_COUNT`: Maximum retry attempts for failed requests (default: 3).
+- `SERPER_RETRY_BASE_DELAY`: Base delay time for retries in seconds (default: 0.5).
+- `SERPER_ENDPOINT_CONCURRENCY`: Set concurrency per endpoint (JSON format), e.g., {"search":10,"scrape":2}.
+- `SERPER_ENDPOINT_RETRYABLE`: Set retry allowance per endpoint (JSON format), e.g., {"scrape": false}.
+
+## Tool Parameters and Usage Examples
+
+### serper-general-search: Perform general web search
+
+Parameters:
+
+- `search_key_words` (str, required): Keywords to search.
+- `search_country` (str, optional): Specify the country/region for search results. Supports Chinese names (e.g., "China"), English names (e.g., "United States"), or ISO codes (e.g., "US"). Default is "US".
+- `search_num` (int, optional): Number of results to return, range 1-100. Default is 10.
+- `search_time` (str, optional): Filter results by time range. Available values: "hour", "day", "week", "month", "year".
+
+Example:
+
+```Python
+result_json = serper_general_search(
+    search_key_words="AI advancements 2024",
+    search_country="United States",
+    search_num=5,
+    search_time="month"
+)
+```
+
+### serper-lens-search: Perform reverse image search via image URL
+
+Parameters:
+
+- `image_url` (str, required): Public URL of the image to search.
+- `search_country` (str, optional): Specify the country/region for search results. Default is "US".
+
+Example:
+
+```Python
+result_json = serper_lens_search(
+    image_url="https://www.google.com/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png",
+    search_country="JP"
+)
+```
+
+### serper-scrape: Scrape webpage content
+
+Parameters:
+
+- `url` (str, required): URL of the target webpage.
+- `include_markdown` (bool, optional): Whether to include Markdown-formatted content in the returned results. Default is False.
+
+Example:
+
+```Python
+result_json = serper_scrape(
+    url="https://www.example.com",
+    include_markdown=True
+)
+```
+
+## License Agreement
+
+This project is licensed under the MIT License.

serper_toolkit-0.0.4.dist-info/RECORD

@@ -0,0 +1,9 @@
+serper_toolkit/__init__.py,sha256=wKcw1Il2H4tTA8QSrgkRTBKqdtU5wJdo5KxpnKl7EOE,68
+serper_toolkit/__main__.py,sha256=Gfly6uBEry5qVs6ulzz6YHuKd_aKSMdoQoolzjXBB2U,160
+serper_toolkit/server.py,sha256=AbQlC29bgQJud583-o10_IJArlnSABGakpTx-XT31vY,24834
+serper_toolkit/data/country_aliases.json,sha256=c2ScVZ4jyKocn_F7PYo-2xdmoOyb1fHn-qfLeMSqG94,15845
+serper_toolkit-0.0.4.dist-info/METADATA,sha256=w3OKNjX7hviK9w1yq38Pwm3XEZLjHfhytjzLl5EULCY,5932
+serper_toolkit-0.0.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+serper_toolkit-0.0.4.dist-info/entry_points.txt,sha256=2EvO9ttJ6jg2vKMxT3wxOS2DvHB7ot8kPe_3XihMh3U,64
+serper_toolkit-0.0.4.dist-info/top_level.txt,sha256=tAeMIdGmGMJWIyzk2OwNp_vwYOENKaPMhIVqJdzObSs,15
+serper_toolkit-0.0.4.dist-info/RECORD,,

serper_toolkit-0.0.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

serper_toolkit-0.0.4.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+serper-toolkit = serper_toolkit.__main__:main

serper_toolkit-0.0.4.dist-info/top_level.txt

@@ -0,0 +1 @@
+serper_toolkit