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

data_source_interface.py

@@ -0,0 +1,126 @@
+# Defines the abstract interface for financial data sources
+from abc import ABC, abstractmethod
+import pandas as pd
+from typing import Optional, List
+
+class DataSourceError(Exception):
+    """Base exception for data source errors."""
+    pass
+
+
+class LoginError(DataSourceError):
+    """Exception raised for login failures to the data source."""
+    pass
+
+
+class NoDataFoundError(DataSourceError):
+    """Exception raised when no data is found for the given query."""
+    pass
+
+
+class FinancialDataSource(ABC):
+    """
+    Abstract base class defining the interface for financial data sources.
+    Implementations of this class provide access to specific financial data APIs
+    (e.g., Baostock, Akshare).
+    """
+
+    @abstractmethod
+    def get_historical_k_data(
+        self,
+        code: str,
+        start_date: str,
+        end_date: str,
+        frequency: str = "d",
+        adjust_flag: str = "3",
+        fields: Optional[List[str]] = None,
+    ) -> pd.DataFrame:
+        """
+        Fetches historical K-line (OHLCV) data for a given stock code.
+
+        Args:
+            code: The stock code (e.g., 'sh.600000', 'sz.000001').
+            start_date: Start date in 'YYYY-MM-DD' format.
+            end_date: End date in 'YYYY-MM-DD' format.
+            frequency: Data frequency. Common values depend on the underlying
+                       source (e.g., 'd' for daily, 'w' for weekly, 'm' for monthly,
+                       '5', '15', '30', '60' for minutes). Defaults to 'd'.
+            adjust_flag: Adjustment flag for historical data. Common values
+                         depend on the source (e.g., '1' for forward adjusted,
+                         '2' for backward adjusted, '3' for non-adjusted).
+                         Defaults to '3'.
+            fields: Optional list of specific fields to retrieve. If None,
+                    retrieves default fields defined by the implementation.
+
+        Returns:
+            A pandas DataFrame containing the historical K-line data, with
+            columns corresponding to the requested fields.
+
+        Raises:
+            LoginError: If login to the data source fails.
+            NoDataFoundError: If no data is found for the query.
+            DataSourceError: For other data source related errors.
+            ValueError: If input parameters are invalid.
+        """
+        pass
+
+    @abstractmethod
+    def get_stock_basic_info(self, code: str) -> pd.DataFrame:
+        """
+        Fetches basic information for a given stock code.
+
+        Args:
+            code: The stock code (e.g., 'sh.600000', 'sz.000001').
+
+        Returns:
+            A pandas DataFrame containing the basic stock information.
+            The structure and columns depend on the underlying data source.
+            Typically contains info like name, industry, listing date, etc.
+
+        Raises:
+            LoginError: If login to the data source fails.
+            NoDataFoundError: If no data is found for the query.
+            DataSourceError: For other data source related errors.
+            ValueError: If the input code is invalid.
+        """
+        pass
+
+    @abstractmethod
+    def get_trade_dates(self, start_date: Optional[str] = None, end_date: Optional[str] = None) -> pd.DataFrame:
+        """Fetches trading dates information within a range."""
+        pass
+
+    @abstractmethod
+    def get_all_stock(self, date: Optional[str] = None) -> pd.DataFrame:
+        """Fetches list of all stocks and their trading status on a given date."""
+        pass
+
+    @abstractmethod
+    def get_deposit_rate_data(self, start_date: Optional[str] = None, end_date: Optional[str] = None) -> pd.DataFrame:
+        """Fetches benchmark deposit rates."""
+        pass
+
+    @abstractmethod
+    def get_loan_rate_data(self, start_date: Optional[str] = None, end_date: Optional[str] = None) -> pd.DataFrame:
+        """Fetches benchmark loan rates."""
+        pass
+
+    @abstractmethod
+    def get_required_reserve_ratio_data(self, start_date: Optional[str] = None, end_date: Optional[str] = None, year_type: str = '0') -> pd.DataFrame:
+        """Fetches required reserve ratio data."""
+        pass
+
+    @abstractmethod
+    def get_money_supply_data_month(self, start_date: Optional[str] = None, end_date: Optional[str] = None) -> pd.DataFrame:
+        """Fetches monthly money supply data (M0, M1, M2)."""
+        pass
+
+    @abstractmethod
+    def get_money_supply_data_year(self, start_date: Optional[str] = None, end_date: Optional[str] = None) -> pd.DataFrame:
+        """Fetches yearly money supply data (M0, M1, M2 - year end balance)."""
+        pass
+
+    @abstractmethod
+    def get_shibor_data(self, start_date: Optional[str] = None, end_date: Optional[str] = None) -> pd.DataFrame:
+        """Fetches SHIBOR (Shanghai Interbank Offered Rate) data."""
+        pass

