# whistle-mcp

MCP (Model Context Protocol) Server for whistle - 让 AI 直接操作 whistle 的 Mock 数据。

## 安装

```bash
# 全局安装（推荐）
npm install -g whistle-mcp

# 或直接用 npx，无需安装
npx whistle-mcp
```

## 配置

### 方式一：Cursor

编辑 Cursor 的 MCP 配置文件（`~/.cursor/mcp.json`）：

```json
{
  "mcpServers": {
    "whistle": {
      "command": "npx",
      "args": ["-y", "whistle-mcp"],
      "env": {
        "WHISTLE_BASE_URL": "http://127.0.0.1:8899",
        "WHISTLE_USERNAME": "",
        "WHISTLE_PASSWORD": ""
      }
    }
  }
}
```

全局安装后也可以写成：

```json
{
  "mcpServers": {
    "whistle": {
      "command": "whistle-mcp",
      "env": {
        "WHISTLE_BASE_URL": "http://127.0.0.1:8899"
      }
    }
  }
}
```

### 方式二：Claude Desktop

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) 或 `%APPDATA%\Claude\claude_desktop_config.json` (Windows)：

```json
{
  "mcpServers": {
    "whistle": {
      "command": "npx",
      "args": ["-y", "whistle-mcp"],
      "env": {
        "WHISTLE_BASE_URL": "http://127.0.0.1:8899",
        "WHISTLE_USERNAME": "",
        "WHISTLE_PASSWORD": ""
      }
    }
  }
}
```

> 如果 whistle 启用了鉴权（`w2 start -u admin -p 123456`），请填写 `WHISTLE_USERNAME` 和 `WHISTLE_PASSWORD`。

### 方式三：其他 MCP 客户端

任何支持 stdio 传输的 MCP 客户端都可以使用：

```bash
WHISTLE_BASE_URL=http://127.0.0.1:8899 \
WHISTLE_USERNAME=admin \
WHISTLE_PASSWORD=123456 \
npx -y whistle-mcp
```

## 功能

### 规则管理
- `whistle_rule_list` - 获取所有规则列表
- `whistle_rule_get` - 获取规则内容
- `whistle_rule_set` - 创建/更新规则
- `whistle_rule_remove` - 删除规则
- `whistle_rule_enable` / `whistle_rule_disable` - 启用/禁用规则

### Values 管理
- `whistle_value_list` - 获取所有 Values
- `whistle_value_get` - 获取 Value 内容
- `whistle_value_set` - 创建/更新 Value
- `whistle_value_remove` - 删除 Value

### Mock 工作流
- `whistle_mock_create` - 一键创建完整 Mock 方案（规则 + Values）
- `whistle_mock_apply` - 启用/禁用 Mock 规则

### 抓包数据查看
- `whistle_sessions_list` - 获取最近抓包的 session 列表，可按 URL / HTTP 方法过滤
- `whistle_session_get` - 获取单个请求的完整详情，**自动解析 Query 参数、POST 参数和响应 JSON 字段树**
- `whistle_sessions_search` - **按请求参数名（query/POST body）或响应 JSON 字段名搜索抓包**，例如"哪些请求带了 token 参数"、"哪些接口返回了 address 字段"

### 系统状态
- `whistle_status` - 检查 whistle 服务状态
- `whistle_server_info` - 获取服务器信息

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `WHISTLE_BASE_URL` | 自动探测 | whistle Web UI 地址。不设置时会自动读取 `~/.startingAppData/` 状态文件探测运行中的实例 |
| `WHISTLE_USERNAME` | `` | whistle 鉴权用户名（可选） |
| `WHISTLE_PASSWORD` | `` | whistle 鉴权密码（可选） |

### 端口自动探测

MCP Server 启动时会自动检测运行中的 whistle 实例（不管用什么端口启动），优先级：

1. 环境变量 `WHISTLE_BASE_URL`（显式指定，最高优先级）
2. whistle 状态文件 `~/.startingAppData/`（自动探测）
3. 默认 `http://127.0.0.1:8899`（fallback）

