whistle-mcp-server

MCP server for running whistle, capturing requests, exporting decoded results, and setting JSON mock hooks.

Requirements

• Node.js 18 or newer
• A client that can run stdio MCP servers

whistle is bundled as a package dependency, so users do not need to install w2 globally. If you prefer a local/global whistle binary, set WHISTLE_BIN.

MCP Config

Use with npx:

{
  "mcpServers": {
    "whistle_proxy": {
      "command": "npx",
      "args": ["-y", "whistle-mcp-server"],
      "env": {
        "WHISTLE_MCP_WORKDIR": "/absolute/path/to/your/workdir"
      }
    }
  }
}

Use a locally installed package:

{
  "mcpServers": {
    "whistle_proxy": {
      "command": "whistle-mcp-server",
      "env": {
        "WHISTLE_MCP_WORKDIR": "/absolute/path/to/your/workdir"
      }
    }
  }
}

Environment Variables

• WHISTLE_MCP_WORKDIR: directory for generated files such as capture-results/ and mock-hooks/. Defaults to the MCP process current working directory.
• WHISTLE_MCP_OUTPUT_DIR: alias for WHISTLE_MCP_WORKDIR.
• WHISTLE_BIN: optional path to w2 or whistle. Defaults to the bundled whistle CLI.

Tools

• start-whistle: start whistle on a port, default 8899.
• start-capture: start polling whistle network records with optional filters.
• get-capture-results: export captured requests to JSON. Relative filePath values are written under WHISTLE_MCP_WORKDIR.
• set-mock-hook: write a JSON value and add a managed whistle rule.
• clear-mock-hooks: clear all mock hooks generated by this MCP server.
• get-status: return whistle and capture status.
• stop-whistle: stop whistle.

Mock Hook Example

Call set-mock-hook with:

{
  "urlRegex": "/[?&]functionId=queryMessagesV1326(&|$)/",
  "valueName": "mock.json",
  "mockJson": {
    "code": "0",
    "data": []
  }
}

The server writes the JSON into whistle Values and generates this managed rule:

/[?&]functionId=queryMessagesV1326(&|$)/ file://{mock.json}

Use clear-mock-hooks to remove generated mock rules when debugging is done.

Local Package Test

Before publishing:

npm run build
npm pack
mkdir -p /tmp/whistle-mcp-test
cd /tmp/whistle-mcp-test
npm init -y
npm install /path/to/whistle-mcp-server-1.0.11.tgz
WHISTLE_MCP_WORKDIR="$PWD" npx whistle-mcp-server

For MCP-client testing, configure the installed whistle-mcp-server command in a fresh project directory and verify start-whistle, set-mock-hook, and get-capture-results.