Merge pull request #35 from ncdcdev/fix/excel-merged-cells

fix: JSON出力に結合セル情報を含める

Author: k-ibaraki

README.md

@@ -35,10 +35,9 @@ Two authentication methods are supported:
   - Read or search Excel files in SharePoint
   - Search mode: find cells containing specific text with `query` parameter
   - Read mode: get data from specific sheets/ranges with `sheet` and `cell_range` parameters
-  - Auto-include headers: with `include_header` parameter, automatically includes frozen rows (detected via `freeze_panes`) as headers even when they're outside the specified cell range
-  - Metadata-only mode: exclude data rows and retrieve only headers and file structure with `metadata_only` parameter
-  - Default: lightweight response with value and coordinate only
-  - Optional: include formatting (data_type, fill colors, merged cells, dimensions)
+  - Response includes data in `rows` and structure info (`freeze_panes`, `merged_ranges`) when available
+  - Default: value + coordinate (structural info such as merged ranges is included when present)
+  - Optional: include_formatting currently does not change the output; structural info is still included only when present
   - No Excel Services dependency - uses direct file download + openpyxl parsing
 
 ### OneDrive Support

README_ja.md

@@ -35,10 +35,9 @@ stdioとHTTPの両方のトランスポートに対応しています。
   - SharePoint上のExcelファイルの読み取りと検索
   - 検索モード: `query`パラメータで特定テキストを含むセルを検索
   - 読み取りモード: `sheet`と`cell_range`パラメータで特定シート/範囲を取得
-  - ヘッダー自動追加: `include_header`パラメータで`freeze_panes`で固定された行をヘッダーとして認識し、範囲指定時にヘッダーが範囲外でも自動的に追加
-  - メタデータのみ取得: `metadata_only`パラメータでデータ行を除外し、ヘッダーとファイル構造のみ取得
-  - デフォルト: 値と座標のみの軽量レスポンス
-  - オプション: 書式情報を含む（データ型、塗りつぶし色、結合セル、サイズ）
+  - 構造情報（`freeze_panes`）とデータを `rows` で常に返却し、結合セルがある場合は `merged_ranges` も含めて返却
+  - デフォルト: 値と座標のみ（結合セルがある場合は merged / merged_ranges を追加）
+  - オプション: include_formatting を指定しても返却内容（値・座標・結合セル情報など）は変わらない（結合セル情報は結合セルが存在する場合にのみ付与）
   - Excel Services不要 - 直接ファイルダウンロード+openpyxl解析方式
 
 ### OneDrive対応

docs/usage.md

@@ -166,6 +166,28 @@ SHAREPOINT_ONEDRIVE_PATHS=sales1@company.com:/Documents/Customers,sales2@company
 SHAREPOINT_SITE_NAME=@onedrive,sales-team,customer-portal
 ```
 
+### `sharepoint_docs_search` Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `query` | str | Required | Search keyword |
+| `max_results` | int | 20 | Max results (capped at 100) |
+| `file_extensions` | list[str] \| None | None | File extensions filter (unsupported values are ignored) |
+| `response_format` | str | `detailed` | `detailed` or `compact` |
+
+- `max_results` is capped at 100.
+- `file_extensions` is filtered by `SHAREPOINT_ALLOWED_FILE_EXTENSIONS`; unsupported values are ignored.
+- `response_format="compact"` returns only `title` / `path` / `extension` to reduce tokens.
+
+**Compact response example**
+```python
+results = sharepoint_docs_search(
+    query="budget 2024",
+    response_format="compact",
+    max_results=10,
+)
+```
+
 ## Excel Operations Usage Examples
 
 The `sharepoint_excel` tool allows you to read and search Excel files in SharePoint. It supports two modes:
@@ -186,9 +208,7 @@ The `sharepoint_excel` tool allows you to read and search Excel files in SharePo
 | `query` | str \| None | None | Search keyword (enables search mode) |
 | `sheet` | str \| None | None | Sheet name (get specific sheet only) |
 | `cell_range` | str \| None | None | Cell range (e.g., "A1:D10") |
-| `include_formatting` | bool | False | Include formatting information |
-| `include_header` | bool | True | Auto-detect and separate header rows using `freeze_panes` |
-| `metadata_only` | bool | False | Exclude data rows to return only metadata (reduce response size) |
+| `include_formatting` | bool | False | Does not change the output currently (merged info is always included when present) |
 
 ### Basic Workflow
 
@@ -256,102 +276,18 @@ result = sharepoint_excel(
 )
 ```
 
