Merge pull request #51 from ncdcdev/feat/add-cell-styles

feat: add include_cell_styles parameter for Excel cell formatting (Issue #43)

Author: k-ibaraki

README.md

@@ -37,6 +37,9 @@ Two authentication methods are supported:
   - Read mode: get data from specific sheets/ranges with `sheet` and `cell_range` parameters
   - **Automatic header inclusion**: when `cell_range` is specified, frozen rows (headers) are automatically included by default
     - Set `include_frozen_rows=False` to get only the specified range
+  - **Cell style information** (optional): set `include_cell_styles=True` to get background colors, column widths, and row heights
+    - Default is `False` to minimize token usage
+    - Useful for identifying highlighted cells, colored headers, or visually emphasized content
   - Response includes cell data in `rows` (value and coordinate) and structural information when available
   - Structural info: sheet name, dimensions, frozen_rows, frozen_cols, freeze_panes (when present), merged_ranges (when merged cells exist)
   - No Excel Services dependency - uses direct file download + openpyxl parsing

README_ja.md

@@ -37,6 +37,9 @@ stdioとHTTPの両方のトランスポートに対応しています。
   - 読み取りモード: `sheet`と`cell_range`パラメータで特定シート/範囲を取得
   - **ヘッダー自動追加**: `cell_range`指定時、デフォルトで固定行（ヘッダー）を自動的に含める
     - `include_frozen_rows=False`を指定すると、指定範囲のみを取得
+  - **セルスタイル情報**（オプション）: `include_cell_styles=True`を指定すると、背景色・列幅・行高さを取得
+    - デフォルトは`False`でトークン消費を最小化
+    - 強調表示されたセル、色付きヘッダー、視覚的に強調されたコンテンツの識別に便利
   - レスポンスには`rows`内のセルデータ（値と座標）と構造情報（利用可能な場合）を含む
   - 構造情報: シート名、dimensions、frozen_rows、frozen_cols、freeze_panes（存在する場合）、merged_ranges（結合セルが存在する場合）
   - Excel Services不要 - 直接ファイルダウンロード+openpyxl解析方式

src/server.py

@@ -454,6 +454,7 @@ def sharepoint_excel(
     sheet: str | None = None,
     cell_range: str | None = None,
     include_frozen_rows: bool = True,
+    include_cell_styles: bool = False,
     ctx: Context | None = None,
 ) -> str:
     """
@@ -471,6 +472,10 @@ def sharepoint_excel(
         include_frozen_rows: cell_range指定時に固定行を自動追加（デフォルト: True）
             True: frozen_rowsで指定された行（通常はヘッダー）を自動的に取得
             False: 指定されたcell_rangeのみを取得
+        include_cell_styles: セルの色・サイズ情報（default: false）
+            色分けされたデータを抽出する場合のみTrueを指定
+            背景色（fill）、列幅（width）、行高さ（height）を取得
+            ※トークン消費が約20%増加
         ctx: FastMCP context (injected automatically)
 
     Returns:
@@ -498,6 +503,7 @@ def sharepoint_excel(
             sheet_name=sheet,
             cell_range=cell_range,
             include_frozen_rows=include_frozen_rows,
+            include_cell_styles=include_cell_styles,
         )
 
     except Exception as e:
@@ -542,6 +548,7 @@ def register_tools():
                 "frozen at the top of the sheet (typically column headers). "
                 "Response includes cell data in 'rows' (value and coordinate) and structural information "
                 "(sheet name, dimensions, frozen_rows, frozen_cols, freeze_panes when present, merged_ranges when merged cells exist). "
+                "Cell styles (include_cell_styles, default: false): background colors and sizes. Use only for color-coded data extraction. "
                 "Header detection: Cannot be auto-detected from frozen_rows. "
                 "ALWAYS read exactly 5 rows for header check: 'A1:Z5' (NOT 'A1:Z50' or more). "
                 "Prefer 'query' search when possible to locate data first. "

src/sharepoint_excel.py

@@ -107,6 +107,7 @@ def parse_to_json(
         sheet_name: str | None = None,
         cell_range: str | None = None,
         include_frozen_rows: bool = True,
+        include_cell_styles: bool = False,
     ) -> str:
         """
         Excelファイルを解析してJSON形式で返す
@@ -118,13 +119,16 @@ def parse_to_json(
             include_frozen_rows: cell_range指定時に固定行（ヘッダー）を自動追加
                 True（デフォルト）: frozen_rowsで指定された行を自動的に取得
                 False: 指定されたcell_rangeのみを取得
+            include_cell_styles: セルの色・サイズ情報（default: false）
+                色分けデータ抽出時のみ使用。トークン消費+約20%
 
         Returns:
             JSON文字列
             - 各セルのデータ: value（値）、coordinate（座標）
             - 構造情報: シート名、dimensions（シート全体のセル範囲、例: "A1:D10"）
             - 構造情報: frozen_rows（固定行数）、frozen_cols（固定列数）
             - 条件付き構造情報: freeze_panes（存在する場合）、merged_ranges（結合セルが存在する場合）
+            - スタイル情報（include_cell_styles=Trueの場合）: fill（背景色）、width（列幅）、height（行高さ）
         """
         logger.info(
             f"Parsing Excel file: {file_path} (sheet={sheet_name}, range={cell_range})"
@@ -205,6 +209,7 @@ def parse_to_json(
                     sheet,
                     cell_range,
                     include_frozen_rows,
+                    include_cell_styles,
                 )
                 result["sheets"].append(sheet_data)
 
@@ -289,9 +294,7 @@ def _scan_sheet(
                                     }
                                 )
 
-    def _calculate_header_range(
-        self, cell_range: str, frozen_rows: int
-    ) -> str | None:
+    def _calculate_header_range(self, cell_range: str, frozen_rows: int) -> str | None:
         """
         セル範囲に対してfrozen_rowsに基づくヘッダー範囲を計算
 
@@ -393,6 +396,7 @@ def _parse_sheet(
         sheet,
         cell_range: str | None = None,
         include_frozen_rows: bool = True,
+        include_cell_styles: bool = False,
     ) -> dict[str, Any]:
         """
         シートを解析してdict形式で返す
@@ -401,6 +405,7 @@ def _parse_sheet(
             sheet: openpyxl Worksheet
             cell_range: セル範囲指定（例: "A1:D10"）
             include_frozen_rows: cell_range指定時に固定行（ヘッダー）を自動追加
+            include_cell_styles: セルのスタイル情報を含めるか
 
         Returns:
             シートデータのdict
@@ -467,7 +472,9 @@ def _parse_sheet(
 
             # ヘッダー自動追加の場合、マージセルキャッシュにもヘッダー範囲を含める
             if include_frozen_rows and frozen_rows > 0:
-                header_range = self._calculate_header_range(effective_range, frozen_rows)
+                header_range = self._calculate_header_range(
+                    effective_range, frozen_rows
+                )
                 if header_range:
                     # ヘッダー範囲とデータ範囲を結合した範囲を計算
                     effective_range_for_merge = self._merge_ranges(
@@ -519,6 +526,19 @@ def _parse_sheet(
         if merged_ranges:
             sheet_data["merged_ranges"] = merged_ranges
 
+        # セルサイズのキャッシュを構築（パフォーマンス最適化）
+        col_widths: dict[str, float] | None = None
+        row_heights: dict[int, float] | None = None
+        if include_cell_styles:
+            col_widths = {}
+            row_heights = {}
+            for col_letter, dim in sheet.column_dimensions.items():
+                if dim.width:
+                    col_widths[col_letter] = dim.width
+            for row_num, dim in sheet.row_dimensions.items():
+                if dim.height:
+                    row_heights[row_num] = dim.height
+
         # データ取得
         if cell_range:
             # ヘッダー自動追加（include_frozen_rows=Trueの場合）
@@ -530,8 +550,11 @@ def _parse_sheet(
                 all_rows.extend(
                     self._parse_rows(
                         header_rows,
+                        include_cell_styles,
                         merged_cell_map,
                         merged_anchor_value_map,
+                        col_widths,
+                        row_heights,
                     )
                 )
 
@@ -541,8 +564,11 @@ def _parse_sheet(
             all_rows.extend(
                 self._parse_rows(
                     rows_to_process,
+                    include_cell_styles,
                     merged_cell_map,
                     merged_anchor_value_map,
+                    col_widths,
+                    row_heights,
                 )
             )
 
@@ -554,8 +580,11 @@ def _parse_sheet(
                 all_rows.extend(
                     self._parse_rows(
                         rows_to_process,
+                        include_cell_styles,
                         merged_cell_map,
                         merged_anchor_value_map,
+                        col_widths,
+                        row_heights,
                     )
                 )
 
@@ -741,16 +770,22 @@ def _expand_axis_range(self, range_str: str) -> str:
     def _parse_cell(
         self,
         cell,
+        include_cell_styles: bool = False,
         merged_cell_map: dict[str, str] | None = None,
         merged_anchor_value_map: dict[str, Any] | None = None,
+        col_widths: dict[str, float] | None = None,
+        row_heights: dict[int, float] | None = None,
     ) -> dict[str, Any]:
         """
         セルを解析してdict形式で返す
 
         Args:
             cell: openpyxl Cell
+            include_cell_styles: セルのスタイル情報を含めるか（デフォルト: False）
             merged_cell_map: マージセル座標からマージ範囲へのマップ（パフォーマンス最適化用）
             merged_anchor_value_map: マージ範囲 -> アンカー値 のマップ（結合セルの値埋め用）
+            col_widths: 列幅のキャッシュ（パフォーマンス最適化用）
+            row_heights: 行高さのキャッシュ（パフォーマンス最適化用）
 
         Returns:
             セルデータのdict
@@ -776,22 +811,53 @@ def _parse_cell(
                 if anchor_value is not None:
                     cell_data["value"] = anchor_value
 
-        # 書式情報（fill/width/height/data_type）は現在サポートされていません
+        # スタイル情報（include_cell_styles=Trueの場合のみ）
+        if include_cell_styles:
+            # 背景色情報
+            if cell.fill and cell.fill.patternType:
+                fill_info = {
+                    "pattern_type": cell.fill.patternType,
+                }
+                fg_color = self._color_to_hex(cell.fill.fgColor)
+                if fg_color:
+                    fill_info["fg_color"] = fg_color
+                bg_color = self._color_to_hex(cell.fill.bgColor)
+                if bg_color:
+                    fill_info["bg_color"] = bg_color
+                cell_data["fill"] = fill_info
+
+            # セルサイズ（列幅・行高さ）
+            # MergedCellの場合は属性が存在しないため、hasattrでチェック
+            if hasattr(cell, "column_letter") and hasattr(cell, "row"):
+                if cell.column_letter and cell.row:
+                    # キャッシュから列幅を取得（パフォーマンス最適化）
+                    if col_widths and cell.column_letter in col_widths:
+                        cell_data["width"] = col_widths[cell.column_letter]
+                    # キャッシュから行高さを取得（パフォーマンス最適化）
+                    if row_heights and cell.row in row_heights:
+                        cell_data["height"] = row_heights[cell.row]
+
         return cell_data
 
     def _parse_rows(
         self,
         rows: tuple[tuple[Cell, ...], ...],
+        include_cell_styles: bool = False,
         merged_cell_map: dict[str, str] | None = None,
         merged_anchor_value_map: dict[str, Any] | None = None,
+        col_widths: dict[str, float] | None = None,
+        row_heights: dict[int, float] | None = None,
     ) -> list[list[dict[str, Any]]]:
         """
         行データを解析してリスト形式で返す（コード重複削減用ヘルパー）
 
         Args:
             rows: 行データのタプル
+            include_cell_styles: セルのスタイル情報を含めるか
             merged_cell_map: マージセル情報
             merged_anchor_value_map: マージ範囲 -> アンカー値
+            col_widths: 列幅のキャッシュ（パフォーマンス最適化用）
+            row_heights: 行高さのキャッシュ（パフォーマンス最適化用）
 
         Returns:
             解析された行データのリスト
@@ -801,8 +867,11 @@ def _parse_rows(
             row_data = [
                 self._parse_cell(
                     cell,
+                    include_cell_styles,
                     merged_cell_map,
                     merged_anchor_value_map,
+                    col_widths,
+                    row_heights,
                 )
                 for cell in row
             ]

tests/test_server.py

@@ -225,6 +225,7 @@ def test_excel_read_default(
                     sheet_name=None,
                     cell_range=None,
                     include_frozen_rows=True,
+                    include_cell_styles=False,
                 )
 
     @pytest.mark.unit
@@ -265,6 +266,7 @@ def test_excel_with_sheet_parameter(
                     sheet_name="Sheet2",
                     cell_range=None,
                     include_frozen_rows=True,
+                    include_cell_styles=False,
                 )
 
     @pytest.mark.unit
@@ -287,6 +289,7 @@ def test_excel_with_cell_range_parameter(
                     sheet_name="Sheet1",
                     cell_range="A1:D10",
                     include_frozen_rows=True,
+                    include_cell_styles=False,
                 )
 
     @pytest.mark.unit