Merge pull request #2 from jonemo/default-folders

Look for file in Desktop and Downloads directories if not given full path.

Author: jonemo

.github/workflows/tests.yml

@@ -8,7 +8,10 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [windows-latest, macos-latest]
 
     steps:
       - uses: actions/checkout@v4

openpyxl_mcp_server.py

@@ -21,13 +21,15 @@
     "e": "error",
 }
 
+FILEPATH_DOCSTRING = 'The path to the Excel workbook. For example, "~/Downloads/test.xlsx" or "C:\\myfolder\\myfile.xlsx". If only a filename is provided, the file will be searched for in the Desktop and Downloads folders.'
+
 
 @mcp.tool()
 async def get_cell_details(filepath: str, sheet_name: str, cell_name: str) -> str:
-    """Get value, data type, style, comments, formulas, hyperlinks, and other details for a single cell in a workbook.
+    f"""Get value, data type, style, comments, formulas, hyperlinks, and other details for a single cell in a workbook.
 
     Args:
-        file_path: The path to the Excel workbook. For example, "~/Downloads/test.xlsx" or "C:\\myfolder\\myfile.xlsx".
+        file_path: {FILEPATH_DOCSTRING}
         sheet_name: The name of the sheet to get the value from.
         cell name: The name of the cell to get the value from. For example, "A1", "B2", "R5987".
     """
@@ -199,10 +201,10 @@ async def get_cell_details(filepath: str, sheet_name: str, cell_name: str) -> st
 
 @mcp.tool()
 async def get_cell_value(filepath: str, sheet_name: str, cell_name: str) -> str:
-    """Get the raw value of a single cell in a workbook.
+    f"""Get the raw value of a single cell in a workbook.
 
     Args:
-        file_path: The path to the Excel workbook. For example, "~/Downloads/test.xlsx" or "C:\\myfolder\\myfile.xlsx".
+        file_path: {FILEPATH_DOCSTRING}
         sheet_name: The name of the sheet to get the value from.
         cell name: The name of the cell to get the value from. For example, "A1", "B2", "R5987".
     """
@@ -217,10 +219,10 @@ async def get_cell_value(filepath: str, sheet_name: str, cell_name: str) -> str:
 async def get_values_of_cell_range(
     filepath: str, sheet_name: str, top_left_cell: str, bottom_right_cell: str
 ) -> str:
-    """Get the value, data type, style, and any comments, of a continuous range of cells in an Excel workbook.
+    f"""Get the value, data type, style, and any comments, of a continuous range of cells in an Excel workbook.
 
     Args:
-        file_path: The path to the Excel workbook. For example, "~/Downloads/test.xlsx" or "C:\\myfolder\\myfile.xlsx".
+        file_path: {FILEPATH_DOCSTRING}
         sheet_name: The name of the sheet to get the value from.
         top_left_cell: The top left cell of the range. For example, "A1".
         bottom_right_cell: The bottom right cell of the range. For example, "RC976".
