A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
refactor(tools): introduce ToolBase and centralize tool implementations (#6309)
Joaquin Corominab700c0bead3c
diff --git a/marimo/_ai/_tools/base.py b/marimo/_ai/_tools/base.pynew file mode 100644index 0000000000..a0e9a8d8cb--- /dev/null+++ b/marimo/_ai/_tools/base.py@@ -0,0 +1,243 @@+# Copyright 2025 Marimo. All rights reserved.+from __future__ import annotations++import dataclasses+import inspect+import re+from abc import ABC, abstractmethod+from dataclasses import asdict, dataclass, is_dataclass+from typing import (+ TYPE_CHECKING,+ Any,+ Generic,+ Optional,+ TypeVar,+ cast,+ get_args,+ get_origin,+)++from starlette.applications import (+ Starlette, # noqa: TCH002 - required at runtime for MCP/Pydantic schema validation and isinstance checks+)++from marimo._ai._tools.utils.exceptions import ToolExecutionError+from marimo._server.api.deps import AppStateBase+from marimo._server.sessions import Session, SessionManager+from marimo._types.ids import SessionId+from marimo._utils.parse_dataclass import parse_raw++ArgsT = TypeVar("ArgsT")+OutT = TypeVar("OutT")++ArgsP = TypeVar("ArgsP", contravariant=True)+OutC = TypeVar("OutC", covariant=True)++if TYPE_CHECKING:+ from collections.abc import Awaitable, Callable+++@dataclass+class ToolContext:+ app: Optional[Starlette] = None++ @property+ def session_manager(self) -> SessionManager:+ app = self.get_app()+ state = AppStateBase.from_app(app)+ session_manager = state.session_manager+ return session_manager++ def get_app(self) -> Starlette:+ app = self.app+ if app is None:+ raise ToolExecutionError(+ "App is not available",+ code="APP_NOT_AVAILABLE",+ is_retryable=False,+ suggested_fix="Try restarting the marimo server.",+ )+ return app++ def get_session(self, session_id: SessionId) -> Session:+ session_manager = self.session_manager+ if session_id not in session_manager.sessions:+ raise ToolExecutionError(+ f"Session {session_id} not found",+ code="SESSION_NOT_FOUND",+ is_retryable=False,+ suggested_fix="Use get_active_notebooks to find valid session IDs",+ meta={"session_id": session_id},+ )+ return session_manager.sessions[session_id]+++class ToolBase(Generic[ArgsT, OutT], ABC):+ """+ Minimal base class for dual-registered tools.++ Subclasses MUST set:+ - name: str (optional; defaults to class name)+ - description: str (optional; defaults to class docstring)+ - Args: Type (input schema type)+ - Output: Type (output schema type)+ - Args and Output must be set via generics, e.g. ToolBase[ArgsModel, OutputModel]+ """++ # Override in subclass, or rely on fallbacks below+ name: str | None = None+ description: str | None = None+ Args: type[ArgsT]+ Output: type[OutT]+ context: ToolContext++ def __init_subclass__(cls, **kwargs: object) -> None:+ """Grab ToolBase[...] type parameters and set Args/Output on the subclass."""+ super().__init_subclass__(**kwargs)++ # Find the ToolBase[...] in the subclass' original bases+ for base in getattr(cls, "__orig_bases__", ()):+ if get_origin(base) is ToolBase:+ a, o = get_args(base)+ cls.Args = a # type: ignore[assignment]+ cls.Output = o # type: ignore[assignment]+ break++ # If not provided via generics and not manually set, fail early+ if not hasattr(cls, "Args") or not hasattr(cls, "Output"):+ raise TypeError(+ f"{cls.__name__} must specify type arguments, e.g. "+ f"class {cls.__name__}(ToolBase[ArgsModel, OutputModel]): ..."+ )++ def __init__(self, context: ToolContext) -> None:+ self.context = context++ # get name from class name+ if self.name is None:+ self.name = self._to_snake_case(self.__class__.__name__)++ # get description from class docstring+ if self.description is None:+ self.description = (self.__class__.__doc__ or "").strip()++ async def __call__(self, args: ArgsT) -> OutT:+ """+ Unified runner: calls __call__ and awaits if it returns a coroutine.+ Adapters should always use this.+ """+ try:+ coerced_args = self._coerce_args(args)+ except Exception as e:+ raise ToolExecutionError(+ f"Bad arguments: {args}",+ code="BAD_ARGUMENTS",+ is_retryable=False,+ suggested_fix="Try again with valid arguments.",+ meta={"args": args},+ ) from e+ try:+ result = self.handle(coerced_args)+ if inspect.isawaitable(result):+ awaited = await result # type: ignore[no-any-return]+ return cast(OutT, awaited)+ return cast(OutT, result) # type: ignore[redundant-cast]+ except ToolExecutionError:+ # Let intentional tool errors propagate unchanged+ raise+ except Exception as e:+ # Standardize unexpected failures+ raise ToolExecutionError(+ self._default_error_message(),+ code=self._default_error_code(),+ is_retryable=self._default_is_retryable(),+ suggested_fix=self._default_suggested_fix(),+ meta=self._error_context(coerced_args),+ ) from e++ @abstractmethod+ def handle(self, args: ArgsT) -> OutT:+ """Actual tool function."""+ ...++ # adapters+ def as_mcp_tool_fn(self) -> Callable[[ArgsT], Awaitable[OutT]]:+ """Return a typed, annotated callable suitable for MCP registration."""+ Args = self.Args+ Output = self.Output++ async def handler(args: ArgsT) -> OutT: # type: ignore[type-var]+ result = await self.__call__(args)+ # Ensure JSON-serializable output for MCP+ if is_dataclass(result):+ # Some MCP clients expect dicts only+ return cast(OutT, asdict(result)) # type: ignore[arg-type]+ return result++ # name/doc metadata (guard for None types)+ handler_any = cast(Any, handler)+ handler_any.__name__ = self.name or handler_any.__name__+ handler_any.__doc__ = self.description or handler_any.__doc__++ # help static consumers and schema tools+ handler_any.__annotations__ = {"args": Args, "return": Output}++ # Advertise intended signature for mypy/tests+ # Keep in try/except to avoid breaking tool registration+ try:+ handler_any.__signature__ = inspect.Signature(+ parameters=[+ inspect.Parameter(+ "args",+ inspect.Parameter.POSITIONAL_OR_KEYWORD,+ annotation=Args,+ )+ ],+ return_annotation=Output,+ )+ except Exception:+ # Best-effort only; safe to skip if inspect behavior changes+ pass++ return handler++ def as_backend_tool(self) -> None:+ """Convert the tool to a backend tool."""+ # TODO: implement+ ...++ # helpers++ def _coerce_args(self, args: Any) -> ArgsT: # type: ignore[override]+ """If Args is a dataclass and args is a dict, construct it; else pass through."""+ if dataclasses.is_dataclass(args):+ # Already parsed+ return args # type: ignore[return-value]+ return parse_raw(args, self.Args)++ def _to_snake_case(self, name: str) -> str:+ """Convert a PascalCase/CamelCase class name to snake_case function name.++ Examples:+ GetCellMap -> get_cell_map+ """+ # Handle acronyms and normal Camel/Pascal case transitions+ s1 = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1_\2", name)+ s2 = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s1)+ return s2.replace("-", "_").lower()++ # error defaults/hooks+ def _default_error_code(self) -> str:+ return "UNEXPECTED_ERROR"++ def _default_error_message(self) -> str:+ return f"{self.name or self.__class__.__name__} failed"++ def _default_is_retryable(self) -> bool:+ return True++ def _default_suggested_fix(self) -> Optional[str]:+ return None++ def _error_context(self, _args: Any) -> dict[str, Any]:+ return {}diff --git a/marimo/_ai/_tools/tools/cells.py b/marimo/_ai/_tools/tools/cells.pynew file mode 100644index 0000000000..02242baa2a--- /dev/null+++ b/marimo/_ai/_tools/tools/cells.py@@ -0,0 +1,389 @@+from __future__ import annotations++from dataclasses import dataclass, field+from enum import Enum+from typing import TYPE_CHECKING, Any, Optional++from marimo._ai._tools.base import ToolBase+from marimo._ai._tools.types import SuccessResult+from marimo._ai._tools.utils.exceptions import ToolExecutionError+from marimo._ast.models import CellData+from marimo._types.ids import CellId_t, SessionId++if TYPE_CHECKING:+ from marimo._ast.models import CellData+ from marimo._server.sessions import Session+++class SupportedCellType(str, Enum):+ CODE = "code"+ MARKDOWN = "markdown"+ SQL = "sql"+++@dataclass+class GetLightweightCellMapArgs:+ session_id: SessionId+ preview_lines: int = 3 # random default value+++@dataclass+class LightweightCellInfo:+ cell_id: str+ preview: str+ line_count: int+ cell_type: SupportedCellType+++@dataclass+class GetLightweightCellMapOutput(SuccessResult):+ session_id: str = ""+ notebook_name: str = ""+ cells: list[LightweightCellInfo] = field(default_factory=list)+ total_cells: int = 0+ preview_lines: int = 3+++@dataclass+class ErrorDetail:+ type: str+ message: str+ traceback: list[str]+++@dataclass+class CellErrors:+ has_errors: bool+ error_details: Optional[list[ErrorDetail]]+++@dataclass+class CellRuntimeMetadata:+ # String form of the runtime state (see marimo._ast.cell.RuntimeStateType);+ # keep as str for py39/Pydantic compatibility and to avoid Literal/Enum+ # validation issues in models.+ runtime_state: Optional[str] = None+ execution_time: Optional[float] = None+++@dataclass+class CellVariableValue:+ name: str+ # Cell variables can be arbitrary Python values (int, str, list, dict, ...),+ # so we keep this as Any to reflect actual runtime.+ value: Optional[Any] = None+ datatype: Optional[str] = None+++CellVariables = dict[str, CellVariableValue]+++@dataclass+class GetCellRuntimeDataData:+ session_id: str+ cell_id: str+ code: Optional[str] = None+ errors: Optional[CellErrors] = None+ metadata: Optional[CellRuntimeMetadata] = None+ variables: Optional[CellVariables] = None+++def _default_cell_runtime_data() -> GetCellRuntimeDataData:+ return GetCellRuntimeDataData(session_id="", cell_id="")+++@dataclass+class GetCellRuntimeDataArgs:+ session_id: SessionId+ cell_id: CellId_t+++@dataclass+class GetCellRuntimeDataOutput(SuccessResult):+ data: GetCellRuntimeDataData = field(+ default_factory=_default_cell_runtime_data+ )+++class GetLightweightCellMap(+ ToolBase[GetLightweightCellMapArgs, GetLightweightCellMapOutput]+):+ """Get a lightweight map of cells showing the first few lines of each cell.++ This tool provides an overview of notebook structure for initial navigation,+ showing a preview of each cell's content without full code or outputs.++ Args:+ session_id: The session ID of the notebook from get_active_notebooks+ preview_lines: Number of lines to show per cell (default: 3)++ Returns:+ A success result containing lightweight cell previews and navigation info.+ """++ def handle(+ self, args: GetLightweightCellMapArgs+ ) -> GetLightweightCellMapOutput:+ session_id = args.session_id+ context = self.context+ session = context.get_session(session_id)+ cell_manager = session.app_file_manager.app.cell_manager+ notebook_filename = (+ session.app_file_manager.filename or "untitled_notebook.py"+ )++ # Validate preview_lines+ preview_lines = max(1, min(50, args.preview_lines))++ cells: list[LightweightCellInfo] = []+ for cell_data in cell_manager.cell_data():+ code_lines = cell_data.code.split("\n")+ preview = "\n".join(code_lines[:preview_lines])++ # Determine cell type using compiled cell info when available+ cell_type = self._get_cell_type(cell_data)++ # Add cell to cell map+ cells.append(+ LightweightCellInfo(+ cell_id=cell_data.cell_id,+ preview=preview,+ line_count=len(code_lines),+ cell_type=cell_type,+ )+ )++ return GetLightweightCellMapOutput(+ status="success",+ session_id=args.session_id,+ notebook_name=notebook_filename,+ cells=cells,+ total_cells=len(cells),+ preview_lines=preview_lines,+ next_steps=[+ "Use cell_id to get full cell content or execute specific cells",+ "Identify key sections based on cell types and previews",+ "Focus on import cells first to understand dependencies",+ ],+ message=(+ "Refer to cells ordinally in the following format: @[cell:1]. "+ "Do _not_ use cell_id when discussing with users."+ ),+ )++ # helper methods++ def _is_markdown_cell(self, code: str) -> bool:+ return code.lstrip().startswith("mo.md(")++ def _get_cell_type(self, cell_data: CellData) -> SupportedCellType:+ if cell_data.cell is None:+ # Fallback when compiled cell is unavailable+ return (+ SupportedCellType.MARKDOWN+ if self._is_markdown_cell(cell_data.code)+ else SupportedCellType.CODE+ )++ # Otherwise, use the compiled cell's language+ language = cell_data.cell._cell.language+ if language == "sql":+ return SupportedCellType.SQL+ elif language == "python":+ return (+ SupportedCellType.MARKDOWN+ if self._is_markdown_cell(cell_data.code)+ else SupportedCellType.CODE+ )+ else:+ return SupportedCellType.CODE+++class GetCellRuntimeData(+ ToolBase[GetCellRuntimeDataArgs, GetCellRuntimeDataOutput]+):+ """Get runtime data for a specific cell including code, errors, and variables.++ This tool provides detailed runtime information for a specific cell,+ including its source code, any execution errors, and the variables+ defined or modified in that cell.++ Args:+ session_id: The session ID of the notebook from get_active_notebooks+ cell_id: The specific cell ID to get runtime data for from get_lightweight_cell_map++ Returns:+ A success result containing cell runtime data including code, errors, and variables.+ """++ def handle(self, args: GetCellRuntimeDataArgs) -> GetCellRuntimeDataOutput:+ session_id = args.session_id+ cell_id = args.cell_id+ context = self.context+ session = context.get_session(session_id)++ # Get cell data using CellManager's existing method+ cell_data = self._get_cell_data(session, session_id, cell_id)++ # Get cell code/source+ cell_code = cell_data.code++ # Get cell errors from session view with actual error details+ cell_errors = self._get_cell_errors(session, cell_id)++ # Get cell runtime metadata+ cell_metadata = self._get_cell_metadata(session, cell_id)++ # Get variable names and values defined by the cell+ cell_variables = self._get_cell_variables(session, cell_data)++ return GetCellRuntimeDataOutput(+ data=GetCellRuntimeDataData(+ session_id=session_id,+ cell_id=cell_id,+ code=cell_code,+ errors=cell_errors,+ metadata=cell_metadata,+ variables=cell_variables,+ ),+ next_steps=[+ "Review cell code for understanding the implementation",+ "Check errors to identify any execution issues",+ "Examine variables to understand cell outputs and state",+ ],+ )++ # helper methods++ def _get_cell_data(+ self, session: Session, session_id: SessionId, cell_id: CellId_t+ ) -> CellData:+ cell_manager = session.app_file_manager.app.cell_manager+ cell_data = cell_manager.get_cell_data(cell_id)+ if cell_data is None:+ raise ToolExecutionError(+ f"Cell {cell_id} not found in session {session_id}",+ code="CELL_NOT_FOUND",+ is_retryable=False,+ suggested_fix="Use get_lightweight_cell_map to find valid cell IDs",+ )+ return cell_data++ def _get_cell_errors(+ self, session: Session, cell_id: CellId_t+ ) -> CellErrors:+ """Get cell errors from session view with actual error details."""+ from marimo._messaging.cell_output import CellChannel++ # Get cell operation from session view+ session_view = session.session_view+ cell_op = session_view.cell_operations.get(cell_id)++ if cell_op is None:+ # No operations recorded for this cell+ return CellErrors(has_errors=False, error_details=None)++ # Check for actual error details in the output+ has_errors = False+ error_details = []+ if (+ cell_op.output+ and cell_op.output.channel == CellChannel.MARIMO_ERROR+ ):+ has_errors = True+ # Extract actual error objects+ errors = cell_op.output.data+ if isinstance(errors, list):+ for error in errors:+ if hasattr(error, "type") and hasattr(error, "describe"):+ # Rich Error object+ error_detail = ErrorDetail(+ type=error.type,+ message=error.describe(),+ traceback=getattr(error, "traceback", []),+ )+ error_details.append(error_detail)+ elif isinstance(error, dict):+ # Dict-based error+ dict_error_detail = ErrorDetail(+ type=error.get("type", "UnknownError"),+ message=error.get("msg", str(error)),+ traceback=error.get("traceback", []),+ )+ error_details.append(dict_error_detail)+ else:+ # Fallback for other error types+ fallback_error_detail = ErrorDetail(+ type=type(error).__name__,+ message=str(error),+ traceback=[],+ )+ error_details.append(fallback_error_detail)++ # Check console outputs for STDERR (includes print statements to stderr, warnings, etc.)+ if cell_op.console:+ console_outputs = (+ cell_op.console+ if isinstance(cell_op.console, list)+ else [cell_op.console]+ )+ for console_output in console_outputs:+ if console_output.channel == CellChannel.STDERR:+ has_errors = True+ stderr_error_detail = ErrorDetail(+ type="STDERR",+ message=str(console_output.data),+ traceback=[],+ )+ error_details.append(stderr_error_detail)++ return CellErrors(+ has_errors=has_errors,+ error_details=error_details if error_details else None,+ )++ def _get_cell_metadata(+ self, session: Session, cell_id: CellId_t+ ) -> CellRuntimeMetadata:+ """Get cell runtime metadata including status and execution info."""+ # Get basic runtime state from session view+ session_view = session.session_view+ cell_op = session_view.cell_operations.get(cell_id)++ runtime_state = None+ if cell_op and cell_op.status is not None:+ runtime_state = cell_op.status++ # Get execution time if available+ execution_time = session_view.last_execution_time.get(cell_id)++ return CellRuntimeMetadata(+ runtime_state=runtime_state, execution_time=execution_time+ )++ def _get_cell_variables(+ self, session: Session, cell_data: Optional[CellData]+ ) -> CellVariables:+ """Get variables defined by a specific cell and their values."""+ if not cell_data or not cell_data.cell:+ return {}++ # Get all current variables from session view+ session_view = session.session_view+ all_variables = session_view.variable_values++ # Get variables defined by this cell+ cell_defs = cell_data.cell._cell.defs++ # Filter to only variables defined by this cell+ cell_variables: CellVariables = {}+ for var_name in cell_defs:+ if var_name in all_variables:+ var_value = all_variables[var_name]+ cell_variables[var_name] = CellVariableValue(+ name=var_name,+ value=var_value.value,+ datatype=var_value.datatype,+ )++ return cell_variablesdiff --git a/marimo/_ai/_tools/tools/notebooks.py b/marimo/_ai/_tools/tools/notebooks.pynew file mode 100644index 0000000000..1ed9fbb4ec--- /dev/null+++ b/marimo/_ai/_tools/tools/notebooks.py@@ -0,0 +1,129 @@+from dataclasses import dataclass, field+from typing import Optional++from marimo._ai._tools.base import ToolBase+from marimo._ai._tools.types import (+ EmptyArgs,+ SuccessResult,+)+from marimo._server.model import ConnectionState+from marimo._server.models.home import MarimoFile+from marimo._server.sessions import SessionManager+from marimo._types.ids import SessionId+from marimo._utils.paths import pretty_path+++@dataclass+class NotebookInfo:+ name: str+ path: str+ session_id: Optional[SessionId] = None+ initialization_id: Optional[str] = None+++@dataclass+class SummaryInfo:+ total_notebooks: int+ total_sessions: int+ active_connections: int+++@dataclass+class GetActiveNotebooksData:+ summary: SummaryInfo+ notebooks: list[NotebookInfo]+++def _default_active_notebooks_data() -> GetActiveNotebooksData:+ return GetActiveNotebooksData(+ summary=SummaryInfo(+ total_notebooks=0, total_sessions=0, active_connections=0+ ),+ notebooks=[],+ )+++@dataclass+class GetActiveNotebooksOutput(SuccessResult):+ data: GetActiveNotebooksData = field(+ default_factory=_default_active_notebooks_data+ )+++class GetActiveNotebooks(ToolBase[EmptyArgs, GetActiveNotebooksOutput]):+ """List currently active marimo notebooks and a summary block.++ Returns:+ A success result containing summary statistics and notebook details.+ """++ def handle(self, args: EmptyArgs) -> GetActiveNotebooksOutput:+ del args+ context = self.context+ session_manager = context.session_manager+ active_files = self._get_active_sessions_internal(session_manager)++ # Build notebooks list+ notebooks: list[NotebookInfo] = []+ for file_info in active_files:+ notebooks.append(+ NotebookInfo(+ name=file_info.name,+ path=file_info.path,+ session_id=file_info.session_id,+ initialization_id=file_info.initialization_id,+ )+ )++ # Build summary statistics+ summary: SummaryInfo = SummaryInfo(+ total_notebooks=len(active_files),+ total_sessions=len(session_manager.sessions),+ active_connections=session_manager.get_active_connection_count(),+ )++ # Build data object+ data = GetActiveNotebooksData(summary=summary, notebooks=notebooks)++ # Return a success result with summary statistics and notebook details+ return GetActiveNotebooksOutput(+ data=data,+ next_steps=[+ "Use the `get_lightweight_cell_map` tool to get the content of a notebook",+ "Use the `get_cell_runtime_data` tool to get the code, errors, and variables of a cell if you already have the cell id",+ ],+ )++ # helper methods++ def _get_active_sessions_internal(+ self, session_manager: SessionManager+ ) -> list[MarimoFile]:+ """+ Get active sessions from the app state.++ This replicates the logic from marimo/_server/api/endpoints/home.py+ """+ import os++ files: list[MarimoFile] = []+ for session_id, session in session_manager.sessions.items():+ state = session.connection_state()+ if (+ state == ConnectionState.OPEN+ or state == ConnectionState.ORPHANED+ ):+ filename = session.app_file_manager.filename+ basename = os.path.basename(filename) if filename else None+ files.append(+ MarimoFile(+ name=(basename or "new notebook"),+ path=(+ pretty_path(filename) if filename else session_id+ ),+ session_id=session_id,+ initialization_id=session.initialization_id,+ )+ )+ # Return most recent notebooks first (reverse chronological order)+ return files[::-1]diff --git a/marimo/_ai/_tools/types.py b/marimo/_ai/_tools/types.pynew file mode 100644index 0000000000..0cb92d5203--- /dev/null+++ b/marimo/_ai/_tools/types.py@@ -0,0 +1,23 @@+# Copyright 2025 Marimo. All rights reserved.+from __future__ import annotations++from dataclasses import dataclass+from typing import Any, Literal, Optional++# helper classes+StatusValue = Literal["success", "error", "warning"]+++@dataclass+class SuccessResult:+ status: StatusValue = "success"+ auth_required: bool = False+ next_steps: Optional[list[str]] = None+ action_url: Optional[str] = None+ message: Optional[str] = None+ meta: Optional[dict[str, Any]] = None+++@dataclass+class EmptyArgs:+ passdiff --git a/marimo/_ai/_tools/utils/exceptions.py b/marimo/_ai/_tools/utils/exceptions.pynew file mode 100644index 0000000000..654bbf073b--- /dev/null+++ b/marimo/_ai/_tools/utils/exceptions.py@@ -0,0 +1,39 @@+from __future__ import annotations++from dataclasses import asdict, dataclass+from typing import Any, Optional+++@dataclass+class ToolExecutionError(Exception):+ """Raise this from a tool to signal a descriptive, structured failure."""++ message: str+ code: str = "TOOL_ERROR"+ status: int = 400+ is_retryable: bool = False+ suggested_fix: Optional[str] = None+ meta: Optional[dict[str, Any]] = None++ def __post_init__(self) -> None:+ # Initialize base Exception with the structured JSON message+ # Necessary since some MCP client (e.g. Cursor) only logs the original message+ super().__init__(self._create_structured_message())++ @property+ def original_message(self) -> str:+ return self.message++ def _create_structured_message(self) -> str:+ """Create a message that includes all structured error information."""+ import json++ payload = asdict(self)+ payload["meta"] = payload.get("meta", {})+ return json.dumps(payload, separators=(",", ":"))++ def to_dict(self) -> dict[str, Any]:+ """Return a dictionary representation for testing."""+ payload = asdict(self)+ payload["meta"] = payload.get("meta", {})+ return payloaddiff --git a/marimo/_mcp/server/tools/cells.py b/marimo/_mcp/server/tools/cells.pyindex 5341cc3276..4a30788d67 100644--- a/marimo/_mcp/server/tools/cells.py+++ b/marimo/_mcp/server/tools/cells.py@@ -1,424 +1,19 @@# Copyright 2025 Marimo. All rights reserved.-from dataclasses import dataclass-from enum import Enum-from typing import TYPE_CHECKING, Optionalfrom mcp.server.fastmcp import FastMCPfrom starlette.applications import Starlette-from marimo._ast.cell import RuntimeStateType-from marimo._ast.models import CellData-from marimo._mcp.server.exceptions import ToolExecutionError-from marimo._mcp.server.responses import (- SuccessResult,+from marimo._ai._tools.base import ToolContext+from marimo._ai._tools.tools.cells import (+ GetCellRuntimeData,+ GetLightweightCellMap,)-from marimo._server.api.deps import AppStateBase-from marimo._types.ids import CellId_t, SessionId--if TYPE_CHECKING:- from marimo._ast.cell import Cell- from marimo._server.sessions import Session---class SupportedCellType(Enum):- """Enum for core marimo cell types."""-- CODE = "code"- MARKDOWN = "markdown"- SQL = "sql"---@dataclass(kw_only=True)-class LightweightCellInfo:- cell_id: str- preview: str # First X lines of code- line_count: int- cell_type: SupportedCellType---@dataclass(kw_only=True)-class GetLightweightCellMapData:- session_id: str- notebook_name: str- cells: list[LightweightCellInfo]- total_cells: int- preview_lines: int # How many lines were shown per cell---@dataclass(kw_only=True)-class GetLightweightCellMapResponse(SuccessResult):- data: GetLightweightCellMapData---@dataclass(kw_only=True)-class ErrorDetail:- type: str- message: str- traceback: list[str]---@dataclass(kw_only=True)-class CellErrors:- has_errors: bool- error_details: Optional[list[ErrorDetail]]---@dataclass(kw_only=True)-class CellRuntimeMetadata:- runtime_state: Optional[RuntimeStateType]- execution_time: Optional[float]---@dataclass(kw_only=True)-class CellVariableValue:- name: str- value: Optional[str] = None- datatype: Optional[str] = None---CellVariables = dict[str, CellVariableValue]---@dataclass(kw_only=True)-class GetCellRuntimeDataData:- session_id: str- cell_id: str- code: Optional[str]- errors: Optional[CellErrors]- metadata: Optional[CellRuntimeMetadata]- variables: Optional[CellVariables]---@dataclass(kw_only=True)-class GetCellRuntimeDataResponse(SuccessResult):- data: GetCellRuntimeDataDatadef register_cells_tools(mcp: FastMCP, app: Starlette) -> None:"""Register cell-level management tools"""- @mcp.tool()- def get_lightweight_cell_map(- session_id: str, preview_lines: int = 3- ) -> GetLightweightCellMapResponse:- """Get a lightweight map of cells showing the first few lines of each cell.-- This tool provides an overview of notebook structure for initial navigation,- showing a preview of each cell's content without full code or outputs.-- Args:- session_id: The session ID of the notebook from get_active_notebooks- preview_lines: Number of lines to show per cell (default: 3)-- Returns:- A success result containing lightweight cell previews and navigation info.- """- try:- app_state = AppStateBase.from_app(app)-- # Access session manager and get the specific session- session_manager = app_state.session_manager- session_id_typed = SessionId(session_id)- if session_id_typed not in session_manager.sessions:- raise ToolExecutionError(- f"Session {session_id} not found",- code="SESSION_NOT_FOUND",- is_retryable=False,- suggested_fix="Use get_active_notebooks to find valid session IDs",- )-- session = session_manager.sessions[session_id_typed]-- # Get cell manager from the session's app file manager- cell_manager = session.app_file_manager.app.cell_manager- notebook_filename = (- session.app_file_manager.filename or "untitled_notebook.py"- )-- # Build actual cell map from cell manager data- cells: list[LightweightCellInfo] = []- for cell_data in cell_manager.cell_data():- code_lines = cell_data.code.split("\n")- preview = "\n".join(code_lines[:preview_lines])-- # Determine cell type using actual marimo cell data when available- cell_type = _determine_cell_type(- cell_data.code, cell_data.cell- )-- cells.append(- LightweightCellInfo(- cell_id=cell_data.cell_id,- preview=preview,- line_count=len(code_lines),- cell_type=cell_type,- )- )-- # Return a success result with lightweight cell map- return GetLightweightCellMapResponse(- data=GetLightweightCellMapData(- session_id=session_id,- notebook_name=notebook_filename,- cells=cells,- total_cells=len(cells),- preview_lines=preview_lines,- ),- next_steps=[- "Use cell_id to get full cell content or execute specific cells",- "Identify key sections based on cell types and previews",- "Focus on import cells first to understand dependencies",- ],- message="Refer to cells ordinally in the following format: @[cell:1]. Do _not_ use cell_id when discussing the with users.",- )-- except Exception as e:- # Return a structured error result- raise ToolExecutionError(- f"Failed to retrieve cell map for session {session_id}",- code="CELL_MAP_ERROR",- is_retryable=True,- suggested_fix="Verify the session_id exists and the notebook is active. You can use the get_active_notebooks tool.",- meta={- "session_id": session_id,- "preview_lines": preview_lines,- },- ) from e-- @mcp.tool()- def get_cell_runtime_data(- session_id: str, cell_id: str- ) -> GetCellRuntimeDataResponse:- """Get runtime data for a specific cell including code, errors, and variables.-- This tool provides detailed runtime information for a specific cell,- including its source code, any execution errors, and the variables- defined or modified in that cell.-- Args:- session_id: The session ID of the notebook from get_active_notebooks- cell_id: The specific cell ID to get runtime data for from get_lightweight_cell_map-- Returns:- A success result containing cell runtime data including code, errors, and variables.- """- try:- app_state = AppStateBase.from_app(app)-- # Access session manager and get the specific session- session_manager = app_state.session_manager- session_id_typed = SessionId(session_id)- if session_id_typed not in session_manager.sessions:- raise ToolExecutionError(- f"Session {session_id} not found",- code="SESSION_NOT_FOUND",- is_retryable=False,- suggested_fix="Use get_active_notebooks to find valid session IDs",- )-- session = session_manager.sessions[session_id_typed]- cell_manager = session.app_file_manager.app.cell_manager-- # Get cell data using CellManager's existing method- cell_id_typed = CellId_t(cell_id)- cell_data = cell_manager.get_cell_data(cell_id_typed)- if cell_data is None:- raise ToolExecutionError(- f"Cell {cell_id} not found in session {session_id}",- code="CELL_NOT_FOUND",- is_retryable=False,- suggested_fix="Use get_lightweight_cell_map to find valid cell IDs",- )-- # Get cell code/source- cell_code = cell_data.code-- # Get cell errors from session view with actual error details- cell_errors = _get_cell_errors(session, cell_id_typed)-- # Get cell runtime metadata- cell_metadata = _get_cell_metadata(session, cell_id_typed)-- # Get variable names and values defined by the cell- cell_variables = _get_cell_variables(session, cell_data)-- return GetCellRuntimeDataResponse(- data=GetCellRuntimeDataData(- session_id=session_id,- cell_id=cell_id,- code=cell_code,- errors=cell_errors,- metadata=cell_metadata,- variables=cell_variables,- ),- next_steps=[- "Review cell code for understanding the implementation",- "Check errors to identify any execution issues",- "Examine variables to understand cell outputs and state",- ],- )-- except ToolExecutionError:- # Re-raise our specific tool errors (like CELL_NOT_FOUND, SESSION_NOT_FOUND)- raise- except Exception as e:- # Only catch unexpected exceptions- raise ToolExecutionError(- f"Failed to retrieve runtime data for cell {cell_id} in session {session_id}",- code="CELL_RUNTIME_ERROR",- is_retryable=True,- suggested_fix="Verify the session_id using get_active_notebooks and the cell_id using get_lightweight_cell_map.",- meta={"session_id": session_id, "cell_id": cell_id},- ) from e---# Utility functions-def is_markdown_cell(code: str) -> bool:- """Check if a cell is a markdown cell."""- if code.lstrip().startswith("mo.md("):- return True- return False---def _determine_cell_type(- code: str, cell: Optional["Cell"] = None-) -> SupportedCellType:- """Determine the type of cell based on marimo's compiled cell data.-- Uses the actual Language field from CellData.cell.language when available,- falling back to code analysis for edge cases.- Only returns types from Literal["code", "markdown", "sql"].- """-- # If we have the compiled cell data, use marimo's official language detection- if cell is not None:- language = cell._cell.language- if language == "sql":- return SupportedCellType.SQL- elif language == "python":- # For Python cells, check if it's actually a markdown cell- # by using marimo's official markdown detection- if is_markdown_cell(code):- return SupportedCellType.MARKDOWN- return SupportedCellType.CODE-- # Default to code for all other cases- return SupportedCellType.CODE---def _get_cell_errors(session: "Session", cell_id: CellId_t) -> CellErrors:- """Get cell errors from session view with actual error details."""- from marimo._messaging.cell_output import CellChannel-- # Get cell operation from session view- session_view = session.session_view- cell_op = session_view.cell_operations.get(cell_id)-- if cell_op is None:- # No operations recorded for this cell- return CellErrors(has_errors=False, error_details=None)-- # Check for actual error details in the output- has_errors = False- error_details = []- if cell_op.output and cell_op.output.channel == CellChannel.MARIMO_ERROR:- has_errors = True- # Extract actual error objects- errors = cell_op.output.data- if isinstance(errors, list):- for error in errors:- if hasattr(error, "type") and hasattr(error, "describe"):- # Rich Error object- error_detail = ErrorDetail(- type=error.type,- message=error.describe(),- traceback=getattr(error, "traceback", []),- )- error_details.append(error_detail)- elif isinstance(error, dict):- # Dict-based error- dict_error_detail = ErrorDetail(- type=error.get("type", "UnknownError"),- message=error.get("msg", str(error)),- traceback=error.get("traceback", []),- )- error_details.append(dict_error_detail)- else:- # Fallback for other error types- fallback_error_detail = ErrorDetail(- type=type(error).__name__,- message=str(error),- traceback=[],- )- error_details.append(fallback_error_detail)-- # Check console outputs for STDERR (includes print statements to stderr, warnings, etc.)- if cell_op.console:- console_outputs = (- cell_op.console- if isinstance(cell_op.console, list)- else [cell_op.console]- )- for console_output in console_outputs:- if console_output.channel == CellChannel.STDERR:- has_errors = True- stderr_error_detail = ErrorDetail(- type="STDERR",- message=str(console_output.data),- traceback=[],- )- error_details.append(stderr_error_detail)-- return CellErrors(- has_errors=has_errors,- error_details=error_details if error_details else None,- )---def _get_cell_metadata(- session: "Session", cell_id: CellId_t-) -> CellRuntimeMetadata:- """Get cell runtime metadata including status and execution info."""- # Get basic runtime state from session view- session_view = session.session_view- cell_op = session_view.cell_operations.get(cell_id)-- runtime_state = None- if cell_op and cell_op.status is not None:- runtime_state = cell_op.status-- # Get execution time if available- execution_time = session_view.last_execution_time.get(cell_id)-- return CellRuntimeMetadata(- runtime_state=runtime_state, execution_time=execution_time- )---def _get_cell_variables(- session: "Session", cell_data: Optional[CellData]-) -> CellVariables:- """Get variables defined by a specific cell and their values."""- if not cell_data or not cell_data.cell:- return {}-- # Get all current variables from session view- session_view = session.session_view- all_variables = session_view.variable_values-- # Get variables defined by this cell- cell_defs = cell_data.cell._cell.defs-- # Filter to only variables defined by this cell- cell_variables: CellVariables = {}- for var_name in cell_defs:- if var_name in all_variables:- var_value = all_variables[var_name]- # Convert VariableValue to pydantic parsable dataclass- cell_variables[var_name] = CellVariableValue(- name=var_name,- value=var_value.value,- datatype=var_value.datatype,- )+ context = ToolContext(app=app)- return cell_variables+ mcp.tool()(GetLightweightCellMap(context).as_mcp_tool_fn())+ mcp.tool()(GetCellRuntimeData(context).as_mcp_tool_fn())diff --git a/marimo/_mcp/server/tools/notebooks.py b/marimo/_mcp/server/tools/notebooks.pyindex b470cab6fa..c0aca850fa 100644--- a/marimo/_mcp/server/tools/notebooks.py+++ b/marimo/_mcp/server/tools/notebooks.py@@ -1,126 +1,15 @@# Copyright 2025 Marimo. All rights reserved.-from dataclasses import dataclass-from typing import Optionalfrom mcp.server.fastmcp import FastMCPfrom starlette.applications import Starlette-from marimo._mcp.server.exceptions import ToolExecutionError-from marimo._mcp.server.responses import (- SuccessResult,-)-from marimo._server.api.deps import AppStateBase-from marimo._server.model import ConnectionState-from marimo._server.models.home import MarimoFile-from marimo._types.ids import SessionId-from marimo._utils.paths import pretty_path---@dataclass(kw_only=True)-class NotebookInfo:- name: str- path: str- session_id: Optional[SessionId]- initialization_id: Optional[str]---@dataclass(kw_only=True)-class SummaryInfo:- total_notebooks: int- total_sessions: int- active_connections: int---@dataclass(kw_only=True)-class GetActiveNotebooksData:- summary: SummaryInfo- notebooks: list[NotebookInfo]---@dataclass(kw_only=True)-class GetActiveNotebooksResponse(SuccessResult):- data: GetActiveNotebooksData+from marimo._ai._tools.base import ToolContext+from marimo._ai._tools.tools.notebooks import GetActiveNotebooksdef register_notebooks_tools(mcp: FastMCP, app: Starlette) -> None:"""Register notebook-level management tools"""- @mcp.tool()- def get_active_notebooks() -> GetActiveNotebooksResponse:- """List currently active marimo notebooks and a summary block.-- Returns:- A success result containing summary statistics and notebook details.- """- try:- app_state = AppStateBase.from_app(app)- active_files = _get_active_sessions_internal(app_state)-- # Build notebooks list- notebooks: list[NotebookInfo] = []- for file_info in active_files:- notebooks.append(- NotebookInfo(- name=file_info.name,- path=file_info.path,- session_id=file_info.session_id,- initialization_id=file_info.initialization_id,- )- )-- # Build summary statistics- session_manager = app_state.session_manager- summary: SummaryInfo = SummaryInfo(- total_notebooks=len(active_files),- total_sessions=len(session_manager.sessions),- active_connections=session_manager.get_active_connection_count(),- )-- # Build data object- data = GetActiveNotebooksData(summary=summary, notebooks=notebooks)-- # Return a success result with summary statistics and notebook details- return GetActiveNotebooksResponse(- data=data,- next_steps=[- "Use the `get_lightweight_cell_map` tool to get the content of a notebook"- ],- )-- except Exception as e:- # Return a structured error result- raise ToolExecutionError(- "Failed to retrieve active notebooks",- code="NOTEBOOK_FETCH_ERROR",- is_retryable=True,- suggested_fix="Tell the user to check if marimo server is running and accessible. Suggest restarting the server if they haven't already tried that.",- ) from e---# Utility functions---def _get_active_sessions_internal(app_state: AppStateBase) -> list[MarimoFile]:- """- Get active sessions from the app state.-- This replicates the logic from marimo/_server/api/endpoints/home.py- """- import os+ context = ToolContext(app=app)- files: list[MarimoFile] = []- for session_id, session in app_state.session_manager.sessions.items():- state = session.connection_state()- if state == ConnectionState.OPEN or state == ConnectionState.ORPHANED:- filename = session.app_file_manager.filename- basename = os.path.basename(filename) if filename else None- files.append(- MarimoFile(- name=(basename or "new notebook"),- path=(pretty_path(filename) if filename else session_id),- session_id=session_id,- initialization_id=session.initialization_id,- )- )- # Return most recent notebooks first (reverse chronological order)- return files[::-1]+ mcp.tool()(GetActiveNotebooks(context).as_mcp_tool_fn())diff --git a/tests/_ai/tools/test_base.py b/tests/_ai/tools/test_base.pynew file mode 100644index 0000000000..7616f31b8d--- /dev/null+++ b/tests/_ai/tools/test_base.py@@ -0,0 +1,55 @@+from __future__ import annotations++import inspect+from dataclasses import dataclass+from typing import Any++from marimo._ai._tools.base import ToolBase, ToolContext+++@dataclass+class _Args:+ value: int+++@dataclass+class _Out:+ doubled: int+++class _EchoTool(ToolBase[_Args, _Out]):+ """Dummy tool for testing base adapter behavior."""++ def handle(self, args: _Args) -> _Out:+ return _Out(doubled=args.value * 2)+++def test_as_mcp_tool_fn_returns_async_callable() -> None:+ tool = _EchoTool(ToolContext())+ handler = tool.as_mcp_tool_fn()++ assert inspect.iscoroutinefunction(handler)+++def test_handler_annotations_and_signature() -> None:+ tool = _EchoTool(ToolContext())+ handler = tool.as_mcp_tool_fn()++ annotations: dict[str, Any] = getattr(handler, "__annotations__", {})+ assert annotations.get("args") is _Args+ assert annotations.get("return") is _Out++ sig = getattr(handler, "__signature__", None)+ assert sig is not None+ params = list(sig.parameters.values())+ assert len(params) == 1+ assert params[0].name == "args"+ assert sig.return_annotation is _Out+++def test_name_and_description_defaults() -> None:+ tool = _EchoTool(ToolContext())+ # Name should default from class name+ assert tool.name == "_echo_tool"+ # Description defaults to class docstring (stripped)+ assert "Dummy tool" in (tool.description or "")diff --git a/tests/_ai/tools/tools/test_cells.py b/tests/_ai/tools/tools/test_cells.pynew file mode 100644index 0000000000..566a161d6c--- /dev/null+++ b/tests/_ai/tools/tools/test_cells.py@@ -0,0 +1,173 @@+from __future__ import annotations++from dataclasses import dataclass, field+from unittest.mock import Mock++from marimo._ai._tools.base import ToolContext+from marimo._ai._tools.tools.cells import (+ CellErrors,+ CellRuntimeMetadata,+ CellVariables,+ CellVariableValue,+ GetCellRuntimeData,+ GetLightweightCellMap,+)+from marimo._messaging.cell_output import CellChannel+from marimo._messaging.ops import VariableValue+++@dataclass+class MockCellOp:+ output: object | None = None+ console: object | None = None+ status: object | None = None+++@dataclass+class MockOutput:+ channel: object+ data: object+++@dataclass+class MockConsoleOutput:+ channel: object+ data: object+++@dataclass+class MockError:+ type: str+ _message: str+ traceback: list[str] = field(default_factory=list)++ def describe(self) -> str:+ return self._message+++@dataclass+class MockSessionView:+ cell_operations: dict | None = None+ last_execution_time: dict | None = None+ variable_values: dict | None = None++ def __post_init__(self) -> None:+ if self.cell_operations is None:+ self.cell_operations = {}+ if self.last_execution_time is None:+ self.last_execution_time = {}+ if self.variable_values is None:+ self.variable_values = {}+++@dataclass+class MockSession:+ session_view: MockSessionView+++def test_is_markdown_cell():+ tool = GetLightweightCellMap(ToolContext())+ assert tool._is_markdown_cell('mo.md("hi")') is True+ assert tool._is_markdown_cell("print('x')") is False+++def test_get_cell_errors_no_cell_op():+ tool = GetCellRuntimeData(ToolContext())+ session = MockSession(MockSessionView())++ result = tool._get_cell_errors(session, "missing")+ assert result == CellErrors(has_errors=False, error_details=None)+++def test_get_cell_errors_with_marimo_error():+ tool = GetCellRuntimeData(ToolContext())+ error = MockError(+ "NameError", "name 'x' is not defined", ["line1", "line2"]+ )+ output = MockOutput(CellChannel.MARIMO_ERROR, [error])+ cell_op = MockCellOp(output=output)+ session = MockSession(MockSessionView(cell_operations={"c1": cell_op}))++ result = tool._get_cell_errors(session, "c1")+ assert result.has_errors is True+ assert result.error_details is not None+ assert result.error_details[0].type == "NameError"+++def test_get_cell_errors_with_stderr():+ tool = GetCellRuntimeData(ToolContext())+ console_output = MockConsoleOutput(CellChannel.STDERR, "warn")+ cell_op = MockCellOp(console=[console_output])+ session = MockSession(MockSessionView(cell_operations={"c1": cell_op}))++ result = tool._get_cell_errors(session, "c1")+ assert result.has_errors is True+ assert result.error_details is not None+ assert result.error_details[0].type == "STDERR"+++def test_get_cell_errors_dict_error():+ tool = GetCellRuntimeData(ToolContext())+ dict_error = {"type": "ValueError", "msg": "invalid", "traceback": ["tb1"]}+ output = MockOutput(CellChannel.MARIMO_ERROR, [dict_error])+ cell_op = MockCellOp(output=output)+ session = MockSession(MockSessionView(cell_operations={"c1": cell_op}))++ result = tool._get_cell_errors(session, "c1")+ assert result.has_errors is True+ assert result.error_details is not None+ assert result.error_details[0].type == "ValueError"+++def test_get_cell_metadata_basic():+ tool = GetCellRuntimeData(ToolContext())+ cell_op = MockCellOp(status="idle")+ session = MockSession(+ MockSessionView(+ cell_operations={"c1": cell_op}, last_execution_time={"c1": 42.5}+ )+ )++ result = tool._get_cell_metadata(session, "c1")+ assert result == CellRuntimeMetadata(+ runtime_state="idle", execution_time=42.5+ )+++def test_get_cell_metadata_no_cell_op():+ tool = GetCellRuntimeData(ToolContext())+ session = MockSession(MockSessionView())++ result = tool._get_cell_metadata(session, "missing")+ assert result == CellRuntimeMetadata(+ runtime_state=None, execution_time=None+ )+++def test_get_cell_variables():+ tool = GetCellRuntimeData(ToolContext())+ cell = Mock()+ cell._cell = Mock()+ cell._cell.defs = {"x", "y"}+ cell_data = Mock()+ cell_data.cell = cell++ var_x = VariableValue("x", 42, "int")+ var_y = VariableValue("y", "hi", "str")+ var_z = VariableValue("z", [1], "list")++ session = MockSession(+ MockSessionView(variable_values={"x": var_x, "y": var_y, "z": var_z})+ )++ result = tool._get_cell_variables(session, cell_data)+ expected: CellVariables = {+ "x": CellVariableValue(+ name="x", value=var_x.value, datatype=var_x.datatype+ ),+ "y": CellVariableValue(+ name="y", value=var_y.value, datatype=var_y.datatype+ ),+ }+ assert result == expected+ assert "z" not in resultdiff --git a/tests/_ai/tools/tools/test_notebooks.py b/tests/_ai/tools/tools/test_notebooks.pynew file mode 100644index 0000000000..1c5e88815d--- /dev/null+++ b/tests/_ai/tools/tools/test_notebooks.py@@ -0,0 +1,122 @@+from __future__ import annotations++import os+from unittest.mock import Mock, patch++from marimo._ai._tools.base import ToolContext+from marimo._ai._tools.tools.notebooks import GetActiveNotebooks+from marimo._server.model import ConnectionState+++class MockSession:+ def __init__(+ self, connection_state, filename=None, session_id="test_session"+ ):+ self._connection_state = connection_state+ self.app_file_manager = Mock()+ self.app_file_manager.filename = filename+ self.initialization_id = f"init_{session_id}"++ def connection_state(self):+ return self._connection_state+++class MockSessionManager:+ def __init__(self, sessions=None):+ self.sessions = sessions or {}+++def test_get_active_sessions_internal_empty():+ tool = GetActiveNotebooks(ToolContext())+ result = tool._get_active_sessions_internal(MockSessionManager())+ assert result == []+++def test_get_active_sessions_internal_open_session():+ tool = GetActiveNotebooks(ToolContext())+ session = MockSession(+ connection_state=ConnectionState.OPEN,+ filename="/path/to/notebook.py",+ session_id="session1",+ )+ session_manager = MockSessionManager({"session1": session})++ with patch(+ "marimo._ai._tools.tools.notebooks.pretty_path"+ ) as mock_pretty_path:+ mock_pretty_path.return_value = "notebook.py"+ result = tool._get_active_sessions_internal(session_manager)++ assert len(result) == 1+ assert result[0].name == "notebook.py"+ assert result[0].path == "notebook.py"+ assert result[0].session_id == "session1"+ assert result[0].initialization_id == "init_session1"+++def test_get_active_sessions_internal_orphaned_session():+ tool = GetActiveNotebooks(ToolContext())+ session = MockSession(+ connection_state=ConnectionState.ORPHANED,+ filename="/path/to/test.py",+ session_id="session2",+ )+ session_manager = MockSessionManager({"session2": session})++ with patch(+ "marimo._ai._tools.tools.notebooks.pretty_path"+ ) as mock_pretty_path:+ mock_pretty_path.return_value = "test.py"+ result = tool._get_active_sessions_internal(session_manager)++ assert len(result) == 1+ assert result[0].name == "test.py"+++def test_get_active_sessions_internal_closed_session():+ tool = GetActiveNotebooks(ToolContext())+ session = MockSession(+ connection_state=ConnectionState.CLOSED,+ filename="/path/to/closed.py",+ session_id="session3",+ )+ session_manager = MockSessionManager({"session3": session})++ result = tool._get_active_sessions_internal(session_manager)+ assert result == []+++def test_get_active_sessions_internal_no_filename():+ tool = GetActiveNotebooks(ToolContext())+ session = MockSession(+ connection_state=ConnectionState.OPEN, filename=None, session_id="s4"+ )+ session_manager = MockSessionManager({"s4": session})++ result = tool._get_active_sessions_internal(session_manager)+ assert len(result) == 1+ assert result[0].name == "new notebook"+ assert result[0].path == "s4"+ assert result[0].session_id == "s4"+++def test_get_active_sessions_internal_multiple_sessions():+ tool = GetActiveNotebooks(ToolContext())+ sessions = {+ "s1": MockSession(ConnectionState.OPEN, "/path/first.py", "s1"),+ "s2": MockSession(ConnectionState.CLOSED, "/path/closed.py", "s2"),+ "s3": MockSession(ConnectionState.ORPHANED, "/path/third.py", "s3"),+ }+ session_manager = MockSessionManager(sessions)++ with patch(+ "marimo._ai._tools.tools.notebooks.pretty_path"+ ) as mock_pretty_path:+ mock_pretty_path.side_effect = lambda x: os.path.basename(x)+ result = tool._get_active_sessions_internal(session_manager)++ assert len(result) == 2+ session_ids = [f.session_id for f in result]+ assert "s3" in session_ids+ assert "s1" in session_ids+ assert "s2" not in session_idsdiff --git a/tests/_mcp/server/tools/test_cells.py b/tests/_mcp/server/tools/test_cells.pydeleted file mode 100644index 772ef48a7e..0000000000--- a/tests/_mcp/server/tools/test_cells.py+++ /dev/null@@ -1,278 +0,0 @@-"""Tests for marimo._mcp.server.tools.cells module."""--from unittest.mock import Mock--import pytest--# Skip all MCP tests if Python < 3.10 or MCP not available-pytest.importorskip("mcp", reason="MCP requires Python 3.10+")---from marimo._mcp.server.tools.cells import (- CellErrors,- CellRuntimeMetadata,- CellVariables,- CellVariableValue,- SupportedCellType,- _determine_cell_type,- _get_cell_errors,- _get_cell_metadata,- _get_cell_variables,-)-from marimo._messaging.cell_output import CellChannel-from marimo._messaging.ops import VariableValue---class MockCellOp:- """Mock CellOp for testing."""-- def __init__(self, output=None, console=None, status=None):- self.output = output- self.console = console- self.status = status---class MockOutput:- """Mock output for testing."""-- def __init__(self, channel, data):- self.channel = channel- self.data = data---class MockConsoleOutput:- """Mock console output for testing."""-- def __init__(self, channel, data):- self.channel = channel- self.data = data---class MockError:- """Mock error object for testing."""-- def __init__(self, error_type, message, traceback=None):- self.type = error_type- self._message = message- self.traceback = traceback or []-- def describe(self):- return self._message---class MockSessionView:- """Mock session view for testing."""-- def __init__(- self,- cell_operations=None,- last_execution_time=None,- variable_values=None,- ):- self.cell_operations = cell_operations or {}- self.last_execution_time = last_execution_time or {}- self.variable_values = variable_values or {}---class MockSession:- """Mock session for testing."""-- def __init__(self, session_view):- self.session_view = session_view---class MockCell:- """Mock cell for testing."""-- def __init__(self, language="python", defs=None):- self._cell = Mock()- self._cell.language = language- self._cell.defs = defs or set()---def test_determine_cell_type_default():- """Test _determine_cell_type defaults to CODE."""- result = _determine_cell_type("print('hello')")- assert result == SupportedCellType.CODE---def test_determine_cell_type_with_sql_cell():- """Test _determine_cell_type with SQL cell."""- cell = MockCell(language="sql")-- result = _determine_cell_type("SELECT * FROM table", cell)- assert result == SupportedCellType.SQL---def test_determine_cell_type_with_python_cell():- """Test _determine_cell_type with Python cell."""- cell = MockCell(language="python")-- result = _determine_cell_type("x = 1", cell)- assert result == SupportedCellType.CODE---def test_get_cell_errors_no_cell_op():- """Test _get_cell_errors when no cell operation exists."""- session_view = MockSessionView()- session = MockSession(session_view)-- result = _get_cell_errors(session, "nonexistent_cell")-- expected = CellErrors(has_errors=False, error_details=None)- assert result == expected---def test_get_cell_errors_with_marimo_error():- """Test _get_cell_errors with marimo error."""- error = MockError(- "NameError", "name 'x' is not defined", ["line 1", "line 2"]- )- output = MockOutput(CellChannel.MARIMO_ERROR, [error])- cell_op = MockCellOp(output=output)-- session_view = MockSessionView(cell_operations={"cell1": cell_op})- session = MockSession(session_view)-- result = _get_cell_errors(session, "cell1")-- assert result.has_errors is True- assert len(result.error_details) == 1- assert result.error_details[0].type == "NameError"- assert result.error_details[0].message == "name 'x' is not defined"- assert result.error_details[0].traceback == ["line 1", "line 2"]---def test_get_cell_errors_with_stderr():- """Test _get_cell_errors with STDERR output."""- console_output = MockConsoleOutput(- CellChannel.STDERR, "Warning: deprecated function"- )- cell_op = MockCellOp(console=[console_output])-- session_view = MockSessionView(cell_operations={"cell1": cell_op})- session = MockSession(session_view)-- result = _get_cell_errors(session, "cell1")-- assert result.has_errors is True- assert len(result.error_details) == 1- assert result.error_details[0].type == "STDERR"- assert result.error_details[0].message == "Warning: deprecated function"- assert result.error_details[0].traceback == []---def test_get_cell_errors_dict_error():- """Test _get_cell_errors with dict-based error."""- dict_error = {- "type": "ValueError",- "msg": "invalid value",- "traceback": ["tb1"],- }- output = MockOutput(CellChannel.MARIMO_ERROR, [dict_error])- cell_op = MockCellOp(output=output)-- session_view = MockSessionView(cell_operations={"cell1": cell_op})- session = MockSession(session_view)-- result = _get_cell_errors(session, "cell1")-- assert result.has_errors is True- assert result.error_details[0].type == "ValueError"- assert result.error_details[0].message == "invalid value"- assert result.error_details[0].traceback == ["tb1"]---def test_get_cell_metadata_basic():- """Test _get_cell_metadata basic functionality."""- cell_op = MockCellOp(status="idle")- session_view = MockSessionView(- cell_operations={"cell1": cell_op}, last_execution_time={"cell1": 42.5}- )- session = MockSession(session_view)-- result = _get_cell_metadata(session, "cell1")-- expected = CellRuntimeMetadata(- runtime_state="idle",- execution_time=42.5,- )- assert result == expected---def test_get_cell_metadata_no_cell_op():- """Test _get_cell_metadata when no cell operation exists."""- session_view = MockSessionView()- session = MockSession(session_view)-- result = _get_cell_metadata(session, "nonexistent")-- expected = CellRuntimeMetadata(- runtime_state=None,- execution_time=None,- )- assert result == expected---def test_get_cell_variables_no_cell_data():- """Test _get_cell_variables with no cell data."""- session = MockSession(MockSessionView())-- result = _get_cell_variables(session, None)-- assert result == {}---def test_get_cell_variables_with_variables():- """Test _get_cell_variables with actual variables."""- # Mock cell with defined variables- cell = MockCell(defs={"x", "y"})- cell_data = Mock()- cell_data.cell = cell-- # Mock variable values- var_x = VariableValue("x", 42, "int")- var_y = VariableValue("y", "hello", "str")- var_z = VariableValue("z", [1, 2, 3], "list") # Not defined by this cell-- session_view = MockSessionView(- variable_values={"x": var_x, "y": var_y, "z": var_z}- )- session = MockSession(session_view)-- result = _get_cell_variables(session, cell_data)-- expected: CellVariables = {- "x": CellVariableValue(- name="x", value=var_x.value, datatype=var_x.datatype- ),- "y": CellVariableValue(- name="y", value=var_y.value, datatype=var_y.datatype- ),- }- assert result == expected- assert (- "z" not in result- ) # Should not include variables not defined by this cell---def test_get_cell_variables_missing_variables():- """Test _get_cell_variables when some defined variables are missing from session."""- cell = MockCell(defs={"x", "y", "z"})- cell_data = Mock()- cell_data.cell = cell-- # Only some variables are available in session- var_x = VariableValue("x", 1, "int")- session_view = MockSessionView(variable_values={"x": var_x})- session = MockSession(session_view)-- result = _get_cell_variables(session, cell_data)-- # Should only include variables that exist in session- expected: CellVariables = {- "x": CellVariableValue(- name="x", value=var_x.value, datatype=var_x.datatype- )- }- assert result == expecteddiff --git a/tests/_mcp/server/tools/test_notebooks.py b/tests/_mcp/server/tools/test_notebooks.pydeleted file mode 100644index 738b6a8f16..0000000000--- a/tests/_mcp/server/tools/test_notebooks.py+++ /dev/null@@ -1,185 +0,0 @@-"""Tests for marimo._mcp.server.tools.notebooks module."""--import os-from unittest.mock import Mock, patch--import pytest--# Skip all MCP tests if Python < 3.10 or MCP not available-pytest.importorskip("mcp", reason="MCP requires Python 3.10+")--from marimo._mcp.server.tools.notebooks import _get_active_sessions_internal-from marimo._server.model import ConnectionState---class MockSession:- """Mock session for testing."""-- def __init__(- self, connection_state, filename=None, session_id="test_session"- ):- self._connection_state = connection_state- self.app_file_manager = Mock()- self.app_file_manager.filename = filename- self.initialization_id = f"init_{session_id}"-- def connection_state(self):- return self._connection_state---class MockSessionManager:- """Mock session manager for testing."""-- def __init__(self, sessions=None):- self.sessions = sessions or {}---class MockAppState:- """Mock app state for testing."""-- def __init__(self, sessions=None):- self.session_manager = MockSessionManager(sessions)---def test_get_active_sessions_internal_empty():- """Test _get_active_sessions_internal with no sessions."""- app_state = MockAppState()-- result = _get_active_sessions_internal(app_state)-- assert result == []---def test_get_active_sessions_internal_open_session():- """Test _get_active_sessions_internal with an open session."""- session = MockSession(- connection_state=ConnectionState.OPEN,- filename="/path/to/notebook.py",- session_id="session1",- )-- app_state = MockAppState({"session1": session})-- with patch(- "marimo._mcp.server.tools.notebooks.pretty_path"- ) as mock_pretty_path:- mock_pretty_path.return_value = "notebook.py"-- result = _get_active_sessions_internal(app_state)-- assert len(result) == 1- assert result[0].name == "notebook.py"- assert result[0].path == "notebook.py"- assert result[0].session_id == "session1"- assert result[0].initialization_id == "init_session1"---def test_get_active_sessions_internal_orphaned_session():- """Test _get_active_sessions_internal with an orphaned session."""- session = MockSession(- connection_state=ConnectionState.ORPHANED,- filename="/path/to/test.py",- session_id="session2",- )-- app_state = MockAppState({"session2": session})-- with patch(- "marimo._mcp.server.tools.notebooks.pretty_path"- ) as mock_pretty_path:- mock_pretty_path.return_value = "test.py"-- result = _get_active_sessions_internal(app_state)-- assert len(result) == 1- assert result[0].name == "test.py"---def test_get_active_sessions_internal_closed_session():- """Test _get_active_sessions_internal ignores closed sessions."""- session = MockSession(- connection_state=ConnectionState.CLOSED,- filename="/path/to/closed.py",- session_id="session3",- )-- app_state = MockAppState({"session3": session})-- result = _get_active_sessions_internal(app_state)-- assert result == []---def test_get_active_sessions_internal_no_filename():- """Test _get_active_sessions_internal with session that has no filename."""- session = MockSession(- connection_state=ConnectionState.OPEN,- filename=None,- session_id="session4",- )-- app_state = MockAppState({"session4": session})-- result = _get_active_sessions_internal(app_state)-- assert len(result) == 1- assert result[0].name == "new notebook"- assert result[0].path == "session4" # Uses session_id as path- assert result[0].session_id == "session4"---def test_get_active_sessions_internal_multiple_sessions():- """Test _get_active_sessions_internal with multiple sessions."""- sessions = {- "session1": MockSession(- ConnectionState.OPEN, "/path/first.py", "session1"- ),- "session2": MockSession(- ConnectionState.CLOSED, "/path/closed.py", "session2"- ),- "session3": MockSession(- ConnectionState.ORPHANED, "/path/third.py", "session3"- ),- }-- app_state = MockAppState(sessions)-- with patch(- "marimo._mcp.server.tools.notebooks.pretty_path"- ) as mock_pretty_path:- mock_pretty_path.side_effect = lambda x: os.path.basename(x)-- result = _get_active_sessions_internal(app_state)-- # Should only include OPEN and ORPHANED sessions (not CLOSED)- assert len(result) == 2-- # Results should be in reverse order (most recent first)- session_ids = [f.session_id for f in result]- assert "session3" in session_ids # ORPHANED session included- assert "session1" in session_ids # OPEN session included- assert "session2" not in session_ids # CLOSED session excluded---def test_get_active_sessions_internal_reverse_order():- """Test that results are returned in reverse order."""- sessions = {- "first": MockSession(ConnectionState.OPEN, "/path/a.py", "first"),- "second": MockSession(ConnectionState.OPEN, "/path/b.py", "second"),- "third": MockSession(ConnectionState.OPEN, "/path/c.py", "third"),- }-- app_state = MockAppState(sessions)-- with patch(- "marimo._mcp.server.tools.notebooks.pretty_path"- ) as mock_pretty_path:- mock_pretty_path.side_effect = lambda x: os.path.basename(x)-- result = _get_active_sessions_internal(app_state)-- # The exact order depends on dict iteration, but should be reversed- # We can at least verify that we get all 3 sessions- assert len(result) == 3- session_ids = [f.session_id for f in result]- assert set(session_ids) == {"first", "second", "third"}