diff --git a/docs/README.skills.md b/docs/README.skills.md index 3f7f8cad6..df66b58ae 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -173,6 +173,9 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [eyeball](../skills/eyeball/SKILL.md)
`gh skills install github/awesome-copilot eyeball` | Document analysis with inline source screenshots. When you ask Copilot to analyze a document, Eyeball generates a Word doc where every factual claim includes a highlighted screenshot from the source material so you can verify it with your own eyes. | `tools` | | [fabric-lakehouse](../skills/fabric-lakehouse/SKILL.md)
`gh skills install github/awesome-copilot fabric-lakehouse` | Use this skill to get context about Fabric Lakehouse and its features for software systems and AI-powered functions. It offers descriptions of Lakehouse data components, organization with schemas and shortcuts, access control, and code examples. This skill supports users in designing, building, and optimizing Lakehouse solutions using best practices. | `references/getdata.md`
`references/pyspark.md` | | [fedora-linux-triage](../skills/fedora-linux-triage/SKILL.md)
`gh skills install github/awesome-copilot fedora-linux-triage` | Triage and resolve Fedora issues with dnf, systemd, and SELinux-aware guidance. | None | +| [fiddler-download-setup](../skills/fiddler-download-setup/SKILL.md)
`gh skills install github/awesome-copilot fiddler-download-setup` | Download, install, and launch Fiddler Everywhere from scratch, then configure MCP for AI agent tools. Use this skill when the user does not have Fiddler installed, says "download Fiddler", "install Fiddler Everywhere", "get started with Fiddler", "first time Fiddler setup", "set up Fiddler from scratch", or needs a complete onboarding from zero to a working Fiddler MCP connection. | None | +| [fiddler-mcp-setup](../skills/fiddler-mcp-setup/SKILL.md)
`gh skills install github/awesome-copilot fiddler-mcp-setup` | Set up the Fiddler Everywhere MCP server connection for AI agent tools (Claude Code, GitHub Copilot CLI, GitHub Copilot in VS Code, Cursor, OpenAI Codex CLI). ALWAYS use this skill when Fiddler MCP tools are not available, you cannot see Fiddler tools, get an authentication error connecting to Fiddler, need to configure Fiddler MCP for the first time, or hear "tool not found" errors when trying to use other Fiddler skills. Calls Fiddler's local autoconfigure API to detect existing config and write the correct settings automatically. The only prerequisite is that Fiddler Everywhere is running. | None | +| [fiddler-traffic-debugging](../skills/fiddler-traffic-debugging/SKILL.md)
`gh skills install github/awesome-copilot fiddler-traffic-debugging` | Verify that a developer-run feature behaved correctly by analyzing HTTP traffic captured by Fiddler Everywhere. Use this skill when a developer asks to debug or verify HTTP traffic captured with Fiddler, wants to see what requests a feature made, needs to debug a failed API call, is checking Fiddler-captured traffic after running a feature, or wants to confirm what each endpoint returned. Summarizes the capture by endpoint and flags likely issues such as failed calls, missing follow-up requests, retries, auth failures, timeouts, and suspicious status-code patterns. Requires Fiddler Everywhere to be running with its MCP server enabled. | None | | [finalize-agent-prompt](../skills/finalize-agent-prompt/SKILL.md)
`gh skills install github/awesome-copilot finalize-agent-prompt` | Finalize prompt file using the role of an AI agent to polish the prompt for the end user. | None | | [finnish-humanizer](../skills/finnish-humanizer/SKILL.md)
`gh skills install github/awesome-copilot finnish-humanizer` | Detect and remove AI-generated markers from Finnish text, making it sound like a native Finnish speaker wrote it. Use when asked to "humanize", "naturalize", or "remove AI feel" from Finnish text, or when editing .md/.txt files containing Finnish content. Identifies 26 patterns (12 Finnish-specific + 14 universal) and 4 style markers. | `references/patterns.md` | | [first-ask](../skills/first-ask/SKILL.md)
`gh skills install github/awesome-copilot first-ask` | Interactive, input-tool powered, task refinement workflow: interrogates scope, deliverables, constraints before carrying out the task; Requires the Joyride extension. | None | diff --git a/skills/fiddler-download-setup/SKILL.md b/skills/fiddler-download-setup/SKILL.md new file mode 100644 index 000000000..994801a30 --- /dev/null +++ b/skills/fiddler-download-setup/SKILL.md @@ -0,0 +1,311 @@ +--- +name: fiddler-download-setup +description: 'Download, install, and launch Fiddler Everywhere from scratch, then configure MCP for AI agent tools. Use this skill when the user does not have Fiddler installed, says "download Fiddler", "install Fiddler Everywhere", "get started with Fiddler", "first time Fiddler setup", "set up Fiddler from scratch", or needs a complete onboarding from zero to a working Fiddler MCP connection.' +--- + +# Fiddler Download & Setup + +Guide the user through downloading, installing, and launching Fiddler Everywhere. + +## Operating rules + +1. This skill is shell-first. Fiddler is not installed yet, so no MCP tools are available. +2. Resolve the current version from the manifest before constructing any download URL. + Never hardcode a version number. +3. On Windows - detect opened terminal. Only if it is not powershell - wrap and run the scripts with: powershell.exe -Command 'script'. Use single quotes to wrap the script! + +--- + +## Phase 1 — Check if Fiddler is already installed + +Before downloading, check whether Fiddler Everywhere is already installed. +If it is installed, also read the installed version and compare it against the latest +available release. Only proceed to Phase 2 if the app is not installed or an update +is available and the user wants to upgrade. + +### macOS — detect and version-check +```bash +if [ -d "/Applications/Fiddler Everywhere.app" ]; then + INSTALLED_VERSION=$(/usr/libexec/PlistBuddy -c "Print CFBundleShortVersionString" \ + "/Applications/Fiddler Everywhere.app/Contents/Info.plist" 2>/dev/null) + echo "INSTALLED: $INSTALLED_VERSION" +else + echo "NOT_INSTALLED" +fi +``` + +If `INSTALLED`, fetch the latest version for the detected architecture and compare: +```bash +ARCH=$(uname -m) +if [ "$ARCH" = "arm64" ]; then + MANIFEST_URL="https://downloads.getfiddler.com/mac-arm64/latest-mac.yml" +else + MANIFEST_URL="https://downloads.getfiddler.com/mac/latest-mac.yml" +fi +LATEST_VERSION=$(curl -s "$MANIFEST_URL" | grep '^version:' | awk '{print $2}') +echo "Installed: $INSTALLED_VERSION | Latest: $LATEST_VERSION" +if [ "$INSTALLED_VERSION" = "$LATEST_VERSION" ]; then + echo "UP_TO_DATE" +else + echo "UPDATE_AVAILABLE" +fi +``` + +### Linux — detect and version-check +```bash +APPIMAGE=$(ls ~/Downloads/fiddler-everywhere-*.AppImage 2>/dev/null | sort -V | tail -1) +if command -v fiddler-everywhere &>/dev/null || [ -n "$APPIMAGE" ]; then + # Extract version from AppImage filename as the most reliable source + INSTALLED_VERSION=$(echo "$APPIMAGE" | grep -oP '[\d]+\.[\d]+\.[\d]+') + echo "INSTALLED: $INSTALLED_VERSION" + LATEST_VERSION=$(curl -s "https://downloads.getfiddler.com/linux/latest-linux.yml" \ + | grep '^version:' | awk '{print $2}') + echo "Installed: $INSTALLED_VERSION | Latest: $LATEST_VERSION" + if [ "$INSTALLED_VERSION" = "$LATEST_VERSION" ]; then + echo "UP_TO_DATE" + else + echo "UPDATE_AVAILABLE" + fi +else + echo "NOT_INSTALLED" +fi +``` + +### Windows (PowerShell) — detect and version-check +```powershell +$installed = Get-ItemProperty ` + "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*", + "HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*", + "HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*" ` + -ErrorAction SilentlyContinue | + Where-Object { $_.DisplayName -like "*Fiddler Everywhere*" } + +if ($installed) { + $installedVersion = $installed.DisplayVersion + Write-Host "INSTALLED: $installedVersion" + + $manifest = Invoke-WebRequest "https://downloads.getfiddler.com/win/latest.yml" -UseBasicParsing + $text = [System.Text.Encoding]::UTF8.GetString($manifest.RawContentStream.ToArray()) + $latestVersion = ($text | Select-String '(?m)^version:\s*(.+)').Matches.Groups[1].Value.Trim() + Write-Host "Installed: $installedVersion | Latest: $latestVersion" + + if ($installedVersion -eq $latestVersion) { "UP_TO_DATE" } else { "UPDATE_AVAILABLE" } +} else { + "NOT_INSTALLED" +} +``` + +**Interpreting the result:** + +- `NOT_INSTALLED` — continue to Phase 2 to download and install. +- `UP_TO_DATE` — inform the user their Fiddler Everywhere is already on the latest version + and stop further execution of the skill. +- `UPDATE_AVAILABLE` — tell the user the installed version and the latest version, then ask + whether they want to upgrade. If yes, continue to Phase 2 (the new installer will replace + the existing one). If no, stop. +--- + +## Phase 2 — Detect OS and resolve version + +Run both commands together. The manifest probe also confirms network access. + +```bash +uname -s && uname -m +VERSION=$(curl -s "https://downloads.getfiddler.com/mac-arm64/latest-mac.yml" \ + | grep '^version:' | awk '{print $2}') +echo "Latest Fiddler Everywhere: $VERSION" +``` + +On Windows (PowerShell): +```powershell +$env:PROCESSOR_ARCHITECTURE # AMD64 or ARM64 +$manifest = Invoke-WebRequest "https://downloads.getfiddler.com/win/latest.yml" -UseBasicParsing +$text = [System.Text.Encoding]::UTF8.GetString($manifest.RawContentStream.ToArray()) +$VERSION = ($text | Select-String '(?m)^version:\s*(.+)').Matches.Groups[1].Value.Trim() +Write-Host "Latest Fiddler Everywhere: $VERSION" +``` + +| `uname -s` | `uname -m` | Platform | +|-------------|------------|----------| +| `Darwin` | `arm64` | macOS Apple Silicon | +| `Darwin` | `x86_64` | macOS Intel | +| `Linux` | anything | Linux | +| — | — | Windows — use PowerShell path above | + +--- + +## Phase 3 — Download + +Use `$VERSION` resolved in Phase 2 to construct a direct, versioned URL. +The `.pkg` format is preferred on macOS. + +### macOS + +```bash +# Apple Silicon (arm64) +curl -L \ + "https://agent-downloads.getfiddler.com/mac-arm64/Fiddler%20Everywhere%20${VERSION}.pkg" \ + -o ~/Downloads/FiddlerEverywhere.pkg + +# Intel (x86_64) +curl -L \ + "https://agent-downloads.getfiddler.com/mac/Fiddler%20Everywhere%20${VERSION}.pkg" \ + -o ~/Downloads/FiddlerEverywhere.pkg +``` + +### Linux + +```bash +VERSION=$(curl -s "https://downloads.getfiddler.com/linux/latest-linux.yml" \ + | grep '^version:' | awk '{print $2}') +curl -L \ + "https://agent-downloads.getfiddler.com/linux/fiddler-everywhere-${VERSION}.AppImage" \ + -o ~/Downloads/FiddlerEverywhere.AppImage +``` + +### Windows (PowerShell) + +```powershell +Invoke-WebRequest ` + "https://agent-downloads.getfiddler.com/win/Fiddler%20Everywhere%20$VERSION.exe" ` + -OutFile "$env:USERPROFILE\Downloads\FiddlerEverywhere.exe" +``` + +--- + +## Phase 4 — Install + +### macOS — PKG (headless, no wizard) + +Do **not** use `sudo installer` directly — `sudo` blocks on a password prompt inside +the agent's hidden shell where the user cannot type. Use `osascript` instead, which +raises the native macOS authentication dialog that the user can see on screen. + +`do shell script with administrator privileges` runs as root and cannot access +`~/Downloads` due to macOS sandbox restrictions. Copy the package to `/tmp` first +(world-readable), then install from there. + +Run both commands via bash tool calls: + +```bash +cp ~/Downloads/FiddlerEverywhere.pkg /tmp/FiddlerEverywhere.pkg +``` + +Then announce before the next command: +> "A macOS password dialog will appear on your screen. Enter your login password there +> to authorize the installation, then I'll continue automatically." + +```bash +osascript -e 'do shell script "installer -pkg /tmp/FiddlerEverywhere.pkg -target /" with administrator privileges' +``` + +`osascript` blocks until the user approves the dialog and the install completes. Once it +exits with code 0, clean up. + +```bash +rm /tmp/FiddlerEverywhere.pkg +``` + + +### Linux + +```bash +chmod +x ~/Downloads/FiddlerEverywhere.AppImage +~/Downloads/FiddlerEverywhere.AppImage & +``` + +### Windows — silent install + +```powershell +Start-Process "$env:USERPROFILE\Downloads\FiddlerEverywhere.exe" -ArgumentList "/S" -Wait +``` + +**Launch Fiddler:** + +macOS: +```bash +open -a "Fiddler Everywhere" && sleep 15 +``` + +Linux: +```bash +(nohup "$HOME/Downloads/FiddlerEverywhere.AppImage" &>/dev/null &); sleep 15 +``` + +Windows: +**Important** On windows if the current terminal used is bash, use the specific **GitBash** script. + +**PowerShell** +```powershell +$candidates = @( + "$env:LOCALAPPDATA\Programs\Fiddler Everywhere\Fiddler Everywhere.exe", + "C:\Program Files\Fiddler Everywhere\Fiddler Everywhere.exe", + "C:\Program Files (x86)\Fiddler Everywhere\Fiddler Everywhere.exe" +) +$fiddlerExe = $candidates | Where-Object { Test-Path $_ } | Select-Object -First 1 +if ($fiddlerExe) { + $cmdLine = '"' + $fiddlerExe + '"' + Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{ CommandLine = $cmdLine } | Out-Null + Start-Sleep 15 +} +``` + +**Git Bash** +```bash +FIDDLER_EXE="" +for dir in "$LOCALAPPDATA/Programs/Fiddler Everywhere" \ + "/c/Program Files/Fiddler Everywhere" \ + "/c/Program Files (x86)/Fiddler Everywhere"; do + if [ -f "$dir/Fiddler Everywhere.exe" ]; then + FIDDLER_EXE="$dir/Fiddler Everywhere.exe" + break + fi +done +if [ -n "$FIDDLER_EXE" ]; then + "$FIDDLER_EXE" & + sleep 15 +fi +``` + +--- + +## Phase 5 — Suggest MCP setup + +After Fiddler Everywhere is installed and launched, inform the user that there is +an automatic MCP setup skill that can configure the Fiddler MCP server connection. + +Present the following message: + +> Fiddler Everywhere is installed and running. +> +> There is an **automatic MCP setup** skill that can configure the Fiddler MCP +> server connection for your AI agent. This will allow agent tools +> to interact with Fiddler directly — capturing traffic, +> inspecting sessions, creating rules, and more — all from within your editor. +> +> Would you like me to auto-configure MCP now? + +Ask the user to choose: +- **Yes, auto-configure MCP** (recommended) +- **No, I'll set it up manually later** + +### If the user accepts + +Install the `fiddler-mcp-setup` skill from its remote location and invoke it: + +**Remote skill URL:** `https://github.com/telerik/fiddler-agent-tools/tree/master/skills/fiddler-mcp-setup` + +Follow the `fiddler-mcp-setup` skill instructions to complete MCP configuration end-to-end. + +### If the user declines + +Acknowledge and let them know they can download the MCP setup skill later at any time. + +## Troubleshooting + +| Issue | Solution | +|-------|----------| +| macOS password dialog canceled / install aborted | Rerun the `osascript` command — the pkg in `/tmp` is still there | +| `hdiutil: attach failed` | File may not be fully downloaded — rerun the `curl` command | +| Windows EXE blocked by SmartScreen | Right-click → Run as Administrator | +| App won't open on macOS | Run `xattr -cr "/Applications/Fiddler Everywhere.app"` to clear quarantine | diff --git a/skills/fiddler-mcp-setup/SKILL.md b/skills/fiddler-mcp-setup/SKILL.md new file mode 100644 index 000000000..f62f78231 --- /dev/null +++ b/skills/fiddler-mcp-setup/SKILL.md @@ -0,0 +1,340 @@ +--- +name: fiddler-mcp-setup +description: 'Set up the Fiddler Everywhere MCP server connection for AI agent tools (Claude Code, GitHub Copilot CLI, GitHub Copilot in VS Code, Cursor, OpenAI Codex CLI). ALWAYS use this skill when Fiddler MCP tools are not available, you cannot see Fiddler tools, get an authentication error connecting to Fiddler, need to configure Fiddler MCP for the first time, or hear "tool not found" errors when trying to use other Fiddler skills. Calls Fiddler''s local autoconfigure API to detect existing config and write the correct settings automatically. The only prerequisite is that Fiddler Everywhere is running.' +--- + +# Fiddler MCP Setup + +Configure the Fiddler Everywhere MCP server so that agent tools can call Fiddler's traffic +inspection, status, and session APIs. + +--- + +## Operating rules + +- **Shell-first.** MCP is not yet configured, so you cannot use MCP tools. +- **Sequential execution only.** Follow steps strictly in order — do not run steps or scripts in parallel. Each step may depend on values produced by the previous one. +- **On Windows** — detect opened terminal. Only if it is not PowerShell, wrap scripts with: `powershell.exe -Command 'script'`. Use single quotes to wrap the script. + +--- + +## Step 1 — Verify Fiddler is installed + +**macOS:** +```bash +if [ -d "/Applications/Fiddler Everywhere.app" ]; then echo "INSTALLED"; else echo "NOT_INSTALLED"; fi +``` + +**Linux:** +```bash +if command -v fiddler-everywhere &>/dev/null || [ -x "$HOME/Downloads/FiddlerEverywhere.AppImage" ]; then echo "INSTALLED"; else echo "NOT_INSTALLED"; fi +``` + +**Windows (PowerShell):** +```powershell +$installed = Get-ItemProperty ` + "HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*", + "HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\*", + "HKLM:\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*" ` + -ErrorAction SilentlyContinue | + Where-Object { $_.DisplayName -like "*Fiddler Everywhere*" } +if ($installed) { "INSTALLED" } else { "NOT_INSTALLED" } +``` + +If `NOT_INSTALLED`: stop and tell the user: +> "Fiddler Everywhere is not installed. Please install it first." + +--- + +## Step 2 — Detect the provider + +Identify which agent is being configured and set `PROVIDER`. + +### Parent process name + +Inspect the parent process: + +macOS / Linux: +```bash +ps -p $PPID -o comm= 2>/dev/null +``` + +Windows (PowerShell): +```powershell +(Get-Process -Id (Get-CimInstance Win32_Process -Filter "ProcessId=$PID").ParentProcessId).Name +``` + +Match the output against known process names: + +| Process name contains | Provider value | +|-----------------------|---------------| +| `code`, `code-helper` | `vscode` | +| `cursor` | `cursor` | +| `claude` | `claude_code` | +| `copilot` | `copilot_cli` | +| `codex` | `codex_cli` | + + +If matched unambiguously, set `PROVIDER` to Provider value from the table and proceed to Step 3. + +If still unrecognised, ask the user: +> "Which agent are you setting Fiddler MCP up for? (VS Code / GitHub Copilot, Cursor, Claude Code CLI, GitHub Copilot CLI, or OpenAI Codex CLI)" + +Use the user's answer to set `PROVIDER` from the table above. + +--- + +## Step 3 — Discover the port + +Fiddler Everywhere listens on port `8868` by default. Confirm it is reachable and set `PORT` for all subsequent steps. + +macOS / Linux: +```bash +curl -s -o /dev/null -w "%{http_code}" "http://localhost:8868/api/McpManagement/Detect?provider=PROVIDER" +``` + +Windows (PowerShell): +```powershell +curl.exe -s -o NUL -w "%{http_code}" "http://localhost:8868/api/McpManagement/Detect?provider=PROVIDER" +``` + +| Result | Action | +|--------|--------| +| Expected Fiddler Detect response, including documented authentication or plan errors | Port `8868` is serving Fiddler. Set `PORT=8868` and proceed to Step 4. | +| `000` (connection refused) or an unrecognized response | Port `8868` is not serving Fiddler. Run the port discovery script below. | + +**Port discovery script:** + +macOS / Linux: +```bash +python3 -c " +import json, glob, os +ports = set() +for f in glob.glob(os.path.expanduser('~/.fiddler/*/Settings/appsettings.json')): + try: + p = json.load(open(f)).get('MCPServerSettings', {}).get('Port') + if p and p != 8868: + ports.add(p) + except: pass +print(' '.join(str(p) for p in ports) if ports else 'none') +" +``` + +Windows (PowerShell): +```powershell +$ports = Get-ChildItem "$env:USERPROFILE\.fiddler\*\Settings\appsettings.json" -ErrorAction SilentlyContinue | + ForEach-Object { (Get-Content $_ | ConvertFrom-Json).MCPServerSettings.Port } | + Where-Object { $_ -and $_ -ne 8868 } | Select-Object -Unique +Write-Output $(if ($ports) { $ports -join ' ' } else { 'none' }) +``` + +For each port returned, probe it: + +macOS / Linux: +```bash +curl -s -o /dev/null -w "%{http_code}" "http://localhost:PORT/api/McpManagement/Detect?provider=PROVIDER" +``` + +Windows (PowerShell): +```powershell +curl.exe -s -o NUL -w "%{http_code}" "http://localhost:PORT/api/McpManagement/Detect?provider=PROVIDER" +``` + +Set `PORT` to the first port that returns any HTTP response. If no port responds, Fiddler is not running — launch it and retry from the top of Step 3. + +**Launch Fiddler:** + +macOS: +```bash +open -a "Fiddler Everywhere" && sleep 15 +``` + +Linux: +```bash +if command -v fiddler-everywhere >/dev/null 2>&1; then + (nohup fiddler-everywhere >/dev/null 2>&1 &) +elif [ -x "$HOME/Downloads/FiddlerEverywhere.AppImage" ]; then + (nohup "$HOME/Downloads/FiddlerEverywhere.AppImage" >/dev/null 2>&1 &) +fi +sleep 15 +``` + +Windows: +**Important** On windows if the current terminal used is bash, use the specific **GitBash** script. + +**PowerShell** +```powershell +$candidates = @( + "$env:LOCALAPPDATA\Programs\Fiddler Everywhere\Fiddler Everywhere.exe", + "C:\Program Files\Fiddler Everywhere\Fiddler Everywhere.exe", + "C:\Program Files (x86)\Fiddler Everywhere\Fiddler Everywhere.exe" +) +$fiddlerExe = $candidates | Where-Object { Test-Path $_ } | Select-Object -First 1 +if ($fiddlerExe) { + $cmdLine = '"' + $fiddlerExe + '"' + Invoke-CimMethod -ClassName Win32_Process -MethodName Create -Arguments @{ CommandLine = $cmdLine } | Out-Null + Start-Sleep 15 +} +``` + +**Git Bash** +```bash +FIDDLER_EXE="" +for dir in "$LOCALAPPDATA/Programs/Fiddler Everywhere" \ + "/c/Program Files/Fiddler Everywhere" \ + "/c/Program Files (x86)/Fiddler Everywhere"; do + if [ -f "$dir/Fiddler Everywhere.exe" ]; then + FIDDLER_EXE="$dir/Fiddler Everywhere.exe" + break + fi +done +if [ -n "$FIDDLER_EXE" ]; then + "$FIDDLER_EXE" & + sleep 15 +fi +``` + +**Important:** Wait 15 seconds for Fiddler to launch, before continuing with the next steps! + +If still unreachable after relaunch: +> "Fiddler Everywhere is not reachable. Please verify it is running and try again." + +> `PORT` is used in all subsequent steps. + +--- + +## Step 4 — Check for existing configuration + +Call the Detect endpoint to see if Fiddler MCP is already configured for this provider: + +macOS / Linux: +```bash +curl -sS -w '\nHTTP_STATUS:%{http_code}\n' "http://localhost:$PORT/api/McpManagement/Detect?provider=PROVIDER" +``` + +Windows (PowerShell): +```powershell +curl.exe -sS -w "\nHTTP_STATUS:%{http_code}\n" "http://localhost:$PORT/api/McpManagement/Detect?provider=PROVIDER" +``` + +Replace `PROVIDER` with the value from Step 2. + +| Response | Action | +|----------|--------| +| Indicates config exists / already configured | Inform the user: "Fiddler MCP is already configured for `PROVIDER`." Ask if they want to re-run setup to refresh the configuration. Only continue if confirmed. | +| Indicates not configured | Proceed to Step 5. | +| `403` | Stop: "Your Fiddler plan does not include MCP access. Please upgrade your subscription." | +| User not logged in | Follow the **Login** procedure below, then retry Step 4. | + +--- + +### Login (if Fiddler reports the user is not logged in) + +Use the MCP protocol to trigger the login flow. Follow these sub-steps in order. + +**1. Open an MCP session and get the session ID:** + +macOS / Linux: +```bash +SESSION_ID=$(curl -si -X POST "http://localhost:$PORT/mcp" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"mcp-setup","version":"1.0"}}}' \ + | grep -i "^mcp-session-id:" | awk '{print $2}' | tr -d '\r') +echo "Session ID: $SESSION_ID" +``` + +Windows (PowerShell): +```powershell +$initResp = curl.exe -si -X POST "http://localhost:$PORT/mcp" ` + -H "Content-Type: application/json" ` + -H "Accept: application/json, text/event-stream" ` + -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"mcp-setup\",\"version\":\"1.0\"}}}' +$SESSION_ID = ($initResp | Select-String "(?i)mcp-session-id:\s*(\S+)").Matches.Groups[1].Value.Trim() +Write-Host "Session ID: $SESSION_ID" +``` + +If `SESSION_ID` is empty, Fiddler may not be fully started — wait a few seconds and retry. + +**2. Fetch the tools list to confirm `initiate_login` is available:** + +macOS / Linux: +```bash +curl -s -X POST "http://localhost:$PORT/mcp" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -H "Mcp-Session-Id: $SESSION_ID" \ + -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' +``` + +Windows (PowerShell): +```powershell +curl.exe -s -X POST "http://localhost:$PORT/mcp" ` + -H "Content-Type: application/json" ` + -H "Accept: application/json, text/event-stream" ` + -H "Mcp-Session-Id: $SESSION_ID" ` + -d '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}' +``` + +Confirm `initiate_login` appears in the response before continuing. + +**3. Call `initiate_login`:** + +macOS / Linux: +```bash +curl -s -X POST "http://localhost:$PORT/mcp" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + -H "Mcp-Session-Id: $SESSION_ID" \ + -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"initiate_login","arguments":{}}}' +``` + +Windows (PowerShell): +```powershell +curl.exe -s -X POST "http://localhost:$PORT/mcp" ` + -H "Content-Type: application/json" ` + -H "Accept: application/json, text/event-stream" ` + -H "Mcp-Session-Id: $SESSION_ID" ` + -d '{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"initiate_login\",\"arguments\":{}}}' +``` + +Tell the user: +> "A login window has been opened in your browser. Please complete sign-in, then let me know when done." + +Wait for the user to confirm sign-in is complete, then retry the step that triggered this login flow. + +--- + +## Step 5 — Autoconfigure + +Call the Configure endpoint. Fiddler will automatically generate or reuse the API key and write the correct config file for the provider: + +macOS / Linux: +```bash +curl -sS -w '\nHTTP_STATUS:%{http_code}\n' -X POST "http://localhost:$PORT/api/McpManagement/Configure" \ + -H "Content-Type: application/json" \ + -d '{"provider":"PROVIDER"}' +``` + +Windows (PowerShell): +```powershell +curl.exe -sS -w "\nHTTP_STATUS:%{http_code}\n" -X POST "http://localhost:$PORT/api/McpManagement/Configure" ` + -H "Content-Type: application/json" ` + -d '{\"provider\":\"PROVIDER\"}'` +``` + +Replace `PROVIDER` with the value from Step 2. + +| Response | Action | +|----------|--------| +| Success / 2xx | Configuration written. Proceed to Step 6. | +| `403` | Stop: "Your Fiddler plan does not include MCP access. Please upgrade your subscription." | +| User not logged in | Follow the **Login** procedure in Step 4, then retry Step 5. | +| Any other failure | Note the response and ask the user to check Fiddler is running correctly. | + +--- + +## Step 6 — Confirm success + +Tell the user: +> "Fiddler MCP has been configured for `PROVIDER`. Restart your agent (reload the VS Code window, restart Cursor, etc.) to pick up the new configuration, then try using a Fiddler tool." diff --git a/skills/fiddler-traffic-debugging/SKILL.md b/skills/fiddler-traffic-debugging/SKILL.md new file mode 100644 index 000000000..fe0232197 --- /dev/null +++ b/skills/fiddler-traffic-debugging/SKILL.md @@ -0,0 +1,222 @@ +--- +name: fiddler-traffic-debugging +description: 'Verify that a developer-run feature behaved correctly by analyzing HTTP traffic captured by Fiddler Everywhere. Use this skill when a developer asks to debug or verify HTTP traffic captured with Fiddler, wants to see what requests a feature made, needs to debug a failed API call, is checking Fiddler-captured traffic after running a feature, or wants to confirm what each endpoint returned. Summarizes the capture by endpoint and flags likely issues such as failed calls, missing follow-up requests, retries, auth failures, timeouts, and suspicious status-code patterns. Requires Fiddler Everywhere to be running with its MCP server enabled.' +--- + +# Fiddler Feature Verification + +Analyze the traffic generated by a feature run, decide whether the observed HTTP behavior +looks correct, and produce a grouped-by-endpoint summary with likely issues. + +## Operating rules + +1. This skill is MCP-first. Use Fiddler Everywhere MCP tools for traffic analysis whenever they are available in the current session. +2. Do not use shell tools, `rg`, `grep`, workspace file scans, or exported session dumps to inspect traffic if the Fiddler MCP tools are available. +3. Prefer `CaptureApplication` as a pre-capture step when you know which process to focus on — it scopes the capture at the OS level and keeps the session list clean from the start. Use `ApplyFilters` whenever it helps narrow a large or noisy capture to the traffic that matters for the feature verification. +4. Keep the analysis practical. The goal is to verify whether the feature appears to work, not to produce an exhaustive packet-level audit. +5. If the Fiddler MCP tools are not available in the current session, stop and tell the user Fiddler MCP server must be configured first. +6. Never manually probe `/mcp` or send raw MCP protocol requests with `curl` when the runtime already exposes Fiddler MCP tools. +7. Use only tool names that the host advertises in `tools/list`. Never invent or assume tool names beyond the ones available in the session. +8. All session tools (`GetSessionsCount`, `GetSessions`, `GetSessionDetails`, `ClearSessions`, `ApplyFilters`) require a `sessionsSource` parameter — always pass `LiveTraffic` for captured HTTP/HTTPS traffic or `AgentCalls` for LLM/AI agent API calls. Never omit this parameter. + +## Session sources + +Fiddler exposes two session sources; always pass the correct one to every session tool: + +| `sessionsSource` | When to use | +|---|---| +| `LiveTraffic` | Real-time captured HTTP/HTTPS traffic from browsers, terminals, or instrumented processes. Default for feature verification. | +| `AgentCalls` | LLM/AI agent API calls (e.g. OpenAI, Anthropic, Azure OpenAI). Sessions here also carry `isCached`, the LLM model name, and a preview of the last user prompt. Use when verifying AI agent behavior or investigating LLM call patterns. | + +Agent API calls are also HTTP traffic and appear in both sources; `AgentCalls` gives the enriched metadata view. + +## Prerequisites check + +1. Verify that Fiddler Everywhere is installed. +2. Verify that the Fiddler Everywhere MCP tools are available. + +## Useful tools and how to use them + +### `GetStatus` + +Use this first to confirm that Fiddler is reachable and in a usable state. + +What it helps verify: +- Whether the user is logged in +- Whether Fiddler appears to be capturing traffic +- Whether there are browser or terminal instances attached +- Whether HTTPS inspection prerequisites look healthy + +### `CaptureApplication` + +**Use this as the first step whenever you know which process generates the traffic you want to verify.** + +This is the most powerful noise-reduction tool available. It scopes the OS-level capture to one or more specific processes, so only their traffic appears in the Live Traffic inspector — eliminating background noise from browsers, IDEs, system services, and other apps running at the same time. + +How to use it: +- Supply the process name or PID inferred from the current IDE or CLI context (e.g. the process running the feature under test). +- Multiple targets are space-separated; multi-word names must be quoted (e.g. `"Google Chrome"`). +- The supplied list replaces the current capture filter. When elicitation is supported, Fiddler may offer to merge with the existing filter instead. +- After calling `CaptureApplication`, clear any stale sessions with `ClearSessions` (passing `sessionsSource: LiveTraffic`) before the user runs the feature, so the resulting capture contains only the relevant run. + +When `CaptureApplication` is not appropriate: +- The process name or PID is unknown and cannot be inferred. +- The feature spans multiple processes whose names are not determinable. +- The user explicitly wants to analyze unfiltered traffic. + +In those cases, fall back to `ApplyFilters` after `GetSessions`. + +### `GetSessionsCount` + +Use this as a fast sanity check before deeper analysis. + +What it helps verify: +- Whether anything has been captured at all +- Whether the user likely ran the feature recently enough to analyze it + +### `GetSessions` + +This is the main tool for verification. Use it to pull the captured session list, then narrow the traffic locally in memory. + +Use it to: +- Find the requests most likely related to the feature run +- Identify the order of requests +- Spot failures, retries, redirects, preflights, and slow calls +- Build endpoint groups for the final summary + +When narrowing the list, prefer clues from the user's request such as: +- Hostname +- URL path or path fragment +- HTTP method +- Feature name or keyword +- A rough time window such as "just now" or "after clicking Save" + +If the session list is already manageable, narrowing locally in memory is usually enough. If the capture is large or noisy, use `ApplyFilters` to focus Fiddler on the host, endpoint family, method, or failure pattern that matters. + +### `GetSessionDetails` + +Use this after `GetSessions` identifies the interesting sessions. + +Good candidates for detail inspection: +- Any session with `statusCode` >= 400 +- Any session with an empty or missing `statusCode` +- The slowest session for an endpoint +- A representative successful request for an important endpoint +- OPTIONS preflight requests and the request immediately after them when CORS might be involved + +Use the details to inspect: +- Request headers and response headers +- Request and response bodies +- Redirect targets +- Content length and content type +- Authentication schemes and cookie presence, validation messages, and error payloads. Never reproduce authorization tokens, cookie values, API keys, or other secrets in the report; redact them before quoting evidence. + +For `AgentCalls` sessions, also inspect the LLM model, `isCached` flag, and the last user prompt preview — these often reveal misconfigured model routing or unexpected cache hits. + +Rate limit: avoid firing more than 5 `GetSessionDetails` calls in rapid succession. + +### `ApplyFilters` + +Use this when filtering will make the analysis faster or more reliable. + +Possible use cases: +- Show only traffic for one host +- Show only failing requests +- Focus the UI on a particular endpoint family +- Isolate retries, auth failures, or one request method such as `POST` + +To reset filters, call `ApplyFilters` with an empty filter collection. + +### `ClearSessions` + +Use this to remove stale sessions before a focused capture run. Always pass `sessionsSource`. Typically called after `CaptureApplication` and before the user runs the feature, to ensure the resulting inspector contains only the relevant session set. + +### `StartCaptureWithBrowser` / `StartCaptureWithTerminal` + +Use these when the feature under test needs a fresh, proxy-configured environment: +- `StartCaptureWithBrowser` — opens a Chrome instance with Fiddler proxy pre-applied. +- `StartCaptureWithTerminal` — opens a terminal with Fiddler proxy environment variables set. + +These are useful when the target process cannot be instrumented via `CaptureApplication`, or when a clean browser session is needed to avoid cached auth state. + +## Suggested workflow + +This workflow is intentionally flexible. Adapt it to the feature and the amount of captured traffic. + +1. **Understand the feature scope.** + - Extract any useful clue from the user's request: action performed, host, path fragment, method, target process, or expected endpoint. + - Determine the appropriate `sessionsSource`: use `LiveTraffic` for standard HTTP features, `AgentCalls` when verifying LLM or AI agent behavior. + - If the request is vague, analyze the most recent traffic and say that the result is based on the recent capture. + +2. **Scope the capture (strongly preferred).** + - If the target process is known or can be inferred from the IDE/CLI context, call `CaptureApplication` with the process name or PID. + - Then call `ClearSessions` (with `sessionsSource: LiveTraffic`) to discard prior noise, so the next run produces a clean capture. + - Ask the user to run the feature if they haven't yet, or proceed to analysis if they already have. + +3. **Pull the session list with `GetSessions`.** + - Shortlist sessions that match the feature scope. + - If no clear clue is available, focus on the most recent burst of related sessions rather than the entire capture history. + - If the capture is still too noisy, use `ApplyFilters` to narrow further. + +4. **Group traffic by endpoint.** + - Group by host + normalized path. + - Strip query strings for grouping. + - Treat numeric IDs and UUID-like segments as path variables, so `/users/123` and `/users/456` are understood as the same endpoint family. + +5. **Review the sequence.** + - Check whether the request flow looks plausible for the feature. + - Look for expected follow-up calls such as create then fetch, preflight then actual request, upload then status poll, or save then refresh. + - If a needed follow-up call is absent, call that out as a possible issue rather than a certainty unless the evidence is strong. + +6. **Inspect representative details.** + - Fetch details for failures, slow calls, mixed-status endpoints, and one or two key successful endpoints. + - For `AgentCalls`, also check model name, cache hits, and prompt previews. + - Use response bodies and headers as evidence when explaining whether the feature appears healthy. + +7. **Decide whether the feature appears to work properly.** + - A healthy feature run usually shows the expected endpoints, mostly successful status codes, reasonable latency, and no repeated failures. + - If the traffic is incomplete or ambiguous, say so directly. + +## Output format + +Do not dump raw JSON. Write a plain-language verification report with these sections. + +```text +Feature Verification + +Overall verdict: [Feature appears healthy / Feature appears partially successful / Feature likely failed / Inconclusive] + +Traffic window: [what part of the capture you analyzed] +Sessions source: [LiveTraffic / AgentCalls] +Capture scope: [CaptureApplication used: / Unscoped — all traffic analyzed] + +Endpoint summary: +- METHOD HOST /normalized/path + Calls: [N] + Statuses: [e.g. 200 x3, 401 x1] + Timing: [avg X ms, max Y ms] + What happened: [plain-language summary of what this endpoint appears to do] + Evidence: [optional header/body/status detail when useful] + +- METHOD HOST /another/path + Calls: [N] + Statuses: [...] + Timing: [...] + What happened: [...] + +Possible issues: +- ⚠️ [Endpoint] [Issue name] — [what looks wrong and why it matters] +- ⚠️ [Endpoint] [Issue name] — [supporting evidence] + +Conclusion: +- [Short answer on whether the feature appears to work properly] +``` + +## Output requirements + +1. Group the summary by endpoint, not by raw session ID. +2. Include status-code distribution and timing for each endpoint group. +3. Always state which `sessionsSource` was used and whether `CaptureApplication` scoped the capture. +4. If there are no obvious issues, say so explicitly: `No obvious issues detected in the analyzed traffic.` +5. If there are issues, prefix each issue with `⚠️`, name it clearly, and explain what it appears to be. +6. If the capture is ambiguous or incomplete, say that the conclusion is tentative.