formatting/__init__.py

@@ -0,0 +1 @@
+# Initialization file for formatting package

formatting/markdown_formatter.py

@@ -0,0 +1,65 @@
+"""
+Markdown formatting utilities for A-Share MCP Server.
+"""
+import pandas as pd
+import logging
+from datetime import datetime, timedelta
+
+logger = logging.getLogger(__name__)
+
+# Configuration
+# Common number of trading days per year. Max rows to display in Markdown output
+MAX_MARKDOWN_ROWS = 250
+
+
+def format_df_to_markdown(df: pd.DataFrame, max_rows: int = None) -> str:
+    """Formats a Pandas DataFrame to a Markdown string with row truncation.
+
+    Args:
+        df: The DataFrame to format
+        max_rows: Maximum rows to include in output. Defaults to MAX_MARKDOWN_ROWS if None.
+
+    Returns:
+        A markdown formatted string representation of the DataFrame
+    """
+    if df.empty:
+        logger.warning("Attempted to format an empty DataFrame to Markdown.")
+        return "(No data available to display)"
+
+    # Default max_rows to the configured limit if not provided
+    if max_rows is None:
+        max_rows = MAX_MARKDOWN_ROWS
+        logger.debug(f"max_rows defaulted to MAX_MARKDOWN_ROWS: {max_rows}")
+
+    original_rows = df.shape[0]  # Only need original_rows now
+    truncated = False
+    truncation_notes = []
+
+    # Determine the actual number of rows to display, capped by max_rows
+    rows_to_show = min(original_rows, max_rows)
+
+    # Always apply the row limit
+    df_display = df.head(rows_to_show)
+
+    # Check if actual row truncation occurred (only if original_rows > rows_to_show)
+    if original_rows > rows_to_show:
+        truncation_notes.append(
+            f"rows truncated to the limit of {rows_to_show} (from {original_rows})")
+        truncated = True
+
+    try:
+        markdown_table = df_display.to_markdown(index=False)
+    except Exception as e:
+        logger.error(
+            f"Error converting DataFrame to Markdown: {e}", exc_info=True)
+        return "Error: Could not format data into Markdown table."
+
+    if truncated:
+        # Note: 'truncated' is now only True if rows were truncated
+        notes = "; ".join(truncation_notes)
+        logger.debug(
+            f"Markdown table generated with truncation notes: {notes}")
+        return f"Note: Data truncated ({notes}).\n\n{markdown_table}"
+    else:
+        logger.debug("Markdown table generated without truncation.")
+        return markdown_table

mseep_a_share_mcp-0.1.1.dist-info/METADATA

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: mseep-a-share-mcp
+Version: 0.1.1
+Summary: Add your description here
+Author-email: mseep <support@skydeck.ai>
+Requires-Python: >=3.12
+Description-Content-Type: text/plain
+License-File: LICENSE
+Requires-Dist: baostock>=0.8.9
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: annotated-types>=0.7.0
+Requires-Dist: anyio>=4.9.0
+Requires-Dist: certifi>=2025.4.26
+Requires-Dist: click>=8.1.8
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: h11>=0.16.0
+Requires-Dist: httpcore>=1.0.9
+Requires-Dist: httpx-sse>=0.4.0
+Requires-Dist: idna>=3.10
+Requires-Dist: markdown-it-py>=3.0.0
+Requires-Dist: mdurl>=0.1.2
+Requires-Dist: numpy>=2.2.5
+Requires-Dist: pydantic>=2.11.3
+Requires-Dist: pydantic-core>=2.33.1
+Requires-Dist: pydantic-settings>=2.9.1
+Requires-Dist: pygments>=2.19.1
+Requires-Dist: python-dateutil>=2.9.0
+Requires-Dist: python-dotenv>=1.1.0
+Requires-Dist: pytz>=2025.2
+Requires-Dist: rich>=14.0.0
+Requires-Dist: shellingham>=1.5.4
+Requires-Dist: six>=1.17.0
+Requires-Dist: sniffio>=1.3.1
+Requires-Dist: sse-starlette>=2.3.3
+Requires-Dist: starlette>=0.46.2
+Requires-Dist: tabulate>=0.9.0
+Requires-Dist: typer>=0.15.3
+Requires-Dist: typing-extensions>=4.13.2
+Requires-Dist: typing-inspection>=0.4.0
+Requires-Dist: tzdata>=2025.2
+Requires-Dist: uvicorn>=0.34.2
+Dynamic: license-file
+
+Package managed by MseeP.ai

