Skip to content

Improve DEX remote captures tools, separate by type for clarity #211

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 8, 2025
Merged

Improve DEX remote captures tools, separate by type for clarity #211

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion apps/dex-analysis/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,8 @@ Currently available tools:
| | `dex_traceroute_test_network_path` | Retrieve detailed time series results for the network path of a traceroute test by test id and device id. |
| | `dex_traceroute_test_result_network_path` | Retrieve the hop-by-hop network path for a specific Traceroute DEX test result by id. Use `dex_traceroute_test_network_path` to obain test result ids. |
| **Remote Captures** | `dex_list_remote_capture_eligible_devices` | Retrieve a list of devices eligible for remote captures like packet captures or WARP diagnostics. |
| | `dex_create_remote_capture` | Initiate a remote capture on a specific device by id. |
| | `dex_create_remote_pcap` | Initiate a remote packet capture on a specific device by id. |
| | `dex_create_remote_warp_diag` | Initiate a remote Warp diagnostic capture on a specific device by id. |
| | `dex_list_remote_captures` | Retrieve a list of previously created remote captures along with their details and status. |
| | `dex_list_remote_warp_diag_contents` | List the filenames included in a remote WARP diag capture returned by `dex_list_remote_captures`. |
| | `dex_explore_remote_warp_diag_output` | Retreive remote WARP diag file contents by filepath returned by `dex_list_remote_warp_diag_contents`. |
Expand Down
73 changes: 54 additions & 19 deletions apps/dex-analysis/src/tools/dex-analysis.tools.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -209,19 +209,14 @@ export function registerDEXTools(agent: CloudflareDEXMCP) {
})

registerTool({
name: 'dex_create_remote_capture',
name: 'dex_create_remote_pcap',
description:
'Create a remote capture for a device. This is a resource intensive and privacy-sensitive operation on a real user device.' +
'Create a remote packet capture (PCAP) for a device. This is a resource intensive and privacy-sensitive operation on a real user device.' +
'Always ask for confirmation from the user that the targeted email and device are correct before executing a capture',
schema: {
device_id: z.string().describe('The device ID to target.'),
user_email: z.string().describe('The email of the user associated with the device.'),
type: z.enum(['pcap', 'warp-diag']).describe('The type of remote capture to perform.'),
interfaces: z
.array(z.enum(['default', 'tunnel']))
.optional()
.describe('The network interfaces to capture packets on.'),
max_file_size_mb: z
'max-file-size-mb': z
.number()
.min(1)
.default(5)
Expand All @@ -230,29 +225,68 @@ export function registerDEXTools(agent: CloudflareDEXMCP) {
'Maximum file size in MB for the capture file. Specifies the maximum file size of the warp-daig zip artifact that can be uploaded. ' +
'If the zip artifact exceeds the specified max file size it will NOT be uploaded.'
),
max_packet_size_bytes: z
'packet-size-bytes': z
.number()
.min(1)
.default(160)
.optional()
.describe('Maximum number of bytes to save for each packet.'),
test_all_routes: z
'time-limit-min': z
.number()
.min(1)
.default(5)
.describe('Limit on capture duration in minutes'),
},
agent,
llmContext:
'If the request was successful, the capture has been initiated. You can poll the dex_list_remote_commands tool periodically to check on the completion status.',
callback: async ({ accountId, accessToken, device_id, user_email, ...command_args }) => {
return await fetchCloudflareApi({
endpoint: `/dex/commands`,
accountId,
apiToken: accessToken,
options: {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
commands: [
{
type: 'pcap',
device_id,
user_email,
args: command_args,
version: 1,
},
],
}),
},
})
},
})

registerTool({
name: 'dex_create_remote_warp_diag',
description:
'Create a remote Warp Diagnostic (WARP-diag) for a device. This is a resource intensive and privacy-sensitive operation on a real user device.' +
'Always ask for confirmation from the user that the targeted email and device are correct before executing a capture',
schema: {
device_id: z.string().describe('The device ID to target.'),
user_email: z.string().describe('The email of the user associated with the device.'),
'test-all-routes': z
.boolean()
.default(true)
.describe(
'Test an IP address from all included or excluded ranges. Tests an IP address from all included or excluded ranges.' +
"Essentially the same as running 'route get '' and collecting the results. This option may increase the time taken to collect the warp-diag"
),
time_limit_mins: z
.number()
.min(1)
.default(5)
.describe('Limit on capture duration in minutes'),
},
agent,
llmContext:
'If the request was successful, the command has been created. You can poll the dex_list_remote_commands tool periodically to check on the completion status.',
callback: async ({ accountId, accessToken, type, device_id, user_email, ...command_args }) => {
'If the request was successful, the diagnostic has been initiated. You can poll the dex_list_remote_commands tool periodically to check on the completion status.' +
'See https://developers.cloudflare.com/cloudflare-one/connections/connect-devices/warp/troubleshooting/warp-logs/ for more info on warp-diags',
callback: async ({ accountId, accessToken, device_id, user_email, ...command_args }) => {
return await fetchCloudflareApi({
endpoint: `/dex/commands`,
accountId,
Expand All @@ -265,7 +299,7 @@ export function registerDEXTools(agent: CloudflareDEXMCP) {
body: JSON.stringify({
commands: [
{
type,
type: 'warp-diag',
device_id,
user_email,
args: command_args,
Expand Down Expand Up @@ -498,7 +532,8 @@ export function registerDEXTools(agent: CloudflareDEXMCP) {
},
llmContext:
'Use the dex_explore_remote_warp_diag_output tool for specific file paths to explore the file contents for analysis. ' +
'Hint: you can call dex_explore_remote_warp_diag_output multiple times in parallel if necessary to take advantage of in-memory caching for best performance.',
'Hint: you can call dex_explore_remote_warp_diag_output multiple times in parallel if necessary to take advantage of in-memory caching for best performance.' +
'See https://developers.cloudflare.com/cloudflare-one/connections/connect-devices/warp/troubleshooting/warp-logs/ for more info on warp-diags',
agent,
callback: async ({ accessToken, download }) => {
const reader = await getReader(env, accessToken, download)
Expand Down