Run a shell command in the workspace. Returns stdout, stderr, and exit code. Use this to run any CLI: git, npm, vitest, supabase, node, etc. Prefer specific commands over shell scripts (no shell interpolation).

Read a file from the workspace. Returns text content for code/config files, or base64 image content for screenshots (.png, .jpg, etc.). Truncates very large files; use offset for partial reads.

Write content to a file, overwriting any existing content. Creates parent directories as needed. Use this for new files or full rewrites. For targeted edits, use mavis_edit instead.

Edit a file by replacing a specific string with new text. Default: replaces the FIRST occurrence only. If old_text is not found or matches multiple times and all_occurrences is false, returns an error. Use this for targeted edits; use mavis_write for full rewrites.

Search for a regex pattern across files in the workspace. Returns file:line:match lines. Uses ripgrep if available (fast), else falls back to node recursive search.

Run a git command in the workspace. Args are passed as an array to avoid shell injection. Examples: ["status"], ["log", "--oneline", "-10"], ["diff"], ["add", "."], ["commit", "-m", "msg"], ["push"].

Run a supabase CLI command in the workspace. Read-only by design — write subcommands (db push, db reset, db execute) are denied. Examples: ["db", "query", "--linked", "SELECT 1"], ["db", "diff"], ["db", "remote", "commit"].

Run vitest tests in the workspace. Optional pattern to filter (e.g. file name or directory). Returns the full vitest output (truncated at 5MB). Use this to verify a fix worked or to reproduce a failure.

Get or update the MCP server's persistent state. Use "get" to see recent files touched and last exit codes (useful for context). Use "save" to force flush state to disk.

Call MiniMax-M3 (OpenAI-compatible) for a single text generation. Use for drafting code, writing explanations, summarizing files, or any text-in/text-out task. Returns the model content plus token usage and latency. For multi-step agentic work with tool calling, see Sprint B-2 (not yet implemented).

Run a multi-step agent loop where MiniMax-M3 can call ANY mavis_* tool (mavis_bash, mavis_read, mavis_write, mavis_edit, mavis_search, mavis_git, mavis_supabase, mavis_run_tests, mavis_state, mavis_auditor, mavis_noter, mavis_session_log, mavis_coder) iteratively until the task is done. Default doctrine (B-6): ALL tools are exposed to the LLM — including non-LLM ones. The LLM is the one that decides which to call. Only mavis_coder_agent is excluded (recursion guard). Emits realtime progress notifications (visible in client UI) and persists the full run to ~/.mavis-mcp/agent-sessions/.

Read-only KOMO antipattern detector. Scans files for: muro_de_fuego (queries to ops_* without ownerId), zero_bifurcation (if/else on categoria), service_no_wire (exported service function — verify window.* wire), mega_function (>200 lines), direct_auth_users (RLS referencing auth.users), jsonb_column_audit (touches JSONB col — cross-check other queries). Returns findings with severity, file, line. Read-only — never modifies the workspace. Use before commits, before refactors, or as a code review assistant.

Query and update the KOMO OS NotebookLM notebook via the nlm CLI. Use to check doctrinal alignment, look up historical decisions, and document new patterns. Default notebook is the KOMO OS doctrinal manifiesto (50+ sources). Actions: query, add_source, create_notebook, list_notebooks, doctor. Requires nlm CLI installed and authenticated.

Read agent run traces persisted to ~/.mavis-mcp/agent-sessions/. Actions: list (recent sessions), get (full session by id/file), tail (last N events of a session), clear (delete sessions older than N days). Use to debug, audit, or post-mortem past mavis_coder_agent runs.