parse_excel

Instructions

Implementation Reference

• mcp_tool/tools/excel_tool.py:23-91 (handler)

  The core handler function `execute` for the parse_excel tool. It reads an Excel file using pandas, iterates over all sheets, converts each to dict format, and returns the structured JSON result with metadata (file_name, sheet_count, columns, row/column counts, and data).

  async def execute(self, arguments: dict) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
      """解析Excel文件并返回内容"""
      if "file_path" not in arguments:
          return [types.TextContent(
              type="text",
              text="Error: Missing required argument 'file_path'"
          )]
      
      file_path = arguments["file_path"]
      # 处理文件路径，支持挂载目录的转换
      file_path = self.process_file_path(file_path)
      
      if not os.path.exists(file_path):
          return [types.TextContent(
              type="text",
              text=f"Error: File not found at path: {file_path}"
          )]
      
      if not file_path.lower().endswith(('.xlsx', '.xls', '.xlsm')):
          return [types.TextContent(
              type="text",
              text=f"Error: File is not an Excel file: {file_path}"
          )]
      
      try:
          # 读取Excel文件中的所有sheet
          excel_file = pd.ExcelFile(file_path)
          sheet_names = excel_file.sheet_names
          
          result = {
              "file_name": os.path.basename(file_path),
              "sheet_count": len(sheet_names),
              "sheets": {}
          }
          
          # 解析每个sheet
          for sheet_name in sheet_names:
              df = pd.read_excel(excel_file, sheet_name=sheet_name)
              
              # 将DataFrame转换为字典
              sheet_data = df.to_dict(orient='records')
              
              # 获取列名
              columns = df.columns.tolist()
              
              # 获取行数和列数
              row_count = len(df)
              column_count = len(columns)
              
              result["sheets"][sheet_name] = {
                  "row_count": row_count,
                  "column_count": column_count,
                  "columns": columns,
                  "data": sheet_data
              }
          
          # 将结果转换为JSON字符串，并格式化输出
          result_json = json.dumps(result, ensure_ascii=False, indent=2, default=str)
          
          return [types.TextContent(
              type="text",
              text=result_json
          )]
          
      except Exception as e:
          return [types.TextContent(
              type="text",
              text=f"Error: Failed to parse Excel file: {str(e)}"
          )] 

• mcp_tool/tools/excel_tool.py:12-21 (schema)

  Input schema for parse_excel. Defines a required 'file_path' string property (the path to the Excel file).

  input_schema = {
      "type": "object",
      "required": ["file_path"],
      "properties": {
          "file_path": {
              "type": "string",
              "description": "Path to the Excel file to parse",
          }
      },
  }

• mcp_tool/tools/excel_tool.py:7-8 (registration)

  Registration decorator @ToolRegistry.register on the ExcelTool class with name='parse_excel'. This registers the tool into the ToolRegistry so it can be discovered and invoked.

  @ToolRegistry.register
  class ExcelTool(BaseTool):

• mcp_tool/tools/__init__.py:25-38 (helper)

  The process_file_path helper method inherited from BaseTool. It handles host mount directory path conversion (HOST_MOUNT_SOURCE -> HOST_MOUNT_TARGET) so the tool can resolve user-provided file paths correctly.

  def process_file_path(self, file_path: str) -> str:
      """
      处理文件路径，支持挂载目录的转换
      
      如果路径以HOST_MOUNT_SOURCE环境变量开头，则将其转换为容器内的路径
      """
      host_mount_source = os.environ.get('HOST_MOUNT_SOURCE', '')
      host_mount_target = os.environ.get('HOST_MOUNT_TARGET', '/host_files')
      
      # 如果路径以挂载源目录开头，则替换为挂载目标目录
      if host_mount_source and file_path.startswith(host_mount_source):
          return file_path.replace(host_mount_source, host_mount_target, 1)
      
      return file_path

• mcp_tool/tools/loader.py:12-38 (helper)

  The load_tools function that discovers and imports all tool modules (including excel_tool.py) from the tools directory, triggering their registration with ToolRegistry.

  def load_tools() -> List[Type[BaseTool]]:
      """
      自动加载tools目录下的所有工具模块
      
      Returns:
          List[Type[BaseTool]]: 已加载的工具类列表
      """
      # 获取当前模块的路径
      package_path = os.path.dirname(__file__)
      
      # 获取所有子模块
      for _, name, is_pkg in pkgutil.iter_modules([package_path]):
          # 跳过__init__.py和loader.py
          if name in ['__init__', 'loader']:
              continue
          
          # 导入模块
          module_name = f"{__package__}.{name}"
          try:
              importlib.import_module(module_name)
          except ImportError as e:
              print(f"Warning: Failed to import module {module_name}: {e}")
      
      # 收集所有已注册的工具类
      tools = list(ToolRegistry._tools.values())
      
      return tools