Merge pull request #53 from ncdcdev/feat/issue-47-expand-axis-range-option

feat: make expand_axis_range optional with default false (#47)

Author: k-ibaraki

README.md

@@ -37,6 +37,7 @@ 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
+    - For sheets with `frozen_rows=0`, use `expand_axis_range=True` to include row 1 (for columns) or column A (for rows)
   - **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

README_ja.md

@@ -37,6 +37,7 @@ stdioとHTTPの両方のトランスポートに対応しています。
   - 読み取りモード: `sheet`と`cell_range`パラメータで特定シート/範囲を取得
   - **ヘッダー自動追加**: `cell_range`指定時、デフォルトで固定行（ヘッダー）を自動的に含める
     - `include_frozen_rows=False`を指定すると、指定範囲のみを取得
+    - `frozen_rows=0`のシートでは、`expand_axis_range=True`で1行目（列の場合）またはA列（行の場合）から自動取得
   - **セルスタイル情報**（オプション）: `include_cell_styles=True`を指定すると、背景色・列幅・行高さを取得
     - デフォルトは`False`でトークン消費を最小化
     - 強調表示されたセル、色付きヘッダー、視覚的に強調されたコンテンツの識別に便利

src/server.py

@@ -455,6 +455,7 @@ def sharepoint_excel(
     cell_range: str | None = None,
     include_frozen_rows: bool = True,
     include_cell_styles: bool = False,
+    expand_axis_range: bool = False,
     ctx: Context | None = None,
 ) -> str:
     """
@@ -467,15 +468,16 @@ def sharepoint_excel(
         cell_range: セル範囲（例: "A1:D10"）
             - 推奨形式: "A1:D10"（開始セル:終了セル）
             - 列のみ: "A:D" も可（自動的に行範囲が追加されます）
-            - ⚠️ 単一列/行の部分範囲は開始側のみ 1/A に自動拡張されます
-              例: "J50:J100" → "J1:J100"（開始行が 1 行目に拡張されます）
         include_frozen_rows: cell_range指定時に固定行を自動追加（デフォルト: True）
             True: frozen_rowsで指定された行（通常はヘッダー）を自動的に取得
             False: 指定されたcell_rangeのみを取得
         include_cell_styles: セルの色・サイズ情報（default: false）
             色分けされたデータを抽出する場合のみTrueを指定
             背景色（fill）、列幅（width）、行高さ（height）を取得
             ※トークン消費が約20%増加
+        expand_axis_range: 単一列/行の部分範囲を開始側に自動拡張（default: false）
+            True: 例 "J50:J100" → "J1:J100"（行1に拡張）
+            frozen_rows=0でヘッダー文脈が不明な場合に使用
         ctx: FastMCP context (injected automatically)
 
     Returns:
@@ -504,6 +506,7 @@ def sharepoint_excel(
             cell_range=cell_range,
             include_frozen_rows=include_frozen_rows,
             include_cell_styles=include_cell_styles,
+            expand_axis_range=expand_axis_range,
         )
 
     except Exception as e:
@@ -549,10 +552,14 @@ def register_tools():
                 "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. "
+                "Header detection: For sheets with frozen_rows > 0, headers are automatically included with include_frozen_rows=True (default). "
+                "For sheets with frozen_rows=0, headers are not automatically included and context may be unclear. "
                 "ALWAYS read exactly 5 rows for header check: 'A1:Z5' (NOT 'A1:Z50' or more). "
                 "Prefer 'query' search when possible to locate data first. "
-                "Workflow: 1) Search OR read 'A1:Z5', 2) Read specific range only."
+                "Workflow: 1) Search OR read 'A1:Z5' for header check, "
+                "2) Read specific range (include_frozen_rows adds frozen headers automatically), "
+                "3) If frozen_rows=0 and header context is unclear, retry with expand_axis_range=True "
+                "to auto-include row 1 (for columns) or column A (for rows)."
             )
         )(sharepoint_excel)
         logging.info("Registered tool: sharepoint_excel")

src/sharepoint_excel.py

@@ -108,6 +108,7 @@ def parse_to_json(
         cell_range: str | None = None,
         include_frozen_rows: bool = True,
         include_cell_styles: bool = False,
+        expand_axis_range: bool = False,
     ) -> str:
         """
         Excelファイルを解析してJSON形式で返す
@@ -121,6 +122,9 @@ def parse_to_json(
                 False: 指定されたcell_rangeのみを取得
             include_cell_styles: セルの色・サイズ情報（default: false）
                 色分けデータ抽出時のみ使用。トークン消費+約20%
+            expand_axis_range: 単一列/行指定時に開始側を自動拡張（default: false）
+                True: 例 "J50:J100" → "J1:J100"（行1に拡張）
+                False: 指定範囲をそのまま使用
 
         Returns:
             JSON文字列
@@ -212,6 +216,7 @@ def parse_to_json(
                     cell_range,
                     include_frozen_rows,
                     include_cell_styles,
+                    expand_axis_range,
                 )
                 result["sheets"].append(sheet_data)
 
@@ -399,6 +404,7 @@ def _parse_sheet(
         cell_range: str | None = None,
         include_frozen_rows: bool = True,
         include_cell_styles: bool = False,
+        expand_axis_range: bool = False,
     ) -> dict[str, Any]:
         """
         シートを解析してdict形式で返す
@@ -408,6 +414,7 @@ def _parse_sheet(
             cell_range: セル範囲指定（例: "A1:D10"）
             include_frozen_rows: cell_range指定時に固定行（ヘッダー）を自動追加
             include_cell_styles: セルのスタイル情報を含めるか
+            expand_axis_range: 単一列/行指定時に開始側を自動拡張
 
         Returns:
             シートデータのdict
@@ -446,22 +453,36 @@ def _parse_sheet(
         sheet_data["frozen_rows"] = frozen_rows
         sheet_data["frozen_cols"] = frozen_cols
 
+        # frozen_rows=0 かつ cell_range指定時、expand_axis_range=Falseの場合のみ警告
+        # expand_axis_range=Trueの場合は1行目/A列が含まれるため警告不要
+        if frozen_rows == 0 and cell_range and not expand_axis_range:
+            sheet_data["header_detection"] = {
+                "status": "no_frozen_rows",
+                "frozen_rows": 0,
+                "note": "This sheet has no frozen rows. Headers are not automatically included.",
+                "suggestions": [
+                    "If headers are needed, read 'A1:Z5' to check header structure",
+                    "Or retry with expand_axis_range=True to include row 1 (for columns) or column A (for rows)",
+                ],
+            }
+
         # セル範囲の正規化・拡張（cell_rangeがある場合）
         # マージセル情報のキャッシュに使用するため、先に計算する
         effective_range_for_merge = None
         header_range = None  # ヘッダー範囲（再利用のため事前に初期化）
         if cell_range:
             sheet_data["requested_range"] = cell_range
             effective_range = self._normalize_column_range(cell_range, sheet)
-            expanded_range = self._expand_axis_range(effective_range)
-            if expanded_range != effective_range:
-                logger.info(
-                    "Expanded axis range '%s' -> '%s' (sheet=%s)",
-                    effective_range,
-                    expanded_range,
-                    sheet.title,
-                )
-                effective_range = expanded_range
+            if expand_axis_range:
+                expanded_range = self._expand_axis_range(effective_range)
+                if expanded_range != effective_range:
+                    logger.info(
+                        "Expanded axis range '%s' -> '%s' (sheet=%s)",
+                        effective_range,
+                        expanded_range,
+                        sheet.title,
+                    )
+                    effective_range = expanded_range
 
             if effective_range != cell_range:
                 logger.info(

tests/test_server.py

@@ -226,6 +226,7 @@ def test_excel_read_default(
                     cell_range=None,
                     include_frozen_rows=True,
                     include_cell_styles=False,
+                    expand_axis_range=False,
                 )
 
     @pytest.mark.unit
@@ -267,6 +268,7 @@ def test_excel_with_sheet_parameter(
                     cell_range=None,
                     include_frozen_rows=True,
                     include_cell_styles=False,
+                    expand_axis_range=False,
                 )
 
     @pytest.mark.unit
@@ -290,6 +292,7 @@ def test_excel_with_cell_range_parameter(
                     cell_range="A1:D10",
                     include_frozen_rows=True,
                     include_cell_styles=False,
+                    expand_axis_range=False,
                 )
 
     @pytest.mark.unit