mseep-a-share-mcp 0.1.1__py3-none-any.whl

tools/date_utils.py

@@ -0,0 +1,180 @@
+"""
+Date utility tools for MCP server.
+Contains tools for retrieving current date and latest trading date.
+"""
+import logging
+from datetime import datetime, timedelta
+import calendar
+
+from mcp.server.fastmcp import FastMCP
+from src.data_source_interface import FinancialDataSource
+
+logger = logging.getLogger(__name__)
+
+
+def register_date_utils_tools(app: FastMCP, active_data_source: FinancialDataSource):
+    """
+    Register date utility tools with the MCP app.
+
+    Args:
+        app: The FastMCP app instance
+        active_data_source: The active financial data source
+    """
+
+    # @app.tool()
+    # def get_current_date() -> str:
+    #     """
+    #     获取当前日期，可用于查询最新数据。
+
+    #     Returns:
+    #         当前日期，格式为'YYYY-MM-DD'。
+    #     """
+    #     logger.info("Tool 'get_current_date' called")
+    #     current_date = datetime.now().strftime("%Y-%m-%d")
+    #     logger.info(f"Returning current date: {current_date}")
+    #     return current_date
+
+    @app.tool()
+    def get_latest_trading_date() -> str:
+        """
+        获取最近的交易日期。如果当天是交易日，则返回当天日期；否则返回最近的交易日。
+
+        Returns:
+            最近的交易日期，格式为'YYYY-MM-DD'。
+        """
+        logger.info("Tool 'get_latest_trading_date' called")
+        try:
+            today = datetime.now().strftime("%Y-%m-%d")
+            # 获取当前日期前后一周的交易日历
+            start_date = (datetime.now().replace(day=1)).strftime("%Y-%m-%d")
+            end_date = (datetime.now().replace(day=28)).strftime("%Y-%m-%d")
+
+            df = active_data_source.get_trade_dates(
+                start_date=start_date, end_date=end_date)
+
+            # 筛选出最近的交易日
+            valid_trading_days = df[df['is_trading_day']
+                                    == '1']['calendar_date'].tolist()
+
+            # 找出小于等于今天的最大日期
+            latest_trading_date = None
+            for date in valid_trading_days:
+                if date <= today and (latest_trading_date is None or date > latest_trading_date):
+                    latest_trading_date = date
+
+            if latest_trading_date:
+                logger.info(
+                    f"Latest trading date found: {latest_trading_date}")
+                return latest_trading_date
+            else:
+                logger.warning(
+                    "No trading dates found before today, returning today's date")
+                return today
+
+        except Exception as e:
+            logger.exception(f"Error determining latest trading date: {e}")
+            return datetime.now().strftime("%Y-%m-%d")
+
+    @app.tool()
+    def get_market_analysis_timeframe(period: str = "recent") -> str:
+        """
+        获取适合市场分析的时间范围，基于当前真实日期而不是训练数据。
+        这个工具应该在进行市场分析或大盘分析时首先调用，以确保使用最新的实际数据。
+
+        Args:
+            period: 时间范围类型，可选值:
+                   "recent": 最近1-2个月(默认)
+                   "quarter": 最近一个季度
+                   "half_year": 最近半年
+                   "year": 最近一年
+
+        Returns:
+            包含分析时间范围的详细描述字符串，格式为"YYYY年M月-YYYY年M月"。
+        """
+        logger.info(
+            f"Tool 'get_market_analysis_timeframe' called with period={period}")
+
+        now = datetime.now()
+        end_date = now
+
+        # 根据请求的时间段确定开始日期
+        if period == "recent":
+            # 最近1-2个月
+            if now.day < 15:
+                # 如果当前是月初，看前两个月
+                if now.month == 1:
+                    start_date = datetime(now.year - 1, 11, 1)  # 前年11月
+                    middle_date = datetime(now.year - 1, 12, 1)  # 前年12月
+                elif now.month == 2:
+                    start_date = datetime(now.year, 1, 1)  # 今年1月
+                    middle_date = start_date
+                else:
+                    start_date = datetime(now.year, now.month - 2, 1)  # 两个月前
+                    middle_date = datetime(now.year, now.month - 1, 1)  # 上个月
+            else:
+                # 如果当前是月中或月末，看前一个月到现在
+                if now.month == 1:
+                    start_date = datetime(now.year - 1, 12, 1)  # 前年12月
+                    middle_date = start_date
+                else:
+                    start_date = datetime(now.year, now.month - 1, 1)  # 上个月
+                    middle_date = start_date
+
+        elif period == "quarter":
+            # 最近一个季度 (约3个月)
+            if now.month <= 3:
+                start_date = datetime(now.year - 1, now.month + 9, 1)
+            else:
+                start_date = datetime(now.year, now.month - 3, 1)
+            middle_date = start_date
+
+        elif period == "half_year":
+            # 最近半年
+            if now.month <= 6:
+                start_date = datetime(now.year - 1, now.month + 6, 1)
+            else:
+                start_date = datetime(now.year, now.month - 6, 1)
+            middle_date = datetime(start_date.year, start_date.month + 3, 1) if start_date.month <= 9 else \
+                datetime(start_date.year + 1, start_date.month - 9, 1)
+
+        elif period == "year":
+            # 最近一年
+            start_date = datetime(now.year - 1, now.month, 1)
+            middle_date = datetime(start_date.year, start_date.month + 6, 1) if start_date.month <= 6 else \
+                datetime(start_date.year + 1, start_date.month - 6, 1)
+        else:
+            # 默认为最近1个月
+            if now.month == 1:
+                start_date = datetime(now.year - 1, 12, 1)
+            else:
+                start_date = datetime(now.year, now.month - 1, 1)
+            middle_date = start_date
+
+        # 格式化为用户友好的显示
+        def get_month_end_day(year, month):
+            return calendar.monthrange(year, month)[1]
+
+        # 确保结束日期不超过当前日期
+        end_day = min(get_month_end_day(
+            end_date.year, end_date.month), end_date.day)
+        end_display_date = f"{end_date.year}年{end_date.month}月"
+        end_iso_date = f"{end_date.year}-{end_date.month:02d}-{end_day:02d}"
+
+        # 开始日期显示
+        start_display_date = f"{start_date.year}年{start_date.month}月"
+        start_iso_date = f"{start_date.year}-{start_date.month:02d}-01"
+
+        # 如果跨年或时间段较长，添加年份显示
+        if start_date.year != end_date.year:
+            date_range = f"{start_date.year}年{start_date.month}月-{end_date.year}年{end_date.month}月"
+        elif middle_date.month != start_date.month and middle_date.month != end_date.month:
+            # 如果是季度或半年，显示中间月份
+            date_range = f"{start_date.year}年{start_date.month}月-{middle_date.month}月-{end_date.month}月"
+        elif start_date.month != end_date.month:
+            date_range = f"{start_date.year}年{start_date.month}月-{end_date.month}月"
+        else:
+            date_range = f"{start_date.year}年{start_date.month}月"
+
+        result = f"{date_range} (ISO日期范围: {start_iso_date} 至 {end_iso_date})"
+        logger.info(f"Generated market analysis timeframe: {result}")
+        return result

