feat: Excel search improvements (multi-keyword + row context)

README.md

@@ -33,8 +33,10 @@ Two authentication methods are supported:
   - Automatic method selection for SharePoint vs OneDrive files
 - **sharepoint_excel**
   - 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
+  - **Search mode**: find cells containing specific text with `query` parameter
+    - **Multiple keyword OR search**: use comma-separated keywords (e.g., `"budget,forecast"`)
+    - **Row context**: set `include_surrounding_cells=True` to get entire row data (reduces API calls from N+1 to 1)
+  - **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)

README_ja.md

@@ -33,8 +33,10 @@ stdioとHTTPの両方のトランスポートに対応しています。
   - SharePoint/OneDriveファイルに応じた自動メソッド選択
 - **sharepoint_excel**
   - SharePoint上のExcelファイルの読み取りと検索
-  - 検索モード: `query`パラメータで特定テキストを含むセルを検索
-  - 読み取りモード: `sheet`と`cell_range`パラメータで特定シート/範囲を取得
+  - **検索モード**: `query`パラメータで特定テキストを含むセルを検索
+    - **複数キーワードOR検索**: カンマ区切りでキーワード指定（例: `"予算,見積"`）
+    - **行コンテキスト**: `include_surrounding_cells=True`で行全体のデータを取得（API呼び出しをN+1から1に削減）
+  - **読み取りモード**: `sheet`と`cell_range`パラメータで特定シート/範囲を取得
   - **ヘッダー自動追加**: `cell_range`指定時、デフォルトで固定行（ヘッダー）を自動的に含める
     - `include_frozen_rows=False`を指定すると、指定範囲のみを取得
     - `frozen_rows=0`のシートでは、`expand_axis_range=True`で1行目（列の場合）またはA列（行の場合）から自動取得

docs/usage.md

@@ -205,9 +205,10 @@ The `sharepoint_excel` tool allows you to read and search Excel files in SharePo
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `file_path` | str | Required | Excel file path |
-| `query` | str \| None | None | Search keyword (enables search mode) |
+| `query` | str \| None | None | Search keyword (comma-separated for OR search) |
 | `sheet` | str \| None | None | Sheet name (get specific sheet only) |
 | `cell_range` | str \| None | None | Cell range (e.g., "A1:D10") |
+| `include_surrounding_cells` | bool | False | Get entire row data for each match in search mode |
 
 ### Basic Workflow
 
