Allows performing git operations such as status, diff, commit, push, and log within the workspace.
Provides read-only querying of Supabase databases via the Supabase CLI, with a denylist for dangerous commands like db push and db reset.
Allows running vitest test suites with optional pattern matching.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Mavis MCP Server Find all HTTP 400 errors in the supabase logs and propose a fix."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Expose Mavis's coding tools (bash, edit, git, supabase) to Claude Code via MCP. Let Claude reason. Mavis executes.
A Model Context Protocol (MCP) server that wraps the same tools Mavis uses internally and exposes them as MCP tools. When connected to Claude Code, you get a workflow like:
┌──────────────────┐
│ Claude Code │ ← you talk to Claude
│ (reasoning) │ ← Claude plans, designs, decides
└────────┬─────────┘
│ MCP protocol (stdio)
▼
┌──────────────────┐
│ Mavis MCP │ ← thin wrapper
│ Server │
└────────┬─────────┘
│ spawns subprocesses
▼
┌──────────────────┐
│ bash, git, │ ← actual execution
│ files, supabase │
└──────────────────┘Claude thinks (planning, architecture, decisions). Mavis MCP does (shell, file edits, git, supabase, tests, screenshots).
This is the same set of tools Mavis uses when running inside MiniMax Code. The only difference is the interface: instead of a chat loop, Mavis's tools are exposed as MCP tools for Claude.
Related MCP server: code-mcp
Mavis has battle-tested tools for:
Reading/writing/editing files
Running bash commands
Git operations
Supabase queries
Running vitest
Reading screenshots
Grep / glob search
These are the same tools that make Mavis effective for the KOMO OS codebase. Exposing them via MCP means Claude gets the same operational power without re-implementing anything.
Tool | Description |
| Run a shell command in the workspace |
| Read a file (text or image) |
| Write/overwrite a file |
| Edit a file (find/replace, single or all occurrences) |
| Grep across files (regex + glob). Uses ripgrep if available. |
| Git operations (status, diff, commit, push, log) |
| Supabase CLI queries (read-only, denylist for mutations) |
| Run vitest with optional pattern |
| Get/save the MCP server's persistent state |
All tools accept an optional cwd to operate on a subdirectory.
cd mavis-mcp-server
npm install
npm run buildAdd to your Claude Code MCP config (~/.config/claude-code/mcp.json or via the Claude Code UI):
{
"mcpServers": {
"mavis": {
"command": "node",
"args": ["/absolute/path/to/mavis-mcp-server/dist/cli.js"],
"env": {
"MAVIS_WORKSPACE": "/absolute/path/to/your/project"
}
}
}
}For development (no build step):
{
"mcpServers": {
"mavis": {
"command": "npx",
"args": ["tsx", "/absolute/path/to/mavis-mcp-server/src/cli.ts"],
"env": {
"MAVIS_WORKSPACE": "/absolute/path/to/your/project"
}
}
}
}The MCP server starts when Claude Code launches. Verify with /mcp in Claude Code.
Once connected, Claude can call the tools:
You: Find all HTTP 400 errors in the supabase logs and propose a fix.
Claude: [plans]
[calls mavis_search, mavis_bash, mavis_read, mavis_edit, mavis_bash, mavis_run_tests, ...]
[reports results]The tools return text content (stdout, file content, etc.) and Claude reasons about the next step.
The MCP server operates within a workspace directory set via MAVIS_WORKSPACE.
All tool calls are scoped to that directory (or its subdirectories via cwd).
This means Claude can't accidentally cd / and rm -rf your home directory.
The workspace is a sandbox.
If you pass an absolute path that escapes the workspace, the tool returns
an error. Try: mavis_read /etc/passwd → "path escapes workspace".
Persistent state lives at <workspace>/.mavis/state.json. It tracks:
Recent files touched (deduped, capped at 50)
Last 20 command exit codes
Workspace metadata (created_at, last_used_at)
State is loaded at startup and saved after each tool call. If the file is missing or corrupt, the server starts fresh.
All bash commands run with the same privileges as the user
The workspace boundary is a UX safeguard, not a security boundary
For real sandboxing, run the MCP server in a container/VM
Each tool has its own safety:
mavis_bash: no command whitelist; rely on workspace + user trust
mavis_edit: refuses multi-replace unless all_occurrences=true (prevents accidents)
mavis_supabase: denylist of dangerous subcommands (db push, db reset, db execute)
mavis_run_tests: respects workspace; no side effects outside
You: Fix the off-by-one error in calculateTotal() in src/billing.ts.
Add a regression test and run the suite.
Claude:
1. mavis_read src/billing.ts
2. mavis_search pattern="calculateTotal" glob="*.ts" cwd=src
3. mavis_read tests/billing.test.ts
4. mavis_edit old_text="i <= arr.length" new_text="i < arr.length"
5. mavis_write tests/billing-total.test.ts
6. mavis_run_tests pattern="tests/billing-total.test.ts"
7. mavis_bash command="git add -A && git commit -m 'fix: off-by-one in calculateTotal'"You: Why are we getting 400s when creating deals?
Claude:
1. mavis_search pattern="400|invalid" cwd=supabase/functions/komo-deal-engine
2. mavis_read supabase/functions/komo-deal-engine/_handler.ts
3. mavis_supabase args=["db", "query", "--linked", "SELECT ... FROM ops_deals WHERE ..."]
4. mavis_edit old_text="..." new_text="..." (fix)
5. mavis_run_tests pattern="tests/wire/sprint28"You: Commit the changes from sprint 29 with a clean message.
Claude:
1. mavis_git args=["status"]
2. mavis_git args=["diff", "--stat"]
3. mavis_git args=["log", "-3", "--oneline"] (for message style)
4. mavis_git args=["add", "."]
5. mavis_git args=["commit", "-m", "feat(sprint-29): ..."] (Claude writes the message)
6. mavis_git args=["push", "origin", "main"]mavis-mcp-server/
├── src/
│ ├── cli.ts # Entry point: parses args, loads workspace, starts server
│ ├── server.ts # MCP server: registers tools, dispatches calls
│ ├── workspace.ts # Workspace isolation (sandbox root)
│ ├── state.ts # Persistent per-workspace state
│ └── tools/
│ ├── index.ts # Tool registry (re-exports individual tools)
│ ├── types.ts # ToolDef + ToolContext interfaces
│ ├── bash.ts
│ ├── read.ts
│ ├── write.ts
│ ├── edit.ts
│ ├── search.ts
│ ├── git.ts
│ ├── supabase.ts
│ ├── run_tests.ts
│ └── state.ts
├── tests/ # Vitest tests
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.mdnpm testnpm run test:watchnpm run buildnpm run devDONE — initial sprint:
Project setup (package.json, tsconfig, vitest)
MCP server skeleton (stdio + tool registration)
9 tools implemented
State management (.mavis/state.json)
60 tests (workspace, state, 9 tools, server integration)
README with Claude Code config + examples
Streaming responses for long-running tools (bash, run_tests)
Tool result caching (avoid re-running the same query)
More tools: mavis_image_read (vision), mavis_lsp (type info)
Multi-workspace support (one server, many projects)
OAuth / API key auth for remote Claude Code
WebSocket transport (instead of stdio only)
This server's name is Mavis (Model-context-protocol Agent for Versatile Implementation & Support). It's the same agentic loop Mavis uses internally, exposed as MCP.
MIT
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.
Inputs: glob, path, checks, max_findings, +1 more.
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).
Inputs: command (required), cwd, timeout_ms.
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).
Inputs: prompt (required), model, system, max_tokens, +1 more.
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/.
Inputs: prompt (required), model, tools, system, +6 more.
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.
Inputs: path (required), new_text (required), old_text (required), cwd, +1 more.
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"].
Inputs: args (required), cwd.
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.
Inputs: action (required), title, source, question, +3 more.
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.
Inputs: path (required), cwd, max_lines.
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.
Inputs: cwd, bail, pattern, timeout_ms.
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.
Inputs: pattern (required), cwd, glob, max_results, +1 more.
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.
Inputs: action (required), limit, tail_n, session_id, +1 more.
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.
Inputs: action (required).
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"].
Inputs: args (required), cwd.
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.
Inputs: path (required), content (required), cwd.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 14 tools
Some overlap exists between mavis_git, mavis_supabase, mavis_run_tests, and mavis_bash, since the latter can execute any command. However, each has a clear specialization and descriptions clarify their intended use, so the ambiguity is moderate.
Naming is inconsistent: some tools follow a verb pattern (read, write, edit, search), while others use nouns or noun phrases (git, bash, supabase, coder_agent, session_log). The common 'mavis_' prefix helps, but there is no predictable verb_noun structure across the set.
With 14 tools, the server covers a broad but well-scoped domain (file operations, command execution, LLM integration, auditing, and session tracking). Each tool serves a distinct purpose and the count is within the ideal range of 3-15.
The tool surface is comprehensive for a development assistant: it provides full file lifecycle (read, write, edit, search), command execution via bash and specialized CLIs, test running, state persistence, multiple LLM modes, code auditing, documentation lookup, and session inspection. No critical gaps are apparent.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