tools/financial_reports.py

@@ -0,0 +1,201 @@
+"""
+Financial report related tools for MCP server.
+"""
+import logging
+from typing import List, Optional
+
+from mcp.server.fastmcp import FastMCP
+from src.data_source_interface import FinancialDataSource
+from src.tools.base import call_financial_data_tool
+
+logger = logging.getLogger(__name__)
+
+
+def register_financial_report_tools(app: FastMCP, active_data_source: FinancialDataSource):
+    """
+    Register financial report related tools with the MCP app.
+
+    Args:
+        app: The FastMCP app instance
+        active_data_source: The active financial data source
+    """
+
+    @app.tool()
+    def get_profit_data(code: str, year: str, quarter: int) -> str:
+        """
+        Fetches quarterly profitability data (e.g., ROE, net profit margin) for a stock.
+
+        Args:
+            code: The stock code (e.g., 'sh.600000').
+            year: The 4-digit year (e.g., '2023').
+            quarter: The quarter (1, 2, 3, or 4).
+
+        Returns:
+            Markdown table with profitability data or an error message.
+        """
+        return call_financial_data_tool(
+            "get_profit_data",
+            active_data_source.get_profit_data,
+            "Profitability",
+            code, year, quarter
+        )
+
+    @app.tool()
+    def get_operation_data(code: str, year: str, quarter: int) -> str:
+        """
+        Fetches quarterly operation capability data (e.g., turnover ratios) for a stock.
+
+        Args:
+            code: The stock code (e.g., 'sh.600000').
+            year: The 4-digit year (e.g., '2023').
+            quarter: The quarter (1, 2, 3, or 4).
+
+        Returns:
+            Markdown table with operation capability data or an error message.
+        """
+        return call_financial_data_tool(
+            "get_operation_data",
+            active_data_source.get_operation_data,
+            "Operation Capability",
+            code, year, quarter
+        )
+
+    @app.tool()
+    def get_growth_data(code: str, year: str, quarter: int) -> str:
+        """
+        Fetches quarterly growth capability data (e.g., YOY growth rates) for a stock.
+
+        Args:
+            code: The stock code (e.g., 'sh.600000').
+            year: The 4-digit year (e.g., '2023').
+            quarter: The quarter (1, 2, 3, or 4).
+
+        Returns:
+            Markdown table with growth capability data or an error message.
+        """
+        return call_financial_data_tool(
+            "get_growth_data",
+            active_data_source.get_growth_data,
+            "Growth Capability",
+            code, year, quarter
+        )
+
+    @app.tool()
+    def get_balance_data(code: str, year: str, quarter: int) -> str:
+        """
+        Fetches quarterly balance sheet / solvency data (e.g., current ratio, debt ratio) for a stock.
+
+        Args:
+            code: The stock code (e.g., 'sh.600000').
+            year: The 4-digit year (e.g., '2023').
+            quarter: The quarter (1, 2, 3, or 4).
+
+        Returns:
+            Markdown table with balance sheet data or an error message.
+        """
+        return call_financial_data_tool(
+            "get_balance_data",
+            active_data_source.get_balance_data,
+            "Balance Sheet",
+            code, year, quarter
+        )
+
+    @app.tool()
+    def get_cash_flow_data(code: str, year: str, quarter: int) -> str:
+        """
+        Fetches quarterly cash flow data (e.g., CFO/Operating Revenue ratio) for a stock.
+
+        Args:
+            code: The stock code (e.g., 'sh.600000').
+            year: The 4-digit year (e.g., '2023').
+            quarter: The quarter (1, 2, 3, or 4).
+
+        Returns:
+            Markdown table with cash flow data or an error message.
+        """
+        return call_financial_data_tool(
+            "get_cash_flow_data",
+            active_data_source.get_cash_flow_data,
+            "Cash Flow",
+            code, year, quarter
+        )
+
+    @app.tool()
+    def get_dupont_data(code: str, year: str, quarter: int) -> str:
+        """
+        Fetches quarterly DuPont analysis data (ROE decomposition) for a stock.
+
+        Args:
+            code: The stock code (e.g., 'sh.600000').
+            year: The 4-digit year (e.g., '2023').
+            quarter: The quarter (1, 2, 3, or 4).
+
+        Returns:
+            Markdown table with DuPont analysis data or an error message.
+        """
+        return call_financial_data_tool(
+            "get_dupont_data",
+            active_data_source.get_dupont_data,
+            "DuPont Analysis",
+            code, year, quarter
+        )
+
+    @app.tool()
+    def get_performance_express_report(code: str, start_date: str, end_date: str) -> str:
+        """
+        Fetches performance express reports (业绩快报) for a stock within a date range.
+        Note: Companies are not required to publish these except in specific cases.
+
+        Args:
+            code: The stock code (e.g., 'sh.600000').
+            start_date: Start date (for report publication/update) in 'YYYY-MM-DD' format.
+            end_date: End date (for report publication/update) in 'YYYY-MM-DD' format.
+
+        Returns:
+            Markdown table with performance express report data or an error message.
+        """
+        logger.info(
+            f"Tool 'get_performance_express_report' called for {code} ({start_date} to {end_date})")
+        try:
+            # Add date validation if desired
+            df = active_data_source.get_performance_express_report(
+                code=code, start_date=start_date, end_date=end_date)
+            logger.info(
+                f"Successfully retrieved performance express reports for {code}.")
+            from src.formatting.markdown_formatter import format_df_to_markdown
+            return format_df_to_markdown(df)
+
+        except Exception as e:
+            logger.exception(
+                f"Exception processing get_performance_express_report for {code}: {e}")
+            return f"Error: An unexpected error occurred: {e}"
+
+    @app.tool()
+    def get_forecast_report(code: str, start_date: str, end_date: str) -> str:
+        """
+        Fetches performance forecast reports (业绩预告) for a stock within a date range.
+        Note: Companies are not required to publish these except in specific cases.
+
+        Args:
+            code: The stock code (e.g., 'sh.600000').
+            start_date: Start date (for report publication/update) in 'YYYY-MM-DD' format.
+            end_date: End date (for report publication/update) in 'YYYY-MM-DD' format.
+
+        Returns:
+            Markdown table with performance forecast report data or an error message.
+        """
+        logger.info(
+            f"Tool 'get_forecast_report' called for {code} ({start_date} to {end_date})")
+        try:
+            # Add date validation if desired
+            df = active_data_source.get_forecast_report(
+                code=code, start_date=start_date, end_date=end_date)
+            logger.info(
+                f"Successfully retrieved performance forecast reports for {code}.")
+            from src.formatting.markdown_formatter import format_df_to_markdown
+            return format_df_to_markdown(df)
+
+        except Exception as e:
+            logger.exception(
+                f"Exception processing get_forecast_report for {code}: {e}")
+            return f"Error: An unexpected error occurred: {e}"

