fix(sse_transport): Resolve connection and routing errors in SSE transport

This commit addresses several critical errors in the SSE transport layer (`sse_transport.py`) that prevented successful client connections after recent refactoring:

- Corrected `SseServerTransport` initialization to use the `/messages/` endpoint path, ensuring clients POST back to the correct handler.
- Added the necessary Starlette route `Mount` for `/messages` to handle client POSTs.
- Fixed the `handle_sse` request handler logic:
    - Ensured it correctly retrieves streams yielded by `transport.connect_sse`.
    - Changed the `mcp_server._mcp_server.run()` call to correctly use the underlying `Server` instance (`_mcp_server`) to generate `initialization_options`.
    - Ensured `run()` is called on the underlying `Server` instance with the required streams and options, resolving previous `TypeError` and `AttributeError` issues.
- Removed redundant application setup code within the `run_sse_server` function.

These changes ensure the SSE transport now correctly establishes connections, routes client messages, and initiates the MCP session based on the `mcp-sdk`'s intended usage pattern.

See CHANGELOG.md for the release summary.

Author: jbeno

CHANGELOG.md

@@ -30,6 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Bug in `notebook_read` size estimation loop (`NameError: name 'i' is not defined`).
 - Multiple test failures related to incorrect mocking, error expectations, path handling, test setup, and imports (`StringIO`, `FastMCP`).
 - Invalid escape sequence in `pyproject.toml` coverage exclusion pattern.
+- Several issues in SSE transport (`sse_transport.py`) related to refactoring, including incorrect `SseServerTransport` initialization, missing `/messages` route handling, and incorrect parameters passed to the underlying `mcp.server.Server.run` method, causing connection failures.
 
 ## [0.2.2] - 2025-04-19
 

README.md

