chore(release): Bump version to 0.2.4 and improved test coverage.

- Added `notebook_get_outline` for analyzing notebook structure and extracting cell outlines.
- Introduced `notebook_search` for case-insensitive searching within notebook cells.
- Enhanced test coverage with dedicated tests for error paths and edge cases, improving overall code coverage to 84%.
- Updated version and clarified Python minimum version of 3.10

Author: jbeno

CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.4] - 2025-04-26
+
+### Added
+
+- Added tools to get an outline and search a notebook, so specific cells can be targeted for read/edit.
+- The `notebook_get_outline` method analyzes a Jupyter notebook's structure, extracting cell types, line counts, and outlines for code and markdown cells.
+- The `notebook_search` method allows for case-insensitive searching within notebook cells, returning matches with context snippets.
+- Added dedicated tests for error paths and edge cases in the NotebookTools module, focusing on improving code coverage.
+- Added tests for handling issues with `diagnose_imports`, including subprocess errors and malformed JSON.
+- Added validation tests for notebooks addressing invalid JSON and non-notebook files.
+- Added tests for outline extraction with invalid code syntax.
+- Added tests for empty search queries and behavior of large file truncation.
+- Added edge case tests for export functionality and cell transformations.
+
+### Changed
+- Improved overall code coverage to 84%.
+- Improved `tools.py` coverage to 80%.
+- Achieved 100% coverage for `notebook_ops.py`.
+
 ## [0.2.3] - 2025-04-20
 
 ### Added

README.md

@@ -26,7 +26,10 @@ This MCP server uses the `nbformat` library to safely manipulate notebook struct
 
 ## Latest Version
 
-**Current Version:** `0.2.3` - See the [CHANGELOG.md](CHANGELOG.md) for details on recent changes.
+**Current Version:** `0.2.4` - See the [CHANGELOG.md](CHANGELOG.md) for details on recent changes. Two new tools were added that make it easier to work with large notebooks:
+
+- `notebook_get_outline` analyzes a Jupyter notebook's structure, extracting cell types, line counts, and headings/functions/classes. It then returns an outline the agent can reference.
+- `notebook_search` enables case-insensitive searching within notebook cells. The results show which cell the match was found, and include contextual snippets. This helps the agent know which cell to read/edit when asked to modify something.
 
 ## Features
 
@@ -56,14 +59,16 @@ Exposes the following MCP tools (registered under the `notebook_mcp` server):
 *   `notebook_validate`: Validates the notebook structure against the `nbformat` schema.
 *   `notebook_get_info`: Retrieves general information (cell count, metadata, kernel, language info).
 *   `notebook_export`: Exports the notebook to another format (e.g., python, html) using nbconvert. **Note:** See External Dependencies below for requirements needed for certain export formats like PDF.
+* `notebook_get_outline`: Produces an outline showing cell numbers with major headings/functions and line counts to make it easier for the agent to navigate a large notebook.
+* `notebook_search`: Searches cells for a keyword, showing which cell matches were found with contextual snippets. This helps the agent know which cell to read/edit when asked to modify something.
 
 ## Requirements
 
 This project has both Python package dependencies and potentially external system dependencies for full functionality.
 
 ### Python Dependencies
 
-*   **Python Version:** 3.9+
+*   **Python Version:** 3.10+
 *   **Core:** `mcp>=0.1.0`, `nbformat>=5.0`, `nbconvert>=6.0`, `ipython`, `jupyter_core`. These are installed automatically when you install `cursor-notebook-mcp`.
 *   **Optional - SSE Transport:** `uvicorn>=0.20.0`, `starlette>=0.25.0`. Needed only if using the SSE transport mode. Install via `pip install cursor-notebook-mcp[sse]`.
 *   **Optional - Development/Testing:** `pytest>=7.0`, `pytest-asyncio>=0.18`, `pytest-cov`, `coveralls`. Install via `pip install -e ".[dev]"` from source checkout.