tools/indices.py

@@ -0,0 +1,103 @@
+"""
+Index related tools for MCP server.
+Contains tools for fetching index constituent stocks.
+"""
+import logging
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+from src.data_source_interface import FinancialDataSource
+from src.tools.base import call_index_constituent_tool
+
+logger = logging.getLogger(__name__)
+
+
+def register_index_tools(app: FastMCP, active_data_source: FinancialDataSource):
+    """
+    Register index related tools with the MCP app.
+
+    Args:
+        app: The FastMCP app instance
+        active_data_source: The active financial data source
+    """
+
+    @app.tool()
+    def get_stock_industry(code: Optional[str] = None, date: Optional[str] = None) -> str:
+        """
+        Fetches industry classification for a specific stock or all stocks on a given date.
+
+        Args:
+            code: Optional. The stock code (e.g., 'sh.600000'). If None, fetches for all stocks.
+            date: Optional. The date in 'YYYY-MM-DD' format. If None, uses the latest available date.
+
+        Returns:
+            Markdown table with industry classification data or an error message.
+        """
+        log_msg = f"Tool 'get_stock_industry' called for code={code or 'all'}, date={date or 'latest'}"
+        logger.info(log_msg)
+        try:
+            # Add date validation if desired
+            df = active_data_source.get_stock_industry(code=code, date=date)
+            logger.info(
+                f"Successfully retrieved industry data for {code or 'all'}, {date or 'latest'}.")
+            from src.formatting.markdown_formatter import format_df_to_markdown
+            return format_df_to_markdown(df)
+
+        except Exception as e:
+            logger.exception(
+                f"Exception processing get_stock_industry: {e}")
+            return f"Error: An unexpected error occurred: {e}"
+
+    @app.tool()
+    def get_sz50_stocks(date: Optional[str] = None) -> str:
+        """
+        Fetches the constituent stocks of the SZSE 50 Index for a given date.
+
+        Args:
+            date: Optional. The date in 'YYYY-MM-DD' format. If None, uses the latest available date.
+
+        Returns:
+            Markdown table with SZSE 50 constituent stocks or an error message.
+        """
+        return call_index_constituent_tool(
+            "get_sz50_stocks",
+            active_data_source.get_sz50_stocks,
+            "SZSE 50",
+            date
+        )
+
+    @app.tool()
+    def get_hs300_stocks(date: Optional[str] = None) -> str:
+        """
+        Fetches the constituent stocks of the CSI 300 Index for a given date.
+
+        Args:
+            date: Optional. The date in 'YYYY-MM-DD' format. If None, uses the latest available date.
+
+        Returns:
+            Markdown table with CSI 300 constituent stocks or an error message.
+        """
+        return call_index_constituent_tool(
+            "get_hs300_stocks",
+            active_data_source.get_hs300_stocks,
+            "CSI 300",
+            date
+        )
+
+    @app.tool()
+    def get_zz500_stocks(date: Optional[str] = None) -> str:
+        """
+        Fetches the constituent stocks of the CSI 500 Index for a given date.
+
+        Args:
+            date: Optional. The date in 'YYYY-MM-DD' format. If None, uses the latest available date.
+
+        Returns:
+            Markdown table with CSI 500 constituent stocks or an error message.
+        """
+        return call_index_constituent_tool(
+            "get_zz500_stocks",
+            active_data_source.get_zz500_stocks,
+            "CSI 500",
+            date
+        )

