Skip to content

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.

refactor(tools): introduce ToolBase and centralize tool implementations (#6309)

Joaquin Corominab700c0bead3c
diff --git a/marimo/_ai/_tools/base.py b/marimo/_ai/_tools/base.py
new file mode 100644
index 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.py
new file mode 100644
index 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_variables
diff --git a/marimo/_ai/_tools/tools/notebooks.py b/marimo/_ai/_tools/tools/notebooks.py
new file mode 100644
index 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.py
new file mode 100644
index 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:
+ pass
diff --git a/marimo/_ai/_tools/utils/exceptions.py b/marimo/_ai/_tools/utils/exceptions.py
new file mode 100644
index 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 payload
diff --git a/marimo/_mcp/server/tools/cells.py b/marimo/_mcp/server/tools/cells.py
index 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, Optional
from mcp.server.fastmcp import FastMCP
from 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: GetCellRuntimeDataData
def 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.py
index 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 Optional
from mcp.server.fastmcp import FastMCP
from 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 GetActiveNotebooks
def 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 result
diff --git a/tests/_ai/tools/tools/test_notebooks.py b/tests/_ai/tools/tools/test_notebooks.py
new file mode 100644
index 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_ids
diff --git a/tests/_mcp/server/tools/test_cells.py b/tests/_mcp/server/tools/test_cells.py
deleted file mode 100644
index 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 == expected
diff --git a/tests/_mcp/server/tools/test_notebooks.py b/tests/_mcp/server/tools/test_notebooks.py
deleted file mode 100644
index 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"}