# Mavis MCP Server

将 Mavis 作为 MCP Server 暴露给 Claude Code / Agent SDK / 任何 MCP 客户端调用。

## 快速开始

### 1. 添加到 Claude Code

```bash
# 方法一：直接配置（全局）
claude mcp add mavis --type stdio -- node /Users/cunning/.mavis/agents/mavis-mcp-server/src/index.js

# 方法二：手动配置项目
# 将以下内容添加到项目根目录的 .mcp.json 文件
```

在项目 `.mcp.json` 中添加：

```json
{
  "mcpServers": {
    "mavis": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/cunning/.mavis/agents/mavis-mcp-server/src/index.js"]
    }
  }
}
```

### 2. 用 Agent SDK 调用

```typescript
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "用 mavis_spawn_worker 启动一个 coder agent，帮我审查 /path/to/project 的代码安全",
  options: {
    mcpServers: {
      mavis: {
        command: "node",
        args: ["/Users/cunning/.mavis/agents/mavis-mcp-server/src/index.js"]
      }
    }
  }
})) {
  console.log(message);
}
```

## 可用工具（22个）

### Session 管理
| Tool | 说明 |
|------|------|
| `mavis_session_list` | 列出所有会话 |
| `mavis_session_info` | 获取会话详情 |
| `mavis_session_messages` | 获取会话消息历史 |
| `mavis_session_new` | 创建新会话（spawn agent） |
| `mavis_session_abort` | 中止运行中的会话 |
| `mavis_session_rotate` | 轮换当前会话 |
| `mavis_session_diff` | 查看会话的文件变更 |

### 通信
| Tool | 说明 |
|------|------|
| `mavis_comm_send` | 向会话发送消息/命令 |
| `mavis_comm_peers` | 列出所有可达会话 |

### Team 编排
| Tool | 说明 |
|------|------|
| `mavis_team_plan` | 多 Agent 并行任务规划执行 |

### Agent 管理
| Tool | 说明 |
|------|------|
| `mavis_agent_list` | 列出所有可用 Agent |
| `mavis_agent_info` | 获取 Agent 详情 |
| `mavis_spawn_worker` | 启动单次验证/审查 Agent |

### Memory
| Tool | 说明 |
|------|------|
| `mavis_memory_append` | 追加记忆条目 |
| `mavis_memory_search` | 搜索记忆 |

### Cron 调度
| Tool | 说明 |
|------|------|
| `mavis_cron_create` | 创建定时任务 |
| `mavis_cron_list` | 列出定时任务 |
| `mavis_cron_delete` | 删除定时任务 |

### 其他
| Tool | 说明 |
|------|------|
| `mavis_skill_list` / `mavis_skill_info` | 技能管理 |
| `mavis_hook_list` | Hook 管理 |
| `mavis_config_show` | 查看配置 |
| `mavis_mcp_list` / `mavis_mcp_call` | MCP 服务器管理 |
| `mavis_status` | 守护进程状态 |
| `mavis_usage` | Token 使用统计 |

## 使用示例

### 在 Claude Code 中使用

```
你：我需要审查这个代码库的安全性，让 Mavis agent 来做
Claude Code：调用 mavis_team_plan，描述任务，Mavis 自动编排 coder + verifier agent 协作完成
```

### 用 mavis_session_new 启动任务

```json
{
  "name": "mavis_session_new",
  "arguments": {
    "agent": "coder",
    "prompt": "审查 /path/to/project/src 的 SQL 注入风险",
    "title": "安全审查任务",
    "workspace": "/path/to/project"
  }
}
```

## 本地开发

```bash
cd /Users/cunning/.mavis/agents/mavis-mcp-server

# 安装
npm install

# 测试 MCP server
node scripts/test-client.js

# 启动 server（stdio 模式）
node src/index.js
```

## 架构说明

```
Claude Code / Agent SDK (MCP Client)
         │
         ▼ stdio JSON-RPC
  ┌─────────────────────────┐
  │   mavis-mcp-server     │
  │   (Node.js stdio transport)
  │                         │
  │   22 MCP tools         │
  │        │                │
  │        ▼ spawn / IPC    │
  └────────┬────────────────┘
           │
           ▼ exec mavis CLI
      Mavis Daemon
      (port 15321)
           │
           ▼
      Mavis Agents
      (mavis, coder, verifier, general)
```

## 文件结构

```
mavis-mcp-server/
├── package.json
├── src/
│   └── index.js       # MCP Server 实现（22个工具）
└── scripts/
    └── test-client.js # 测试客户端
```