ras_infra_get_agents
Retrieve a list of all deployed Parallels RAS agents with hostname, IP, OS, version, and status to verify deployment, diagnose connectivity, or check versions.
Instructions
List all Parallels RAS agents deployed across the farm, including their hostname, IP, OS, agent version, and current status. Use this to verify agent deployment, diagnose connectivity issues, or check agent versions.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/tools/infrastructure.ts:32-39 (handler)The async handler function that executes ras_infra_get_agents tool logic. It calls rasClient.get('/api/infrastructure/agents') to fetch agent data from the RAS API, returns the JSON stringified result, and handles errors with sanitiseError helper.async () => { try { const data = await rasClient.get("/api/infrastructure/agents"); return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] }; } catch (err) { return { content: [{ type: "text" as const, text: sanitiseError(err, "Failed to retrieve agents") }], isError: true }; } }
- src/tools/infrastructure.ts:21-40 (registration)Tool registration using server.registerTool() with name 'ras_infra_get_agents', including metadata (title, description, annotations for read-only/idempotent hints), empty inputSchema (no parameters required), and the handler function.server.registerTool( "ras_infra_get_agents", { title: "RAS Agents", description: "List all Parallels RAS agents deployed across the farm, including their " + "hostname, IP, OS, agent version, and current status. Use this to verify " + "agent deployment, diagnose connectivity issues, or check agent versions.", annotations: READ_ONLY_ANNOTATIONS, inputSchema: {}, }, async () => { try { const data = await rasClient.get("/api/infrastructure/agents"); return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] }; } catch (err) { return { content: [{ type: "text" as const, text: sanitiseError(err, "Failed to retrieve agents") }], isError: true }; } } );
- src/tools/infrastructure.ts:30-30 (schema)Input schema definition - an empty object {} indicating this tool takes no input parameters.inputSchema: {},
- src/client.ts:128-166 (helper)The RasClient.get() method that makes authenticated GET requests to the RAS REST API. It handles lazy authentication, automatic retry on 401 unauthorized, request timeouts, and error handling.async get(path: string): Promise<unknown> { // Ensure we have a valid session if (!this.authToken) { await this.login(); } const fetchOptions = { method: "GET" as const, headers: { ...this.headers, auth_token: this.authToken!, }, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS), }; let response = await fetch(`${this.baseUrl}${path}`, fetchOptions); // Token may have expired — re-authenticate once and retry if (response.status === 401) { await this.login(); response = await fetch(`${this.baseUrl}${path}`, { ...fetchOptions, headers: { ...this.headers, auth_token: this.authToken!, }, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS), }); } if (!response.ok) { const body = await response.text(); throw new Error( `RAS API error (HTTP ${response.status}) on ${path}: ${body.substring(0, 300)}` ); } return response.json(); }
- src/client.ts:43-54 (helper)The sanitiseError() helper function that sanitizes error messages by removing auth tokens and passwords, truncating long API responses, and adding context to prevent leaking sensitive information.function sanitiseError(err: unknown, context: string): string { const raw = err instanceof Error ? err.message : String(err); // Remove anything that looks like a token or password value let sanitised = raw .replace(/auth_token[=:]\s*\S+/gi, "auth_token=[REDACTED]") .replace(/password[=:]\s*\S+/gi, "password=[REDACTED]"); // Truncate excessively long API response bodies if (sanitised.length > 500) { sanitised = sanitised.substring(0, 500) + "... (truncated)"; } return `${context}: ${sanitised}`; }