所以即使你 `w2 start -p 8888` 用别的端口启动，也能自动识别，无需改配置。

## 使用示例

### 1. 创建 Mock 接口

AI 指令：
> 帮我创建一个 Mock，当请求 `api.example.com/user/info` 时返回用户数据

AI 会调用：
```json
{
  "tool": "whistle_mock_create",
  "arguments": {
    "pattern": "api.example.com/user/info",
    "response": {
      "code": 200,
      "data": {
        "id": 12345,
        "name": "张三",
        "email": "zhangsan@example.com"
      }
    },
    "statusCode": 200,
    "delay": 100
  }
}
```

### 2. 管理规则

AI 指令：
> 列出所有 whistle 规则

AI 会调用：
```json
{
  "tool": "whistle_rule_list"
}
```

### 3. 更新 Mock 数据

AI 指令：
> 把用户 Mock 数据里的邮箱改成 lisi@example.com

AI 会调用：
```json
{
  "tool": "whistle_value_set",
  "arguments": {
    "name": "mock_value_1234567890",
    "content": "{\"statusCode\":200,\"headers\":{\"Content-Type\":\"application/json\"},\"body\":{\"code\":200,\"data\":{\"id\":12345,\"name\":\"张三\",\"email\":\"lisi@example.com\"}}}"
  }
}
```

### 4. 查看抓包数据

AI 指令：
> 帮我看看最近有没有抓到 api.vip.com 的请求

AI 会调用：
```json
{
  "tool": "whistle_sessions_list",
  "arguments": {
    "urlFilter": "api.vip.com",
    "count": 10
  }
}
```

AI 指令：
> 查看最后一个请求的完整响应数据

AI 会调用：
```json
{
  "tool": "whistle_session_get",
  "arguments": {
    "id": "abc123-def456"
  }
}
```

### 5. 按参数/字段搜索抓包

AI 指令：
> 查一下最近有没有请求带了 userId 参数

AI 会调用：
```json
{
  "tool": "whistle_sessions_search",
  "arguments": {
    "param": "userId",
    "count": 50
  }
}
```

AI 指令：
> 看看最近 POST 到 api.vip.com 的接口，返回的数据里有没有 address 字段

AI 会调用：
```json
{
  "tool": "whistle_sessions_search",
  "arguments": {
    "urlFilter": "api.vip.com",
    "method": "POST",
    "field": "address",
    "count": 50
  }
}
```

## 前置条件

1. **whistle 已安装并运行**：
   ```bash
   npm i -g whistle
   w2 start
   ```

2. **确认 whistle Web UI 可访问**：
   ```bash
   curl http://127.0.0.1:8899/cgi-bin/status
   ```

## 架构

```
┌─────────────┐      MCP (stdio)      ┌──────────────────┐      HTTP       ┌─────────────┐
│   AI Client │ ◄──────────────────► │ whistle-mcp-server│ ◄─────────────► │   whistle   │
│ (Claude/    │                      │   (Node.js)       │                 │  (127.0.0.1 │
│  Cursor)    │                      │                   │                 │   :8899)    │
└─────────────┘                      └──────────────────┘                 └─────────────┘
                                                                              │
                                                                              ▼
                                                                       ┌─────────────┐
                                                                       │ ~/.whistle/ │
                                                                       │  rules/     │
                                                                       │  values/    │
                                                                       └─────────────┘
```

## 开发

### 本地测试

```bash
# 启动 whistle
w2 start

# 启动 MCP Server（开发模式）
npm run dev

# 测试 MCP 协议
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node src/index.js
```

### 调试

查看 whistle Web UI 的 CGI 接口：
```bash
# 规则列表
curl http://127.0.0.1:8899/cgi-bin/rules/list

# Values 列表
curl http://127.0.0.1:8899/cgi-bin/values/list
```

## License

MIT