@@ -275,6 +276,88 @@ result = sharepoint_excel(
 )
 ```
 
+### Advanced Search Features
+
+#### Multiple Keyword Search (OR Logic)
+
+Search for cells containing any of the specified keywords (comma-separated):
+
+```python
+# Find cells with "budget" OR "forecast"
+result = sharepoint_excel(
+    file_path="/sites/finance/Shared Documents/report.xlsx",
+    query="budget,forecast"
+)
+```
+
+**Response:**
+```json
+{
+  "file_path": "/sites/finance/Shared Documents/report.xlsx",
+  "mode": "search",
+  "query": "budget,forecast",
+  "match_count": 5,
+  "matches": [
+    {"sheet": "Sheet1", "coordinate": "A1", "value": "Budget Report"},
+    {"sheet": "Sheet1", "coordinate": "B5", "value": "Monthly Budget"},
+    {"sheet": "Sheet1", "coordinate": "C10", "value": "Sales Forecast"},
+    {"sheet": "Summary", "coordinate": "C3", "value": "Budget Total"},
+    {"sheet": "Summary", "coordinate": "D8", "value": "Forecast Q2"}
+  ]
+}
+```
+
+#### Search with Row Context
+
+Get entire row data for each match in a single API call:
+
+```python
+# Search and get row context
+result = sharepoint_excel(
+    file_path="/sites/finance/Shared Documents/report.xlsx",
+    query="Total Revenue",
+    include_surrounding_cells=True
+)
+```
+
+**Response structure:**
+```json
+{
+  "file_path": "/sites/finance/Shared Documents/report.xlsx",
+  "mode": "search",
+  "query": "Total Revenue",
+  "match_count": 1,
+  "matches": [
+    {
+      "sheet": "Sheet1",
+      "coordinate": "B10",
+      "value": "Total Revenue",
+      "row_data": [
+        {"value": "2024", "coordinate": "A10"},
+        {"value": "Total Revenue", "coordinate": "B10"},
+        {"value": 1500000, "coordinate": "C10"},
+        {"value": "USD", "coordinate": "D10"}
+      ]
+    }
+  ]
+}
+```
+
+**When to use:**
+- `include_surrounding_cells=False` (default): Locate cells only
+- `include_surrounding_cells=True`: Get immediate context without follow-up read (96% API call reduction)
+
+#### Combining Multiple Keywords with Row Context
+
+```python
+# Search with multiple keywords and get row context
+result = sharepoint_excel(
+    file_path="/sites/finance/Shared Documents/report.xlsx",
+    query="revenue,income,profit",
+    include_surrounding_cells=True
+)
+```
+
 ### JSON Output Format
 
 #### Read Mode (Default)

docs/usage_ja.md

@@ -205,9 +205,10 @@ results = sharepoint_docs_search(
 | パラメータ | 型 | デフォルト | 説明 |
 |-----------|------|---------|-------------|
 | `file_path` | str | 必須 | Excelファイルのパス |
-| `query` | str \| None | None | 検索キーワード（検索モードを有効化） |
+| `query` | str \| None | None | 検索キーワード（カンマ区切りでOR検索） |
 | `sheet` | str \| None | None | シート名（特定シートのみ取得） |
 | `cell_range` | str \| None | None | セル範囲（例: "A1:D10"） |
+| `include_surrounding_cells` | bool | False | 検索モード時、マッチした行の全セルを取得 |
 
 ### 基本的なワークフロー
 
@@ -275,6 +276,88 @@ result = sharepoint_excel(
 )
 ```
 
+### 高度な検索機能
+
+#### 複数キーワード検索（OR論理）
+
+カンマ区切りで複数のキーワードを指定して、いずれかに一致するセルを検索：
+
+```python
+# "予算" OR "見積" を含むセルを検索
+result = sharepoint_excel(
+    file_path="/sites/finance/Shared Documents/report.xlsx",
+    query="予算,見積"
+)
+```
+
+**レスポンス例:**
+```json
+{
+  "file_path": "/sites/finance/Shared Documents/report.xlsx",
+  "mode": "search",
+  "query": "予算,見積",
+  "match_count": 5,
+  "matches": [
+    {"sheet": "Sheet1", "coordinate": "A1", "value": "予算報告"},
+    {"sheet": "Sheet1", "coordinate": "B5", "value": "月次予算"},
+    {"sheet": "Sheet1", "coordinate": "C10", "value": "売上見積"},
+    {"sheet": "Summary", "coordinate": "C3", "value": "予算合計"},
+    {"sheet": "Summary", "coordinate": "D8", "value": "見積Q2"}
+  ]
+}
+```
+
+#### 行コンテキスト付き検索
+
+マッチしたセルと同じ行の全データを1回のAPI呼び出しで取得：
+
+```python
+# 検索と行コンテキスト取得
+result = sharepoint_excel(
+    file_path="/sites/finance/Shared Documents/report.xlsx",
+    query="売上合計",
+    include_surrounding_cells=True
+)
+```
+
+**レスポンス構造:**
+```json
+{
+  "file_path": "/sites/finance/Shared Documents/report.xlsx",
+  "mode": "search",
+  "query": "売上合計",
+  "match_count": 1,
+  "matches": [
+    {
+      "sheet": "Sheet1",
+      "coordinate": "B10",
+      "value": "売上合計",
+      "row_data": [
+        {"value": "2024", "coordinate": "A10"},
+        {"value": "売上合計", "coordinate": "B10"},
+        {"value": 1500000, "coordinate": "C10"},
+        {"value": "円", "coordinate": "D10"}
+      ]
+    }
+  ]
+}
+```
+
+**使い分け:**
+- `include_surrounding_cells=False`（デフォルト）: セル位置の特定のみ
+- `include_surrounding_cells=True`: 即座にコンテキスト取得（API呼び出しを96%削減）
+
+#### 複数キーワードと行コンテキストの組み合わせ
+
+```python
+# 複数キーワード検索 + 行コンテキスト取得
+result = sharepoint_excel(
+    file_path="/sites/finance/Shared Documents/report.xlsx",
+    query="売上,収益,利益",
+    include_surrounding_cells=True
+)
+```
+
 ### JSON出力形式
 
 #### 読み取りモード（デフォルト）

