@youhaozhao/cninfo-mcp 1.4.1 → 2.0.0

package/README.md

@@ -4,11 +4,23 @@
 
 通过 MCP 协议查询和下载巨潮资讯网上市公司定期报告及招股书 PDF 的工具，适用于 Claude Desktop / Claude Code。
 
+> 本项目是社区维护的开源实现，**不是巨潮资讯网的官方产品**，详见[免责声明与数据使用](#免责声明与数据使用)。
+
 ## 并发限制
 巨潮资讯网后端禁止大量并发，推荐将并发数设置为 4 以防止后端返回大量 403 导致 IP 短暂被封
 
 ## 使用方法
 
+### 1. 安装 Python 依赖（只需一次）
+
+```bash
+npx -y @youhaozhao/cninfo-mcp install
+```
+
+这条命令会在 `~/.cninfo-mcp/venv` 创建 Python 虚拟环境，并用 pip 从 PyPI 安装 [`python/requirements.txt`](python/requirements.txt) 里的依赖。`npm install` 和服务器启动都不会创建环境或执行 pip；环境缺失或依赖过期时，服务器会直接报错并提示重新运行这条命令。
+
+### 2. 添加到 MCP 客户端
+
 在 Claude Desktop / Claude Code 配置文件中添加：
 
 **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
@@ -20,12 +32,17 @@
   "mcpServers": {
     "cninfo": {
       "command": "npx",
-      "args": ["-y", "@youhaozhao/cninfo-mcp"]
+      "args": ["-y", "@youhaozhao/cninfo-mcp"],
+      "env": {
+        "CNINFO_MCP_DOWNLOAD_DIR": "/Users/me/reports"
+      }
     }
   }
 }
 ```
 
+`env` 可以省略。`CNINFO_MCP_DOWNLOAD_DIR` 是下载根目录，不设置时为 `~/Downloads/cninfo-mcp`。
+
 重启 Claude Desktop 后即可使用。
 
 ## 可用工具
@@ -33,6 +50,15 @@
 - **`query_annual_reports_tool`** — 查询报告列表，参数：股票代码（必填）、年份（可选）、报告类型（可选，默认 `annual`）
 - **`download_annual_reports_tool`** — 下载报告 PDF，参数：股票代码（必填）、年份（可选）、保存路径（可选）、报告类型（可选，默认 `annual`）
 
+保存路径只能是下载根目录内的位置：相对路径（如 `annual/2024`）按根目录下的子目录解析，落在根目录之外的路径（包括 `..` 和指向外部的符号链接）会被拒绝，不会写入任何文件。
+
+两个工具都声明了 MCP 工具注解：
+
+| 工具 | `readOnlyHint` | `destructiveHint` | `idempotentHint` | `openWorldHint` |
+| --- | --- | --- | --- | --- |
+| `query_annual_reports_tool` | `true` | `false` | `true` | `true` |
+| `download_annual_reports_tool` | `false` | `false` | `true` | `true` |
+
 支持的 `report_type`：
 
 - `annual` — 年度报告 / 年报
@@ -56,12 +82,53 @@
 ## 系统要求
 
 - Node.js 18+
-- Python 3.10+（Python 依赖会自动安装；需要 MCP Python SDK v2，旧环境会在下次启动时自动升级）
+- Python 3.10+（需要 MCP Python SDK v2；依赖通过上面的 `install` 命令安装，升级后如提示依赖过期，重新运行一次即可）
+
+## 安全边界
+
+- **网络**：只访问 `https://www.cninfo.com.cn`（查询）和 `https://static.cninfo.com.cn`（PDF 下载），全程 HTTPS。
+- **文件**：只有下载工具会写盘，并且只写入下载根目录（`CNINFO_MCP_DOWNLOAD_DIR`，默认 `~/Downloads/cninfo-mcp`）。根目录由部署方在客户端配置里指定，工具调用方无法更改。
+- **写入确认**：服务器自身不弹确认框。下载工具声明了 `readOnlyHint: false`，是否在调用前向用户确认由 MCP 客户端决定。
+- **安装**：创建虚拟环境和 pip 安装只发生在显式的 `install` 命令里，位置固定为 `~/.cninfo-mcp/venv`。
+- **凭据**：不需要、也不读取任何账号、Cookie 或密钥。
 
 ## 数据来源
 
 [巨潮资讯网](https://www.cninfo.com.cn) — 支持沪深两市（主板、创业板、科创板）及北京证券交易所（北交所）
 
+## 免责声明与数据使用
+
+- **非官方**：本项目是社区维护的开源工具，不是巨潮资讯网的官方产品，与其运营方深圳证券信息有限公司没有隶属、合作或授权关系。
+- **非官方接口**：工具调用的是巨潮资讯网网页自身使用的查询接口，不是官方数据服务接口，可能随时变更、限流或停用。
+- **内容权利**：本项目不托管、不转发任何报告内容，所有数据都由你的机器直接从巨潮资讯网获取。网站页脚标注“深圳证券信息有限公司 版权所有”，报告文件由各上市公司披露；下载后的使用方式（尤其是再分发和商业用途）请自行确认是否合规。
+- **上游声明**：巨潮资讯网在[首页](https://www.cninfo.com.cn)页脚公布了免责声明，写明网站“竭力保证所提供的证券市场信息准确可靠，但并不担保（无论提示、默示、法定或其他形式）其准确性和完整性”，并且进入网站即视为接受该声明。通过本工具访问同样受其约束，请以网站公布的最新内容为准。
+- **合理使用**：请遵守上面的[并发限制](#并发限制)，不要用本工具做高频或大批量抓取。
+- **不构成投资建议**：工具只负责检索和下载公开披露文件，不对内容的准确性、完整性和时效性作任何保证。
+
+## 从 1.4.x 及更早版本升级
+
+- 启动器不再自动创建虚拟环境或安装依赖。已有的 `~/.cninfo-mcp/venv` 满足依赖时无需操作，否则先运行一次 `npx -y @youhaozhao/cninfo-mcp install`。
+- 下载位置改为受限的下载根目录，默认从包目录下的 `pdf/` 变为 `~/Downloads/cninfo-mcp`。以前传给保存路径的任意绝对路径会被拒绝，需要改用 `CNINFO_MCP_DOWNLOAD_DIR` 指定根目录。
+- 查询接口改为通过 HTTPS 访问。
+
 ## Credits
 
 爬虫逻辑基于 [gaodechen/cninfo_process](https://github.com/gaodechen/cninfo_process)。
+
+## 开发测试
+
+在独立环境中安装运行依赖和 pytest 后执行全部 Python 与 Node 回归测试：
+
+```bash
+python3 -m venv .venv
+# Windows: .venv\Scripts\activate
+source .venv/bin/activate
+python -m pip install -r python/requirements.txt pytest
+npm test
+```
+
+也可使用 uv 临时环境：
+
+```bash
+uv run --no-project --with pytest --with requests --with 'mcp~=2.1.1' npm test
+```

package/bin/cninfo-mcp.js

@@ -2,7 +2,8 @@
 
 /**
  * 巨潮资讯 MCP 服务器启动器
- * 自动检测 Python 并安装依赖，然后启动 Python MCP 服务器。
+ * 只校验已有的 Python 环境并启动 Python MCP 服务器：不联网，不写用户目录。
+ * 环境由显式命令 `cninfo-mcp install` 准备（scripts/install-python-deps.js）。
  */
 
 const { spawn } = require("child_process");
@@ -12,15 +13,16 @@ const os = require("os");
 
 // 配置路径
 const PYTHON_SCRIPT = path.join(__dirname, "..", "python", "mcp_server.py");
-const PYTHON_REQUIREMENTS = path.join(
+const INSTALL_SCRIPT = path.join(
   __dirname,
   "..",
-  "python",
-  "requirements.txt",
+  "scripts",
+  "install-python-deps.js",
 );
+const INSTALL_COMMAND = "npx -y @youhaozhao/cninfo-mcp install";
 
 // 虚拟环境目录，放在用户目录下保证跨 npx 调用持久化
-const VENV_DIR = path.join(os.homedir(), ".cninfo-mcp", "venv");
+let VENV_DIR = path.join(os.homedir(), ".cninfo-mcp", "venv");
 
 // 获取虚拟环境中的 Python 可执行文件路径
 function getVenvPython() {
@@ -30,83 +32,65 @@ function getVenvPython() {
   return path.join(VENV_DIR, "bin", "python3");
 }
 
-// 查找可用的系统 Python 可执行文件（仅用于创建 venv）
-async function findPython() {
-  const pythonCommands = [
-    "python3",
-    "python",
-    "python3.12",
-    "python3.11",
-    "python3.10",
-  ];
-
-  for (const cmd of pythonCommands) {
-    try {
-      const result = await spawnAsync(cmd, ["--version"]);
-      if (result.stdout && result.stdout.includes("Python")) {
-        return cmd;
-      }
-    } catch (error) {
-      // 继续尝试下一个命令
-    }
+async function isSupportedPython(cmd) {
+  try {
+    const result = await spawnAsync(cmd, ["--version"]);
+    const version = `${result.stdout || ""} ${result.stderr || ""}`.match(/\bPython (\d+)\.(\d+)\.(\d+)\b/);
+    return Boolean(version && Number(version[1]) === 3 && Number(version[2]) >= 10);
+  } catch {
+    return false;
   }
-
-  throw new Error(
-    "Python not found. Please install Python 3.10+ from https://python.org\n" +
-      "After installation, restart your terminal and try again.",
-  );
 }
 
-// 创建虚拟环境（如果不存在）
-async function ensureVenv(systemPythonCmd) {
-  const venvPython = getVenvPython();
-  if (fs.existsSync(venvPython)) {
-    return venvPython;
-  }
-
-  console.error("Creating Python virtual environment...");
-  fs.mkdirSync(path.dirname(VENV_DIR), { recursive: true });
-  await spawnAsync(systemPythonCmd, ["-m", "venv", VENV_DIR], {
-    stdio: "inherit",
-  });
-  console.error("Virtual environment created\n");
-  return venvPython;
+// An obsolete environment is left intact; its compatible sibling is used instead.
+async function reusableVenv() {
+  if (!fs.existsSync(getVenvPython())) return null;
+  if (await isSupportedPython(getVenvPython())) return getVenvPython();
+  VENV_DIR += "-py310";
+  if (!fs.existsSync(getVenvPython())) return null;
+  if (await isSupportedPython(getVenvPython())) return getVenvPython();
+  throw new Error(`Unsupported or broken Python environment at ${VENV_DIR}. Recreate it with Python 3.10+.`);
 }
 
 // 依赖探针：校验 venv 是否满足 requirements.txt 的全部约束
 const DEPS_CHECK = path.join(__dirname, "..", "python", "check_deps.py");
 
-// 检查并安装 Python 依赖（使用 venv 中的 python）
-async function ensureDependencies(venvPython) {
-  const requirementsPath = PYTHON_REQUIREMENTS;
-
-  if (!fs.existsSync(requirementsPath)) {
-    console.error("Error: requirements.txt not found at", requirementsPath);
-    process.exit(1);
+// 只读校验：环境缺失或依赖不满足时报错并给出安装命令，不在启动阶段安装
+async function requireEnvironment() {
+  const venvPython = await reusableVenv();
+  if (!venvPython) {
+    throw new Error(
+      "Python environment for cninfo-mcp is not installed.\n" +
+        `Run this once, then restart the MCP client: ${INSTALL_COMMAND}`,
+    );
   }
 
   try {
-    // 校验依赖是否满足约束（不满足时抛错，转入下方安装流程）
     await spawnAsync(venvPython, [DEPS_CHECK]);
-  } catch (error) {
-    // 未安装，执行安装
-    console.error("Installing Python dependencies...");
-    try {
-      await spawnAsync(
-        venvPython,
-        ["-m", "pip", "install", "-r", requirementsPath],
-        {
-          stdio: "inherit",
-        },
-      );
-      console.error("Python dependencies installed successfully\n");
-    } catch (installError) {
-      console.error("\n❌ Failed to install Python dependencies");
-      console.error("Please run manually:");
-      console.error(`  ${venvPython} -m pip install -r ${requirementsPath}`);
-      process.exit(1);
-    }
+  } catch {
+    throw new Error(
+      `Python dependencies in ${VENV_DIR} are missing or out of date.\n` +
+        `Run this, then restart the MCP client: ${INSTALL_COMMAND}`,
+    );
   }
+  return venvPython;
+}
+
+// 显式安装入口：唯一会联网并写用户目录的路径
+function runInstaller() {
+  const child = spawn(process.execPath, [INSTALL_SCRIPT], {
+    stdio: "inherit",
+    shell: false,
+  });
+
+  child.on("error", (error) => {
+    console.error("Failed to start installer:", error.message);
+    process.exit(1);
+  });
+
+  child.on("exit", (code) => {
+    process.exit(code ?? 1);
+  });
 }
 
 // 启动子进程并返回结果
@@ -114,7 +98,7 @@ function spawnAsync(command, args, options = {}) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, args, {
       stdio: options.stdio || "pipe",
-      shell: process.platform === "win32",
+      shell: false,
       ...options,
     });
 
@@ -155,21 +139,24 @@ function spawnAsync(command, args, options = {}) {
 
 async function main() {
   try {
+    if (process.argv[2] === "install") {
+      runInstaller();
+      return;
+    }
+
     // 检查 Python 脚本是否存在
     if (!fs.existsSync(PYTHON_SCRIPT)) {
       console.error("Error: mcp_server.py not found at", PYTHON_SCRIPT);
       process.exit(1);
     }
 
-    const systemPython = await findPython();
-    const venvPython = await ensureVenv(systemPython);
-    await ensureDependencies(venvPython);
+    const venvPython = await requireEnvironment();
 
     // 启动 MCP 服务器
     console.error("巨潮资讯 MCP 服务器已启动，等待连接...");
     const child = spawn(venvPython, [PYTHON_SCRIPT], {
       stdio: "inherit",
-      shell: process.platform === "win32",
+      shell: false,
       env: {
         ...process.env,
         PYTHONPATH: path.join(__dirname, "..", "python"),

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@youhaozhao/cninfo-mcp",
-  "version": "1.4.1",
+  "version": "2.0.0",
+  "mcpName": "io.github.youhaozhao/cninfo-mcp",
   "description": "MCP Server for querying and downloading Chinese listed companies' periodic reports from CNINFO (巨潮资讯网)",
   "keywords": [
     "mcp",
@@ -37,10 +38,9 @@
     "cninfo-mcp": "bin/cninfo-mcp.js"
   },
   "scripts": {
-    "postinstall": "node scripts/install-python-deps.js",
     "start": "node bin/cninfo-mcp.js",
     "dev": "node bin/cninfo-mcp.js",
-    "test": "python3 -m pytest python/test_spider.py -q"
+    "test": "python3 -m pytest python -q && node --test scripts/test-launcher.js scripts/test-manifest.js"
   },
   "dependencies": {
     "spawn-please": "^2.0.2"

package/python/mcp_server.py

@@ -13,14 +13,22 @@ from typing import Optional
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
 from mcp.server.mcpserver import MCPServer
+from mcp.types import ToolAnnotations
 from spider import (
     query_reports,
+    QueryError,
+    normalize_stock_code,
     download_reports,
     format_reports,
-    saving_path,
     supported_report_types,
 )
 
+# 下载根目录由部署方通过环境变量指定，调用方（模型）无法用工具参数改写，
+# 因此所有写盘都落在这一个可审计的目录内。
+DOWNLOAD_DIR_ENV = "CNINFO_MCP_DOWNLOAD_DIR"
+DEFAULT_DOWNLOAD_DIR = os.path.join("~", "Downloads", "cninfo-mcp")
+
+
 def _package_version(default: str = "0.0.0") -> str:
     """从 package.json 读取版本，避免与 npm 包版本各写一份而漂移。
 
@@ -49,7 +57,43 @@ def _supported_report_types_text() -> str:
     return ", ".join(supported_report_types().keys())
 
 
-@mcp.tool()
+def _download_root() -> str:
+    configured = os.environ.get(DOWNLOAD_DIR_ENV, "").strip()
+    return os.path.realpath(os.path.expanduser(configured or DEFAULT_DOWNLOAD_DIR))
+
+
+def _resolve_save_path(save_path: Optional[str]) -> str:
+    """把调用方给的 save_path 限制在下载根目录内，返回最终写入目录。
+
+    相对路径按根目录下的子目录解析；绝对路径只有落在根目录内才接受。两侧都
+    先 realpath，因此 `..` 和指向根目录之外的符号链接都会被拒绝。
+    """
+    root = _download_root()
+    requested = (save_path or "").strip()
+    if not requested:
+        return root
+    candidate = os.path.realpath(os.path.join(root, os.path.expanduser(requested)))
+    try:
+        inside = os.path.commonpath([root, candidate]) == root
+    except ValueError:
+        # Windows 上不同盘符之间没有公共路径
+        inside = False
+    if not inside:
+        raise ValueError(
+            f"save_path must be inside the download directory {root}. "
+            f"Set {DOWNLOAD_DIR_ENV} in the MCP server configuration to change it"
+        )
+    return candidate
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        read_only_hint=True,
+        destructive_hint=False,
+        idempotent_hint=True,
+        open_world_hint=True,
+    )
+)
 def query_annual_reports_tool(
     stock_code: str, year: Optional[int] = None, report_type: str = "annual"
 ) -> dict:
@@ -63,7 +107,8 @@ def query_annual_reports_tool(
 
     Returns:
         Dictionary containing:
-        - success: Boolean indicating if the query was successful
+        - success: True only for complete queries, including empty results
+        - status: complete, partial, or error; incomplete queries include error details
         - stock_code: The queried stock code
         - report_type: The requested report type
         - year: The filtered year (if any)
@@ -71,11 +116,13 @@ def query_annual_reports_tool(
         - reports: List of report details (announcementTitle, announcementTime, secCode, secName, adjunctUrl)
     """
     try:
+        stock_code = normalize_stock_code(stock_code)
         reports = query_reports(stock_code, report_type, year)
 
         if not reports:
             return {
-                "success": False,
+                "success": True,
+                "status": "complete",
                 "stock_code": stock_code,
                 "report_type": report_type,
                 "year": year,
@@ -87,6 +134,7 @@ def query_annual_reports_tool(
 
         return {
             "success": True,
+            "status": "complete",
             "stock_code": stock_code,
             "report_type": report_type,
             "year": year,
@@ -96,9 +144,24 @@ def query_annual_reports_tool(
             + (f" for year {year}" if year else ""),
         }
 
+    except QueryError as e:
+        return {
+            "success": False,
+            "status": e.status,
+            "stock_code": stock_code,
+            "report_type": report_type,
+            "year": year,
+            "count": len(e.reports),
+            "reports": format_reports(e.reports),
+            "errors": e.errors,
+            "error": str(e),
+            "message": f"Query incomplete: {str(e)}",
+        }
+
     except Exception as e:
         return {
             "success": False,
+            "status": "error",
             "stock_code": stock_code,
             "report_type": report_type,
             "year": year,
@@ -109,7 +172,16 @@ def query_annual_reports_tool(
         }
 
 
-@mcp.tool()
+# 非只读：会在下载根目录内写文件。文件名带附件 URL 的 SHA-256，重复调用只会
+# 原子替换同一附件的旧副本，不会改动其他文件，因此不是破坏性操作且幂等。
+@mcp.tool(
+    annotations=ToolAnnotations(
+        read_only_hint=False,
+        destructive_hint=False,
+        idempotent_hint=True,
+        open_world_hint=True,
+    )
+)
 def download_annual_reports_tool(
     stock_code: str,
     year: Optional[int] = None,
@@ -122,12 +194,16 @@ def download_annual_reports_tool(
     Args:
         stock_code: Stock code (e.g., '000888' for 峨眉山, '688777' for 中科德芯)
         year: Optional year to filter (e.g., 2024). If not provided, downloads all available years
-        save_path: Optional directory to save files (e.g., '/Users/me/reports'). Defaults to pdf/ in package directory
+        save_path: Optional sub-directory for the files (e.g., 'annual/2024'). It must resolve inside the server's download directory, which is set by the CNINFO_MCP_DOWNLOAD_DIR environment variable (default ~/Downloads/cninfo-mcp); relative paths are taken relative to that directory and anything outside it is rejected. Omit to save directly in the download directory.
         report_type: Optional report type. Supported values: annual, semiannual, q1, q3, prospectus. Defaults to annual for backward compatibility.
 
     Returns:
         Dictionary containing:
-        - success: Boolean indicating if download was successful
+        - success: True only when the query and all downloads completed
+        - status: complete, partial, or error
+        - query_status: Whether the source query completed
+        - files / failures: Successful paths and per-attachment errors
+        - failed: Number of failed attachments
         - stock_code: The stock code
         - report_type: The requested report type
         - year: The filtered year (if any)
@@ -135,9 +211,10 @@ def download_annual_reports_tool(
         - path: Directory where files were saved
         - message: Status message
     """
+    output_dir = _download_root()
     try:
-        output_dir = save_path or saving_path
-        os.makedirs(output_dir, exist_ok=True)
+        output_dir = _resolve_save_path(save_path)
+        stock_code = normalize_stock_code(stock_code)
 
         result = download_reports(
             stock_code, report_type, year=year, save_path=output_dir
@@ -151,11 +228,16 @@ def download_annual_reports_tool(
     except Exception as e:
         return {
             "success": False,
+            "status": "error",
             "stock_code": stock_code,
             "report_type": report_type,
             "year": year,
             "downloaded": 0,
-            "path": save_path or saving_path,
+            "files": [],
+            "failed": 0,
+            "failures": [],
+            "query_status": "error",
+            "path": output_dir,
             "error": str(e),
             "message": f"Error downloading reports: {str(e)}. Supported report_type values: {_supported_report_types_text()}",
         }
@@ -165,12 +247,21 @@ def download_annual_reports_tool(
 def get_annual_reports_list(stock_code: str) -> str:
     """返回指定股票代码的年度报告格式化列表"""
     try:
-        reports = query_reports(stock_code, "annual")
-
+        warning = ""
+        try:
+            reports = query_reports(stock_code, "annual")
+        except QueryError as exc:
+            reports = exc.reports
+            warning = f"Query incomplete ({exc.status}): {exc}"
+
+        if not reports and warning:
+            return warning
         if not reports:
             return f"No annual reports found for stock {stock_code}"
 
         output = [f"Annual Reports for {stock_code}:", "=" * 60]
+        if warning:
+            output.append(warning)
 
         for report in reports:
             title = report.get("announcementTitle", "N/A")

package/python/spider.py

@@ -3,12 +3,15 @@
 """
 
 import datetime
+import hashlib
 import logging
 import os
 import random
 import re
+import tempfile
 import time
 from typing import Optional, Union
+from urllib.parse import urljoin, urlsplit, urlunsplit
 
 import requests
 
@@ -25,9 +28,9 @@ PAGE_SIZE = 30
 # 翻页安全上限，防止异常情况下无限循环
 MAX_PAGES = 100
 # 巨潮搜索联想接口：把股票代码/简称解析为 orgId（北交所查询必需）
-TOP_SEARCH_URL = "http://www.cninfo.com.cn/new/information/topSearch/query"
+TOP_SEARCH_URL = "https://www.cninfo.com.cn/new/information/topSearch/query"
 # 公告查询接口
-QUERY_URL = "http://www.cninfo.com.cn/new/hisAnnouncement/query"
+QUERY_URL = "https://www.cninfo.com.cn/new/hisAnnouncement/query"
 # 瞬时失败（网络抖动/限流）的重试次数与退避基数（秒）
 MAX_RETRIES = 3
 RETRY_BACKOFF = 1.0
@@ -144,8 +147,8 @@ BASE_HEADERS = {
     "Accept-Encoding": "gzip, deflate",
     "Accept-Language": "zh-CN,zh;q=0.9,en-US;q=0.8,en;q=0.7,zh-HK;q=0.6,zh-TW;q=0.5",
     "Host": "www.cninfo.com.cn",
-    "Origin": "http://www.cninfo.com.cn",
-    "Referer": "http://www.cninfo.com.cn/new/commonUrl?url=disclosure/list/notice",
+    "Origin": "https://www.cninfo.com.cn",
+    "Referer": "https://www.cninfo.com.cn/new/commonUrl?url=disclosure/list/notice",
     "X-Requested-With": "XMLHttpRequest",
 }
 
@@ -167,6 +170,46 @@ def normalize_report_type(report_type: Optional[str]) -> str:
     return normalized
 
 
+def normalize_stock_code(stock_code) -> str:
+    """Require a six-digit security code; preserve leading zeroes."""
+    code = str(stock_code).strip()
+    if not re.fullmatch(r"[0-9]{6}", code):
+        raise ValueError("stock_code must contain exactly six ASCII digits")
+    return code
+
+
+class QueryError(RuntimeError):
+    """An incomplete query, optionally carrying already fetched reports."""
+
+    def __init__(self, errors, reports=None, partial=False):
+        self.errors = errors
+        self.reports = reports or []
+        self.status = "partial" if partial else "error"
+        super().__init__("; ".join(errors))
+
+
+def resolve_attachment_url(value: str, base: str = download_path) -> str:
+    """Resolve attachment paths, allowing only HTTPS on CNINFO's static host."""
+    if (
+        not isinstance(value, str)
+        or not value
+        or re.search(r"[\s\\\x00-\x1f\x7f]", value)
+    ):
+        raise ValueError("Invalid attachment URL")
+    parsed = urlsplit(urljoin(base, value))
+    if (
+        parsed.scheme != "https"
+        or parsed.hostname != "static.cninfo.com.cn"
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.port not in (None, 443)
+    ):
+        raise ValueError("Attachment URLs must use https://static.cninfo.com.cn")
+    return urlunsplit(
+        ("https", "static.cninfo.com.cn", parsed.path or "/", parsed.query, "")
+    )
+
+
 def format_reports(reports: list) -> list:
     """提取公告中稳定、有用的字段，并把附件路径补全为可访问的绝对 URL。
 
@@ -176,15 +219,23 @@ def format_reports(reports: list) -> list:
     formatted = []
     for report in reports:
         adj = report.get("adjunctUrl", "")
+        attachment_error = None
+        try:
+            url = resolve_attachment_url(adj) if adj else ""
+        except ValueError as exc:
+            url = ""
+            attachment_error = str(exc)
         formatted.append(
             {
                 "announcementTitle": report.get("announcementTitle", ""),
                 "announcementTime": report.get("announcementTime", ""),
                 "secCode": report.get("secCode", ""),
                 "secName": report.get("secName", ""),
-                "adjunctUrl": download_path + adj if adj else "",
+                "adjunctUrl": url,
             }
         )
+        if attachment_error:
+            formatted[-1]["attachmentError"] = attachment_error
     return formatted
 
 
@@ -229,9 +280,12 @@ def _post_json(url: str, data: dict) -> dict:
 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 []
+    if not isinstance(result, dict) or "announcements" not in result:
+        raise ValueError("Invalid announcement response")
+    items = result["announcements"]
+    if items is not None and not isinstance(items, list):
+        raise ValueError("Invalid announcements list")
+    return items or []
 
 
 def _is_bse_code(stock_code) -> bool:
@@ -253,13 +307,10 @@ def _resolve_org_id(stock_code) -> Optional[tuple]:
     优先返回 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:
+    hits = _post_json(TOP_SEARCH_URL, {"keyWord": stock_code, "maxNum": 10})
+    if not isinstance(hits, list):
+        raise ValueError("Invalid orgId response")
+    if not hits:
         return None
 
     target = re.sub(r"\D", "", str(stock_code or ""))
@@ -288,14 +339,17 @@ def _paginate(fetch_fn, stock):
     """
     all_items = []
     for page in range(1, MAX_PAGES + 1):
-        items = fetch_fn(page, stock)
+        try:
+            items = fetch_fn(page, stock)
+        except Exception as exc:
+            raise QueryError([f"page {page}: {exc}"], all_items, page > 1) from exc
         if not items:
             break
         all_items.extend(items)
         if len(items) < PAGE_SIZE:
             break
     else:
-        logger.warning("翻页达到上限 %s，结果可能被截断（%s）", MAX_PAGES, stock)
+        raise QueryError([f"Pagination limit reached ({MAX_PAGES})"], all_items, True)
     return all_items
 
 
@@ -314,13 +368,28 @@ def _is_report_title(
     spec = REPORT_TYPE_SPECS[normalized_type]
 
     if normalized_type == "prospectus":
-        matched = next((kw for kw in spec["keywords"] if kw in compact_title), None)
-        if matched is None:
+        # Historical version labels vary; filter document kind below instead
+        # of restricting prospectus versions to a fixed suffix vocabulary.
+        match = re.fullmatch(
+            r".*?(?:招股说明书|招股意向书|招股书)(?:\([^()（）]+\)|（[^()（）]+）)*",
+            compact_title,
+        )
+        if not match:
             return False
-        # 去掉招股书正式名称后再判断摘要/更正等变体，避免“招股说明书”自带的
-        # “说明”被 COMMON_EXCLUDE_KEYWORDS 误伤（参见 #2）。
-        remainder = compact_title.replace(matched, "")
-        return not any(kw in remainder for kw in COMMON_EXCLUDE_KEYWORDS)
+        remainder = re.sub(r"招股说明书|招股意向书|招股书", "", compact_title)
+        excluded = COMMON_EXCLUDE_KEYWORDS + [
+            "关于",
+            "意见",
+            "核查",
+            "验证",
+            "问询",
+            "回复",
+            "公告",
+            "审计报告",
+            "附件",
+            "附录",
+        ]
+        return not any(kw in remainder for kw in excluded)
 
     # 摘要/更正/修订等非正文变体应排除
     if any(keyword in compact_title for keyword in COMMON_EXCLUDE_KEYWORDS):
@@ -353,7 +422,8 @@ def _matches_year(
         # announcementTime 通常是 "YYYY-MM-DD" 字符串；个别接口可能返回 epoch 毫秒
         if isinstance(announcement_time, (int, float)):
             announcement_time = datetime.datetime.fromtimestamp(
-                announcement_time / 1000
+                announcement_time / 1000,
+                tz=datetime.timezone(datetime.timedelta(hours=8)),
             ).strftime("%Y-%m-%d")
         return str(announcement_time).startswith(str(year))
     return _is_report_title(
@@ -442,68 +512,141 @@ def sseStock(page, stock):
     return _query_exchange_report(page, stock, "prospectus", "sse", "sh")
 
 
+def _get_attachment(url):
+    """Follow at most five redirects, validating before every network request."""
+    url = resolve_attachment_url(url)
+    for redirects in range(6):
+        response = requests.get(
+            url,
+            headers={"User-Agent": random.choice(User_Agent)},
+            timeout=30,
+            allow_redirects=False,
+        )
+        if response.status_code not in (301, 302, 303, 307, 308):
+            return response
+        try:
+            if redirects == 5:
+                raise ValueError("Too many attachment redirects")
+            url = resolve_attachment_url(response.headers.get("Location", ""), base=url)
+        finally:
+            response.close()
+    raise RuntimeError("Attachment redirect handling failed")
+
+
+def _fetch_pdf(url):
+    for attempt in range(MAX_RETRIES):
+        try:
+            response = _get_attachment(url)
+            try:
+                response.raise_for_status()
+                content = response.content
+                content_type = (
+                    response.headers.get("Content-Type", "")
+                    .lower()
+                    .split(";", 1)[0]
+                    .strip()
+                )
+                if content_type and content_type not in (
+                    "application/pdf",
+                    "application/octet-stream",
+                    "binary/octet-stream",
+                    "application/x-pdf",
+                ):
+                    raise ValueError(f"Unexpected PDF content type: {content_type}")
+                if not content.startswith(b"%PDF-"):
+                    raise ValueError("Empty or non-PDF response")
+                return content
+            finally:
+                response.close()
+        except (requests.exceptions.Timeout, requests.exceptions.ConnectionError):
+            if attempt == MAX_RETRIES - 1:
+                raise
+        except requests.exceptions.HTTPError as exc:
+            status = exc.response.status_code if exc.response is not None else None
+            if status != 429 and (status is None or status < 500):
+                raise
+            if attempt == MAX_RETRIES - 1:
+                raise
+        time.sleep(RETRY_BACKOFF * (2**attempt) + random.random())
+    raise RuntimeError("No download attempts configured")
+
+
 def Download(
     single_page,
     report_type: Optional[str] = None,
     year_filter: Optional[Union[int, str]] = None,
     save_path: Optional[str] = None,
+    *,
+    details=False,
 ):
-    """下载公告列表中的 PDF 文件。"""
-    if single_page is None:
-        return 0
-
-    output_dir = (save_path or saving_path).rstrip("/\\") + "/"
-    downloaded_count = 0
+    """Download independently and atomically; legacy callers receive a count."""
+    output_dir = save_path or saving_path
+    files, failures = [], []
     normalized_type = normalize_report_type(report_type) if report_type else None
-
-    for i in single_page:
-        title = i.get("announcementTitle", "")
-        if normalized_type:
-            should_download = _is_report_title(
-                title, normalized_type, year_filter=year_filter
+    for report in single_page or []:
+        title = report.get("announcementTitle", "")
+        types = [normalized_type] if normalized_type else REPORT_TYPE_SPECS
+        if not any(_is_report_title(title, kind, year_filter) for kind in types):
+            continue
+        adjunct_url = report.get("adjunctUrl", "")
+        temporary_path = None
+        try:
+            if not adjunct_url:
+                raise ValueError("Missing adjunctUrl")
+            url = resolve_attachment_url(adjunct_url)
+            # Full attachment digest keeps distinct URLs distinct, even with identical titles.
+            attachment_id = hashlib.sha256(adjunct_url.encode("utf-8")).hexdigest()
+            stem = _sanitize_filename(
+                f"{report.get('secCode', '')}_{report.get('secName', '')}_{title}"
             )
-        else:
-            should_download = any(
-                _is_report_title(title, candidate, year_filter=year_filter)
-                for candidate in REPORT_TYPE_SPECS
+            # Leave room for the digest on filesystems with a 255-byte name limit.
+            stem = stem.encode("utf-8")[:160].decode("utf-8", errors="ignore")
+            file_path = os.path.join(output_dir, f"{stem}_{attachment_id}.pdf")
+            time.sleep(random.random() * 2)
+            content = _fetch_pdf(url)
+            os.makedirs(output_dir, exist_ok=True)
+            with tempfile.NamedTemporaryFile(
+                dir=output_dir, suffix=".tmp", delete=False
+            ) as fh:
+                temporary_path = fh.name
+                fh.write(content)
+            os.replace(temporary_path, file_path)
+            temporary_path = None
+            files.append({"adjunctUrl": adjunct_url, "path": file_path})
+        except Exception as exc:
+            failures.append(
+                {
+                    "adjunctUrl": adjunct_url,
+                    "announcementTitle": title,
+                    "error": str(exc),
+                }
             )
-
-        if not should_download:
-            continue
-
-        adjunct_url = i.get("adjunctUrl", "")
-        if not adjunct_url:
-            logger.warning("公告缺少 adjunctUrl，跳过：%s", title)
-            continue
-
-        download = download_path + adjunct_url
-        name = _sanitize_filename(
-            i.get("secCode", "") + "_" + i.get("secName", "") + "_" + title + ".pdf"
-        )
-        file_path = output_dir + name
-
-        logger.info("↓ %s", name)
-        os.makedirs(output_dir, exist_ok=True)
-
-        time.sleep(random.random() * 2)
-
-        r = requests.get(
-            download, headers={"User-Agent": random.choice(User_Agent)}, timeout=30
-        )
-        r.raise_for_status()
-        with open(file_path, "wb") as f:
-            f.write(r.content)
-        downloaded_count += 1
-
-    return downloaded_count
+            logger.warning("Download failed (%s): %s", title, exc)
+        finally:
+            if temporary_path is not None:
+                try:
+                    os.unlink(temporary_path)
+                except OSError as exc:
+                    logger.warning(
+                        "Could not remove temporary file %s: %s", temporary_path, exc
+                    )
+    result = {
+        "downloaded": len(files),
+        "files": files,
+        "failed": len(failures),
+        "failures": failures,
+    }
+    return result if details else len(files)
 
 
 def query_reports(stock_code, report_type="annual", year=None):
-    """查询指定股票和报告类型的公告列表。"""
+    """Return complete results or raise QueryError carrying partial reports."""
+    stock_code = normalize_stock_code(stock_code)
     normalized_type = normalize_report_type(report_type)
     all_announcements = []
-    requested_code = re.sub(r"\D", "", str(stock_code or ""))
-    allowed_sec_codes = {requested_code} if requested_code else set()
+    allowed_sec_codes = {stock_code}
+    errors = []
+    partial = False
 
     exchanges = [
         ("sse", "sh", "沪市"),
@@ -515,7 +658,12 @@ def query_reports(stock_code, report_type="annual", year=None):
                 page, stock_code, normalized_type, c, p
             )
             all_announcements.extend(_paginate(fetch_fn, stock_code))
+            partial = True
         except Exception as e:
+            errors.append(f"{label}: {e}")
+            if isinstance(e, QueryError):
+                all_announcements.extend(e.reports)
+                partial = partial or e.status == "partial"
             logger.warning(
                 "%s%s查询失败: %s",
                 label,
@@ -539,7 +687,14 @@ def query_reports(stock_code, report_type="annual", year=None):
                     stock_value=stock_value,
                 )
                 all_announcements.extend(_paginate(fetch_fn, stock_value))
+                partial = True
+            else:
+                raise ValueError(f"Could not resolve orgId for {stock_code}")
         except Exception as e:
+            errors.append(f"北交所: {e}")
+            if isinstance(e, QueryError):
+                all_announcements.extend(e.reports)
+                partial = partial or e.status == "partial"
             logger.warning(
                 "北交所%s查询失败: %s",
                 REPORT_TYPE_SPECS[normalized_type]["label"],
@@ -569,41 +724,43 @@ def query_reports(stock_code, report_type="annual", year=None):
             continue
         filtered.append(announcement)
 
+    if errors:
+        raise QueryError(errors, filtered, partial)
     return filtered
 
 
 def download_reports(stock_code, report_type="annual", year=None, save_path=None):
     """下载指定股票和报告类型的 PDF。"""
+    stock_code = normalize_stock_code(stock_code)
     normalized_type = normalize_report_type(report_type)
-    label = REPORT_TYPE_SPECS[normalized_type]["label"]
-    announcements = query_reports(stock_code, normalized_type, year)
-
-    if not announcements:
-        return {
-            "success": False,
-            "message": f"未找到股票 {stock_code} 的{label}"
-            + (f"（{year} 年）" if year else ""),
-            "downloaded": 0,
-        }
-
+    query_error = None
+    try:
+        announcements = query_reports(stock_code, normalized_type, year)
+    except QueryError as exc:
+        query_error = exc
+        announcements = exc.reports
     output_dir = save_path or saving_path
-    count = Download(
-        announcements,
-        report_type=normalized_type,
-        year_filter=year,
-        save_path=output_dir,
+    result = Download(announcements, normalized_type, year, output_dir, details=True)
+    status = "complete"
+    if query_error or result["failed"]:
+        status = (
+            "partial"
+            if result["downloaded"] or (query_error and query_error.status == "partial")
+            else "error"
+        )
+    result.update(
+        success=status == "complete",
+        status=status,
+        query_status=query_error.status if query_error else "complete",
+        path=output_dir,
+        message=f"Downloaded {result['downloaded']} file(s); {result['failed']} failed. Status: {status}.",
     )
-
-    downloaded = count or 0
-    year_suffix = f"（{year} 年）" if year else ""
-    return {
-        "success": downloaded > 0,
-        "message": f"已下载 {stock_code} {label}{year_suffix}，共 {downloaded} 个文件"
-        if downloaded > 0
-        else f"未下载任何文件（{stock_code} {label}{year_suffix}）",
-        "downloaded": downloaded,
-        "path": output_dir,
-    }
+    if query_error:
+        result["query_errors"] = query_error.errors
+        result["error"] = str(query_error)
+    elif result["failed"]:
+        result["error"] = f"{result['failed']} download(s) failed"
+    return result
 
 
 def query_annual_reports(stock_code, year=None):

package/scripts/install-python-deps.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 /**
- * npm install 后自动安装 Python 依赖
+ * 显式安装 Python 依赖：在用户目录创建 venv 并执行 pip install。
+ * 只由 `cninfo-mcp install` 触发；npm install 和服务器启动都不会运行它。
  */
 
 const { spawn } = require("child_process");
@@ -16,7 +17,7 @@ const REQUIREMENTS_FILE = path.join(
   "requirements.txt",
 );
 
-const VENV_DIR = path.join(os.homedir(), ".cninfo-mcp", "venv");
+let VENV_DIR = path.join(os.homedir(), ".cninfo-mcp", "venv");
 
 // 依赖探针：校验 venv 是否满足 requirements.txt 的全部约束
 const DEPS_CHECK = path.join(__dirname, "..", "python", "check_deps.py");
@@ -28,6 +29,26 @@ function getVenvPython() {
   return path.join(VENV_DIR, "bin", "python3");
 }
 
+async function isSupportedPython(cmd) {
+  try {
+    const result = await spawnCommand(cmd, ["--version"]);
+    const version = `${result.stdout || ""} ${result.stderr || ""}`.match(/\bPython (\d+)\.(\d+)\.(\d+)\b/);
+    return Boolean(version && Number(version[1]) === 3 && Number(version[2]) >= 10);
+  } catch {
+    return false;
+  }
+}
+
+// Preserve an obsolete environment and create a compatible sibling if needed.
+async function reusableVenv() {
+  if (!fs.existsSync(getVenvPython())) return null;
+  if (await isSupportedPython(getVenvPython())) return getVenvPython();
+  VENV_DIR += "-py310";
+  if (!fs.existsSync(getVenvPython())) return null;
+  if (await isSupportedPython(getVenvPython())) return getVenvPython();
+  throw new Error(`Unsupported or broken Python environment at ${VENV_DIR}. Recreate it with Python 3.10+.`);
+}
+
 async function findPython() {
   const pythonCommands = [
     "python3",
@@ -38,22 +59,18 @@ async function findPython() {
   ];
 
   for (const cmd of pythonCommands) {
-    try {
-      const result = await spawnCommand(cmd, ["--version"]);
-      if (result.stdout && result.stdout.includes("Python")) {
-        return cmd;
-      }
-    } catch (error) {}
+    if (await isSupportedPython(cmd)) return cmd;
   }
 
   return null;
 }
 
-function spawnCommand(cmd, args) {
+function spawnCommand(cmd, args, options = {}) {
   return new Promise((resolve, reject) => {
     const child = spawn(cmd, args, {
       stdio: "pipe",
-      shell: process.platform === "win32",
+      ...options,
+      shell: false,
     });
     let stdout = "";
     let stderr = "";
@@ -71,36 +88,23 @@ function spawnCommand(cmd, args) {
 }
 
 async function main() {
-  // requirements.txt 不存在则跳过
   if (!fs.existsSync(REQUIREMENTS_FILE)) {
-    console.log(
-      "⚠️  requirements.txt not found, skipping Python dependencies installation",
-    );
-    return;
+    throw new Error(`requirements.txt not found at ${REQUIREMENTS_FILE}`);
   }
 
-  const pythonCmd = await findPython();
-  if (!pythonCmd) {
-    console.warn(
-      "⚠️  Python not found. Python dependencies will be installed on first run.",
-    );
-    console.warn("   Please install Python 3.10+ from https://python.org");
-    return;
-  }
-
-  // 创建虚拟环境（如果不存在）
-  const venvPython = getVenvPython();
-  if (!fs.existsSync(venvPython)) {
-    console.log("Creating Python virtual environment...");
-    try {
-      fs.mkdirSync(path.dirname(VENV_DIR), { recursive: true });
-      await spawnCommand(pythonCmd, ["-m", "venv", VENV_DIR]);
-      console.log("Virtual environment created");
-    } catch (venvError) {
-      console.warn("  Failed to create virtual environment during npm install");
-      console.warn("  It will be created automatically on first run");
-      return;
+  let venvPython = await reusableVenv();
+  if (!venvPython) {
+    const pythonCmd = await findPython();
+    if (!pythonCmd) {
+      throw new Error(
+        "Python 3.10+ not found. Install it from https://python.org, then run this command again.",
+      );
     }
+    venvPython = getVenvPython();
+    console.log(`Creating Python virtual environment at ${VENV_DIR}...`);
+    fs.mkdirSync(path.dirname(VENV_DIR), { recursive: true });
+    await spawnCommand(pythonCmd, ["-m", "venv", VENV_DIR]);
+    console.log("Virtual environment created");
   }
 
   try {
@@ -110,22 +114,18 @@ async function main() {
   } catch (error) {
     // 执行安装（用 venv 的 pip）
     console.log("📦 Installing Python dependencies...");
-    try {
-      await spawnCommand(
-        venvPython,
-        ["-m", "pip", "install", "-r", REQUIREMENTS_FILE],
-        {
-          stdio: "inherit",
-        },
-      );
-      console.log("✅ Python dependencies installed successfully");
-    } catch (installError) {
-      console.warn(
-        "⚠️  Failed to install Python dependencies during npm install",
-      );
-      console.warn("   They will be installed automatically on first run");
-    }
+    await spawnCommand(
+      venvPython,
+      ["-m", "pip", "install", "-r", REQUIREMENTS_FILE],
+      {
+        stdio: "inherit",
+      },
+    );
+    console.log("✅ Python dependencies installed successfully");
   }
 }
 
-main().catch(console.error);
+main().catch((error) => {
+  console.error(`❌ ${error.message}`);
+  process.exit(1);
+});