mseep_a_share_mcp-0.1.1.dist-info/RECORD

@@ -0,0 +1,20 @@
+__init__.py,sha256=AWl8YWEZfzOKWAeTp95xP8pKfd6qXK0gt45H0Cyp7-Q,39
+baostock_data_source.py,sha256=8516O2cvDgqapdk-Ip0GLOIp1OG4BWy-j5DvtCvofOo,34530
+data_source_interface.py,sha256=rzduDOcbwc2YIbaR4xfNHBzhjhpALShlU26YelCWgZg,4829
+utils.py,sha256=kcIn7S6ValYMiclIMOP8d5yifNmIt8Y9YXZK3CtD-Hk,2359
+formatting/__init__.py,sha256=Tyqwy1nJmF3OFPSCgxga44JwEhqenT9QB0j9orKSI1c,45
+formatting/markdown_formatter.py,sha256=g9ppHZTetKpUxT3nCU3p4gJuA608rGHjz3IekiopWBk,2264
+mseep_a_share_mcp-0.1.1.dist-info/licenses/LICENSE,sha256=3RDP-0gPJrroR5V1bjnuYWcdC3Evdo_LVAtm5xqFK9E,1062
+tools/__init__.py,sha256=Zh7xp3j0jT32WPGAkCKAWkUFGK4mFkqcjOL6K9BWiSc,40
+tools/analysis.py,sha256=i4jZPDQACcu1G_QQ_n8pzNUJGVZNUMDjkcsYYmEh7YA,8504
+tools/base.py,sha256=CY7qEB66_nYE4n7gjte6B9IWthzNBniMuVyXKwqCFV8,6097
+tools/date_utils.py,sha256=_LEyy2vBD-PqwninYwJoG6lId9MIKRBKqTecv17vAsY,7512
+tools/financial_reports.py,sha256=clksV528suQZ9dSI4lHHhc6UNAyw4Ubar9150RAIqeg,7310
+tools/indices.py,sha256=SeTew1eBb2k23UE8tGSUEU6BCOhYMljnbh0_G5KNK58,3543
+tools/macroeconomic.py,sha256=wdTkXFzl14xAFddlPSS9CjuoKzpIx0ppie0YfcK215s,5339
+tools/market_overview.py,sha256=VGEyibX3V48pCdUiF-pbDWWaEZC8LGUs-oDHPG8hvU4,4085
+tools/stock_market.py,sha256=fvMDpaYS_J8KnmjnK3tUlR2vHSO39sR7dRAmNHrTN6c,11138
+mseep_a_share_mcp-0.1.1.dist-info/METADATA,sha256=8PoHx2OzC0w2cAFBcqPscaUCUQ_xAbPRd5qu3-jS-1o,1392
+mseep_a_share_mcp-0.1.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mseep_a_share_mcp-0.1.1.dist-info/top_level.txt,sha256=rhSJLqDXlTNnV3YJTEQtQyJOJGXap8iZrFmcJ0vfuFg,75
+mseep_a_share_mcp-0.1.1.dist-info/RECORD,,

mseep_a_share_mcp-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mseep_a_share_mcp-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Devin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mseep_a_share_mcp-0.1.1.dist-info/top_level.txt

@@ -0,0 +1,6 @@
+__init__
+baostock_data_source
+data_source_interface
+formatting
+tools
+utils

tools/__init__.py

@@ -0,0 +1 @@
+# Initialization file for tools package

tools/analysis.py

