whistle-mcp

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

安装

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

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

配置

方式一：Cursor

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

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

全局安装后也可以写成：

{
  "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)：

{
  "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 客户端都可以使用：

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 会调用：

{
  "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 会调用：

{
  "tool": "whistle_rule_list"
}

3. 更新 Mock 数据

AI 指令：

把用户 Mock 数据里的邮箱改成 lisi@example.com

AI 会调用：

{
  "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 会调用：

{
  "tool": "whistle_sessions_list",
  "arguments": {
    "urlFilter": "api.vip.com",
    "count": 10
  }
}

AI 指令：

查看最后一个请求的完整响应数据

AI 会调用：

{
  "tool": "whistle_session_get",
  "arguments": {
    "id": "abc123-def456"
  }
}

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

AI 指令：

查一下最近有没有请求带了 userId 参数

AI 会调用：

{
  "tool": "whistle_sessions_search",
  "arguments": {
    "param": "userId",
    "count": 50
  }
}

AI 指令：

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

AI 会调用：

{
  "tool": "whistle_sessions_search",
  "arguments": {
    "urlFilter": "api.vip.com",
    "method": "POST",
    "field": "address",
    "count": 50
  }
}

前置条件

1. whistle 已安装并运行：

   npm i -g whistle
   w2 start
   

2. 确认 whistle Web UI 可访问：

   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/    │
                                                                       └─────────────┘

开发

本地测试

# 启动 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 接口：

# 规则列表
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