@@ -242,9 +242,66 @@ For smooth collaboration with the AI agent on Jupyter Notebooks, you might want
     *   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 (`
+    *   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`).
+
+4.  **Math Notation:** For LaTeX in Markdown cells, use `$ ... $` for inline math and `$$ ... $$` for display math. Avoid `\( ... \)` and `\[ ... \]`.
+
+5.  **Cell Magics:**
+    *   Avoid unsupported cell magics like `%%bash`, `%%timeit`, and `%%writefile`.
+    *   Use `!command` for shell commands instead of `%%bash`.
+    *   Use `%timeit` (line magic) for timing single statements.
+    *   `%%html` works for rendering HTML output.
+    *   `%%javascript` can execute (e.g., `alert`), but avoid relying on it for manipulating cell output display.
+
+6.  **Rich Outputs:** Matplotlib, Pandas DataFrames, Plotly, ipywidgets (`tqdm.notebook`), and embedded HTML in Markdown generally render correctly.
+
+7.  **Mermaid:** Diagrams in ` ```mermaid ``` ` blocks are not rendered by default.
+
+8.  **Character Escaping in `source` Parameter:**
+    *   When providing the `source` string for `add_cell` or `edit_cell`, ensure that backslashes (`\`) are handled correctly. Newline characters **must** be represented as `\n` (not `\\n`), and LaTeX commands **must** use single backslashes (e.g., `\Sigma`, not `\\Sigma`).
+    *   Incorrect escaping by the tool or its interpretation can break Markdown formatting (like paragraphs intended to be separated by `\n\n`) and LaTeX rendering.
+    *   After adding or editing cells with complex strings (especially those involving newlines or LaTeX), consider using `read_cell` to verify the content was saved exactly as intended and correct if necessary.
 ```
 
+## Command-Line Arguments
+
+The server accepts the following command-line arguments:
+
+*   `--allow-root`: (Required, can use multiple times) Absolute path to directory where notebooks are allowed.
+*   `--log-dir`: Directory to store log files. Defaults to `~/.cursor_notebook_mcp`.
+*   `--log-level`: Set the logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. Defaults to `INFO`.
+*   `--max-cell-source-size`: Maximum allowed size in bytes for cell source content. Defaults to 10 MiB.
+*   `--max-cell-output-size`: Maximum allowed size in bytes for cell output content. Defaults to 10 MiB.
+*   `--transport`: Transport type to use: `stdio` or `sse`. Defaults to `stdio`.
+*   `--host`: Host to bind the SSE server to. Only used with `--transport=sse`. Defaults to `127.0.0.1`.
+*   `--port`: Port to bind the SSE server to. Only used with `--transport=sse`. Defaults to `8080`.
+
+## Security
+
+*   **Workspace Root Enforcement:** The server **requires** the `--allow-root` command-line argument during startup. It will refuse to operate on any notebook file located outside the directories specified by these arguments. This is a critical security boundary.
+*   **Path Handling:** The server uses `os.path.realpath` to resolve paths and checks against the allowed roots before any read or write operation.
+*   **Input Validation:** Basic checks for `.ipynb` extension are performed.
+*   **Cell Source Size Limit:** The server enforces a maximum size limit (configurable via `--max-cell-source-size`, default 10 MiB) on the source content provided to `notebook_edit_cell` and `notebook_add_cell` to prevent excessive memory usage.
+*   **Cell Output Size Limit:** The server enforces a maximum size limit (configurable via `--max-cell-output-size`, default 10 MiB) on the total serialized size of outputs returned by `notebook_read_cell_output`.
+
+## Limitations
+
+*   **No Cell Execution:** This server **cannot execute** notebook cells. It operates solely on the `.ipynb` file structure using the `nbformat` library and does not interact with Jupyter kernels. Cell execution must be performed manually by the user within the Cursor UI (selecting the desired kernel and running the cell). Implementing execution capabilities in this server would require kernel management and introduce significant complexity and security considerations.
+
+## Known Issues
+
+*   **UI Refresh Issues:** Occasionally, some notebook operations (like cell splitting or merging) may succeed at the file level, but the Cursor UI might not show the updated content correctly. In such situations, you can:
+    * Close and re-open the notebook file
+    * Save the file, which might prompt to "Revert" or "Overwrite" - select "Revert" to reload the actual file content
+
+## Development & Testing
+
+1. Setup virtual environment and install dev dependencies:
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate
+   pip install -e ".[dev]"
+   ```
 2. Run tests:
    ```bash
    # Use the wrapper script to ensure environment variables are set
@@ -253,4 +310,45 @@ For smooth collaboration with the AI agent on Jupyter Notebooks, you might want
    # ./run_tests.sh tests/test_notebook_tools.py
    ```
 
-## Issues
+## Issues
+
+If you encounter any bugs or issues, please submit them to our GitHub issue tracker:
+
+1. Visit [jbeno/cursor-notebook-mcp](https://github.com/jbeno/cursor-notebook-mcp/issues)
+2. Click on "New Issue"
+3. Provide:
+   - A clear description of the problem
+   - Steps to reproduce the issue
+   - Expected vs actual behavior
+   - Your environment details (OS, Python version, etc.)
+   - Any relevant error messages or logs
+   - Which model and client/version you're using
+
+## Contributing
+
+Contributions are welcome! Please follow these steps:
+
+1. Fork the repository
+2. Create a new branch for your feature (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Run tests to ensure nothing is broken (`pytest tests/`)
+5. Commit your changes (`git commit -m 'Add amazing feature'`)
+6. Push to your branch (`git push origin feature/amazing-feature`)
+7. Open a Pull Request
+
+Please make sure your PR:
+- Includes tests for new functionality
+- Updates documentation as needed
+- Follows the existing code style
+- Includes a clear description of the changes
+
+For major changes, please open an issue first to discuss what you would like to change.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+
+## Author
+
+This project was created and is maintained by Jim Beno - jim@jimbeno.net

cursor_notebook_mcp/sse_transport.py

@@ -40,13 +40,15 @@
 async def handle_sse(request):
     """Handles incoming SSE connections and delegates to MCP transport."""
     mcp_server = request.app.state.mcp_server
+    # Retrieve the shared transport instance
+    transport = request.app.state.sse_transport 
     config = request.app.state.config
     client_host = request.client.host
     client_port = request.client.port
     log_prefix = f"[SSE {client_host}:{client_port}]"
     logger.info(f"{log_prefix} New SSE connection request from {client_host}:{client_port}")
 
-    transport = SseServerTransport()
+    # 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
@@ -55,11 +57,18 @@ async def handle_sse(request):
         ) as streams:
             read_stream, write_stream = streams
             logger.info(f"{log_prefix} Connection established. Running MCP session.")
-            # Run the MCP server logic using the established streams
-            await mcp_server._mcp_server.run(
-                transport='stream', 
-                read_stream=read_stream, 
-                write_stream=write_stream
+            
+            # Get the underlying server instance that has the necessary methods
+            underlying_server = mcp_server._mcp_server
+            
+            # Create options using the underlying server instance
+            init_options = underlying_server.create_initialization_options()
+            
+            # Call run() on the underlying server instance, passing streams and options
+            await underlying_server.run(
+                read_stream=streams[0], 
+                write_stream=streams[1],
+                initialization_options=init_options
             )
             logger.info(f"{log_prefix} MCP session finished.")
     except Exception as e:
@@ -94,9 +103,14 @@ async def generic_exception_handler(request, exc):
 # Function to create the Starlette app (refactored)
 def create_starlette_app(mcp_server: FastMCP, config: 'ServerConfig') -> Starlette:
     """Creates the Starlette application instance."""
+    # Create the SSE transport instance once, passing the **correct** endpoint path
+    # This is the path the client will be instructed to POST messages back to.
+    transport = SseServerTransport(endpoint="/messages/")
+    
     routes = [
-        Route("/", endpoint=handle_root, methods=["GET"]),
-        Route("/sse", endpoint=handle_sse) # Default methods handled by SSE transport
+        Route("/", endpoint=handle_root, methods=["GET"]), # Root info
+        Route("/sse", endpoint=handle_sse), # Initial SSE connection (GET)
+        Mount("/messages", app=transport.handle_post_message) # Client message handler (POST)
     ]
     middleware = [
         Middleware(ServerErrorMiddleware, handler=generic_exception_handler)
@@ -111,6 +125,7 @@ def create_starlette_app(mcp_server: FastMCP, config: 'ServerConfig') -> Starlet
     # Store shared instances in app state
     app.state.mcp_server = mcp_server
     app.state.config = config
+    app.state.sse_transport = transport # Store the transport instance
     return app
 
 
@@ -140,56 +155,4 @@ def run_sse_server(mcp_server: FastMCP, config: 'ServerConfig'):
         raise # Re-raise for main server loop to catch
     except Exception as e:
         logger.exception(f"Failed to start or run Uvicorn server: {e}")
-        raise # Re-raise for main server loop to catch
-
-    async def health_endpoint(request):
-        """Simple health check endpoint."""
-        return JSONResponse({
-            "status": "ok",
-            "service": "Jupyter Notebook MCP Server",
-            "version": config.version,
-            "transport": "sse"
-        })
-
-    async def info_endpoint(request):
-        """Provides basic server information."""
-        return JSONResponse({
-            "name": "Jupyter Notebook MCP Server",
-            "version": config.version,
-            "transport": "sse",
-            "allowed_roots": config.allowed_roots,
-            # Add other relevant config details if needed
-        })
-
-    # Define Starlette routes
-    routes = [
-        Route("/sse", endpoint=handle_sse), # SSE connection endpoint
-        Route("/health", endpoint=health_endpoint), # Health check
-        Route("/", endpoint=info_endpoint),       # Basic info
-        Mount("/messages", app=transport.handle_post_message), # Endpoint for clients to POST messages
-    ]
-
-    # Create Starlette app
-    app = Starlette(routes=routes, debug=config.log_level <= logging.DEBUG)
-
-    logger.info(f"Starting Uvicorn server on http://{config.host}:{config.port}")
-    
-    # Configure Uvicorn logging based on server log level
-    log_config = uvicorn.config.LOGGING_CONFIG
-    log_config["loggers"]["uvicorn"]["level"] = logging.getLevelName(config.log_level)
-    log_config["loggers"]["uvicorn.error"]["level"] = logging.getLevelName(config.log_level)
-    log_config["loggers"]["uvicorn.access"]["level"] = logging.getLevelName(config.log_level)
-    # Disable access logs propagation if too noisy at DEBUG level
-    log_config["loggers"]["uvicorn.access"]["propagate"] = config.log_level > logging.DEBUG 
-
-    try:
-        # Run the Uvicorn server
-        uvicorn.run(
-            app, 
-            host=config.host, 
-            port=config.port, 
-            log_config=log_config
-        )
-    except Exception as e:
-        logger.exception(f"Uvicorn server failed to run: {e}")
-        raise # Re-raise the exception to be caught by the main loop 
+        raise # Re-raise for main server loop to catch