-#### 5. Read with Formatting Information
+#### 5. include_formatting flag (no output changes yet)
 ```python
-# Get data with formatting (colors, merged cells, etc.)
+# include_formatting flag (currently does not change output)
 result = sharepoint_excel(
     file_path="/sites/finance/Shared Documents/report.xlsx",
     sheet="Sheet1",
     include_formatting=True
 )
 ```
 
-#### 6. Automatic Header Detection
-```python
-# Auto-detect and separate header and data rows using freeze_panes
-result = sharepoint_excel(
-    file_path="/sites/finance/Shared Documents/report.xlsx",
-    sheet="Sheet1",
-    include_header=True
-)
-```
-
-**Header Detection Response:**
-```json
-{
-  "file_path": "/sites/finance/Shared Documents/report.xlsx",
-  "sheets": [{
-    "name": "Sheet1",
-    "freeze_panes": "B2",
-    "frozen_rows": 1,
-    "frozen_cols": 1,
-    "header_rows": [
-      [
-        {"value": "Product", "coordinate": "A1"},
-        {"value": "Price", "coordinate": "B1"},
-        {"value": "Stock", "coordinate": "C1"}
-      ]
-    ],
-    "data_rows": [
-      [
-        {"value": "Product A", "coordinate": "A2"},
-        {"value": 1000, "coordinate": "B2"},
-        {"value": 50, "coordinate": "C2"}
-      ],
-      ...
-    ]
-  }]
-}
-```
-
-**Features:**
-- Auto-detects Excel freeze panes (frozen rows/columns)
-- Separates header rows and data rows in response (default behavior)
-- When `cell_range` is specified, automatically includes frozen range
-- Set `include_header=False` to return legacy `rows` format
-```
-
-#### 7. Metadata-Only Mode (File Structure Inspection)
-```python
-# Get only file structure without data rows
-result = sharepoint_excel(
-    file_path="/sites/finance/Shared Documents/large-report.xlsx",
-    metadata_only=True
-)
-```
-
-**Metadata-Only Response:**
-```json
-{
-  "file_path": "/sites/finance/Shared Documents/large-report.xlsx",
-  "sheets": [{
-    "name": "Sheet1",
-    "freeze_panes": "B2",
-    "frozen_rows": 1,
-    "frozen_cols": 1,
-    "dimensions": "A1:E1000",
-    "header_rows": [
-      [
-        {"value": "Product", "coordinate": "A1"},
-        {"value": "Price", "coordinate": "B1"},
-        {"value": "Stock", "coordinate": "C1"}
-      ]
-    ],
-    "data_rows": []
-  }]
-}
-```
-
-**Use Cases:**
-- Inspect large file structure before fetching data
-- Understand what headers exist in each sheet
-- Determine the necessary `cell_range` before retrieving full data
-- Significantly reduce response size (save tokens)
-
-**Recommended Workflow:**
-1. Use `metadata_only=True` to inspect file structure
-2. Identify the required range
-3. Fetch actual data with specific `cell_range`
+Note: `include_formatting=true` currently does not return colors/width/height/types.  
+Merged cell info (`merged` / `merged_ranges`) is always included when present.
 
 ### JSON Output Format
 
@@ -400,7 +336,10 @@ result = sharepoint_excel(
 }
 ```
 