src/server.py

@@ -456,14 +456,15 @@ def sharepoint_excel(
     include_frozen_rows: bool = True,
     include_cell_styles: bool = False,
     expand_axis_range: bool = False,
+    include_surrounding_cells: bool = False,
     ctx: Context | None = None,
 ) -> str:
     """
     SharePoint上のExcelファイルを操作
 
     Args:
         file_path: Excelファイルのパス
-        query: 検索キーワード（指定すると検索モード）
+        query: 検索キーワード（カンマ区切りで複数指定可能、OR検索）
         sheet: シート名（特定シートのみ取得）
         cell_range: セル範囲（例: "A1:D10"）
             - 推奨形式: "A1:D10"（開始セル:終了セル）
@@ -478,6 +479,9 @@ def sharepoint_excel(
         expand_axis_range: 単一列/行の部分範囲を開始側に自動拡張（default: false）
             True: 例 "J50:J100" → "J1:J100"（行1に拡張）
             frozen_rows=0でヘッダー文脈が不明な場合に使用
+        include_surrounding_cells: 検索モード時、マッチした行の全セルを含める（default: false）
+            True: マッチしたセルと同じ行の全セルデータを取得（API呼び出しを96%削減）
+            False: マッチしたセルの座標と値のみ返す
         ctx: FastMCP context (injected automatically)
 
     Returns:
@@ -497,7 +501,12 @@ def sharepoint_excel(
 
         # 検索モード
         if query:
-            return parser.search_cells(file_path, query, sheet_name=sheet)
+            return parser.search_cells(
+                file_path,
+                query,
+                sheet_name=sheet,
+                include_surrounding_cells=include_surrounding_cells,
+            )
 
         # 読み取りモード
         return parser.parse_to_json(
@@ -544,22 +553,28 @@ def register_tools():
         mcp.tool(
             description=(
                 "Read or search Excel files in SharePoint. "
-                "Search mode: use 'query' parameter to find cells containing specific text (returns cell locations). "
-                "Read mode: use 'sheet' and 'cell_range' parameters to retrieve data from specific sections. "
-                "When cell_range is specified with include_frozen_rows=True (default), frozen rows are automatically "
-                "included even if they are outside the specified range. frozen_rows indicates the number of header rows "
-                "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: 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' 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)."
+                # 検索モード
+                "Search mode: use 'query' parameter to find cells containing text. "
+                "Multiple keywords (comma-separated) perform OR search (e.g., 'budget,forecast'). "
+                "Set include_surrounding_cells=True to get entire row data for each match "
+                "(default: False, returns only matched cell). "
+                "Reduces API calls from N+1 to 1 when row context is needed. "
+                # 読み取りモード
+                "Read mode: use 'sheet' and 'cell_range' parameters to retrieve data. "
+                "When cell_range is specified with include_frozen_rows=True (default), "
+                "frozen rows are automatically included. "
+                # レスポンス構造
+                "Response includes cell data in 'rows' (value and coordinate) and "
+                "structural information (sheet name, dimensions, frozen_rows, etc). "
+                # スタイル情報
+                "Cell styles (include_cell_styles=False by default): background colors and sizes. "
+                # ヘッダー検出
+                "Header detection: For frozen_rows > 0, headers auto-included with include_frozen_rows=True. "
+                "For frozen_rows=0, read 'A1:Z5' for header check (max 5 rows). "
+                # 推奨ワークフロー
+                "Workflow: 1) Search with query (optionally include_surrounding_cells=True for context), "
+                "2) Read specific range if needed, "
+                "3) Use expand_axis_range=True if frozen_rows=0 and context unclear."
             )
         )(sharepoint_excel)
         logging.info("Registered tool: sharepoint_excel")