get_workbook_metadata

Instructions

Implementation Reference

• src/excel_mcp/server.py:513-518 (registration)

  Registration of the 'get_workbook_metadata' tool as an MCP tool via @mcp.tool decorator with ToolAnnotations including title and readOnlyHint=True.

  @mcp.tool(
      annotations=ToolAnnotations(
          title="Get Workbook Metadata",
          readOnlyHint=True,
      ),
  )

• src/excel_mcp/server.py:519-532 (handler)

  Handler function that resolves the filepath via get_excel_path(), calls get_workbook_info() and returns the result as a string. Catches WorkbookError and generic exceptions.

  def get_workbook_metadata(
      filepath: str,
      include_ranges: bool = False
  ) -> str:
      """Get metadata about workbook including sheets, ranges, etc."""
      try:
          full_path = get_excel_path(filepath)
          result = get_workbook_info(full_path, include_ranges=include_ranges)
          return str(result)
      except WorkbookError as e:
          return f"Error: {str(e)}"
      except Exception as e:
          logger.error(f"Error getting workbook metadata: {e}")
          raise

• src/excel_mcp/workbook.py:63-96 (helper)

  Helper function get_workbook_info() that loads the workbook, collects metadata (filename, sheets, size, modified time), and optionally includes used ranges per sheet.

  def get_workbook_info(filepath: str, include_ranges: bool = False) -> dict[str, Any]:
      """Get metadata about workbook including sheets, ranges, etc."""
      try:
          path = Path(filepath)
          if not path.exists():
              raise WorkbookError(f"File not found: {filepath}")
              
          wb = load_workbook(filepath, read_only=False)
          
          info = {
              "filename": path.name,
              "sheets": wb.sheetnames,
              "size": path.stat().st_size,
              "modified": path.stat().st_mtime
          }
          
          if include_ranges:
              # Add used ranges for each sheet
              ranges = {}
              for sheet_name in wb.sheetnames:
                  ws = wb[sheet_name]
                  if ws.max_row > 0 and ws.max_column > 0:
                      ranges[sheet_name] = f"A1:{get_column_letter(ws.max_column)}{ws.max_row}"
              info["used_ranges"] = ranges
              
          wb.close()
          return info
          
      except WorkbookError as e:
          logger.error(str(e))
          raise
      except Exception as e:
          logger.error(f"Failed to get workbook info: {e}")
          raise WorkbookError(str(e))

• src/excel_mcp/server.py:520-521 (schema)

  Input schema for the tool: filepath (str) and include_ranges (bool, default False). The return type is str.

  filepath: str,
  include_ranges: bool = False

• src/excel_mcp/exceptions.py:5-8 (helper)

  WorkbookError exception class used by get_workbook_info and get_workbook_metadata for error handling.

  class WorkbookError(ExcelMCPError):
      """Raised when workbook operations fail."""
      pass