Merge pull request #54 from ncdcdev/feat/merge-4-refine-excel

Feat/merge 4 refine excel

Author: k-ibaraki

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
   pull_request:
-    branches: [ main ]
+    branches: [ main, feat/refine-excel-reading ]
   push:
     branches: [ main ]
 

CLAUDE.md

@@ -67,6 +67,32 @@ def some_function():
     return something()
 ```
 
+## Design Principles
+
+### MCP Server Design Philosophy
+
+**Simplicity over Complexity**
+- Prefer simple, explicit APIs over "smart" automatic conversions
+- Trust LLM's ability to learn from clear error messages
+- Avoid over-engineering: features are easy to add but hard to remove
+
+**YAGNI (You Aren't Gonna Need It)**
+- Only implement features when they are clearly needed
+- Before adding a feature, ask: "Can LLM handle this on its own?"
+- Consider long-term maintenance cost vs. short-term convenience
+
+**Feature Addition Checklist**
+- [ ] Is this feature truly necessary? (Can't LLM adapt?)
+- [ ] Is there a simpler alternative?
+- [ ] Can this be removed in the future without breaking compatibility?
+- [ ] Is the maintenance cost acceptable?
+- [ ] Does this add significant value to justify the complexity?
+
+**Context Efficiency**
+- Keep tool descriptions concise (they're included in every LLM call)
+- Prioritize essential information over exhaustive documentation
+- Use external docs (README) for detailed explanations
+
 ### Project-Specific Guidelines
 
 #### MCP Development

README.md

@@ -35,10 +35,14 @@ 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)
+  - **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
+  - 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
 
 ### OneDrive Support

README_ja.md

@@ -35,10 +35,14 @@ stdioとHTTPの両方のトランスポートに対応しています。
   - SharePoint上のExcelファイルの読み取りと検索
   - 検索モード: `query`パラメータで特定テキストを含むセルを検索
   - 読み取りモード: `sheet`と`cell_range`パラメータで特定シート/範囲を取得
-  - ヘッダー自動追加: `include_header`パラメータで`freeze_panes`で固定された行をヘッダーとして認識し、範囲指定時にヘッダーが範囲外でも自動的に追加
-  - メタデータのみ取得: `metadata_only`パラメータでデータ行を除外し、ヘッダーとファイル構造のみ取得
-  - デフォルト: 値と座標のみの軽量レスポンス
-  - オプション: 書式情報を含む（データ型、塗りつぶし色、結合セル、サイズ）
+  - **ヘッダー自動追加**: `cell_range`指定時、デフォルトで固定行（ヘッダー）を自動的に含める
+    - `include_frozen_rows=False`を指定すると、指定範囲のみを取得
+    - `frozen_rows=0`のシートでは、`expand_axis_range=True`で1行目（列の場合）またはA列（行の場合）から自動取得
+  - **セルスタイル情報**（オプション）: `include_cell_styles=True`を指定すると、背景色・列幅・行高さを取得
+    - デフォルトは`False`でトークン消費を最小化
+    - 強調表示されたセル、色付きヘッダー、視覚的に強調されたコンテンツの識別に便利
+  - レスポンスには`rows`内のセルデータ（値と座標）と構造情報（利用可能な場合）を含む
+  - 構造情報: シート名、dimensions、frozen_rows、frozen_cols、freeze_panes（存在する場合）、merged_ranges（結合セルが存在する場合）
   - 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,6 @@ 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) |
 
 ### Basic Workflow
 
@@ -256,103 +275,6 @@ result = sharepoint_excel(
 )
 ```
 
-#### 5. Read with Formatting Information
-```python
-# Get data with formatting (colors, merged cells, etc.)
-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`
-
 ### JSON Output Format
 
 #### Read Mode (Default)
@@ -400,7 +322,9 @@ result = sharepoint_excel(
 }
 ```
 
-#### With Formatting (include_formatting=true)
+#### Merged Cells
+
+When merged cells exist, the response includes merged cell information:
 
 ```json
 {
@@ -414,20 +338,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 +365,33 @@ 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:**
 - **merged**: Merged cell information (range, position)
-- **width**: Column width
-- **height**: Row height
+- **merged_ranges**: Merged ranges list per sheet (range + anchor info)
+
+### 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 +409,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**