@youhaozhao/cninfo-mcp 1.2.0 → 1.3.0

package/README.md

@@ -1,54 +1,64 @@
-# 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。
+
+## 使用方法
+
+在 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 依赖会自动安装）
+
+## 数据来源
+
+[巨潮资讯网](https://www.cninfo.com.cn) — 支持沪深两市（主板、创业板、科创板）及北京证券交易所（北交所）
+
+## Credits
+
+爬虫逻辑基于 [gaodechen/cninfo_process](https://github.com/gaodechen/cninfo_process)。

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.3.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"

package/python/mcp_server.py

@@ -1,268 +1,193 @@
-#!/usr/bin/env python3
-"""
-巨潮资讯 MCP 服务器
-用于查询和下载 A 股年度报告的 MCP 工具服务
-"""
-
-import os
-import sys
-from typing import Optional
-
-# 将当前目录加入模块搜索路径
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-
-from mcp.server import FastMCP
-from spider import (
-    query_annual_reports,
-    download_annual_reports,
-    query_prospectus,
-    download_prospectus,
-    saving_path,
-)
-
-# 创建 MCP 服务器实例
-mcp = FastMCP(
-    name="cninfo-server",
-    instructions="CNINFO annual reports server - Query and download Chinese listed companies' annual reports from cninfo.com.cn",
-)
-
-
-@mcp.tool()
-def query_annual_reports_tool(stock_code: str, year: Optional[int] = None) -> dict:
-    """
-    Query annual reports for a Chinese listed company
-
-    Args:
-        stock_code: Stock code (e.g., '000888' for峨眉山, '688777' for 中科德芯)
-        year: Optional year to filter (e.g., 2024). If not provided, returns all available years
-
-    Returns:
-        Dictionary containing:
-        - success: Boolean indicating if the query was successful
-        - stock_code: The queried stock code
-        - year: The filtered year (if any)
-        - count: Number of reports found
-        - reports: List of report details (announcementTitle, announcementTime, secCode, secName)
-    """
-    try:
-        reports = query_annual_reports(stock_code, year)
-
-        if not reports:
-            return {
-                "success": False,
-                "stock_code": stock_code,
-                "year": year,
-                "count": 0,
-                "reports": [],
-                "message": f"No annual reports found for stock {stock_code}"
-                + (f" in year {year}" if year else ""),
-            }
-
-        # 提取关键字段
-        base_url = "https://static.cninfo.com.cn/"
-        report_details = []
-        for report in reports:
-            adj = report.get("adjunctUrl", "")
-            report_details.append(
-                {
-                    "announcementTitle": report.get("announcementTitle", ""),
-                    "announcementTime": report.get("announcementTime", ""),
-                    "secCode": report.get("secCode", ""),
-                    "secName": report.get("secName", ""),
-                    "adjunctUrl": base_url + adj if adj else "",
-                }
-            )
-
-        return {
-            "success": True,
-            "stock_code": stock_code,
-            "year": year,
-            "count": len(reports),
-            "reports": report_details,
-            "message": f"Found {len(reports)} annual report(s)"
-            + (f" for year {year}" if year else ""),
-        }
-
-    except Exception as e:
-        return {
-            "success": False,
-            "stock_code": stock_code,
-            "year": year,
-            "count": 0,
-            "reports": [],
-            "error": str(e),
-            "message": f"Error querying annual reports: {str(e)}",
-        }
-
-
-@mcp.tool()
-def download_annual_reports_tool(
-    stock_code: str, year: Optional[int] = None, save_path: Optional[str] = None
-) -> dict:
-    """
-    Download annual reports for a Chinese listed company
-
-    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
-
-    Returns:
-        Dictionary containing:
-        - success: Boolean indicating if download was successful
-        - stock_code: The stock code
-        - year: The filtered year (if any)
-        - downloaded: Number of files downloaded
-        - path: Directory where files were saved
-        - message: Status message
-    """
-    try:
-        output_dir = save_path or saving_path
-        os.makedirs(output_dir, exist_ok=True)
-
-        result = download_annual_reports(stock_code, year, save_path=output_dir)
-        result["stock_code"] = stock_code
-        result["year"] = year
-
-        return result
-
-    except Exception as e:
-        return {
-            "success": False,
-            "stock_code": stock_code,
-            "year": year,
-            "downloaded": 0,
-            "path": save_path or saving_path,
-            "error": str(e),
-            "message": f"Error downloading annual reports: {str(e)}",
-        }
-
-
-@mcp.tool()
-def query_prospectus_tool(stock_code: str) -> dict:
-    """
-    Query prospectus documents for a Chinese listed company
-
-    Args:
-        stock_code: Stock code (e.g., '000888' for 峨眉山, '688777' for 中科德芯)
-
-    Returns:
-        Dictionary containing:
-        - success: Boolean indicating if the query was successful
-        - stock_code: The queried stock code
-        - count: Number of documents found
-        - reports: List of document details (announcementTitle, announcementTime, secCode, secName)
-    """
-    try:
-        reports = query_prospectus(stock_code)
-
-        if not reports:
-            return {
-                "success": False,
-                "stock_code": stock_code,
-                "count": 0,
-                "reports": [],
-                "message": f"No prospectus found for stock {stock_code}",
-            }
-
-        base_url = "https://static.cninfo.com.cn/"
-        report_details = [
-            {
-                "announcementTitle": r.get("announcementTitle", ""),
-                "announcementTime": r.get("announcementTime", ""),
-                "secCode": r.get("secCode", ""),
-                "secName": r.get("secName", ""),
-                "adjunctUrl": base_url + r.get("adjunctUrl", "")
-                if r.get("adjunctUrl")
-                else "",
-            }
-            for r in reports
-        ]
-
-        return {
-            "success": True,
-            "stock_code": stock_code,
-            "count": len(reports),
-            "reports": report_details,
-            "message": f"Found {len(reports)} prospectus document(s)",
-        }
-
-    except Exception as e:
-        return {
-            "success": False,
-            "stock_code": stock_code,
-            "count": 0,
-            "reports": [],
-            "error": str(e),
-            "message": f"Error querying prospectus: {str(e)}",
-        }
-
-
-@mcp.tool()
-def download_prospectus_tool(stock_code: str, save_path: Optional[str] = None) -> dict:
-    """
-    Download prospectus documents for a Chinese listed company
-
-    Args:
-        stock_code: Stock code (e.g., '000888' for 峨眉山, '688777' for 中科德芯)
-        save_path: Optional directory to save files (e.g., '/Users/me/reports'). Defaults to pdf/ in package directory
-
-    Returns:
-        Dictionary containing:
-        - success: Boolean indicating if download was successful
-        - stock_code: The stock code
-        - downloaded: Number of files downloaded
-        - path: Directory where files were saved
-        - message: Status message
-    """
-    try:
-        output_dir = save_path or saving_path
-        os.makedirs(output_dir, exist_ok=True)
-
-        result = download_prospectus(stock_code, save_path=output_dir)
-        result["stock_code"] = stock_code
-
-        return result
-
-    except Exception as e:
-        return {
-            "success": False,
-            "stock_code": stock_code,
-            "downloaded": 0,
-            "path": save_path or saving_path,
-            "error": str(e),
-            "message": f"Error downloading prospectus: {str(e)}",
-        }
-
-
-@mcp.resource("annual-reports-list://{stock_code}")
-def get_annual_reports_list(stock_code: str) -> str:
-    """返回指定股票代码的年度报告格式化列表"""
-    try:
-        reports = query_annual_reports(stock_code)
-
-        if not reports:
-            return f"No annual reports found for stock {stock_code}"
-
-        output = [f"Annual Reports for {stock_code}:", "=" * 60]
-
-        for report in reports:
-            title = report.get("announcementTitle", "N/A")
-            time = report.get("announcementTime", "N/A")
-            name = report.get("secName", "N/A")
-            output.append(f"\n📄 {title}")
-            output.append(f"   Company: {name}")
-            output.append(f"   Date: {time}")
-
-        output.append("\n" + "=" * 60)
-        output.append(f"Total: {len(reports)} report(s)")
-
-        return "\n".join(output)
-
-    except Exception as e:
-        return f"Error retrieving annual reports: {str(e)}"
-
-
-if __name__ == "__main__":
-    # 以 stdio 方式运行服务器
-    mcp.run()
+#!/usr/bin/env python3
+"""
+巨潮资讯 MCP 服务器
+用于查询和下载 A 股定期报告、招股书的 MCP 工具服务
+"""
+
+import os
+import sys
+from typing import Optional
+
+# 将当前目录加入模块搜索路径
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from mcp.server import FastMCP
+from spider import (
+    query_reports,
+    download_reports,
+    saving_path,
+    supported_report_types,
+)
+
+# 创建 MCP 服务器实例
+mcp = FastMCP(
+    name="cninfo-server",
+    instructions="CNINFO reports server - Query and download Chinese listed companies' periodic reports from cninfo.com.cn",
+)
+
+
+def _format_reports(reports: list) -> list:
+    """提取 MCP 返回中稳定、有用的公告字段。"""
+    base_url = "https://static.cninfo.com.cn/"
+    report_details = []
+    for report in reports:
+        adj = report.get("adjunctUrl", "")
+        report_details.append(
+            {
+                "announcementTitle": report.get("announcementTitle", ""),
+                "announcementTime": report.get("announcementTime", ""),
+                "secCode": report.get("secCode", ""),
+                "secName": report.get("secName", ""),
+                "adjunctUrl": base_url + adj if adj else "",
+            }
+        )
+    return report_details
+
+
+def _supported_report_types_text() -> str:
+    return ", ".join(supported_report_types().keys())
+
+
+@mcp.tool()
+def query_annual_reports_tool(
+    stock_code: str, year: Optional[int] = None, report_type: str = "annual"
+) -> dict:
+    """
+    Query periodic reports for a Chinese listed company.
+
+    Args:
+        stock_code: Stock code (e.g., '000888' for 峨眉山, '688777' for 中科德芯)
+        year: Optional year to filter (e.g., 2024). If not provided, returns all available years
+        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 the query was successful
+        - stock_code: The queried stock code
+        - report_type: The requested report type
+        - year: The filtered year (if any)
+        - count: Number of reports found
+        - reports: List of report details (announcementTitle, announcementTime, secCode, secName, adjunctUrl)
+    """
+    try:
+        reports = query_reports(stock_code, report_type, year)
+
+        if not reports:
+            return {
+                "success": False,
+                "stock_code": stock_code,
+                "report_type": report_type,
+                "year": year,
+                "count": 0,
+                "reports": [],
+                "message": f"No {report_type} reports found for stock {stock_code}"
+                + (f" in year {year}" if year else ""),
+            }
+
+        return {
+            "success": True,
+            "stock_code": stock_code,
+            "report_type": report_type,
+            "year": year,
+            "count": len(reports),
+            "reports": _format_reports(reports),
+            "message": f"Found {len(reports)} {report_type} report(s)"
+            + (f" for year {year}" if year else ""),
+        }
+
+    except Exception as e:
+        return {
+            "success": False,
+            "stock_code": stock_code,
+            "report_type": report_type,
+            "year": year,
+            "count": 0,
+            "reports": [],
+            "error": str(e),
+            "message": f"Error querying reports: {str(e)}. Supported report_type values: {_supported_report_types_text()}",
+        }
+
+
+@mcp.tool()
+def download_annual_reports_tool(
+    stock_code: str,
+    year: Optional[int] = None,
+    save_path: Optional[str] = None,
+    report_type: str = "annual",
+) -> dict:
+    """
+    Download periodic reports for a Chinese listed company.
+
+    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
+        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
+        - stock_code: The stock code
+        - report_type: The requested report type
+        - year: The filtered year (if any)
+        - downloaded: Number of files downloaded
+        - path: Directory where files were saved
+        - message: Status message
+    """
+    try:
+        output_dir = save_path or saving_path
+        os.makedirs(output_dir, exist_ok=True)
+
+        result = download_reports(
+            stock_code, report_type, year=year, save_path=output_dir
+        )
+        result["stock_code"] = stock_code
+        result["report_type"] = report_type
+        result["year"] = year
+
+        return result
+
+    except Exception as e:
+        return {
+            "success": False,
+            "stock_code": stock_code,
+            "report_type": report_type,
+            "year": year,
+            "downloaded": 0,
+            "path": save_path or saving_path,
+            "error": str(e),
+            "message": f"Error downloading reports: {str(e)}. Supported report_type values: {_supported_report_types_text()}",
+        }
+
+
+@mcp.resource("annual-reports-list://{stock_code}")
+def get_annual_reports_list(stock_code: str) -> str:
+    """返回指定股票代码的年度报告格式化列表"""
+    try:
+        reports = query_reports(stock_code, "annual")
+
+        if not reports:
+            return f"No annual reports found for stock {stock_code}"
+
+        output = [f"Annual Reports for {stock_code}:", "=" * 60]
+
+        for report in reports:
+            title = report.get("announcementTitle", "N/A")
+            time = report.get("announcementTime", "N/A")
+            name = report.get("secName", "N/A")
+            output.append(f"\n📄 {title}")
+            output.append(f"   Company: {name}")
+            output.append(f"   Date: {time}")
+
+        output.append("\n" + "=" * 60)
+        output.append(f"Total: {len(reports)} report(s)")
+
+        return "\n".join(output)
+
+    except Exception as e:
+        return f"Error retrieving annual reports: {str(e)}"
+
+
+if __name__ == "__main__":
+    # 以 stdio 方式运行服务器
+    mcp.run()