rename execute_ipython to execute_code (#134)

Author: ChengJiale150

jupyter_mcp_server/server.py

@@ -53,7 +53,7 @@
     # Cell Execution
     ExecuteCellTool,
     # Other Tools
-    ExecuteIpythonTool,
+    ExecuteCodeTool,
     ListFilesTool,
     ListKernelsTool,
 )
@@ -470,23 +470,22 @@ async def delete_cell(
 
 
 @mcp.tool()
-async def execute_ipython(
-    code: Annotated[str, Field(description="IPython code to execute (supports magic commands, shell commands with !, and Python code)")],
-    timeout: Annotated[int, Field(description="Execution timeout in seconds (default: 60s)")] = 60,
+async def execute_code(
+    code: Annotated[str, Field(description="Code to execute (supports magic commands with %, shell commands with !)")],
+    timeout: Annotated[int, Field(description="Execution timeout in seconds",le=60)] = 30,
 ) -> Annotated[list[str | ImageContent], Field(description="List of outputs from the executed code")]:
-    """Execute IPython code directly in the kernel on the current active notebook.
-
-    This powerful tool supports:
-    1. Magic commands (e.g., %timeit, %who, %load, %run, %matplotlib)
-    2. Shell commands (e.g., !pip install, !ls, !cat)
-    3. Python code (e.g., print(df.head()), df.info())
-
-    Use cases:
-    - Performance profiling and debugging
-    - Environment exploration and package management
-    - Variable inspection and data analysis
-    - File system operations on Jupyter server
-    - Temporary calculations and quick tests
+    """Execute code directly in the kernel (not saved to notebook) on the current activated notebook.
+
+    Recommended to use in following cases:
+    1. Execute Jupyter magic commands(e.g., `%timeit`, `%pip install xxx`)
+    2. Performance profiling and debugging.
+    3. View intermediate variable values(e.g., `print(xxx)`, `df.head()`)
+    4. Temporary calculations and quick tests(e.g., `np.mean(df['xxx'])`)
+    5. Execute Shell commands in Jupyter server(e.g., `!git xxx`)
+
+    Under no circumstances should you use this tool to:
+    1. Import new modules or perform variable assignments that affect subsequent Notebook execution
+    2. Execute dangerous code that may harm the Jupyter server or the user's data without permission
     """
     # Get kernel_id for JUPYTER_SERVER mode
     # Let the tool handle getting kernel_id via get_current_notebook_context()
@@ -498,7 +497,7 @@ async def execute_ipython(
         # but the tool will fall back to config values via get_current_notebook_context()
 
     return await safe_notebook_operation(
-        lambda: ExecuteIpythonTool().execute(
+        lambda: ExecuteCodeTool().execute(
             mode=server_context.mode,
             server_client=server_context.server_client,
             kernel_manager=server_context.kernel_manager,

jupyter_mcp_server/tools/__init__.py

@@ -31,7 +31,7 @@
 from jupyter_mcp_server.tools.execute_cell_tool import ExecuteCellTool
 
 # Import tool implementations - Other Tools
-from jupyter_mcp_server.tools.execute_ipython_tool import ExecuteIpythonTool
+from jupyter_mcp_server.tools.execute_code_tool import ExecuteCodeTool
 from jupyter_mcp_server.tools.list_files_tool import ListFilesTool
 from jupyter_mcp_server.tools.list_kernels_tool import ListKernelsTool
 
@@ -55,7 +55,7 @@
     # Cell Execution
     "ExecuteCellTool",
     # Other Tools
-    "ExecuteIpythonTool",
+    "ExecuteCodeTool",
     "ListFilesTool",
     "ListKernelsTool",
 ]

jupyter_mcp_server/tools/execute_ipython_tool.py renamed to jupyter_mcp_server/tools/execute_code_tool.py

@@ -16,8 +16,8 @@
 logger = logging.getLogger(__name__)
 
 
-class ExecuteIpythonTool(BaseTool):
-    """Execute IPython code directly in the kernel on the current active notebook"""
+class ExecuteCodeTool(BaseTool):
+    """Execute code directly in the kernel on the current active notebook"""
 
     async def _execute_via_kernel_manager(
         self,
@@ -39,7 +39,7 @@ async def _execute_via_kernel_manager(
         # Use centralized execute_code_local function
         return await execute_code_local(
             serverapp=serverapp,
-            notebook_path="",  # Not needed for execute_ipython
+            notebook_path="",  # Not needed for execute_code
             code=code,
             kernel_id=kernel_id,
             timeout=timeout,
@@ -149,7 +149,7 @@ async def execute(
 
             if kernel_id is None:
                 # No kernel available - start a new one on demand
-                logger.info("No kernel_id available, starting new kernel for execute_ipython")
+                logger.info("No kernel_id available, starting new kernel for execute_code")
                 kernel_id = await kernel_manager.start_kernel()
 
                 # Store the kernel in notebook_manager if available

tests/test_common.py

@@ -40,7 +40,7 @@
     "list_cells",
     "read_cell",
     "delete_cell",
-    "execute_ipython",
+    "execute_code",
     "list_files",
     "list_kernels"
 ]
@@ -421,11 +421,11 @@ async def overwrite_cell_source(self, cell_index, cell_source):
         return self._get_structured_content_safe(result) if result else None
 
     @requires_session
-    async def execute_ipython(self, code, timeout=60):
-        result = await self._session.call_tool("execute_ipython", arguments={"code": code, "timeout": timeout})  # type: ignore
+    async def execute_code(self, code, timeout=60):
+        result = await self._session.call_tool("execute_code", arguments={"code": code, "timeout": timeout})  # type: ignore
         structured = self._get_structured_content_safe(result)
 
-        # execute_ipython should always return a list of outputs
+        # execute_code should always return a list of outputs
         # If we got a plain string, wrap it as a list
         if structured and "result" in structured:
             result_val = structured["result"]

tests/test_jupyter_extension.py

@@ -10,7 +10,6 @@
 
 Key differences from MCP_SERVER mode:
 - Uses YDoc collaborative editing when notebooks are open
-- Direct kernel_manager access for execute_ipython
 - Local file operations without HTTP roundtrip
 
 The tests connect to the extension's HTTP endpoints (not the standalone MCP server).

tests/test_tools.py

@@ -559,22 +559,22 @@ async def test_notebooks_error_cases(mcp_client_parametrized: MCPClient):
 
 
 ###############################################################################
-# execute_ipython Tests
+# execute_code Tests
 ###############################################################################
 
 @pytest.mark.asyncio
 @timeout_wrapper(30)
-async def test_execute_ipython_python_code(mcp_client_parametrized: MCPClient):
-    """Test execute_ipython with basic Python code in both modes"""
+async def test_execute_code_python_code(mcp_client_parametrized: MCPClient):
+    """Test execute_code with basic Python code in both modes"""
     async with mcp_client_parametrized:
         # Test simple Python code
-        result = await mcp_client_parametrized.execute_ipython("print('Hello IPython World!')")
+        result = await mcp_client_parametrized.execute_code("print('Hello IPython World!')")
 
         # On Windows, if result is None it's likely due to timeout - skip the test
         if platform.system() == "Windows" and result is None:
-            pytest.skip("execute_ipython timed out on Windows - known platform limitation")
+            pytest.skip("execute_code timed out on Windows - known platform limitation")
 
-        assert result is not None, "execute_ipython result should not be None"
+        assert result is not None, "execute_code result should not be None"
         assert "result" in result, "Result should contain 'result' key"
         outputs = result["result"]
         assert isinstance(outputs, list), "Outputs should be a list"
@@ -584,10 +584,10 @@ async def test_execute_ipython_python_code(mcp_client_parametrized: MCPClient):
         assert "Hello IPython World!" in output_text or "[No output generated]" in output_text
 
         # Test mathematical calculation
-        calc_result = await mcp_client_parametrized.execute_ipython("result = 2 ** 10\nprint(f'2^10 = {result}')")
+        calc_result = await mcp_client_parametrized.execute_code("result = 2 ** 10\nprint(f'2^10 = {result}')")
 
         if platform.system() == "Windows" and calc_result is None:
-            pytest.skip("execute_ipython timed out on Windows - known platform limitation")
+            pytest.skip("execute_code timed out on Windows - known platform limitation")
 
         assert calc_result is not None
         calc_outputs = calc_result["result"]
@@ -597,38 +597,38 @@ async def test_execute_ipython_python_code(mcp_client_parametrized: MCPClient):
 
 @pytest.mark.asyncio
 @timeout_wrapper(30)
-async def test_execute_ipython_magic_commands(mcp_client_parametrized: MCPClient):
-    """Test execute_ipython with IPython magic commands in both modes"""
+async def test_execute_code_magic_commands(mcp_client_parametrized: MCPClient):
+    """Test execute_code with IPython magic commands in both modes"""
     async with mcp_client_parametrized:
         # Test %who magic command (list variables)
-        result = await mcp_client_parametrized.execute_ipython("%who")
+        result = await mcp_client_parametrized.execute_code("%who")
 
         # On Windows, if result is None it's likely due to timeout - skip the test
         if platform.system() == "Windows" and result is None:
-            pytest.skip("execute_ipython timed out on Windows - known platform limitation")
+            pytest.skip("execute_code timed out on Windows - known platform limitation")
 
-        assert result is not None, "execute_ipython result should not be None"
+        assert result is not None, "execute_code result should not be None"
         outputs = result["result"]
         assert isinstance(outputs, list), "Outputs should be a list"
 
         # Set a variable first, then use %who to see it
-        var_result = await mcp_client_parametrized.execute_ipython("test_var = 42")
+        var_result = await mcp_client_parametrized.execute_code("test_var = 42")
         if platform.system() == "Windows" and var_result is None:
-            pytest.skip("execute_ipython timed out on Windows - known platform limitation")
+            pytest.skip("execute_code timed out on Windows - known platform limitation")
 
-        who_result = await mcp_client_parametrized.execute_ipython("%who")
+        who_result = await mcp_client_parametrized.execute_code("%who")
         if platform.system() == "Windows" and who_result is None:
-            pytest.skip("execute_ipython timed out on Windows - known platform limitation")
+            pytest.skip("execute_code timed out on Windows - known platform limitation")
 
         who_outputs = who_result["result"]
         who_text = "".join(str(output) for output in who_outputs)
         # %who should show our variable (or no output if variables exist but aren't shown)
         # This test mainly ensures %who doesn't crash
 
         # Test %timeit magic command
-        timeit_result = await mcp_client_parametrized.execute_ipython("%timeit sum(range(100))")
+        timeit_result = await mcp_client_parametrized.execute_code("%timeit sum(range(100))")
         if platform.system() == "Windows" and timeit_result is None:
-            pytest.skip("execute_ipython timed out on Windows - known platform limitation")
+            pytest.skip("execute_code timed out on Windows - known platform limitation")
 
         assert timeit_result is not None
         timeit_outputs = timeit_result["result"]
@@ -639,17 +639,17 @@ async def test_execute_ipython_magic_commands(mcp_client_parametrized: MCPClient
 
 @pytest.mark.asyncio 
 @timeout_wrapper(30)
-async def test_execute_ipython_shell_commands(mcp_client_parametrized: MCPClient):
-    """Test execute_ipython with shell commands in both modes"""
+async def test_execute_code_shell_commands(mcp_client_parametrized: MCPClient):
+    """Test execute_code with shell commands in both modes"""
     async with mcp_client_parametrized:
         # Test basic shell command - echo (works on most systems)
-        result = await mcp_client_parametrized.execute_ipython("!echo 'Hello from shell'")
+        result = await mcp_client_parametrized.execute_code("!echo 'Hello from shell'")
 
         # On Windows, if result is None it's likely due to timeout - skip the test
         if platform.system() == "Windows" and result is None:
-            pytest.skip("execute_ipython timed out on Windows - known platform limitation")
+            pytest.skip("execute_code timed out on Windows - known platform limitation")
 
-        assert result is not None, "execute_ipython result should not be None"
+        assert result is not None, "execute_code result should not be None"
         outputs = result["result"]
         assert isinstance(outputs, list), "Outputs should be a list"
 
@@ -658,9 +658,9 @@ async def test_execute_ipython_shell_commands(mcp_client_parametrized: MCPClient
         assert len(output_text) >= 0  # Just ensure no crash
 
         # Test Python version check
-        python_result = await mcp_client_parametrized.execute_ipython("!python --version")
+        python_result = await mcp_client_parametrized.execute_code("!python --version")
         if platform.system() == "Windows" and python_result is None:
-            pytest.skip("execute_ipython timed out on Windows - known platform limitation")
+            pytest.skip("execute_code timed out on Windows - known platform limitation")
 
         assert python_result is not None
         python_outputs = python_result["result"]
@@ -671,15 +671,15 @@ async def test_execute_ipython_shell_commands(mcp_client_parametrized: MCPClient
 
 @pytest.mark.asyncio
 @timeout_wrapper(30)
-async def test_execute_ipython_timeout(mcp_client_parametrized: MCPClient):
-    """Test execute_ipython timeout functionality in both modes"""
+async def test_execute_code_timeout(mcp_client_parametrized: MCPClient):
+    """Test execute_code timeout functionality in both modes"""
     async with mcp_client_parametrized:
         # Test with very short timeout on a potentially long-running command
-        result = await mcp_client_parametrized.execute_ipython("import time; time.sleep(5)", timeout=2)
+        result = await mcp_client_parametrized.execute_code("import time; time.sleep(5)", timeout=2)
 
         # On Windows, if result is None it's likely due to timeout - skip the test
         if platform.system() == "Windows" and result is None:
-            pytest.skip("execute_ipython timed out on Windows - known platform limitation")
+            pytest.skip("execute_code timed out on Windows - known platform limitation")
 
         assert result is not None
         outputs = result["result"]
@@ -690,15 +690,15 @@ async def test_execute_ipython_timeout(mcp_client_parametrized: MCPClient):
 
 @pytest.mark.asyncio
 @timeout_wrapper(30)
-async def test_execute_ipython_error_handling(mcp_client_parametrized: MCPClient):
-    """Test execute_ipython error handling in both modes"""
+async def test_execute_code_error_handling(mcp_client_parametrized: MCPClient):
+    """Test execute_code error handling in both modes"""
     async with mcp_client_parametrized:
         # Test syntax error
-        result = await mcp_client_parametrized.execute_ipython("invalid python syntax <<<")
+        result = await mcp_client_parametrized.execute_code("invalid python syntax <<<")
 
         # On Windows, if result is None it's likely due to timeout - skip the test
         if platform.system() == "Windows" and result is None:
-            pytest.skip("execute_ipython timed out on Windows - known platform limitation")
+            pytest.skip("execute_code timed out on Windows - known platform limitation")
 
         assert result is not None
         outputs = result["result"]
@@ -707,9 +707,9 @@ async def test_execute_ipython_error_handling(mcp_client_parametrized: MCPClient
         assert len(output_text) >= 0  # Ensure no crash
 
         # Test runtime error  
-        runtime_result = await mcp_client_parametrized.execute_ipython("undefined_variable")
+        runtime_result = await mcp_client_parametrized.execute_code("undefined_variable")
         if platform.system() == "Windows" and runtime_result is None:
-            pytest.skip("execute_ipython timed out on Windows - known platform limitation")
+            pytest.skip("execute_code timed out on Windows - known platform limitation")
 
         assert runtime_result is not None
         runtime_outputs = runtime_result["result"]