@@ -0,0 +1,169 @@
+"""
+Analysis tools for MCP server.
+Contains tools for generating stock analysis reports.
+"""
+import logging
+from datetime import datetime, timedelta
+
+from mcp.server.fastmcp import FastMCP
+from src.data_source_interface import FinancialDataSource
+from src.formatting.markdown_formatter import format_df_to_markdown
+
+logger = logging.getLogger(__name__)
+
+
+def register_analysis_tools(app: FastMCP, active_data_source: FinancialDataSource):
+    """
+    Register analysis tools with the MCP app.
+
+    Args:
+        app: The FastMCP app instance
+        active_data_source: The active financial data source
+    """
+
+    @app.tool()
+    def get_stock_analysis(code: str, analysis_type: str = "fundamental") -> str:
+        """
+        提供基于数据的股票分析报告，而非投资建议。
+
+        Args:
+            code: 股票代码，如'sh.600000'
+            analysis_type: 分析类型，可选'fundamental'(基本面)、'technical'(技术面)或'comprehensive'(综合)
+
+        Returns:
+            数据驱动的分析报告，包含关键财务指标、历史表现和同行业比较
+        """
+        logger.info(
+            f"Tool 'get_stock_analysis' called for {code}, type={analysis_type}")
+
+        # 收集多个维度的实际数据
+        try:
+            # 获取基本信息
+            basic_info = active_data_source.get_stock_basic_info(code=code)
+
+            # 根据分析类型获取不同数据
+            if analysis_type in ["fundamental", "comprehensive"]:
+                # 获取最近一个季度财务数据
+                recent_year = datetime.now().strftime("%Y")
+                recent_quarter = (datetime.now().month - 1) // 3 + 1
+                if recent_quarter < 1:  # 处理年初可能出现的边界情况
+                    recent_year = str(int(recent_year) - 1)
+                    recent_quarter = 4
+
+                profit_data = active_data_source.get_profit_data(
+                    code=code, year=recent_year, quarter=recent_quarter)
+                growth_data = active_data_source.get_growth_data(
+                    code=code, year=recent_year, quarter=recent_quarter)
+                balance_data = active_data_source.get_balance_data(
+                    code=code, year=recent_year, quarter=recent_quarter)
+                dupont_data = active_data_source.get_dupont_data(
+                    code=code, year=recent_year, quarter=recent_quarter)
+
+            if analysis_type in ["technical", "comprehensive"]:
+                # 获取历史价格
+                end_date = datetime.now().strftime("%Y-%m-%d")
+                start_date = (datetime.now() - timedelta(days=180)
+                              ).strftime("%Y-%m-%d")
+                price_data = active_data_source.get_historical_k_data(
+                    code=code, start_date=start_date, end_date=end_date
+                )
+
+            # 构建客观的数据分析报告
+            report = f"# {basic_info['code_name'].values[0] if not basic_info.empty else code} 数据分析报告\n\n"
+            report += "## 免责声明\n本报告基于公开数据生成，仅供参考，不构成投资建议。投资决策需基于个人风险承受能力和研究。\n\n"
+
+            # 添加行业信息
+            if not basic_info.empty:
+                report += f"## 公司基本信息\n"
+                report += f"- 股票代码: {code}\n"
+                report += f"- 股票名称: {basic_info['code_name'].values[0]}\n"
+                report += f"- 所属行业: {basic_info['industry'].values[0] if 'industry' in basic_info.columns else '未知'}\n"
+                report += f"- 上市日期: {basic_info['ipoDate'].values[0] if 'ipoDate' in basic_info.columns else '未知'}\n\n"
+
+            # 添加基本面分析
+            if analysis_type in ["fundamental", "comprehensive"] and not profit_data.empty:
+                report += f"## 基本面指标分析 ({recent_year}年第{recent_quarter}季度)\n\n"
+
+                # 盈利能力
+                report += "### 盈利能力指标\n"
+                if not profit_data.empty and 'roeAvg' in profit_data.columns:
+                    roe = profit_data['roeAvg'].values[0]
+                    report += f"- ROE(净资产收益率): {roe}%\n"
+                if not profit_data.empty and 'npMargin' in profit_data.columns:
+                    npm = profit_data['npMargin'].values[0]
+                    report += f"- 销售净利率: {npm}%\n"
+
+                # 成长能力
+                if not growth_data.empty:
+                    report += "\n### 成长能力指标\n"
+                    if 'YOYEquity' in growth_data.columns:
+                        equity_growth = growth_data['YOYEquity'].values[0]
+                        report += f"- 净资产同比增长: {equity_growth}%\n"
+                    if 'YOYAsset' in growth_data.columns:
+                        asset_growth = growth_data['YOYAsset'].values[0]
+                        report += f"- 总资产同比增长: {asset_growth}%\n"
+                    if 'YOYNI' in growth_data.columns:
+                        ni_growth = growth_data['YOYNI'].values[0]
+                        report += f"- 净利润同比增长: {ni_growth}%\n"
+
+                # 偿债能力
+                if not balance_data.empty:
+                    report += "\n### 偿债能力指标\n"
+                    if 'currentRatio' in balance_data.columns:
+                        current_ratio = balance_data['currentRatio'].values[0]
+                        report += f"- 流动比率: {current_ratio}\n"
+                    if 'assetLiabRatio' in balance_data.columns:
+                        debt_ratio = balance_data['assetLiabRatio'].values[0]
+                        report += f"- 资产负债率: {debt_ratio}%\n"
+
+            # 添加技术面分析
+            if analysis_type in ["technical", "comprehensive"] and not price_data.empty:
+                report += "## 技术面分析\n\n"
+
+                # 计算简单的技术指标
+                # 假设price_data已经按日期排序
+                if 'close' in price_data.columns and len(price_data) > 1:
+                    latest_price = price_data['close'].iloc[-1]
+                    start_price = price_data['close'].iloc[0]
+                    price_change = (
+                        (float(latest_price) / float(start_price)) - 1) * 100
+
+                    report += f"- 最新收盘价: {latest_price}\n"
+                    report += f"- 6个月价格变动: {price_change:.2f}%\n"
+
+                    # 计算简单的均线
+                    if len(price_data) >= 20:
+                        ma20 = price_data['close'].astype(
+                            float).tail(20).mean()
+                        report += f"- 20日均价: {ma20:.2f}\n"
+                        if float(latest_price) > ma20:
+                            report += f"  (当前价格高于20日均线 {((float(latest_price)/ma20)-1)*100:.2f}%)\n"
+                        else:
+                            report += f"  (当前价格低于20日均线 {((ma20/float(latest_price))-1)*100:.2f}%)\n"
+
+            # 添加行业比较分析
+            try:
+                if not basic_info.empty and 'industry' in basic_info.columns:
+                    industry = basic_info['industry'].values[0]
+                    industry_stocks = active_data_source.get_stock_industry(
+                        date=None)
+                    if not industry_stocks.empty:
+                        same_industry = industry_stocks[industry_stocks['industry'] == industry]
+                        report += f"\n## 行业比较 ({industry})\n"
+                        report += f"- 同行业股票数量: {len(same_industry)}\n"
+
+                        # 这里可以添加更多行业比较数据
+            except Exception as e:
+                logger.warning(f"获取行业比较数据失败: {e}")
+
+            report += "\n## 数据解读建议\n"
+            report += "- 以上数据仅供参考，建议结合公司公告、行业趋势和宏观环境进行综合分析\n"
+            report += "- 个股表现受多种因素影响，历史数据不代表未来表现\n"
+            report += "- 投资决策应基于个人风险承受能力和投资目标\n"
+
+            logger.info(f"成功生成{code}的分析报告")
+            return report
+
+        except Exception as e:
+            logger.exception(f"分析生成失败 for {code}: {e}")
+            return f"分析生成失败: {e}"