tools/macroeconomic.py

@@ -0,0 +1,146 @@
+"""
+Macroeconomic data tools for MCP server.
+Contains tools for fetching interest rates, money supply data, and more.
+"""
+import logging
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+from src.data_source_interface import FinancialDataSource
+from src.tools.base import call_macro_data_tool
+
+logger = logging.getLogger(__name__)
+
+
+def register_macroeconomic_tools(app: FastMCP, active_data_source: FinancialDataSource):
+    """
+    Register macroeconomic data tools with the MCP app.
+
+    Args:
+        app: The FastMCP app instance
+        active_data_source: The active financial data source
+    """
+
+    @app.tool()
+    def get_deposit_rate_data(start_date: Optional[str] = None, end_date: Optional[str] = None) -> str:
+        """
+        Fetches benchmark deposit rates (活期, 定期) within a date range.
+
+        Args:
+            start_date: Optional. Start date in 'YYYY-MM-DD' format.
+            end_date: Optional. End date in 'YYYY-MM-DD' format.
+
+        Returns:
+            Markdown table with deposit rate data or an error message.
+        """
+        return call_macro_data_tool(
+            "get_deposit_rate_data",
+            active_data_source.get_deposit_rate_data,
+            "Deposit Rate",
+            start_date, end_date
+        )
+
+    @app.tool()
+    def get_loan_rate_data(start_date: Optional[str] = None, end_date: Optional[str] = None) -> str:
+        """
+        Fetches benchmark loan rates (贷款利率) within a date range.
+
+        Args:
+            start_date: Optional. Start date in 'YYYY-MM-DD' format.
+            end_date: Optional. End date in 'YYYY-MM-DD' format.
+
+        Returns:
+            Markdown table with loan rate data or an error message.
+        """
+        return call_macro_data_tool(
+            "get_loan_rate_data",
+            active_data_source.get_loan_rate_data,
+            "Loan Rate",
+            start_date, end_date
+        )
+
+    @app.tool()
+    def get_required_reserve_ratio_data(start_date: Optional[str] = None, end_date: Optional[str] = None, year_type: str = '0') -> str:
+        """
+        Fetches required reserve ratio data (存款准备金率) within a date range.
+
+        Args:
+            start_date: Optional. Start date in 'YYYY-MM-DD' format.
+            end_date: Optional. End date in 'YYYY-MM-DD' format.
+            year_type: Optional. Year type for date filtering. '0' for announcement date (公告日期, default),
+                    '1' for effective date (生效日期).
+
+        Returns:
+            Markdown table with required reserve ratio data or an error message.
+        """
+        # Basic validation for year_type
+        if year_type not in ['0', '1']:
+            logger.warning(f"Invalid year_type requested: {year_type}")
+            return "Error: Invalid year_type '{year_type}'. Valid options are '0' (announcement date) or '1' (effective date)."
+
+        return call_macro_data_tool(
+            "get_required_reserve_ratio_data",
+            active_data_source.get_required_reserve_ratio_data,
+            "Required Reserve Ratio",
+            start_date, end_date,
+            yearType=year_type  # Pass the extra arg correctly named for Baostock
+        )
+
+    @app.tool()
+    def get_money_supply_data_month(start_date: Optional[str] = None, end_date: Optional[str] = None) -> str:
+        """
+        Fetches monthly money supply data (M0, M1, M2) within a date range.
+
+        Args:
+            start_date: Optional. Start date in 'YYYY-MM' format.
+            end_date: Optional. End date in 'YYYY-MM' format.
+
+        Returns:
+            Markdown table with monthly money supply data or an error message.
+        """
+        # Add specific validation for YYYY-MM format if desired
+        return call_macro_data_tool(
+            "get_money_supply_data_month",
+            active_data_source.get_money_supply_data_month,
+            "Monthly Money Supply",
+            start_date, end_date
+        )
+
+    @app.tool()
+    def get_money_supply_data_year(start_date: Optional[str] = None, end_date: Optional[str] = None) -> str:
+        """
+        Fetches yearly money supply data (M0, M1, M2 - year end balance) within a date range.
+
+        Args:
+            start_date: Optional. Start year in 'YYYY' format.
+            end_date: Optional. End year in 'YYYY' format.
+
+        Returns:
+            Markdown table with yearly money supply data or an error message.
+        """
+        # Add specific validation for YYYY format if desired
+        return call_macro_data_tool(
+            "get_money_supply_data_year",
+            active_data_source.get_money_supply_data_year,
+            "Yearly Money Supply",
+            start_date, end_date
+        )
+
+    @app.tool()
+    def get_shibor_data(start_date: Optional[str] = None, end_date: Optional[str] = None) -> str:
+        """
+        Fetches SHIBOR (Shanghai Interbank Offered Rate) data within a date range.
+
+        Args:
+            start_date: Optional. Start date in 'YYYY-MM-DD' format.
+            end_date: Optional. End date in 'YYYY-MM-DD' format.
+
+        Returns:
+            Markdown table with SHIBOR data or an error message.
+        """
+        return call_macro_data_tool(
+            "get_shibor_data",
+            active_data_source.get_shibor_data,
+            "SHIBOR",
+            start_date, end_date
+        )