@youhaozhao/cninfo-mcp 1.0.7 → 1.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@youhaozhao/cninfo-mcp)](https://www.npmjs.com/package/@youhaozhao/cninfo-mcp)
 
-通过 MCP 协议查询和下载巨潮资讯网上市公司年报的工具，适用于 Claude Desktop。
+通过 MCP 协议查询和下载巨潮资讯网上市公司年报 PDF 的工具，适用于 Claude Desktop。
 
 ## 使用方法
 
@@ -35,6 +35,7 @@
 ```
 查询 000888 的 2024 年报
 下载 688777 的年报
+查询 920185 的年报      # 北交所，新旧代码（如 835185）均可
 ```
 
 ## 系统要求
@@ -44,9 +45,10 @@
 
 ## 数据来源
 
-[巨潮资讯网](https://www.cninfo.com.cn) — 支持沪深两市及科创板
+[巨潮资讯网](https://www.cninfo.com.cn) — 支持沪深两市（主板、创业板、科创板）及北京证券交易所（北交所）
 
 ## Credits
 
 爬虫逻辑基于 [gaodechen/cninfo_process](https://github.com/gaodechen/cninfo_process)。
 
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youhaozhao/cninfo-mcp",
-  "version": "1.0.7",
+  "version": "1.2.0",
   "description": "MCP Server for querying and downloading Chinese listed companies' annual reports from CNINFO (巨潮资讯网)",
   "keywords": [
     "mcp",
@@ -45,9 +45,11 @@
   ],
   "files": [
     "bin/",
-    "python/",
-    "scripts/",
+    "python/mcp_server.py",
+    "python/spider.py",
+    "python/requirements.txt",
+    "scripts/install-python-deps.js",
     "README.md",
     "LICENSE"
   ]
-}
+}

package/python/spider.py

@@ -18,6 +18,20 @@ _saving_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "pdf")
 saving_path = _saving_path + "/"
 logger = logging.getLogger(__name__)
 
+# 巨潮资讯历史公告的实际下限约为 2001 会计年度，再往前查询无数据返回。
+EARLIEST_DATE = "2001-01-01"
+# 接口单页最大返回条数
+PAGE_SIZE = 30
+# 翻页安全上限，防止异常情况下无限循环
+MAX_PAGES = 100
+# 巨潮搜索联想接口：把股票代码/简称解析为 orgId（北交所查询必需）
+TOP_SEARCH_URL = "http://www.cninfo.com.cn/new/information/topSearch/query"
+# 公告查询接口
+QUERY_URL = "http://www.cninfo.com.cn/new/hisAnnouncement/query"
+# 瞬时失败（网络抖动/限流）的重试次数与退避基数（秒）
+MAX_RETRIES = 3
+RETRY_BACKOFF = 1.0
+
 User_Agent = [
     "Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Win64; x64; Trident/5.0; .NET CLR 3.5.30729; .NET CLR 3.0.30729; .NET CLR 2.0.50727; Media Center PC 6.0)",
     "Mozilla/5.0 (compatible; MSIE 8.0; Windows NT 6.0; Trident/4.0; WOW64; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; .NET CLR 1.0.3705; .NET CLR 1.1.4322)",
@@ -48,6 +62,85 @@ def _build_headers() -> dict:
     return headers
 
 
+def _post_json(url: str, data: dict) -> dict:
+    """POST 请求并解析 JSON，仅对可重试的瞬时失败按指数退避重试。
+
+    巨潮接口在批量/高频访问下会偶发超时或限流，导致本可成功的查询失败。
+    可重试：网络异常（超时/连接错误）、5xx、429，以及空/截断响应导致的
+    JSON 解析失败（requests 会抛 JSONDecodeError，实测多为限流时返回空体）。
+    不可重试：4xx（除 429）等客户端错误，快速失败，避免无谓的退避等待。
+    重试用尽后抛出最后一次异常，交由调用方的 try/except 记录并降级。
+    """
+    last_exc = None
+    for attempt in range(MAX_RETRIES):
+        try:
+            resp = requests.post(
+                url, headers=_build_headers(), data=data, timeout=30
+            )
+            resp.raise_for_status()
+            return resp.json()
+        except requests.exceptions.HTTPError as e:
+            status = e.response.status_code if e.response is not None else None
+            # 4xx（429 除外）不会自愈，立即失败，不浪费退避等待
+            if status is not None and status != 429 and 400 <= status < 500:
+                raise
+            last_exc = e
+        except requests.exceptions.RequestException as e:
+            # 网络异常 + JSONDecodeError（空/截断响应，多为瞬时限流）
+            last_exc = e
+        if attempt < MAX_RETRIES - 1:
+            time.sleep(RETRY_BACKOFF * (2**attempt) + random.random())
+    if last_exc is not None:
+        raise last_exc
+    raise RuntimeError(f"_post_json 未执行任何请求（MAX_RETRIES={MAX_RETRIES}）")
+
+
+def _query_announcements(query: dict) -> list:
+    """调用公告查询接口并返回 announcements 列表（带重试）。"""
+    result = _post_json(QUERY_URL, query)
+    if result and "announcements" in result and result["announcements"]:
+        return result["announcements"]
+    return []
+
+
+def _is_bse_code(stock_code) -> bool:
+    """判断是否为北交所代码。
+
+    北交所代码段：4xxxxx / 8xxxxx（原新三板平移），以及 92xxxx 标准段
+    （920，2024-04 起启用，预留 920-929）。这里特意只匹配 92 而非整个 9
+    开头，以排除沪市 B 股 900xxx，避免为其多发一次无效的北交所查询。
+    """
+    digits = re.sub(r"\D", "", str(stock_code or ""))
+    return digits[:1] in ("4", "8") or digits[:2] == "92"
+
+
+def _resolve_org_id(stock_code) -> Optional[tuple]:
+    """通过巨潮搜索联想接口把股票代码解析为 (code, orgId)。
+
+    北交所的 hisAnnouncement 接口不接受 searchkey 或裸代码，必须以
+    stock="代码,orgId" 的形式查询，因此需要先解析 orgId。
+    优先返回 code 完全等于输入的条目；找不到精确匹配则取第一条
+    （同一公司新旧代码共用同一 orgId）。无结果返回 None。
+    """
+    try:
+        hits = _post_json(TOP_SEARCH_URL, {"keyWord": stock_code, "maxNum": 10})
+    except Exception as e:
+        logger.warning("orgId 解析失败（%s）: %s", stock_code, e)
+        return None
+
+    if not isinstance(hits, list) or not hits:
+        return None
+
+    target = re.sub(r"\D", "", str(stock_code or ""))
+    for it in hits:
+        if str(it.get("code")) == target and it.get("orgId"):
+            return str(it.get("code")), str(it.get("orgId"))
+    first = hits[0]
+    if first.get("orgId"):
+        return str(first.get("code")), str(first.get("orgId"))
+    return None
+
+
 def _date_range(start_date: str) -> str:
     """构造查询时间区间，结束日期取当天，避免硬编码过期。"""
     datetime.datetime.strptime(start_date, "%Y-%m-%d")
@@ -55,6 +148,26 @@ def _date_range(start_date: str) -> str:
     return f"{start_date}~{today}"
 
 
+def _paginate(fetch_fn, stock):
+    """
+    对单页查询函数翻页，汇总所有页的公告。
+
+    巨潮接口单页最多返回 PAGE_SIZE 条，放开时间区间后历史年报会跨越多页，
+    必须翻页才能取全。以“返回数量不足一页”作为终止条件，并设安全上限。
+    """
+    all_items = []
+    for page in range(1, MAX_PAGES + 1):
+        items = fetch_fn(page, stock)
+        if not items:
+            break
+        all_items.extend(items)
+        if len(items) < PAGE_SIZE:  # 不足一页说明已到最后一页
+            break
+    else:
+        logger.warning("翻页达到上限 %s，结果可能被截断（%s）", MAX_PAGES, stock)
+    return all_items
+
+
 def _is_annual_report_title(
     title: str, year_filter: Optional[Union[int, str]] = None
 ) -> bool:
@@ -98,10 +211,9 @@ def _is_annual_report_title(
 
 # 深市 年度报告
 def szseAnnual(page, stock):
-    query_path = "http://www.cninfo.com.cn/new/hisAnnouncement/query"
     query = {
         "pageNum": page,  # 页码
-        "pageSize": 30,
+        "pageSize": PAGE_SIZE,
         "tabName": "fulltext",
         "column": "szse",  # 深交所
         "stock": "",
@@ -110,24 +222,17 @@ def szseAnnual(page, stock):
         "plate": "sz",
         "category": "category_ndbg_szsh",  # 年度报告
         "trade": "",
-        "seDate": _date_range("2020-01-01"),  # 时间区间
+        "seDate": _date_range(EARLIEST_DATE),  # 时间区间
     }
 
-    namelist = requests.post(
-        query_path, headers=_build_headers(), data=query, timeout=30
-    )
-    result = namelist.json()
-    if result and "announcements" in result and result["announcements"]:
-        return result["announcements"]
-    return []
+    return _query_announcements(query)
 
 
 # 沪市 年度报告
 def sseAnnual(page, stock):
-    query_path = "http://www.cninfo.com.cn/new/hisAnnouncement/query"
     query = {
         "pageNum": page,  # 页码
-        "pageSize": 30,
+        "pageSize": PAGE_SIZE,
         "tabName": "fulltext",
         "column": "sse",
         "stock": "",
@@ -136,24 +241,41 @@ def sseAnnual(page, stock):
         "plate": "sh",
         "category": "category_ndbg_szsh",  # 年度报告
         "trade": "",
-        "seDate": _date_range("2020-01-01"),  # 时间区间
+        "seDate": _date_range(EARLIEST_DATE),  # 时间区间
     }
 
-    namelist = requests.post(
-        query_path, headers=_build_headers(), data=query, timeout=30
-    )
-    result = namelist.json()
-    if result and "announcements" in result and result["announcements"]:
-        return result["announcements"]
-    return []
+    return _query_announcements(query)
+
+
+# 北交所 年度报告
+def bseAnnual(page, stock):
+    """北交所年报查询。
+
+    stock 形如 "代码,orgId"，由 _resolve_org_id 解析得到。北交所必须
+    通过 plate=bj + stock="代码,orgId" 查询，searchkey/裸代码均返回空。
+    """
+    query = {
+        "pageNum": page,  # 页码
+        "pageSize": PAGE_SIZE,
+        "tabName": "fulltext",
+        "column": "bj",  # 北交所
+        "stock": stock,  # 必须为 "代码,orgId"
+        "searchkey": "",
+        "secid": "",
+        "plate": "bj",
+        "category": "category_ndbg_szsh",  # 年度报告
+        "trade": "",
+        "seDate": _date_range(EARLIEST_DATE),  # 时间区间
+    }
+
+    return _query_announcements(query)
 
 
 # 深市 招股
 def szseStock(page, stock):
-    query_path = "http://www.cninfo.com.cn/new/hisAnnouncement/query"
     query = {
         "pageNum": page,  # 页码
-        "pageSize": 30,
+        "pageSize": PAGE_SIZE,
         "tabName": "fulltext",
         "column": "szse",
         "stock": "",
@@ -162,24 +284,17 @@ def szseStock(page, stock):
         "plate": "sz",
         "category": "",
         "trade": "",
-        "seDate": _date_range("2015-01-01"),  # 时间区间
+        "seDate": _date_range(EARLIEST_DATE),  # 时间区间
     }
 
-    namelist = requests.post(
-        query_path, headers=_build_headers(), data=query, timeout=30
-    )
-    result = namelist.json()
-    if result and "announcements" in result and result["announcements"]:
-        return result["announcements"]
-    return []
+    return _query_announcements(query)
 
 
 # 沪市 招股
 def sseStock(page, stock):
-    query_path = "http://www.cninfo.com.cn/new/hisAnnouncement/query"
     query = {
         "pageNum": page,  # 页码
-        "pageSize": 30,
+        "pageSize": PAGE_SIZE,
         "tabName": "fulltext",
         "column": "sse",
         "stock": "",
@@ -188,16 +303,10 @@ def sseStock(page, stock):
         "plate": "sh",
         "category": "",
         "trade": "",
-        "seDate": _date_range("2015-01-01"),  # 时间区间
+        "seDate": _date_range(EARLIEST_DATE),  # 时间区间
     }
 
-    namelist = requests.post(
-        query_path, headers=_build_headers(), data=query, timeout=30
-    )
-    result = namelist.json()
-    if result and "announcements" in result and result["announcements"]:
-        return result["announcements"]
-    return []
+    return _query_announcements(query)
 
 
 def Download(
@@ -271,13 +380,13 @@ def query_prospectus(stock_code):
     all_announcements = []
 
     try:
-        announcements_sse = sseStock(1, stock_code)
+        announcements_sse = _paginate(sseStock, stock_code)
         all_announcements.extend(announcements_sse)
     except Exception as e:
         logger.warning("沪市招股书查询失败: %s", e)
 
     try:
-        announcements_szse = szseStock(1, stock_code)
+        announcements_szse = _paginate(szseStock, stock_code)
         all_announcements.extend(announcements_szse)
     except Exception as e:
         logger.warning("深市招股书查询失败: %s", e)
@@ -323,18 +432,30 @@ def query_annual_reports(stock_code, year=None):
 
     # 查询沪市
     try:
-        announcements_sse = sseAnnual(1, stock_code)
+        announcements_sse = _paginate(sseAnnual, stock_code)
         all_announcements.extend(announcements_sse)
     except Exception as e:
         logger.warning("沪市年报查询失败: %s", e)
 
     # 查询深市
     try:
-        announcements_szse = szseAnnual(1, stock_code)
+        announcements_szse = _paginate(szseAnnual, stock_code)
         all_announcements.extend(announcements_szse)
     except Exception as e:
         logger.warning("深市年报查询失败: %s", e)
 
+    # 查询北交所（代码以 4/8/9 开头）。北交所接口必须用 orgId，
+    # 故先解析 orgId 再以 stock="代码,orgId" 翻页查询。
+    if _is_bse_code(stock_code):
+        try:
+            resolved = _resolve_org_id(stock_code)
+            if resolved:
+                code, org_id = resolved
+                announcements_bse = _paginate(bseAnnual, f"{code},{org_id}")
+                all_announcements.extend(announcements_bse)
+        except Exception as e:
+            logger.warning("北交所年报查询失败: %s", e)
+
     # 按年份过滤
     if year:
         year_expr = re.escape(str(year))