tools/base.py

@@ -0,0 +1,161 @@
+"""
+Base utilities for MCP tools.
+Contains shared helper functions for calling data sources.
+"""
+import logging
+from typing import Callable, Optional
+import pandas as pd
+
+from src.formatting.markdown_formatter import format_df_to_markdown
+from src.data_source_interface import NoDataFoundError, LoginError, DataSourceError
+
+logger = logging.getLogger(__name__)
+
+
+def call_financial_data_tool(
+    tool_name: str,
+    # Pass the bound method like active_data_source.get_profit_data
+    data_source_method: Callable,
+    data_type_name: str,
+    code: str,
+    year: str,
+    quarter: int
+) -> str:
+    """
+    Helper function to reduce repetition for financial data tools
+
+    Args:
+        tool_name: Name of the tool for logging
+        data_source_method: Method to call on the data source
+        data_type_name: Type of financial data (for logging)
+        code: Stock code
+        year: Year to query
+        quarter: Quarter to query
+
+    Returns:
+        Markdown formatted string with results or error message
+    """
+    logger.info(f"Tool '{tool_name}' called for {code}, {year}Q{quarter}")
+    try:
+        # Basic validation
+        if not year.isdigit() or len(year) != 4:
+            logger.warning(f"Invalid year format requested: {year}")
+            return f"Error: Invalid year '{year}'. Please provide a 4-digit year."
+        if not 1 <= quarter <= 4:
+            logger.warning(f"Invalid quarter requested: {quarter}")
+            return f"Error: Invalid quarter '{quarter}'. Must be between 1 and 4."
+
+        # Call the appropriate method on the already instantiated active_data_source
+        df = data_source_method(code=code, year=year, quarter=quarter)
+        logger.info(
+            f"Successfully retrieved {data_type_name} data for {code}, {year}Q{quarter}.")
+        # Use smaller limits for financial tables?
+        return format_df_to_markdown(df)
+
+    except NoDataFoundError as e:
+        logger.warning(f"NoDataFoundError for {code}, {year}Q{quarter}: {e}")
+        return f"Error: {e}"
+    except LoginError as e:
+        logger.error(f"LoginError for {code}: {e}")
+        return f"Error: Could not connect to data source. {e}"
+    except DataSourceError as e:
+        logger.error(f"DataSourceError for {code}: {e}")
+        return f"Error: An error occurred while fetching data. {e}"
+    except ValueError as e:
+        logger.warning(f"ValueError processing request for {code}: {e}")
+        return f"Error: Invalid input parameter. {e}"
+    except Exception as e:
+        logger.exception(
+            f"Unexpected Exception processing {tool_name} for {code}: {e}")
+        return f"Error: An unexpected error occurred: {e}"
+
+
+def call_macro_data_tool(
+    tool_name: str,
+    data_source_method: Callable,
+    data_type_name: str,
+    start_date: Optional[str] = None,
+    end_date: Optional[str] = None,
+    **kwargs  # For extra params like year_type
+) -> str:
+    """
+    Helper function for macroeconomic data tools
+
+    Args:
+        tool_name: Name of the tool for logging
+        data_source_method: Method to call on the data source
+        data_type_name: Type of data (for logging)
+        start_date: Optional start date
+        end_date: Optional end date
+        **kwargs: Additional keyword arguments to pass to data_source_method
+
+    Returns:
+        Markdown formatted string with results or error message
+    """
+    date_range_log = f"from {start_date or 'default'} to {end_date or 'default'}"
+    kwargs_log = f", extra_args={kwargs}" if kwargs else ""
+    logger.info(f"Tool '{tool_name}' called {date_range_log}{kwargs_log}")
+    try:
+        # Call the appropriate method on the active_data_source
+        df = data_source_method(start_date=start_date,
+                                end_date=end_date, **kwargs)
+        logger.info(f"Successfully retrieved {data_type_name} data.")
+        return format_df_to_markdown(df)
+    except NoDataFoundError as e:
+        logger.warning(f"NoDataFoundError: {e}")
+        return f"Error: {e}"
+    except LoginError as e:
+        logger.error(f"LoginError: {e}")
+        return f"Error: Could not connect to data source. {e}"
+    except DataSourceError as e:
+        logger.error(f"DataSourceError: {e}")
+        return f"Error: An error occurred while fetching data. {e}"
+    except ValueError as e:
+        logger.warning(f"ValueError: {e}")
+        return f"Error: Invalid input parameter. {e}"
+    except Exception as e:
+        logger.exception(f"Unexpected Exception processing {tool_name}: {e}")
+        return f"Error: An unexpected error occurred: {e}"
+
+
+def call_index_constituent_tool(
+    tool_name: str,
+    data_source_method: Callable,
+    index_name: str,
+    date: Optional[str] = None
+) -> str:
+    """
+    Helper function for index constituent tools
+
+    Args:
+        tool_name: Name of the tool for logging
+        data_source_method: Method to call on the data source
+        index_name: Name of the index (for logging)
+        date: Optional date to query
+
+    Returns:
+        Markdown formatted string with results or error message
+    """
+    log_msg = f"Tool '{tool_name}' called for date={date or 'latest'}"
+    logger.info(log_msg)
+    try:
+        # Add date validation if desired
+        df = data_source_method(date=date)
+        logger.info(
+            f"Successfully retrieved {index_name} constituents for {date or 'latest'}.")
+        return format_df_to_markdown(df)
+    except NoDataFoundError as e:
+        logger.warning(f"NoDataFoundError: {e}")
+        return f"Error: {e}"
+    except LoginError as e:
+        logger.error(f"LoginError: {e}")
+        return f"Error: Could not connect to data source. {e}"
+    except DataSourceError as e:
+        logger.error(f"DataSourceError: {e}")
+        return f"Error: An error occurred while fetching data. {e}"
+    except ValueError as e:
+        logger.warning(f"ValueError: {e}")
+        return f"Error: Invalid input parameter. {e}"
+    except Exception as e:
+        logger.exception(f"Unexpected Exception processing {tool_name}: {e}")
+        return f"Error: An unexpected error occurred: {e}"