@youhaozhao/cninfo-mcp 1.2.0 → 1.4.0

package/README.md

@@ -1,54 +1,67 @@
-# cninfo-mcp
-
-[![npm version](https://img.shields.io/npm/v/@youhaozhao/cninfo-mcp)](https://www.npmjs.com/package/@youhaozhao/cninfo-mcp)
-
-通过 MCP 协议查询和下载巨潮资讯网上市公司年报 PDF 的工具，适用于 Claude Desktop。
-
-## 使用方法
-
-在 Claude Desktop / Claude Code 配置文件中添加：
-
-**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-
-**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "cninfo": {
-      "command": "npx",
-      "args": ["-y", "@youhaozhao/cninfo-mcp"]
-    }
-  }
-}
-```
-
-重启 Claude Desktop 后即可使用。
-
-## 可用工具
-
-- **`query_annual_reports_tool`** — 查询年报列表，参数：股票代码（必填）、年份（可选）
-- **`download_annual_reports_tool`** — 下载年报 PDF，参数：股票代码（必填）、年份（可选）
-
-示例对话：
-
-```
-查询 000888 的 2024 年报
-下载 688777 的年报
-查询 920185 的年报      # 北交所，新旧代码（如 835185）均可
-```
-
-## 系统要求
-
-- Node.js 18+
-- Python 3.10+（Python 依赖会自动安装）
-
-## 数据来源
-
-[巨潮资讯网](https://www.cninfo.com.cn) — 支持沪深两市（主板、创业板、科创板）及北京证券交易所（北交所）
-
-## Credits
-
-爬虫逻辑基于 [gaodechen/cninfo_process](https://github.com/gaodechen/cninfo_process)。
-
-
+# cninfo-mcp
+
+[![npm version](https://img.shields.io/npm/v/@youhaozhao/cninfo-mcp)](https://www.npmjs.com/package/@youhaozhao/cninfo-mcp)
+
+通过 MCP 协议查询和下载巨潮资讯网上市公司定期报告及招股书 PDF 的工具，适用于 Claude Desktop / Claude Code。
+
+## 并发限制
+巨潮资讯网后端禁止大量并发，推荐将并发数设置为 4 以防止后端返回大量 403 导致 IP 短暂被封
+
+## 使用方法
+
+在 Claude Desktop / Claude Code 配置文件中添加：
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "cninfo": {
+      "command": "npx",
+      "args": ["-y", "@youhaozhao/cninfo-mcp"]
+    }
+  }
+}
+```
+
+重启 Claude Desktop 后即可使用。
+
+## 可用工具
+
+- **`query_annual_reports_tool`** — 查询报告列表，参数：股票代码（必填）、年份（可选）、报告类型（可选，默认 `annual`）
+- **`download_annual_reports_tool`** — 下载报告 PDF，参数：股票代码（必填）、年份（可选）、保存路径（可选）、报告类型（可选，默认 `annual`）
+
+支持的 `report_type`：
+
+- `annual` — 年度报告 / 年报
+- `semiannual` — 半年度报告 / 半年报 / 中报
+- `q1` — 第一季度报告 / 一季报
+- `q3` — 第三季度报告 / 三季报
+- `prospectus` — 招股书 / 招股说明书 / 招股意向书（招股书无固定年份，省略年份参数即可）
+
+示例对话：
+
+```
+查询 000888 的 2024 年报
+查询 000001 的 2024 半年报
+查询 600519 的 2024 一季报
+下载 300750 的 2023 三季报
+下载 688777 的年报
+查询 920185 的年报      # 北交所，新旧代码（如 835185）均可
+查询 688777 的招股书
+```
+
+## 系统要求
+
+- Node.js 18+
+- Python 3.10+（Python 依赖会自动安装；需要 MCP Python SDK v2，旧环境会在下次启动时自动升级）
+
+## 数据来源
+
+[巨潮资讯网](https://www.cninfo.com.cn) — 支持沪深两市（主板、创业板、科创板）及北京证券交易所（北交所）
+
+## Credits
+
+爬虫逻辑基于 [gaodechen/cninfo_process](https://github.com/gaodechen/cninfo_process)。

package/bin/cninfo-mcp.js

@@ -73,6 +73,9 @@ async function ensureVenv(systemPythonCmd) {
   return venvPython;
 }
 
+// 依赖探针：校验 venv 是否满足 requirements.txt 的全部约束
+const DEPS_CHECK = path.join(__dirname, "..", "python", "check_deps.py");
+
 // 检查并安装 Python 依赖（使用 venv 中的 python）
 async function ensureDependencies(venvPython) {
   const requirementsPath = PYTHON_REQUIREMENTS;
@@ -83,8 +86,8 @@ async function ensureDependencies(venvPython) {
   }
 
   try {
-    // 检查 mcp 包是否已安装
-    await spawnAsync(venvPython, ["-c", "import mcp"]);
+    // 校验依赖是否满足约束（不满足时抛错，转入下方安装流程）
+    await spawnAsync(venvPython, [DEPS_CHECK]);
   } catch (error) {
     // 未安装，执行安装
     console.error("Installing Python dependencies...");

package/package.json

@@ -1,15 +1,28 @@
 {
   "name": "@youhaozhao/cninfo-mcp",
-  "version": "1.2.0",
-  "description": "MCP Server for querying and downloading Chinese listed companies' annual reports from CNINFO (巨潮资讯网)",
+  "version": "1.4.0",
+  "description": "MCP Server for querying and downloading Chinese listed companies' periodic reports from CNINFO (巨潮资讯网)",
   "keywords": [
     "mcp",
     "mcp-server",
     "cninfo",
     "chinese-stock",
     "annual-reports",
+    "quarterly-reports",
+    "semiannual-reports",
+    "periodic-reports",
     "finance",
-    "python"
+    "python",
+    "巨潮",
+    "巨潮资讯",
+    "定期报告",
+    "年报",
+    "半年报",
+    "季报",
+    "招股书",
+    "A股",
+    "上市公司",
+    "财报"
   ],
   "homepage": "https://github.com/youhaozhao/cninfo-mcp#readme",
   "repository": {
@@ -27,7 +40,7 @@
     "postinstall": "node scripts/install-python-deps.js",
     "start": "node bin/cninfo-mcp.js",
     "dev": "node bin/cninfo-mcp.js",
-    "test": "echo \"No tests configured\""
+    "test": "python3 -m pytest python/test_spider.py -q"
   },
   "dependencies": {
     "spawn-please": "^2.0.2"
@@ -46,6 +59,7 @@
   "files": [
     "bin/",
     "python/mcp_server.py",
+    "python/check_deps.py",
     "python/spider.py",
     "python/requirements.txt",
     "scripts/install-python-deps.js",

package/python/check_deps.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""校验当前解释器是否满足 requirements.txt 的全部约束。
+
+退出码 0 表示全部满足,调用方可以跳过 pip 安装;非 0 表示需要执行
+`pip install -r requirements.txt`。
+
+这个脚本只是一个优化——用来省掉一次很慢的 pip 调用,pip 自身才是约束的
+最终权威。因此所有无法确定的情况(依赖缺失、版本不符、约束解析失败、
+连比较版本号的库都找不到)一律返回非 0,让 pip 去做真正的判断。宁可多跑
+一次 pip,也不能放行一个不满足约束的环境。
+"""
+
+import os
+import sys
+from importlib.metadata import PackageNotFoundError, version
+
+REQUIREMENTS = os.path.join(os.path.dirname(os.path.abspath(__file__)), "requirements.txt")
+
+
+def _load_requirement_parser():
+    """返回 packaging 的 Requirement 类,找不到时返回 None。
+
+    packaging 不是本项目的直接依赖,全新 venv 里通常不存在,因此回退到 pip
+    自带的 vendored 副本。部分发行版(如 Debian)会去除 vendoring,那时两者
+    都不可用,由调用方按“未满足”处理。
+    """
+    try:
+        from packaging.requirements import Requirement
+
+        return Requirement
+    except ImportError:
+        pass
+    try:
+        from pip._vendor.packaging.requirements import Requirement
+
+        return Requirement
+    except ImportError:
+        return None
+
+
+def unsatisfied(requirements_path=None):
+    """返回未满足的约束列表;无法判断时抛出异常由调用方兜底。"""
+    # 默认值在调用时解析,而不是在 def 时绑定,便于测试替换 REQUIREMENTS
+    if requirements_path is None:
+        requirements_path = REQUIREMENTS
+
+    Requirement = _load_requirement_parser()
+    if Requirement is None:
+        raise RuntimeError("packaging is unavailable; cannot verify requirements")
+
+    missing = []
+    with open(requirements_path, encoding="utf-8") as fh:
+        for raw in fh:
+            line = raw.split("#", 1)[0].strip()
+            # 跳过空行,以及 -r/-e/--index-url 这类非约束指令
+            if not line or line.startswith("-"):
+                continue
+
+            req = Requirement(line)
+            try:
+                installed = version(req.name)
+            except PackageNotFoundError:
+                missing.append(f"{req.name} (not installed)")
+                continue
+
+            # prereleases=True:已装的预发布版本若落在区间内也算满足,
+            # 避免把 pip 已经接受的环境反复重装。
+            if not req.specifier.contains(installed, prereleases=True):
+                missing.append(f"{req.name} {installed} does not satisfy {req.specifier}")
+
+    return missing
+
+
+def main():
+    try:
+        missing = unsatisfied()
+    except Exception as exc:  # 解析失败、文件缺失等一律按“需要安装”处理
+        print(f"dependency check inconclusive: {exc}", file=sys.stderr)
+        return 1
+
+    if missing:
+        for item in missing:
+            print(f"dependency not satisfied: {item}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())