@@ -242,10 +244,10 @@ async def get_values_of_cell_range(
 async def get_content_of_cell_list(
     filepath: str, sheet_name: str, cell_name_list: list[str]
 ) -> str:
-    """Get the raw values of a list of specific named cells in an Excel workbook.
+    f"""Get the raw values of a list of specific named cells in an Excel workbook.
 
     Args:
-        file_path: The path to the Excel workbook. For example, "~/Downloads/test.xlsx" or "C:\\myfolder\\myfile.xlsx".
+        file_path: {FILEPATH_DOCSTRING}
         sheet_name: The name of the sheet to get the value from.
         cell_name_list: A list of cell names. For example, ["A1", "B2", "C3"].
     """
@@ -268,10 +270,10 @@ async def search_in_cell_range(
     search_string: str,
     exact_match: bool = False,
 ) -> str:
-    """Search for a string in a continuous range of cells in an Excel workbook.
+    f"""Search for a string in a continuous range of cells in an Excel workbook.
 
     Args:
-        file_path: The path to the Excel workbook. For example, "~/Downloads/test.xlsx" or "C:\\myfolder\\myfile.xlsx".
+        file_path: {FILEPATH_DOCSTRING}
         sheet_name: The name of the sheet to get the value from.
         top_left_cell: The top left cell of the range. For example, "A1".
         bottom_right_cell: The bottom right cell of the range. For example, "RC976".
@@ -298,10 +300,10 @@ async def search_in_cell_range(
 
 @mcp.tool()
 async def get_list_of_sheets(filepath: str) -> str:
-    """Get a list of sheets in an Excel workbook. Each line contains a sheet's name and dimensions.
+    f"""Get a list of sheets in an Excel workbook. Each line contains a sheet's name and dimensions.
 
     Args:
-        file_path: The path to the Excel workbook. For example, "~/Downloads/test.xlsx" or "C:\\myfolder\\myfile.xlsx".
+        file_path: {FILEPATH_DOCSTRING}
     """
     filepath_clean = resolve_path_and_assert_file_exists(filepath)
     wb = load_workbook(filename=filepath_clean)
@@ -313,9 +315,20 @@ async def get_list_of_sheets(filepath: str) -> str:
 
 def resolve_path_and_assert_file_exists(filepath: str) -> Path:
     expanded_path = Path(filepath).expanduser()
-    if not expanded_path.exists():
-        raise ValueError(f"File {expanded_path} does not exist 2")
-    return expanded_path
+    if expanded_path.exists():
+        return expanded_path
+    # If filepath is just a filename and this is Winodws or MacOS, try the default locations of the Desktop and
+    # Downloads directories
+    is_windows = sys.platform == "win32" and "\\" not in filepath
+    is_macos = sys.platform == "darwin" and "/" not in filepath
+    if is_windows or is_macos:
+        path_in_desktop = Path.home() / "Desktop" / filepath
+        if path_in_desktop.exists():
+            return path_in_desktop
+        path_in_downloads = Path.home() / "Downloads" / filepath
+        if path_in_downloads.exists():
+            return path_in_downloads
+    raise ValueError(f"File '{filepath}' does not exist")
 
 
 def get_sheet_and_assert_it_exists(wb: Workbook, sheet_name: str) -> Worksheet:

test_openpyxl_mcp_server.py

@@ -1,6 +1,10 @@
+import tempfile
+from unittest.mock import patch
+
 import pytest
 from pathlib import Path
 from openpyxl_mcp_server import get_list_of_sheets
+from openpyxl_mcp_server import resolve_path_and_assert_file_exists
 
 
 @pytest.mark.asyncio
@@ -11,4 +15,37 @@ async def test_get_list_of_sheets():
     sheets = result.split("\n")
     assert len(sheets) == 2
     assert sheets[0] == "Name: First Worksheet, Dimensions: A1:F4"
+    # Yes, you can have use emojis in sheet names:
     assert sheets[1] == "Name: 🧮, Dimensions: A1:B1"
+
+
+def test_resolve_path_and_assert_file_exists_full_path():
+    test_file = Path(__file__).parent / "testdata" / "simple_workbook.xlsx"
+    result = resolve_path_and_assert_file_exists(str(test_file))
+    assert result == test_file
+
+
+def test_resolve_path_and_assert_file_exists_in_home_folder():
+    test_file_name = "file_in_home_folder.xlsx"
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_dir_path = Path(temp_dir)
+        test_file_path = temp_dir_path / test_file_name
+        test_file_path.touch()
+        with patch("openpyxl_mcp_server.Path.expanduser", return_value=test_file_path):
+            result = resolve_path_and_assert_file_exists(f"~/{test_file_name}")
+            assert result == test_file_path
+
+
+@pytest.mark.parametrize("home_folder_name", ["Desktop", "Downloads"])
+def test_resolve_path_and_assert_file_exists_in_default_folder(home_folder_name):
+    test_file_name = "file_in_desktop_folder.xlsx"
+    # Make a temporary directory with the file, then mock Path.home() to return that directory
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_dir_path = Path(temp_dir)
+        home_folder_path = temp_dir_path / home_folder_name
+        home_folder_path.mkdir(parents=True, exist_ok=True)
+        test_file_path = home_folder_path / test_file_name
+        test_file_path.touch()
+        with patch("openpyxl_mcp_server.Path.home", return_value=temp_dir_path):
+            result = resolve_path_and_assert_file_exists(test_file_name)
+            assert result == test_file_path