feat: add include_cell_styles parameter for Excel cell formatting

Issue #43対応: Excelセル書式情報（背景色・列幅・行高さ）を取得する
include_cell_stylesパラメータを追加

設計方針:
- デフォルトはFalse（YAGNI原則、トークン消費最小化）
- 色分けされたデータ抽出時のみ使用を想定
- 実測でトークン消費+約20%

変更内容:
- src/sharepoint_excel.py: _parse_cell()にスタイル情報取得ロジック追加
- src/server.py: sharepoint_excel()にinclude_cell_stylesパラメータ追加
- tests/: 新規テスト4件追加、既存テスト3件修正
- README: パラメータドキュメント追加

LLMフィードバックに基づき、説明文を簡潔化:
- "default: false"を明記
- 用途を限定（"色分けデータ抽出時のみ"）
- 冗長な例示を削除

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

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(
@@ -530,6 +537,7 @@ def _parse_sheet(
                 all_rows.extend(
                     self._parse_rows(
                         header_rows,
+                        include_cell_styles,
                         merged_cell_map,
                         merged_anchor_value_map,
                     )
@@ -541,6 +549,7 @@ def _parse_sheet(
             all_rows.extend(
                 self._parse_rows(
                     rows_to_process,
+                    include_cell_styles,
                     merged_cell_map,
                     merged_anchor_value_map,
                 )
@@ -554,6 +563,7 @@ def _parse_sheet(
                 all_rows.extend(
                     self._parse_rows(
                         rows_to_process,
+                        include_cell_styles,
                         merged_cell_map,
                         merged_anchor_value_map,
                     )
@@ -741,6 +751,7 @@ 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,
     ) -> dict[str, Any]:
@@ -749,6 +760,7 @@ def _parse_cell(
 
         Args:
             cell: openpyxl Cell
+            include_cell_styles: セルのスタイル情報を含めるか（デフォルト: False）
             merged_cell_map: マージセル座標からマージ範囲へのマップ（パフォーマンス最適化用）
             merged_anchor_value_map: マージ範囲 -> アンカー値 のマップ（結合セルの値埋め用）
 
@@ -776,12 +788,43 @@ 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:
+                    sheet = cell.parent
+                    # 列幅
+                    if cell.column_letter in sheet.column_dimensions:
+                        col_dim = sheet.column_dimensions[cell.column_letter]
+                        if col_dim.width:
+                            cell_data["width"] = col_dim.width
+                    # 行高さ
+                    if cell.row in sheet.row_dimensions:
+                        row_dim = sheet.row_dimensions[cell.row]
+                        if row_dim.height:
+                            cell_data["height"] = row_dim.height
+
         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,
     ) -> list[list[dict[str, Any]]]:
@@ -790,6 +833,7 @@ def _parse_rows(
 
         Args:
             rows: 行データのタプル
+            include_cell_styles: セルのスタイル情報を含めるか
             merged_cell_map: マージセル情報
             merged_anchor_value_map: マージ範囲 -> アンカー値
 
@@ -801,6 +845,7 @@ def _parse_rows(
             row_data = [
                 self._parse_cell(
                     cell,
+                    include_cell_styles,
                     merged_cell_map,
                     merged_anchor_value_map,
                 )

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

tests/test_sharepoint_excel.py

@@ -1389,3 +1389,119 @@ def test_frozen_rows_dos_mitigation_custom_limit(self):
 
         sheet_data = result["sheets"][0]
         assert sheet_data["frozen_rows"] == 120
+
+    def test_parse_with_cell_styles_disabled(self):
+        """include_cell_styles=False（デフォルト）でスタイル情報が含まれないこと"""
+        excel_bytes = self._create_formatted_excel()
+        self.mock_download_client.download_file.return_value = excel_bytes
+
+        parser = SharePointExcelParser(self.mock_download_client)
+        # デフォルト（include_cell_styles=False）で解析
+        result_json = parser.parse_to_json("/test/formatted.xlsx")
+
+        result = json.loads(result_json)
+        cell = result["sheets"][0]["rows"][0][0]
+
+        # value と coordinate は含まれる
+        assert "value" in cell
+        assert "coordinate" in cell
+        assert cell["value"] == "Name"
+
+        # スタイル情報は含まれない
+        assert "fill" not in cell
+        assert "width" not in cell
+        assert "height" not in cell
+
+    def test_parse_with_cell_styles_enabled(self):
+        """include_cell_styles=Trueでスタイル情報が含まれること"""
+        excel_bytes = self._create_formatted_excel()
+        self.mock_download_client.download_file.return_value = excel_bytes
+
+        parser = SharePointExcelParser(self.mock_download_client)
+        # include_cell_styles=Trueで解析
+        result_json = parser.parse_to_json(
+            "/test/formatted.xlsx", include_cell_styles=True
+        )
+
+        result = json.loads(result_json)
+        cell = result["sheets"][0]["rows"][0][0]
+
+        # 基本情報は含まれる
+        assert cell["value"] == "Name"
+        assert cell["coordinate"] == "A1"
+
+        # 背景色情報が含まれる
+        assert "fill" in cell
+        assert cell["fill"]["pattern_type"] == "solid"
+        assert "fg_color" in cell["fill"]
+        # 16進数形式であることを確認
+        if cell["fill"]["fg_color"]:
+            assert cell["fill"]["fg_color"].startswith("#")
+
+    def test_cell_styles_with_width_height(self):
+        """列幅・行高さが設定されたセルでwidth/heightが正しく返されること"""
+        wb = Workbook()
+        ws = wb.active
+        ws.title = "SizedSheet"
+
+        # セルにデータを設定
+        ws["A1"] = "Wide Column"
+        ws["A2"] = "Tall Row"
+
+        # 列幅と行高さを設定
+        ws.column_dimensions["A"].width = 30
+        ws.row_dimensions[2].height = 50
+
+        excel_bytes = BytesIO()
+        wb.save(excel_bytes)
+        excel_bytes.seek(0)
+
+        self.mock_download_client.download_file.return_value = excel_bytes.getvalue()
+
+        parser = SharePointExcelParser(self.mock_download_client)
+        result_json = parser.parse_to_json("/test/sized.xlsx", include_cell_styles=True)
+
+        result = json.loads(result_json)
+        rows = result["sheets"][0]["rows"]
+
+        # A1セル: 列幅が設定されている
+        cell_a1 = rows[0][0]
+        assert cell_a1["coordinate"] == "A1"
+        assert "width" in cell_a1
+        assert cell_a1["width"] == 30
+
+        # A2セル: 列幅と行高さが設定されている
+        cell_a2 = rows[1][0]
+        assert cell_a2["coordinate"] == "A2"
+        assert "width" in cell_a2
+        assert cell_a2["width"] == 30
+        assert "height" in cell_a2
+        assert cell_a2["height"] == 50
+
+    def test_cell_styles_none_when_not_set(self):
+        """スタイルが設定されていないセルではfillなどが含まれないこと"""
+        # シンプルなExcelファイルを作成（スタイルなし）
+        excel_bytes = self._create_test_excel()
+        self.mock_download_client.download_file.return_value = excel_bytes
+
+        parser = SharePointExcelParser(self.mock_download_client)
+        # include_cell_styles=Trueで解析
+        result_json = parser.parse_to_json(
+            "/test/file.xlsx", include_cell_styles=True
+        )
+
+        result = json.loads(result_json)
+        cell = result["sheets"][0]["rows"][0][0]
+
+        # 基本情報は含まれる
+        assert cell["value"] == "Name"
+        assert cell["coordinate"] == "A1"
+
+        # スタイルが設定されていないので、fillやwidth/heightは含まれない
+        # （openpyxlがデフォルト値を返す場合もあるが、明示的に設定されていない）
+        # fill情報がない、またはpattern_typeがNoneの場合は含まれない
+        if "fill" in cell:
+            # fillが含まれる場合でも、pattern_typeが設定されていないはず
+            assert cell["fill"].get("pattern_type") is None or cell["fill"].get(
+                "pattern_type"
+            ) == "none"