Parallels RAS MCP Server

Instructions

Implementation Reference

• src/tools/site-settings.ts:32-39 (handler)

  The handler function that executes the tool logic. It makes a GET request to '/api/site-settings/ad-integration' via rasClient, returns the JSON-formatted response, and handles errors using sanitiseError.
  async () => { try { const data = await rasClient.get("/api/site-settings/ad-integration"); 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 AD integration") }], isError: true }; } }
• src/tools/site-settings.ts:21-40 (registration)

  Tool registration for 'ras_site_get_ad_integration' using server.registerTool. Includes the tool title, description, read-only annotations, empty input schema (no parameters), and the async handler function.
  server.registerTool( "ras_site_get_ad_integration", { title: "AD Integration", description: "Get Active Directory integration configuration, including domain settings, " + "forest trust relationships, and OU mappings. Use this to verify AD connectivity, " + "check domain join status, or troubleshoot authentication issues.", annotations: READ_ONLY_ANNOTATIONS, inputSchema: {}, }, async () => { try { const data = await rasClient.get("/api/site-settings/ad-integration"); 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 AD integration") }], isError: true }; } } );
• src/client.ts:43-54 (helper)

  The sanitiseError helper function used by the handler. It sanitizes error messages by removing auth tokens and passwords, truncates long responses, and prepends context 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}`; }
• src/client.ts:56-167 (helper)

  The RasClient class that provides the get() method used by the handler. Handles authentication (login), session management, automatic token refresh on 401, request timeouts, and making GET requests to the RAS API.
  class RasClient { private baseUrl: string; private authToken: string | null = null; private headers: Record<string, string> = { "Content-Type": "application/json; api-version=1.0", }; constructor() { this.baseUrl = `https://${RAS_HOST}:${RAS_PORT}`; } /** * Authenticate with the RAS API and cache the auth token. */ private async login(): Promise<void> { if (!RAS_HOST || !RAS_USERNAME || !RAS_PASSWORD) { throw new Error( "Missing required environment variables: RAS_HOST, RAS_USERNAME, RAS_PASSWORD" ); } const response = await fetch(`${this.baseUrl}/api/session/logon`, { method: "POST", headers: this.headers, body: JSON.stringify({ username: RAS_USERNAME, password: RAS_PASSWORD, }), signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS), }); if (!response.ok) { const body = await response.text(); throw new Error( `RAS login failed (HTTP ${response.status}): ${body.substring(0, 300)}` ); } const data = await response.json(); this.authToken = data.authToken ?? data.AuthToken ?? null; if (!this.authToken) { throw new Error("RAS login response did not contain an auth token"); } } /** * End the current RAS API session. */ async logoff(): Promise<void> { if (!this.authToken) return; try { await fetch(`${this.baseUrl}/api/session/logoff`, { method: "POST", headers: { ...this.headers, auth_token: this.authToken, }, signal: AbortSignal.timeout(5_000), }); } catch { // Best-effort logoff — ignore errors on shutdown } this.authToken = null; } /** * Make a GET request to the RAS API. * Handles lazy authentication, automatic retry on 401, and request timeouts. */ 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:169-171 (helper)

  Export of the rasClient singleton instance that is imported and used by the site-settings tools.
  export const rasClient = new RasClient(); export { sanitiseError };