@@ -230,19 +235,19 @@ When using `sse`, you must run the server process manually first (see "Running t
 For smooth collaboration with the AI agent on Jupyter Notebooks, you might want to add rules like these to your Cursor configuration. Go to Cursor Settings > Rules and add them in either User Roles or Project Rules. This ensures that Cursor's AI features will consistently follow these best practices when working with Jupyter notebooks.
 
 ```markdown 
-### Jupyter Notebook Rules for Cursor (Using notebook_mcp):
+### Jupyter Notebook Rules (Using notebook_mcp):
 
 1.  **Tool Usage:**
     *   Always use the tools provided by the `notebook_mcp` server for operations on Jupyter Notebook (`.ipynb`) files.
     *   Avoid using the standard `edit_file` tool on `.ipynb` files, as this can corrupt the notebook structure.
 
 2.  **Investigation Strategy:**
     *   A comprehensive suite of tools is available to inspect notebooks. If the user mentions an issue, a specific cell, or asks for a modification, first attempt to gather context independently.
-    *   Use the available tools (`notebook_read`, `notebook_read_cell`, `notebook_get_info`, `notebook_read_metadata`, `notebook_read_cell_output`, `notebook_validate`) to examine the notebook structure, content, metadata, and outputs to locate the relevant context or identify the problem.
+    *   Use the available tools (`notebook_get_outline`, `notebook_search`, `notebook_read`, `notebook_read_cell`, `notebook_get_info`, `notebook_read_metadata`, `notebook_read_cell_output`, `notebook_validate`) to examine the notebook structure, content, metadata, and outputs to locate the relevant context or identify the problem.
     *   Ask the user for clarification only if the necessary information cannot be determined after using the investigation tools.
 
 3.  **Available Tools:**
-    *   Be aware of the different categories of tools: File operations (`create`, `delete`, `rename`), Notebook/Cell Reading (`read`, `read_cell`, `get_cell_count`, `get_info`), Cell Manipulation (`add_cell`, `edit_cell`, `delete_cell`, `move_cell`, `change_cell_type`, `duplicate_cell`, `split_cell`, `merge_cells`), Metadata (`read/edit_metadata`, `read/edit_cell_metadata`), Outputs (`read_cell_output`, `clear_cell_outputs`, `clear_all_outputs`), and Utility (`validate`, `export`, `diagnose_imports`).
+    *   Be aware of the different categories of tools: Situation awareness (`notebook_get_outline`), Search (`notebook_search`), File operations (`create`, `delete`, `rename`), Notebook/Cell Reading (`read`, `read_cell`, `get_cell_count`, `get_info`), Cell Manipulation (`add_cell`, `edit_cell`, `delete_cell`, `move_cell`, `change_cell_type`, `duplicate_cell`, `split_cell`, `merge_cells`), Metadata (`read/edit_metadata`, `read/edit_cell_metadata`), Outputs (`read_cell_output`, `clear_cell_outputs`, `clear_all_outputs`), and Utility (`validate`, `export`, `diagnose_imports`).
 
 4.  **Math Notation:** For LaTeX in Markdown cells, use `$ ... $` for inline math and `$$ ... $$` for display math. Avoid `\( ... \)` and `\[ ... \]`.
 

cursor_notebook_mcp/__init__.py

@@ -5,6 +5,6 @@
 AI agents within Cursor to interact with Jupyter Notebook (.ipynb) files.
 """
 
-__version__ = "0.2.3"
+__version__ = "0.2.4"
 
 # Components are imported directly where needed (e.g., in notebook_mcp_server.py)

cursor_notebook_mcp/server.py

@@ -231,10 +231,10 @@ def main():
         config = ServerConfig(args)
     except (SystemExit, ValueError) as e:
         print(f"ERROR: Configuration failed: {e}", file=sys.stderr)
-        sys.exit(e.code if isinstance(e, SystemExit) else 1)
+        return sys.exit(e.code if isinstance(e, SystemExit) else 1)
     except Exception as e:
         print(f"CRITICAL: Failed during argument parsing or validation: {e}", file=sys.stderr)
-        sys.exit(1)
+        return sys.exit(1)
 
     try:
         setup_logging(config.log_dir, config.log_level)
@@ -243,7 +243,11 @@ def main():
         print(f"CRITICAL: Failed during logging setup: {e}", file=sys.stderr)
         logging.basicConfig(level=logging.ERROR)
         logging.exception("Logging setup failed critically")
-        sys.exit(1)
+        return sys.exit(1)
+
+    # Set a default logger if it's still None to prevent NoneType errors
+    if logger is None:
+        logger = logging.getLogger(__name__)
 
     logger.info(f"Notebook MCP Server starting (Version: {config.version}) - via {__name__}")
     logger.info(f"Allowed Roots: {config.allowed_roots}")
@@ -258,7 +262,7 @@ def main():
         logger.info("Notebook tools initialized and registered.")
     except Exception as e:
         logger.exception("Failed to initialize MCP server or tools.")
-        sys.exit(1)
+        return sys.exit(1)
 
     try:
         if config.transport == 'stdio':
@@ -272,19 +276,19 @@ def main():
                 run_sse_server(mcp_server, config)
             except ImportError as e:
                 logger.error(f"Failed to start SSE server due to missing packages: {e}")
-                sys.exit(1)
+                return sys.exit(1)
             except Exception as e:
                 logger.exception("Failed to start or run SSE server.")
-                sys.exit(1)
+                return sys.exit(1)
             logger.info("Server finished (SSE).")
 
         else:
             logger.error(f"Internal Error: Invalid transport specified: {config.transport}")
-            sys.exit(1)
+            return sys.exit(1)
 
     except Exception as e:
         logger.exception("Server encountered a fatal error during execution.")
-        sys.exit(1)
+        return sys.exit(1)
 
 # If this script is run directly (e.g., python -m cursor_notebook_mcp.server)
 if __name__ == "__main__":

cursor_notebook_mcp/sse_transport.py

@@ -48,7 +48,6 @@ async def handle_sse(request):
     log_prefix = f"[SSE {client_host}:{client_port}]"
     logger.info(f"{log_prefix} New SSE connection request from {client_host}:{client_port}")
 
-    # transport = SseServerTransport(endpoint=mcp_server) # Old incorrect line
     try:
         logger.debug(f"{log_prefix} Setting up SSE connection")
         # connect_sse handles the SSE handshake and provides streams
@@ -66,8 +65,8 @@ async def handle_sse(request):
 
             # Call run() on the underlying server instance, passing streams and options
             await underlying_server.run(
-                read_stream=streams[0], 
-                write_stream=streams[1],
+                read_stream=read_stream, 
+                write_stream=write_stream,
                 initialization_options=init_options
             )
             logger.info(f"{log_prefix} MCP session finished.")

cursor_notebook_mcp/tools.py

@@ -17,9 +17,6 @@
 import nbformat
 from nbformat import NotebookNode
 
-# Assuming ServerConfig is defined elsewhere (e.g., in the main server script)
-# from notebook_mcp_server import ServerConfig
-# Assuming notebook_ops functions are available
 from . import notebook_ops
 
 logger = logging.getLogger(__name__)
@@ -69,7 +66,7 @@ def _register_tools(self):
             self.notebook_clear_cell_outputs,
             self.notebook_clear_all_outputs,
             self.notebook_move_cell,
-            self.diagnose_imports, # Keep diagnostic tool
+            self.diagnose_imports,
             self.notebook_validate,
             self.notebook_get_info,
             self.notebook_read_cell_output,
@@ -1156,17 +1153,15 @@ def _extract_markdown_outline(self, source: str) -> List[str]:
             for line in lines:
                 stripped_line = line.strip()
                 # Check for Markdown heading first
-                md_match = re.match(r'^(#+)\s+(.*)', stripped_line)
+                md_match = re.match(r'^(#+)\s*(.*)', stripped_line) # Allow zero spaces after #
                 if md_match:
                     level = len(md_match.group(1))
                     heading_text = md_match.group(2).strip()
                     if heading_text:
                         headings.append(f"H{level}: {heading_text}")
                 else:
-                    # If not Markdown, check for HTML heading
-                    # We search the stripped_line instead of match to find tag anywhere
-                    html_match = html_heading_re.search(stripped_line)
-                    if html_match:
+                    # If not Markdown, check for HTML headings using finditer for multiple matches per line
+                    for html_match in html_heading_re.finditer(stripped_line):
                         level = int(html_match.group(1))
                         # Basic cleanup: remove potential inner tags for outline brevity
                         heading_text = re.sub(r'<.*?>', '', html_match.group(2)).strip()

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cursor-notebook-mcp"
-version = "0.2.3"
+version = "0.2.4"
 authors = [
   { name="Jim Beno", email="jim@jimbeno.net" },
 ]
@@ -21,7 +21,6 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",

tests/test_notebook_ops.py

@@ -126,4 +126,130 @@ def test_setup_logging_filehandler_error(mock_stderr, mock_filehandler, mock_mak
     assert "Could not set up file logging" in mock_stderr.getvalue()
     assert "Cannot open log file for writing" in mock_stderr.getvalue()
 
-# TODO: Add more tests here
+# --- Additional Tests for notebook_ops.py Coverage ---
+
+def test_is_path_allowed_empty_roots():
+    """Test is_path_allowed behavior with empty allowed_roots list."""
+    test_path = "/some/path"
+    allowed_roots = []
+    
+    # Function should return False if no roots are configured
+    assert not notebook_ops.is_path_allowed(test_path, allowed_roots)
+
+def test_is_path_allowed_path_resolve_error():
+    """Test is_path_allowed behavior when path resolution fails."""
+    with mock.patch('os.path.realpath', side_effect=Exception("Path resolution error")):
+        test_path = "/some/path"
+        allowed_roots = ["/allowed/root"]
+        
+        # Function should return False if path resolution fails
+        assert not notebook_ops.is_path_allowed(test_path, allowed_roots)
+
+def test_is_path_allowed_root_resolve_error():
+    """Test is_path_allowed behavior when allowed root resolution fails."""
+    # First call returns successfully, second call raises exception
+    def mock_realpath(path):
+        if path == "/some/path":
+            return "/some/path"
+        raise Exception("Root resolution error")
+    
+    with mock.patch('os.path.realpath', side_effect=mock_realpath):
+        test_path = "/some/path"
+        allowed_roots = ["/allowed/root"]
+        
+        # Function should continue to the next root and return False
+        assert not notebook_ops.is_path_allowed(test_path, allowed_roots)
+
+@pytest.mark.asyncio
+async def test_read_notebook_non_absolute_path():
+    """Test read_notebook rejects non-absolute paths."""
+    non_abs_path = "relative/path/notebook.ipynb"
+    allowed_roots = ["/valid/root"]
+    
+    with pytest.raises(ValueError, match="Invalid notebook path: Only absolute paths are allowed"):
+        await notebook_ops.read_notebook(non_abs_path, allowed_roots)
+
+@pytest.mark.asyncio
+async def test_read_notebook_outside_allowed_roots(tmp_path):
+    """Test read_notebook rejects paths outside allowed roots."""
+    dummy_path = "/some/path/outside/notebook.ipynb"
+    allowed_roots = [str(tmp_path)]
+    
+    with pytest.raises(PermissionError, match="Access denied: Path .* is outside the allowed workspace roots"):
+        await notebook_ops.read_notebook(dummy_path, allowed_roots)
+
+@pytest.mark.asyncio
+async def test_read_notebook_invalid_extension(tmp_path):
+    """Test read_notebook rejects non-notebook files."""
+    dummy_path = tmp_path / "not_a_notebook.txt"
+    dummy_path.touch()
+    allowed_roots = [str(tmp_path)]
+    
+    with pytest.raises(ValueError, match="Invalid file type: .* must point to a .ipynb file"):
+        await notebook_ops.read_notebook(str(dummy_path), allowed_roots)
+
+@pytest.mark.asyncio
+async def test_write_notebook_non_absolute_path():
+    """Test write_notebook rejects non-absolute paths."""
+    non_abs_path = "relative/path/notebook.ipynb"
+    allowed_roots = ["/valid/root"]
+    nb = nbformat.v4.new_notebook()
+    
+    with pytest.raises(ValueError, match="Invalid notebook path: Only absolute paths are allowed for writing"):
+        await notebook_ops.write_notebook(non_abs_path, nb, allowed_roots)
+
+@pytest.mark.asyncio
+async def test_write_notebook_outside_allowed_roots(tmp_path):
+    """Test write_notebook rejects paths outside allowed roots."""
+    dummy_path = "/some/path/outside/notebook.ipynb"
+    allowed_roots = [str(tmp_path)]
+    nb = nbformat.v4.new_notebook()
+    
+    with pytest.raises(PermissionError, match="Access denied: Path .* is outside the allowed workspace roots"):
+        await notebook_ops.write_notebook(dummy_path, nb, allowed_roots)
+
+@pytest.mark.asyncio
+async def test_write_notebook_invalid_extension(tmp_path):
+    """Test write_notebook rejects non-notebook files."""
+    dummy_path = str(tmp_path / "not_a_notebook.txt")
+    allowed_roots = [str(tmp_path)]
+    nb = nbformat.v4.new_notebook()
+    
+    with pytest.raises(ValueError, match="Invalid file type for writing: .* must point to a .ipynb file"):
+        await notebook_ops.write_notebook(dummy_path, nb, allowed_roots)
+
+@pytest.mark.asyncio
+async def test_write_notebook_create_parent_dir(tmp_path):
+    """Test write_notebook creates parent directory."""
+    parent_dir = tmp_path / "nested" / "dir"
+    dummy_path = parent_dir / "notebook.ipynb"
+    allowed_roots = [str(tmp_path)]
+    nb = nbformat.v4.new_notebook()
+    
+    # Ensure the parent directory doesn't exist yet
+    assert not parent_dir.exists()
+    
+    # Mock the directory creation and nbformat.write to verify they're called
+    with mock.patch('os.path.isdir', return_value=False), \
+         mock.patch('os.makedirs') as mock_makedirs, \
+         mock.patch('nbformat.write') as mock_write:
+        
+        await notebook_ops.write_notebook(str(dummy_path), nb, allowed_roots)
+        
+        mock_makedirs.assert_called_once_with(str(parent_dir), exist_ok=True)
+        mock_write.assert_called_once()
+
+@pytest.mark.asyncio
+async def test_write_notebook_parent_dir_creation_fails(tmp_path):
+    """Test write_notebook handles error during parent directory creation."""
+    parent_dir = tmp_path / "nested" / "dir"
+    dummy_path = parent_dir / "notebook.ipynb"
+    allowed_roots = [str(tmp_path)]
+    nb = nbformat.v4.new_notebook()
+    
+    # Mock directory checks and creation to simulate failure
+    with mock.patch('os.path.isdir', return_value=False), \
+         mock.patch('os.makedirs', side_effect=OSError("Failed to create directory")):
+        
+        with pytest.raises(IOError, match="Could not create directory for notebook .* Failed to create directory"):
+            await notebook_ops.write_notebook(str(dummy_path), nb, allowed_roots)