-#### With Formatting (include_formatting=true)
+#### Formatting (include_formatting behavior)
+
+In the current implementation, `include_formatting=true` does not change the output.  
+Merged cell info (`merged` / `merged_ranges`) is included regardless of `include_formatting`.
 
 ```json
 {
@@ -414,20 +353,21 @@ result = sharepoint_excel(
           {
             "value": "Department",
             "coordinate": "A1",
-            "data_type": "s",
-            "fill": {
-              "pattern_type": "solid",
-              "fg_color": "#CCCCCC",
-              "bg_color": null
-            },
             "merged": {
               "range": "A1:B1",
               "is_top_left": true
-            },
-            "width": 15.0,
-            "height": 20.0
+            }
           }
         ]
+      ],
+      "merged_ranges": [
+        {
+          "range": "A1:B1",
+          "anchor": {
+            "coordinate": "A1",
+            "value": "Department"
+          }
+        }
       ]
     }
   ]
@@ -440,12 +380,35 @@ result = sharepoint_excel(
 - **value**: Cell value (string, number, date, formula, etc.)
 - **coordinate**: Cell position (e.g., "A1", "B2")
 
-**With include_formatting=true:**
-- **data_type**: Data type code (`s`=string, `n`=number, `f`=formula, etc.)
-- **fill**: Fill color information (pattern type, foreground/background colors)
+**When merged cells exist (included regardless of include_formatting):**
 - **merged**: Merged cell information (range, position)
-- **width**: Column width
-- **height**: Row height
+- **merged_ranges**: Merged ranges list per sheet (range + anchor info)
+
+Note: `include_formatting` currently does not add formatting fields.
+
+### Additional Metadata
+
+Depending on the request, the response can include metadata such as `response_kind`, `data_included`, `requested_sheet`, `requested_range`, `freeze_panes`, `frozen_rows`, `frozen_cols`, `effective_range`, `sheet_resolution`, and `available_sheets`.
+
+### Sheet Resolution and Fallbacks
+
+- `sheet` is resolved by exact match or a unique `trim + casefold` match.
+- If not resolved, `sheet_resolution` and `available_sheets` are returned with a `warning`.
+- If `cell_range` is provided and `sheet` is not found, the parser falls back to all sheets.
+- If `sheet` is not found and no `cell_range` is provided, `sheets` is empty and `candidates` are returned.
+
+### Cell Range Normalization and Expansion
+
+`cell_range` is normalized/expanded internally, and the result is returned as `effective_range`.
+
+- Column-only ranges (e.g., `J` / `J:J`) expand to `J1:J<max_row>`.
+- Single cell ranges (e.g., `C5`) expand to `C1:C5`.
+- Single-row ranges (e.g., `D5:H5`) expand to `A5:H5`.
+
+### Large Range Limits
+
+If rows/cols exceed limits, a `ValueError` is raised.  
+Use `cell_range` to narrow the selection.
 
 ### Common Use Cases
 
@@ -463,18 +426,17 @@ search_result = sharepoint_excel(file_path=file_path, query="Total Revenue")
 data = sharepoint_excel(file_path=file_path, sheet="Sheet1", cell_range="A1:D20")
 ```
 
-**Analyze Cell Formatting**
+**Inspect Merged Cells**
 ```python
-# Get Excel data with formatting
-json_data = sharepoint_excel(file_path=file_path, include_formatting=True)
+# Get Excel data (merged info is included when present)
+json_data = sharepoint_excel(file_path=file_path)
 data = json.loads(json_data)
 
-# Find cells with specific formatting
+# List merged ranges
 for sheet in data["sheets"]:
-    for row in sheet["rows"]:
-        for cell in row:
-            if cell.get("fill", {}).get("fg_color"):
-                print(f"Colored cell at {cell['coordinate']}: {cell['value']}")
+    for merged in sheet.get("merged_ranges", []):
+        anchor = merged.get("anchor", {})
+        print(f"Merged range {merged['range']}: {anchor.get('value')}")
 ```
 
 **Export Specific Sheet to CSV**