@smartbear/mcp 0.17.0 → 0.18.0

package/dist/pactflow/client.js

@@ -1,6 +1,7 @@
 import zod__default from "zod";
 import { MCP_SERVER_NAME, MCP_SERVER_VERSION } from "../common/info.js";
 import { isSamplingPolyfillResult } from "../common/pollyfills.js";
+import { getRequestHeader } from "../common/request-context.js";
 import { ToolError } from "../common/tools.js";
 import { getOADMatcherRecommendations, getUserMatcherSelection } from "./client/prompt-utils.js";
 import { PROMPTS } from "./client/prompts.js";
@@ -18,38 +19,42 @@ class PactflowClient {
   toolPrefix = "contract-testing";
   configPrefix = "Pact-Broker";
   config = ConfigurationSchema;
-  headers;
+  token;
+  username;
+  password;
   aiBaseUrl;
   baseUrl;
   _clientType;
   _server;
+  /** Returns the configured MCP server instance. @throws Error if not yet configured. */
   get server() {
     if (!this._server) throw new Error("Server not configured");
     return this._server;
   }
+  /**
+   * Initialises the client with auth credentials and the MCP server reference.
+   * Accepts either a Bearer token (PactFlow) or username/password (Pact Broker).
+   * Does nothing if neither is supplied.
+   *
+   * @param server - The MCP server instance to bind to.
+   * @param config - Connection config (base_url + token OR username/password).
+   */
   async configure(server, config) {
+    this.token = config.token;
+    this.username = config.username;
+    this.password = config.password;
     if (typeof config.token === "string") {
-      this.headers = {
-        Authorization: `Bearer ${config.token}`,
-        "Content-Type": "application/json",
-        "User-Agent": `${MCP_SERVER_NAME}/${MCP_SERVER_VERSION}`
-      };
       this._clientType = "pactflow";
     } else if (typeof config.username === "string" && typeof config.password === "string") {
-      const authString = `${config.username}:${config.password}`;
-      this.headers = {
-        Authorization: `Basic ${Buffer.from(authString).toString("base64")}`,
-        "Content-Type": "application/json",
-        "User-Agent": `${MCP_SERVER_NAME}/${MCP_SERVER_VERSION}`
-      };
       this._clientType = "pact_broker";
     } else {
-      return;
+      this._clientType = "pactflow";
     }
     this.baseUrl = config.base_url;
     this.aiBaseUrl = `${this.baseUrl}/api/ai`;
     this._server = server;
   }
+  /** Returns true if the client has been configured with a base URL and credentials. */
   isConfigured() {
     return this.baseUrl !== void 0;
   }
@@ -136,29 +141,84 @@ class PactflowClient {
       errorContext: "PactFlow AI Entitlements Request"
     });
   }
+  /**
+   * Polls the given status URL with a HEAD request to check operation progress.
+   *
+   * @param statusUrl - The URL returned by the async AI operation.
+   * @returns HTTP status code and whether the operation has completed (status 200).
+   */
   async getStatus(statusUrl) {
     const response = await fetch(statusUrl, {
       method: "HEAD",
-      headers: this.headers
+      headers: this.requestHeaders
     });
     return {
       status: response.status,
       isComplete: response.status === 200
     };
   }
+  /** Returns the current auth/content-type headers used for all requests. */
   get requestHeaders() {
-    return this.headers;
+    let contextToken = getRequestHeader("Pact-Token") || getRequestHeader("Authorization");
+    if (Array.isArray(contextToken)) {
+      contextToken = contextToken[0];
+    }
+    if (contextToken) {
+      let authHeader = contextToken;
+      if (!contextToken.startsWith("Basic ") && !contextToken.startsWith("Bearer ")) {
+        authHeader = `Bearer ${contextToken}`;
+      }
+      return {
+        Authorization: authHeader,
+        "Content-Type": "application/json",
+        "User-Agent": `${MCP_SERVER_NAME}/${MCP_SERVER_VERSION}`
+      };
+    }
+    if (this.token) {
+      let authHeader = this.token;
+      if (!authHeader.startsWith("Basic ") && !authHeader.startsWith("Bearer ")) {
+        authHeader = `Bearer ${authHeader}`;
+      }
+      return {
+        Authorization: authHeader,
+        "Content-Type": "application/json",
+        "User-Agent": `${MCP_SERVER_NAME}/${MCP_SERVER_VERSION}`
+      };
+    } else if (this.username && this.password) {
+      const authString = `${this.username}:${this.password}`;
+      return {
+        Authorization: `Basic ${Buffer.from(authString).toString("base64")}`,
+        "Content-Type": "application/json",
+        "User-Agent": `${MCP_SERVER_NAME}/${MCP_SERVER_VERSION}`
+      };
+    }
+    return void 0;
   }
+  /**
+   * Fetches the final result of a completed async operation.
+   *
+   * @param resultUrl - The result URL returned by the async AI operation.
+   * @returns The parsed JSON result of type T.
+   * @throws ToolError if the response is not OK.
+   */
   async getResult(resultUrl) {
     const response = await fetch(resultUrl, {
       method: "GET",
-      headers: this.headers
+      headers: this.requestHeaders
     });
     if (!response.ok) {
       throw new ToolError(`HTTP error! status: ${response.status}`);
     }
     return response.json();
   }
+  /**
+   * Polls status_url every second until the operation completes or times out (120s).
+   *
+   * @param status_response - URLs returned by the initial async submission.
+   * @param operationName - Human-readable name used in error messages.
+   * @returns The parsed result of type T on success.
+   * @throws ToolError on non-202 status or timeout.
+   */
   async pollForCompletion(status_response, operationName) {
     const startTime = Date.now();
     const timeout = 12e4;
@@ -192,7 +252,7 @@ class PactflowClient {
     try {
       const response = await fetch(url, {
         method,
-        headers: this.headers,
+        headers: this.requestHeaders,
         ...body && { body: JSON.stringify(body) }
       });
       if (!response.ok) {
@@ -203,6 +263,9 @@ class PactflowClient {
           /* @__PURE__ */ new Map([["responseStatus", response.status]])
         );
       }
+      if (response.status === 204) {
+        return void 0;
+      }
       return await response.json();
     } catch (error) {
       if (error instanceof ToolError) {
@@ -236,6 +299,13 @@ class PactflowClient {
     );
   }
   // PactFlow / Pact_Broker client methods
+  /**
+   * Retrieves all provider states declared by a provider's pact tests.
+   *
+   * @param params - `provider`: The name of the provider.
+   * @returns List of provider state strings the provider supports.
+   * @throws ToolError if the request fails.
+   */
   async getProviderStates({
     provider
   }) {
@@ -332,7 +402,7 @@ class PactflowClient {
     try {
       const response = await fetch(url, {
         method: "GET",
-        headers: this.headers
+        headers: this.requestHeaders
       });
       if (!response.ok) {
         const errorText = await response.text().catch(() => "");
@@ -357,7 +427,7 @@ class PactflowClient {
     try {
       const response = await fetch(url, {
         method: "GET",
-        headers: this.headers
+        headers: this.requestHeaders
       });
       if (!response.ok) {
         const errorText = await response.text().catch(() => "");
@@ -371,6 +441,1615 @@ class PactflowClient {
       throw error;
     }
   }
+  /**
+   * Retrieves all pacticipants (applications/services) registered in the workspace,
+   * with optional pagination.
+   *
+   * @param params - Optional pagination parameters (`pageNumber`, `pageSize`).
+   * @returns List of pacticipants with their metadata.
+   * @throws ToolError if the request fails.
+   */
+  async listPacticipants(params) {
+    const queryParams = new URLSearchParams();
+    if (params?.pageNumber) queryParams.set("page", String(params.pageNumber));
+    if (params?.pageSize) queryParams.set("size", String(params.pageSize));
+    const qs = queryParams.toString();
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants${qs ? `?${qs}` : ""}`,
+      { method: "GET", errorContext: "List Pacticipants" }
+    );
+  }
+  /**
+   * Retrieves metadata for a specific pacticipant by name.
+   *
+   * @param params - `pacticipantName`: The name of the pacticipant to fetch.
+   * @returns Pacticipant metadata including display name, main branch, and repository URL.
+   * @throws ToolError if the pacticipant is not found or the request fails.
+   */
+  async getPacticipant({ pacticipantName }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}`,
+      { method: "GET", errorContext: "Get Pacticipant" }
+    );
+  }
+  /**
+   * Retrieves all branches for a given pacticipant, with optional name filtering
+   * and pagination.
+   *
+   * @param params - `pacticipantName`, optional `q` (name filter), `pageNumber`, `pageSize`.
+   * @returns List of branches for the pacticipant.
+   * @throws ToolError if the request fails.
+   */
+  async listBranches({
+    pacticipantName,
+    q,
+    pageNumber,
+    pageSize
+  }) {
+    const queryParams = new URLSearchParams();
+    if (q) queryParams.set("q", q);
+    if (pageNumber) queryParams.set("pageNumber", String(pageNumber));
+    if (pageSize) queryParams.set("pageSize", String(pageSize));
+    const qs = queryParams.toString();
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}/branches${qs ? `?${qs}` : ""}`,
+      { method: "GET", errorContext: "List Branches" }
+    );
+  }
+  /**
+   * Retrieves all published versions for a given pacticipant, with optional pagination.
+   *
+   * @param params - `pacticipantName`, optional `pageNumber` and `pageSize`.
+   * @returns List of versions with their branch and tag associations.
+   * @throws ToolError if the request fails.
+   */
+  async listVersions({
+    pacticipantName,
+    pageNumber,
+    pageSize
+  }) {
+    const queryParams = new URLSearchParams();
+    if (pageNumber) queryParams.set("page", String(pageNumber));
+    if (pageSize) queryParams.set("size", String(pageSize));
+    const qs = queryParams.toString();
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}/versions${qs ? `?${qs}` : ""}`,
+      { method: "GET", errorContext: "List Versions" }
+    );
+  }
+  /**
+   * Retrieves metadata for a specific version of a pacticipant.
+   *
+   * @param params - `pacticipantName` and `versionNumber` to retrieve.
+   * @returns Version metadata including branches, tags, and build URL.
+   * @throws ToolError if the version is not found or the request fails.
+   */
+  async getVersion({
+    pacticipantName,
+    versionNumber
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}/versions/${encodeURIComponent(versionNumber)}`,
+      { method: "GET", errorContext: "Get Version" }
+    );
+  }
+  /**
+   * Retrieves the latest version of a pacticipant, optionally filtered by tag.
+   *
+   * @param params - `pacticipantName` and optional `tag` to filter by.
+   * @returns The latest matching version.
+   * @throws ToolError if the request fails.
+   */
+  async getLatestVersion({
+    pacticipantName,
+    tag
+  }) {
+    const path = tag ? `/pacticipants/${encodeURIComponent(pacticipantName)}/latest-version/${encodeURIComponent(tag)}` : `/pacticipants/${encodeURIComponent(pacticipantName)}/latest-version`;
+    return await this.fetchJson(`${this.baseUrl}${path}`, {
+      method: "GET",
+      errorContext: "Get Latest Version"
+    });
+  }
+  /**
+   * Retrieves all environments configured in the workspace.
+   *
+   * @returns List of environments with their UUIDs, names, and production flags.
+   * @throws ToolError if the request fails.
+   */
+  async listEnvironments() {
+    return await this.fetchJson(`${this.baseUrl}/environments`, {
+      method: "GET",
+      errorContext: "List Environments"
+    });
+  }
+  /**
+   * Retrieves metadata for a specific environment by UUID.
+   *
+   * @param params - `environmentId`: The UUID of the environment.
+   * @returns Environment metadata including name, display name, and production flag.
+   * @throws ToolError if the environment is not found or the request fails.
+   */
+  async getEnvironment({ environmentId }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/environments/${encodeURIComponent(environmentId)}`,
+      { method: "GET", errorContext: "Get Environment" }
+    );
+  }
+  /**
+   * Records that a specific version of a pacticipant has been deployed to an environment.
+   *
+   * @param params - `pacticipantName`, `versionNumber`, `environmentId`, and optional
+   *   `applicationInstance` (for blue/green or multi-instance deployments).
+   * @returns The created deployment record.
+   * @throws ToolError if the request fails.
+   */
+  async recordDeployment({
+    pacticipantName,
+    versionNumber,
+    environmentId,
+    applicationInstance
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}/versions/${encodeURIComponent(versionNumber)}/deployed-versions/environment/${encodeURIComponent(environmentId)}`,
+      {
+        method: "POST",
+        body: applicationInstance ? { applicationInstance } : {},
+        errorContext: "Record Deployment"
+      }
+    );
+  }
+  /**
+   * Retrieves all versions currently deployed to a given environment.
+   *
+   * @param params - `environmentId`: The UUID of the environment to query.
+   * @returns List of currently deployed versions across all pacticipants.
+   * @throws ToolError if the request fails.
+   */
+  async getCurrentlyDeployed({
+    environmentId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/environments/${encodeURIComponent(environmentId)}/deployed-versions/currently-deployed`,
+      { method: "GET", errorContext: "Get Currently Deployed" }
+    );
+  }
+  /**
+   * Records that a version of a pacticipant has been released to an environment.
+   * Used for mobile/library workflows where multiple versions coexist simultaneously.
+   *
+   * @param params - `pacticipantName`, `versionNumber`, and `environmentId`.
+   * @returns The created release record.
+   * @throws ToolError if the request fails.
+   */
+  async recordRelease({
+    pacticipantName,
+    versionNumber,
+    environmentId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}/versions/${encodeURIComponent(versionNumber)}/released-versions/environment/${encodeURIComponent(environmentId)}`,
+      { method: "POST", body: {}, errorContext: "Record Release" }
+    );
+  }
+  /**
+   * Retrieves all versions currently released and supported in a given environment.
+   *
+   * @param params - `environmentId`: The UUID of the environment to query.
+   * @returns List of currently supported released versions.
+   * @throws ToolError if the request fails.
+   */
+  async getCurrentlySupported({
+    environmentId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/environments/${encodeURIComponent(environmentId)}/released-versions/currently-supported`,
+      { method: "GET", errorContext: "Get Currently Supported" }
+    );
+  }
+  /**
+   * Publishes one or more consumer Pact contracts to the Pact Broker or PactFlow.
+   *
+   * @param body - Consumer name, version number, contract files (base64-encoded),
+   *   and optional branch/tag metadata.
+   * @returns Publication result including the pacticipant version number.
+   * @throws ToolError if the request fails.
+   */
+  async publishContracts(body) {
+    return await this.fetchJson(`${this.baseUrl}/contracts/publish`, {
+      method: "POST",
+      body,
+      errorContext: "Publish Consumer Contracts"
+    });
+  }
+  /**
+   * Publishes a provider OpenAPI contract and its self-verification results to PactFlow
+   * for use in Bi-Directional Contract Testing.
+   *
+   * @param params - `providerName`, version number, base64-encoded OpenAPI spec,
+   *   content type, and self-verification results.
+   * @returns Publication result.
+   * @throws ToolError if the request fails.
+   */
+  async publishProviderContract({
+    providerName,
+    ...body
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/provider-contracts/provider/${encodeURIComponent(providerName)}/publish`,
+      { method: "POST", body, errorContext: "Publish Provider Contract" }
+    );
+  }
+  /**
+   * Retrieves the set of consumer pacts a provider should verify in its current CI run,
+   * based on consumer version selectors and WIP/pending pact configuration.
+   *
+   * @param params - `providerName`, consumer version selectors, pending/WIP flags,
+   *   and optional provider branch/tag context.
+   * @returns List of pact URLs and metadata the provider must verify.
+   * @throws ToolError if the request fails.
+   */
+  async getPactsForVerification({
+    providerName,
+    ...body
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacts/provider/${encodeURIComponent(providerName)}/for-verification`,
+      { method: "POST", body, errorContext: "Get Pacts for Verification" }
+    );
+  }
+  /**
+   * Fetches the provider OpenAPI contract for a given provider version in BDCT.
+   *
+   * @param params - `providerName` and `providerVersionNumber`.
+   * @returns The published OpenAPI spec and its verification status.
+   * @throws ToolError if the request fails.
+   */
+  async getBiDirectionalProviderContract({
+    providerName,
+    providerVersionNumber
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/contracts/bi-directional/provider/${encodeURIComponent(providerName)}/version/${encodeURIComponent(providerVersionNumber)}/provider-contract`,
+      { method: "GET", errorContext: "Get BDCT Provider Contract" }
+    );
+  }
+  /**
+   * Fetches the self-verification results for a provider contract version in BDCT.
+   *
+   * @param params - `providerName` and `providerVersionNumber`.
+   * @returns The results of the tool (e.g. Dredd, Schemathesis) that verified the provider.
+   * @throws ToolError if the request fails.
+   */
+  async getBiDirectionalProviderContractVerificationResults({
+    providerName,
+    providerVersionNumber
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/contracts/bi-directional/provider/${encodeURIComponent(providerName)}/version/${encodeURIComponent(providerVersionNumber)}/provider-contract-verification-results`,
+      {
+        method: "GET",
+        errorContext: "Get BDCT Provider Contract Verification Results"
+      }
+    );
+  }
+  /**
+   * Fetches all consumer Pact contracts relevant to a given provider version in BDCT.
+   *
+   * @param params - `providerName` and `providerVersionNumber`.
+   * @returns Consumer contracts compared against the provider's OpenAPI spec.
+   * @throws ToolError if the request fails.
+   */
+  async getBiDirectionalConsumerContract({
+    providerName,
+    providerVersionNumber
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/contracts/bi-directional/provider/${encodeURIComponent(providerName)}/version/${encodeURIComponent(providerVersionNumber)}/consumer-contract`,
+      { method: "GET", errorContext: "Get BDCT Consumer Contract" }
+    );
+  }
+  /**
+   * Fetches the consumer contract verification results for a given provider version in BDCT.
+   *
+   * @param params - `providerName` and `providerVersionNumber`.
+   * @returns Results of comparing all consumer pacts against the provider's OpenAPI spec.
+   * @throws ToolError if the request fails.
+   */
+  async getBiDirectionalConsumerContractVerificationResults({
+    providerName,
+    providerVersionNumber
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/contracts/bi-directional/provider/${encodeURIComponent(providerName)}/version/${encodeURIComponent(providerVersionNumber)}/consumer-contract-verification-results`,
+      {
+        method: "GET",
+        errorContext: "Get BDCT Consumer Contract Verification Results"
+      }
+    );
+  }
+  /**
+   * Fetches the cross-contract verification results for a given provider version in BDCT.
+   *
+   * @param params - `providerName` and `providerVersionNumber`.
+   * @returns Combined outcome of PactFlow's automated comparison of the provider spec
+   *   against all relevant consumer pacts.
+   * @throws ToolError if the request fails.
+   */
+  async getBiDirectionalCrossContractVerificationResults({
+    providerName,
+    providerVersionNumber
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/contracts/bi-directional/provider/${encodeURIComponent(providerName)}/version/${encodeURIComponent(providerVersionNumber)}/cross-contract-verification-results`,
+      {
+        method: "GET",
+        errorContext: "Get BDCT Cross-Contract Verification Results"
+      }
+    );
+  }
+  /**
+   * Fetches the consumer Pact contract for a specific consumer-provider version pair in BDCT.
+   *
+   * @param params - `providerName`, `providerVersionNumber`, `consumerName`,
+   *   and `consumerVersionNumber`.
+   * @returns The Pact contract published by the specified consumer version.
+   * @throws ToolError if the request fails.
+   */
+  async getBiDirectionalConsumerContractByConsumer({
+    providerName,
+    providerVersionNumber,
+    consumerName,
+    consumerVersionNumber
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/contracts/bi-directional/provider/${encodeURIComponent(providerName)}/version/${encodeURIComponent(providerVersionNumber)}/consumer/${encodeURIComponent(consumerName)}/version/${encodeURIComponent(consumerVersionNumber)}/consumer-contract`,
+      {
+        method: "GET",
+        errorContext: "Get BDCT Consumer Contract (by consumer version)"
+      }
+    );
+  }
+  /**
+   * Fetches the provider OpenAPI contract for a specific consumer-provider version pair in BDCT.
+   *
+   * @param params - `providerName`, `providerVersionNumber`, `consumerName`,
+   *   and `consumerVersionNumber`.
+   * @returns The provider's OpenAPI spec in the context of the given consumer version.
+   * @throws ToolError if the request fails.
+   */
+  async getBiDirectionalProviderContractByConsumer({
+    providerName,
+    providerVersionNumber,
+    consumerName,
+    consumerVersionNumber
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/contracts/bi-directional/provider/${encodeURIComponent(providerName)}/version/${encodeURIComponent(providerVersionNumber)}/consumer/${encodeURIComponent(consumerName)}/version/${encodeURIComponent(consumerVersionNumber)}/provider-contract`,
+      {
+        method: "GET",
+        errorContext: "Get BDCT Provider Contract (by consumer version)"
+      }
+    );
+  }
+  /**
+   * Fetches the provider contract self-verification results for a specific
+   * consumer-provider version pair in BDCT.
+   *
+   * @param params - `providerName`, `providerVersionNumber`, `consumerName`,
+   *   and `consumerVersionNumber`.
+   * @returns Provider self-verification results scoped to the given consumer version.
+   * @throws ToolError if the request fails.
+   */
+  async getBiDirectionalProviderContractVerificationResultsByConsumer({
+    providerName,
+    providerVersionNumber,
+    consumerName,
+    consumerVersionNumber
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/contracts/bi-directional/provider/${encodeURIComponent(providerName)}/version/${encodeURIComponent(providerVersionNumber)}/consumer/${encodeURIComponent(consumerName)}/version/${encodeURIComponent(consumerVersionNumber)}/provider-contract-verification-results`,
+      {
+        method: "GET",
+        errorContext: "Get BDCT Provider Contract Verification Results (by consumer version)"
+      }
+    );
+  }
+  /**
+   * Fetches the consumer contract verification results for a specific
+   * consumer-provider version pair in BDCT.
+   *
+   * @param params - `providerName`, `providerVersionNumber`, `consumerName`,
+   *   and `consumerVersionNumber`.
+   * @returns Results of comparing the specific consumer pact against the provider's OpenAPI spec.
+   * @throws ToolError if the request fails.
+   */
+  async getBiDirectionalConsumerContractVerificationResultsByConsumer({
+    providerName,
+    providerVersionNumber,
+    consumerName,
+    consumerVersionNumber
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/contracts/bi-directional/provider/${encodeURIComponent(providerName)}/version/${encodeURIComponent(providerVersionNumber)}/consumer/${encodeURIComponent(consumerName)}/version/${encodeURIComponent(consumerVersionNumber)}/consumer-contract-verification-results`,
+      {
+        method: "GET",
+        errorContext: "Get BDCT Consumer Contract Verification Results (by consumer version)"
+      }
+    );
+  }
+  /**
+   * Fetches the cross-contract verification results for a specific
+   * consumer-provider version pair in BDCT.
+   *
+   * @param params - `providerName`, `providerVersionNumber`, `consumerName`,
+   *   and `consumerVersionNumber`.
+   * @returns The precise cross-contract comparison outcome for the given pairing.
+   * @throws ToolError if the request fails.
+   */
+  async getBiDirectionalCrossContractVerificationResultsByConsumer({
+    providerName,
+    providerVersionNumber,
+    consumerName,
+    consumerVersionNumber
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/contracts/bi-directional/provider/${encodeURIComponent(providerName)}/version/${encodeURIComponent(providerVersionNumber)}/consumer/${encodeURIComponent(consumerName)}/version/${encodeURIComponent(consumerVersionNumber)}/cross-contract-verification-results`,
+      {
+        method: "GET",
+        errorContext: "Get BDCT Cross-Contract Verification Results (by consumer version)"
+      }
+    );
+  }
+  /**
+   * Retrieves all consumer-provider integrations registered in the workspace.
+   *
+   * @returns List of all consumer-provider pairings that have pacts published.
+   * @throws ToolError if the request fails.
+   */
+  async listIntegrations() {
+    return await this.fetchJson(`${this.baseUrl}/integrations`, {
+      method: "GET",
+      errorContext: "List Integrations"
+    });
+  }
+  /**
+   * Retrieves the integration network graph for a specific pacticipant,
+   * showing all services it consumes and all consumers that depend on it.
+   *
+   * @param params - `pacticipantName`: The name of the pacticipant.
+   * @returns Network graph of consumer-provider relationships for the pacticipant.
+   * @throws ToolError if the request fails.
+   */
+  async getPacticipantNetwork({
+    pacticipantName
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipant/${encodeURIComponent(pacticipantName)}/network`,
+      { method: "GET", errorContext: "Get Pacticipant Network" }
+    );
+  }
+  /**
+   * Retrieves all labels used across the workspace, with optional pagination.
+   *
+   * @param params - Optional `pageNumber` and `pageSize`.
+   * @returns List of every label applied to any pacticipant.
+   * @throws ToolError if the request fails.
+   */
+  async listLabels(params) {
+    const queryParams = new URLSearchParams();
+    if (params?.pageNumber) queryParams.set("page", String(params.pageNumber));
+    if (params?.pageSize) queryParams.set("size", String(params.pageSize));
+    const qs = queryParams.toString();
+    return await this.fetchJson(
+      `${this.baseUrl}/labels${qs ? `?${qs}` : ""}`,
+      { method: "GET", errorContext: "List Labels" }
+    );
+  }
+  /**
+   * Checks whether a specific label is applied to a pacticipant.
+   *
+   * @param params - `pacticipantName` and `labelName`.
+   * @returns The label resource if it exists (404 if not applied).
+   * @throws ToolError if the request fails.
+   */
+  async getPacticipantLabel({
+    pacticipantName,
+    labelName
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}/labels/${encodeURIComponent(labelName)}`,
+      { method: "GET", errorContext: "Get Pacticipant Label" }
+    );
+  }
+  /**
+   * Retrieves all pacticipants that have a specific label applied.
+   *
+   * @param params - `labelName`: The label to filter by.
+   * @returns List of pacticipants with the given label.
+   * @throws ToolError if the request fails.
+   */
+  async listPacticipantsByLabel({ labelName }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/label/${encodeURIComponent(labelName)}`,
+      { method: "GET", errorContext: "List Pacticipants by Label" }
+    );
+  }
+  /**
+   * Fully replaces a pacticipant's metadata. All fields not provided are cleared.
+   *
+   * @param params - `pacticipantName` plus optional metadata fields
+   *   (displayName, mainBranch, repositoryUrl, etc.).
+   * @returns The updated pacticipant resource.
+   * @throws ToolError if the request fails.
+   */
+  async updatePacticipant({
+    pacticipantName,
+    ...body
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}`,
+      { method: "PUT", body, errorContext: "Update Pacticipant" }
+    );
+  }
+  /**
+   * Partially updates a pacticipant's metadata — only the fields provided are changed.
+   *
+   * @param params - `pacticipantName` plus the specific fields to update.
+   * @returns The updated pacticipant resource.
+   * @throws ToolError if the request fails.
+   */
+  async patchPacticipant({
+    pacticipantName,
+    ...body
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}`,
+      { method: "PATCH", body, errorContext: "Patch Pacticipant" }
+    );
+  }
+  /**
+   * Updates metadata for a specific pacticipant version (e.g. sets the build URL).
+   *
+   * @param params - `pacticipantName`, `versionNumber`, and optional `buildUrl`.
+   * @returns The updated version resource.
+   * @throws ToolError if the request fails.
+   */
+  async updateVersion({
+    pacticipantName,
+    versionNumber,
+    ...body
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}/versions/${encodeURIComponent(versionNumber)}`,
+      { method: "PUT", body, errorContext: "Update Version" }
+    );
+  }
+  /**
+   * Retrieves all versions published from a specific branch of a pacticipant.
+   *
+   * @param params - `pacticipantName`, `branchName`, optional `pageNumber` and `pageSize`.
+   * @returns List of versions created on the given branch.
+   * @throws ToolError if the request fails.
+   */
+  async getBranchVersions({
+    pacticipantName,
+    branchName,
+    pageNumber,
+    pageSize
+  }) {
+    const queryParams = new URLSearchParams();
+    if (pageNumber) queryParams.set("page", String(pageNumber));
+    if (pageSize) queryParams.set("size", String(pageSize));
+    const qs = queryParams.toString();
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}/branches/${encodeURIComponent(branchName)}/versions${qs ? `?${qs}` : ""}`,
+      { method: "GET", errorContext: "Get Branch Versions" }
+    );
+  }
+  /**
+   * Retrieves deployment records for a specific pacticipant version in a given environment.
+   *
+   * @param params - `pacticipantName`, `versionNumber`, and `environmentId`.
+   * @returns All deployment records for the version, including whether each is currently active.
+   * @throws ToolError if the request fails.
+   */
+  async getDeployedVersions({
+    pacticipantName,
+    versionNumber,
+    environmentId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}/versions/${encodeURIComponent(versionNumber)}/deployed-versions/environment/${encodeURIComponent(environmentId)}`,
+      { method: "GET", errorContext: "Get Deployed Versions" }
+    );
+  }
+  /**
+   * Retrieves release records for a specific pacticipant version in a given environment.
+   *
+   * @param params - `pacticipantName`, `versionNumber`, and `environmentId`.
+   * @returns All release records for the version in the environment.
+   * @throws ToolError if the request fails.
+   */
+  async getReleasedVersions({
+    pacticipantName,
+    versionNumber,
+    environmentId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}/versions/${encodeURIComponent(versionNumber)}/released-versions/environment/${encodeURIComponent(environmentId)}`,
+      { method: "GET", errorContext: "Get Released Versions" }
+    );
+  }
+  /**
+   * Creates a new deployment environment in the workspace.
+   *
+   * @param body - Environment name, display name, and whether it is a production environment.
+   * @returns The created environment resource.
+   * @throws ToolError if the request fails.
+   */
+  async createEnvironment({
+    ...body
+  }) {
+    return await this.fetchJson(`${this.baseUrl}/environments`, {
+      method: "POST",
+      body,
+      errorContext: "Create Environment"
+    });
+  }
+  /**
+   * Fully replaces an environment's configuration.
+   *
+   * @param params - `environmentId` (UUID) plus updated name, display name, and production flag.
+   * @returns The updated environment resource.
+   * @throws ToolError if the environment is not found or the request fails.
+   */
+  async updateEnvironment({
+    environmentId,
+    ...body
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/environments/${encodeURIComponent(environmentId)}`,
+      {
+        method: "PUT",
+        body,
+        errorContext: "Update Environment"
+      }
+    );
+  }
+  /**
+   * Deletes a deployment environment from the workspace.
+   *
+   * @param params - `environmentId`: UUID of the environment to delete.
+   * @throws ToolError if the environment is not found or the request fails.
+   */
+  async deleteEnvironment({
+    environmentId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/environments/${encodeURIComponent(environmentId)}`,
+      {
+        method: "DELETE",
+        errorContext: "Delete Environment"
+      }
+    );
+  }
+  /**
+   * Registers a new pacticipant (application/service) in the workspace.
+   *
+   * @param body - Name, optional display name, main branch, and repository URL.
+   * @returns The created pacticipant resource.
+   * @throws ToolError if the request fails.
+   */
+  async createPacticipant({
+    ...body
+  }) {
+    return await this.fetchJson(`${this.baseUrl}/pacticipants`, {
+      method: "POST",
+      body,
+      errorContext: "Create Pacticipant"
+    });
+  }
+  /**
+   * Permanently removes a pacticipant and all its associated data from the workspace.
+   *
+   * @param params - `pacticipantName`: The name of the pacticipant to delete.
+   * @throws ToolError if the request fails.
+   */
+  async deletePacticipant({
+    pacticipantName
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}`,
+      {
+        method: "DELETE",
+        errorContext: "Delete Pacticipant"
+      }
+    );
+  }
+  /**
+   * Retrieves metadata for a specific branch of a pacticipant.
+   *
+   * @param params - `pacticipantName` and `branchName`.
+   * @returns Branch metadata including its versions.
+   * @throws ToolError if the branch is not found or the request fails.
+   */
+  async getBranch({
+    pacticipantName,
+    branchName
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}/branches/${encodeURIComponent(branchName)}`,
+      { method: "GET", errorContext: "Get Branch" }
+    );
+  }
+  /**
+   * Deletes a branch and its version associations from a pacticipant.
+   *
+   * @param params - `pacticipantName` and `branchName`.
+   * @throws ToolError if the branch is not found or the request fails.
+   */
+  async deleteBranch({
+    pacticipantName,
+    branchName
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}/branches/${encodeURIComponent(branchName)}`,
+      { method: "DELETE", errorContext: "Delete Branch" }
+    );
+  }
+  /**
+   * Applies a label to a pacticipant.
+   *
+   * @param params - `pacticipantName` and `labelName` to apply.
+   * @returns The created label resource.
+   * @throws ToolError if the request fails.
+   */
+  async addLabel({
+    pacticipantName,
+    labelName
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}/labels/${encodeURIComponent(labelName)}`,
+      { method: "PUT", body: {}, errorContext: "Add Label" }
+    );
+  }
+  /**
+   * Removes a label from a pacticipant.
+   *
+   * @param params - `pacticipantName` and `labelName` to remove.
+   * @throws ToolError if the label or pacticipant is not found, or the request fails.
+   */
+  async removeLabel({
+    pacticipantName,
+    labelName
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/pacticipants/${encodeURIComponent(pacticipantName)}/labels/${encodeURIComponent(labelName)}`,
+      { method: "DELETE", errorContext: "Remove Label" }
+    );
+  }
+  /**
+   * Retrieves all consumer-provider integrations assigned to a specific team.
+   *
+   * @param params - `teamId`: UUID of the team.
+   * @returns List of integrations associated with the team.
+   * @throws ToolError if the request fails.
+   */
+  async getIntegrationsByTeam({
+    teamId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/integrations/team/${encodeURIComponent(teamId)}`,
+      {
+        method: "GET",
+        errorContext: "Get Integrations by Team"
+      }
+    );
+  }
+  /**
+   * Deletes the integration (pact relationship) between a specific consumer and provider.
+   *
+   * @param params - `providerName` and `consumerName`.
+   * @throws ToolError if the integration is not found or the request fails.
+   */
+  async deleteIntegration({
+    providerName,
+    consumerName
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/integrations/provider/${encodeURIComponent(providerName)}/consumer/${encodeURIComponent(consumerName)}`,
+      { method: "DELETE", errorContext: "Delete Integration" }
+    );
+  }
+  /**
+   * Deletes all consumer-provider integrations in the workspace. Use with caution.
+   *
+   * @throws ToolError if the request fails.
+   */
+  async deleteAllIntegrations() {
+    return await this.fetchJson(`${this.baseUrl}/integrations`, {
+      method: "DELETE",
+      errorContext: "Delete All Integrations"
+    });
+  }
+  /**
+   * Retrieves all webhooks configured in the workspace.
+   *
+   * @returns List of webhook definitions and their trigger configurations.
+   * @throws ToolError if the request fails.
+   */
+  async listWebhooks() {
+    return await this.fetchJson(`${this.baseUrl}/webhooks`, {
+      method: "GET",
+      errorContext: "List Webhooks"
+    });
+  }
+  /**
+   * Retrieves the configuration for a specific webhook by UUID.
+   *
+   * @param params - `webhookId`: UUID of the webhook.
+   * @returns Webhook definition including its URL, events, and consumer/provider filters.
+   * @throws ToolError if the webhook is not found or the request fails.
+   */
+  async getWebhook({
+    webhookId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/webhooks/${encodeURIComponent(webhookId)}`,
+      {
+        method: "GET",
+        errorContext: "Get Webhook"
+      }
+    );
+  }
+  /**
+   * Creates a new webhook triggered by pact publication or verification events.
+   *
+   * @param body - Webhook URL, HTTP method, headers, body, events, and optional
+   *   consumer/provider filters.
+   * @returns The created webhook resource.
+   * @throws ToolError if the request fails.
+   */
+  async createWebhook({
+    ...body
+  }) {
+    return await this.fetchJson(`${this.baseUrl}/webhooks`, {
+      method: "POST",
+      body,
+      errorContext: "Create Webhook"
+    });
+  }
+  /**
+   * Replaces the configuration of an existing webhook.
+   *
+   * @param params - `webhookId` (UUID) plus the full updated webhook definition.
+   * @returns The updated webhook resource.
+   * @throws ToolError if the webhook is not found or the request fails.
+   */
+  async updateWebhook({
+    webhookId,
+    ...body
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/webhooks/${encodeURIComponent(webhookId)}`,
+      {
+        method: "PUT",
+        body,
+        errorContext: "Update Webhook"
+      }
+    );
+  }
+  /**
+   * Deletes a webhook by UUID.
+   *
+   * @param params - `webhookId`: UUID of the webhook to delete.
+   * @throws ToolError if the webhook is not found or the request fails.
+   */
+  async deleteWebhook({
+    webhookId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/webhooks/${encodeURIComponent(webhookId)}`,
+      {
+        method: "DELETE",
+        errorContext: "Delete Webhook"
+      }
+    );
+  }
+  /**
+   * Fires all webhooks in the workspace as a test, regardless of their trigger conditions.
+   *
+   * @throws ToolError if the request fails.
+   */
+  async executeWebhooks() {
+    return await this.fetchJson(`${this.baseUrl}/webhooks/execute`, {
+      method: "POST",
+      body: {},
+      errorContext: "Execute Webhooks"
+    });
+  }
+  /**
+   * Fires a specific webhook as a test, regardless of its trigger conditions.
+   *
+   * @param params - `webhookId`: UUID of the webhook to execute.
+   * @throws ToolError if the webhook is not found or the request fails.
+   */
+  async executeWebhook({
+    webhookId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/webhooks/${encodeURIComponent(webhookId)}/execute`,
+      {
+        method: "POST",
+        body: {},
+        errorContext: "Execute Webhook"
+      }
+    );
+  }
+  /**
+   * Retrieves all secrets stored in the workspace (names only, not values).
+   *
+   * @returns List of secret metadata.
+   * @throws ToolError if the request fails.
+   */
+  async listSecrets() {
+    return await this.fetchJson(`${this.baseUrl}/secrets`, {
+      method: "GET",
+      errorContext: "List Secrets"
+    });
+  }
+  /**
+   * Retrieves metadata for a specific secret by UUID (value is not returned).
+   *
+   * @param params - `secretId`: UUID of the secret.
+   * @throws ToolError if the secret is not found or the request fails.
+   */
+  async getSecret({
+    secretId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/secrets/${encodeURIComponent(secretId)}`,
+      {
+        method: "GET",
+        errorContext: "Get Secret"
+      }
+    );
+  }
+  /**
+   * Creates a new secret for use in webhook configurations.
+   *
+   * @param body - Secret name, description, and value.
+   * @returns The created secret resource (value is not echoed back).
+   * @throws ToolError if the request fails.
+   */
+  async createSecret({
+    ...body
+  }) {
+    return await this.fetchJson(`${this.baseUrl}/secrets`, {
+      method: "POST",
+      body,
+      errorContext: "Create Secret"
+    });
+  }
+  /**
+   * Replaces the value and/or description of an existing secret.
+   *
+   * @param params - `secretId` (UUID) plus updated name, description, and/or value.
+   * @throws ToolError if the secret is not found or the request fails.
+   */
+  async updateSecret({
+    secretId,
+    ...body
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/secrets/${encodeURIComponent(secretId)}`,
+      {
+        method: "PUT",
+        body,
+        errorContext: "Update Secret"
+      }
+    );
+  }
+  /**
+   * Permanently deletes a secret from the workspace.
+   *
+   * @param params - `secretId`: UUID of the secret to delete.
+   * @throws ToolError if the secret is not found or the request fails.
+   */
+  async deleteSecret({
+    secretId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/secrets/${encodeURIComponent(secretId)}`,
+      {
+        method: "DELETE",
+        errorContext: "Delete Secret"
+      }
+    );
+  }
+  /**
+   * Retrieves the profile of the currently authenticated user.
+   *
+   * @returns Current user's name, email, roles, and active status.
+   * @throws ToolError if the request fails.
+   */
+  async getCurrentUser() {
+    return await this.fetchJson(`${this.baseUrl}/user`, {
+      method: "GET",
+      errorContext: "Get Current User"
+    });
+  }
+  /**
+   * Lists all API tokens associated with the current user's account.
+   *
+   * @returns Token metadata (IDs, descriptions) — values are not returned.
+   * @throws ToolError if the request fails.
+   */
+  async listTokens() {
+    return await this.fetchJson(`${this.baseUrl}/settings/tokens`, {
+      method: "GET",
+      errorContext: "List Tokens"
+    });
+  }
+  /**
+   * Regenerates (rotates) an API token, invalidating the previous value.
+   *
+   * @param params - `tokenId`: The identifier of the token to regenerate.
+   * @returns The new token value.
+   * @throws ToolError if the token is not found or the request fails.
+   */
+  async regenerateToken({
+    tokenId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/settings/tokens/${encodeURIComponent(tokenId)}/regenerate`,
+      {
+        method: "POST",
+        body: {},
+        errorContext: "Regenerate Token"
+      }
+    );
+  }
+  /**
+   * Retrieves UI and notification preferences for the currently authenticated user.
+   *
+   * @returns User preference settings.
+   * @throws ToolError if the request fails.
+   */
+  async getUserPreferences() {
+    return await this.fetchJson(
+      `${this.baseUrl}/preferences/current-user`,
+      {
+        method: "GET",
+        errorContext: "Get User Preferences"
+      }
+    );
+  }
+  /**
+   * Retrieves workspace-level system preferences and configuration.
+   *
+   * @returns System preference settings.
+   * @throws ToolError if the request fails.
+   */
+  async getSystemPreferences() {
+    return await this.fetchJson(`${this.baseUrl}/preferences/system`, {
+      method: "GET",
+      errorContext: "Get System Preferences"
+    });
+  }
+  /**
+   * Retrieves the workspace audit log with optional filtering and pagination.
+   *
+   * @param params - Optional filters: `since` (ISO date), `userUuid`, `type`,
+   *   `sort`, `from` cursor, `pageNumber`, and `pageSize`.
+   * @returns Paginated list of audit events.
+   * @throws ToolError if the request fails.
+   */
+  async getAuditLog(params) {
+    const queryParams = new URLSearchParams();
+    if (params.since) queryParams.set("since", params.since);
+    if (params.userUuid) queryParams.set("userUuid", params.userUuid);
+    if (params.type) queryParams.set("type", params.type);
+    if (params.sort) queryParams.set("sort", params.sort);
+    if (params.from) queryParams.set("from", params.from);
+    if (params.pageNumber)
+      queryParams.set("pageNumber", String(params.pageNumber));
+    if (params.pageSize) queryParams.set("pageSize", String(params.pageSize));
+    const qs = queryParams.toString();
+    return await this.fetchJson(
+      `${this.baseUrl}/audit${qs ? `?${qs}` : ""}`,
+      {
+        method: "GET",
+        errorContext: "Get Audit Log"
+      }
+    );
+  }
+  /**
+   * Lists all users in the workspace with optional filtering and pagination (admin).
+   *
+   * @param params - Optional `active` flag, `q` (name/email search), `userType`,
+   *   `page`, and `size`.
+   * @returns Paginated list of user accounts.
+   * @throws ToolError if the request fails.
+   */
+  async listAdminUsers(params) {
+    const queryParams = new URLSearchParams();
+    if (params.active !== void 0)
+      queryParams.set("active", String(params.active));
+    if (params.q) queryParams.set("q", params.q);
+    if (params.userType !== void 0)
+      queryParams.set("userType", String(params.userType));
+    if (params.page) queryParams.set("page", String(params.page));
+    if (params.size) queryParams.set("size", String(params.size));
+    const qs = queryParams.toString();
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/users${qs ? `?${qs}` : ""}`,
+      {
+        method: "GET",
+        errorContext: "List Admin Users"
+      }
+    );
+  }
+  /**
+   * Retrieves a user's full profile by UUID (admin).
+   *
+   * @param params - `userId`: UUID of the user.
+   * @returns User profile including roles and active status.
+   * @throws ToolError if the user is not found or the request fails.
+   */
+  async getAdminUser({
+    userId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/users/${encodeURIComponent(userId)}`,
+      {
+        method: "GET",
+        errorContext: "Get Admin User"
+      }
+    );
+  }
+  /**
+   * Creates a new user account in the workspace (admin).
+   *
+   * @param body - User name, email, and optional SSO identity fields.
+   * @returns The created user resource.
+   * @throws ToolError if the request fails.
+   */
+  async createAdminUser({
+    ...body
+  }) {
+    return await this.fetchJson(`${this.baseUrl}/admin/users`, {
+      method: "POST",
+      body,
+      errorContext: "Create Admin User"
+    });
+  }
+  /**
+   * Replaces a user's profile (admin). Can also deactivate the user.
+   *
+   * @param params - `userId` (UUID) plus updated name, email, active flag, and SSO fields.
+   * @returns The updated user resource.
+   * @throws ToolError if the user is not found or the request fails.
+   */
+  async updateAdminUser({
+    userId,
+    ...body
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/users/${encodeURIComponent(userId)}`,
+      {
+        method: "PUT",
+        body,
+        errorContext: "Update Admin User"
+      }
+    );
+  }
+  /**
+   * Permanently deletes a user account from the workspace (admin).
+   *
+   * @param params - `userId`: UUID of the user to delete.
+   * @throws ToolError if the user is not found or the request fails.
+   */
+  async deleteAdminUser({
+    userId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/users/${encodeURIComponent(userId)}`,
+      {
+        method: "DELETE",
+        errorContext: "Delete Admin User"
+      }
+    );
+  }
+  /**
+   * Sends invitation emails to one or more new users (admin).
+   *
+   * @param params - `users`: Array of objects with email and optional name.
+   * @throws ToolError if the request fails.
+   */
+  async inviteUsers({
+    users
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/users/invite-users`,
+      {
+        method: "POST",
+        body: { users },
+        errorContext: "Invite Users"
+      }
+    );
+  }
+  /**
+   * Fully replaces the roles assigned to a user (admin).
+   * All existing roles are removed; the provided list becomes the new set.
+   *
+   * @param params - `userId` (UUID) and `roles` array of role UUIDs.
+   * @throws ToolError if the user is not found or the request fails.
+   */
+  async setUserRoles({
+    userId,
+    roles
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/users/${encodeURIComponent(userId)}/roles`,
+      {
+        method: "PUT",
+        body: { roles },
+        errorContext: "Set User Roles"
+      }
+    );
+  }
+  /**
+   * Grants a single additional role to a user without affecting their existing roles (admin).
+   *
+   * @param params - `userId` and `roleId` UUIDs.
+   * @throws ToolError if the user or role is not found, or the request fails.
+   */
+  async addRoleToUser({
+    userId,
+    roleId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/users/${encodeURIComponent(userId)}/roles/${encodeURIComponent(roleId)}`,
+      { method: "PUT", body: {}, errorContext: "Add Role to User" }
+    );
+  }
+  /**
+   * Revokes a specific role from a user without affecting their other roles (admin).
+   *
+   * @param params - `userId` and `roleId` UUIDs.
+   * @throws ToolError if the user or role is not found, or the request fails.
+   */
+  async removeRoleFromUser({
+    userId,
+    roleId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/users/${encodeURIComponent(userId)}/roles/${encodeURIComponent(roleId)}`,
+      { method: "DELETE", errorContext: "Remove Role from User" }
+    );
+  }
+  /**
+   * Lists all teams in the workspace with optional name filtering and pagination (admin).
+   *
+   * @param params - Optional `q` (name search), `page`, and `size`.
+   * @returns Paginated list of teams.
+   * @throws ToolError if the request fails.
+   */
+  async listAdminTeams(params) {
+    const queryParams = new URLSearchParams();
+    if (params.q) queryParams.set("q", params.q);
+    if (params.page) queryParams.set("page", String(params.page));
+    if (params.size) queryParams.set("size", String(params.size));
+    const qs = queryParams.toString();
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/teams${qs ? `?${qs}` : ""}`,
+      {
+        method: "GET",
+        errorContext: "List Admin Teams"
+      }
+    );
+  }
+  /**
+   * Retrieves the full configuration of a team by UUID (admin).
+   *
+   * @param params - `teamId`: UUID of the team.
+   * @returns Team details including name, members, environments, and pacticipants.
+   * @throws ToolError if the team is not found or the request fails.
+   */
+  async getAdminTeam({
+    teamId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/teams/${encodeURIComponent(teamId)}`,
+      {
+        method: "GET",
+        errorContext: "Get Admin Team"
+      }
+    );
+  }
+  /**
+   * Creates a new team in the workspace (admin).
+   *
+   * @param body - Team name and optional administrators, environments, and pacticipants.
+   * @returns The created team resource.
+   * @throws ToolError if the request fails.
+   */
+  async createAdminTeam({
+    ...body
+  }) {
+    return await this.fetchJson(`${this.baseUrl}/admin/teams`, {
+      method: "POST",
+      body,
+      errorContext: "Create Admin Team"
+    });
+  }
+  /**
+   * Fully replaces a team's configuration (admin).
+   *
+   * @param params - `teamId` (UUID) plus updated name, administrators, environments,
+   *   and pacticipant assignments.
+   * @throws ToolError if the team is not found or the request fails.
+   */
+  async updateAdminTeam({
+    teamId,
+    ...body
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/teams/${encodeURIComponent(teamId)}`,
+      {
+        method: "PUT",
+        body,
+        errorContext: "Update Admin Team"
+      }
+    );
+  }
+  /**
+   * Permanently deletes a team from the workspace (admin). Members are not deleted.
+   *
+   * @param params - `teamId`: UUID of the team to delete.
+   * @throws ToolError if the team is not found or the request fails.
+   */
+  async deleteAdminTeam({
+    teamId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/teams/${encodeURIComponent(teamId)}`,
+      {
+        method: "DELETE",
+        errorContext: "Delete Admin Team"
+      }
+    );
+  }
+  /**
+   * Lists all user members of a specific team (admin).
+   *
+   * @param params - `teamId`: UUID of the team.
+   * @returns List of users in the team.
+   * @throws ToolError if the team is not found or the request fails.
+   */
+  async listTeamUsers({
+    teamId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/teams/${encodeURIComponent(teamId)}/users`,
+      {
+        method: "GET",
+        errorContext: "List Team Users"
+      }
+    );
+  }
+  /**
+   * Verifies whether a specific user is a member of a team (admin).
+   * Returns 404 if the user is not in the team.
+   *
+   * @param params - `teamId` and `userId` UUIDs.
+   * @throws ToolError if not found or the request fails.
+   */
+  async getTeamUser({
+    teamId,
+    userId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/teams/${encodeURIComponent(teamId)}/users/${encodeURIComponent(userId)}`,
+      { method: "GET", errorContext: "Get Team User" }
+    );
+  }
+  /**
+   * Fully replaces the members of a team (admin).
+   * All existing members are removed; the provided UUID list becomes the new membership.
+   *
+   * @param params - `teamId` (UUID) and `uuids` array of user UUIDs.
+   * @throws ToolError if the team is not found or the request fails.
+   */
+  async setTeamUsers({
+    teamId,
+    uuids
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/teams/${encodeURIComponent(teamId)}/users`,
+      {
+        method: "PUT",
+        body: { uuids },
+        errorContext: "Set Team Users"
+      }
+    );
+  }
+  /**
+   * Adds or removes individual users from a team using JSON Patch semantics (admin).
+   *
+   * @param params - `teamId` (UUID) and `operations` array of JSON Patch ops (add/remove).
+   * @throws ToolError if the team is not found or the request fails.
+   */
+  async patchTeamUsers({
+    teamId,
+    operations
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/teams/${encodeURIComponent(teamId)}/users`,
+      {
+        method: "PATCH",
+        body: operations,
+        errorContext: "Patch Team Users"
+      }
+    );
+  }
+  /**
+   * Removes a specific user from a team (admin).
+   *
+   * @param params - `teamId` and `userId` UUIDs.
+   * @throws ToolError if not found or the request fails.
+   */
+  async removeUserFromTeam({
+    teamId,
+    userId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/teams/${encodeURIComponent(teamId)}/users/${encodeURIComponent(userId)}`,
+      { method: "DELETE", errorContext: "Remove User from Team" }
+    );
+  }
+  /**
+   * Lists all roles defined in the workspace (admin).
+   *
+   * @returns All role definitions and their associated permission scopes.
+   * @throws ToolError if the request fails.
+   */
+  async listAdminRoles() {
+    return await this.fetchJson(`${this.baseUrl}/admin/roles`, {
+      method: "GET",
+      errorContext: "List Admin Roles"
+    });
+  }
+  /**
+   * Retrieves a role's name, description, and full permission set by UUID (admin).
+   *
+   * @param params - `roleId`: UUID of the role.
+   * @throws ToolError if the role is not found or the request fails.
+   */
+  async getAdminRole({
+    roleId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/roles/${encodeURIComponent(roleId)}`,
+      {
+        method: "GET",
+        errorContext: "Get Admin Role"
+      }
+    );
+  }
+  /**
+   * Creates a custom role with a tailored set of permission scopes (admin).
+   *
+   * @param body - Role name, optional description, and array of permission scope strings.
+   * @returns The created role resource.
+   * @throws ToolError if the request fails.
+   */
+  async createAdminRole({
+    ...body
+  }) {
+    return await this.fetchJson(`${this.baseUrl}/admin/roles`, {
+      method: "POST",
+      body,
+      errorContext: "Create Admin Role"
+    });
+  }
+  /**
+   * Updates an existing role's name and/or permission set (admin).
+   * Changes affect all users currently assigned the role.
+   *
+   * @param params - `roleId` (UUID) plus updated name, description, and permissions.
+   * @throws ToolError if the role is not found or the request fails.
+   */
+  async updateAdminRole({
+    roleId,
+    ...body
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/roles/${encodeURIComponent(roleId)}`,
+      {
+        method: "PUT",
+        body,
+        errorContext: "Update Admin Role"
+      }
+    );
+  }
+  /**
+   * Permanently deletes a role (admin). Users assigned this role will lose its permissions.
+   *
+   * @param params - `roleId`: UUID of the role to delete.
+   * @throws ToolError if the role is not found or the request fails.
+   */
+  async deleteAdminRole({
+    roleId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/roles/${encodeURIComponent(roleId)}`,
+      {
+        method: "DELETE",
+        errorContext: "Delete Admin Role"
+      }
+    );
+  }
+  /**
+   * Resets all roles to factory defaults (admin).
+   * Custom roles are removed; built-in roles are restored to their original permissions.
+   *
+   * @throws ToolError if the request fails.
+   */
+  async resetAdminRoles() {
+    return await this.fetchJson(`${this.baseUrl}/admin/roles/reset`, {
+      method: "POST",
+      body: {},
+      errorContext: "Reset Admin Roles"
+    });
+  }
+  /**
+   * Lists all permission scopes available to assign to roles (admin).
+   *
+   * @returns All permission scope definitions.
+   * @throws ToolError if the request fails.
+   */
+  async listAdminPermissions() {
+    return await this.fetchJson(`${this.baseUrl}/admin/permissions`, {
+      method: "GET",
+      errorContext: "List Admin Permissions"
+    });
+  }
+  /**
+   * Creates a machine/service account that authenticates via API token (admin).
+   *
+   * @param body - Account name and optional description.
+   * @returns The created system account resource.
+   * @throws ToolError if the request fails.
+   */
+  async createSystemAccount({
+    ...body
+  }) {
+    return await this.fetchJson(`${this.baseUrl}/admin/system-accounts`, {
+      method: "POST",
+      body,
+      errorContext: "Create System Account"
+    });
+  }
+  /**
+   * Retrieves the API tokens associated with a system account (admin).
+   *
+   * @param params - `accountId`: UUID of the system account.
+   * @returns Token list for use in CI/CD pipelines.
+   * @throws ToolError if the account is not found or the request fails.
+   */
+  async getSystemAccountTokens({
+    accountId
+  }) {
+    return await this.fetchJson(
+      `${this.baseUrl}/admin/system-accounts/${encodeURIComponent(accountId)}/tokens`,
+      {
+        method: "GET",
+        errorContext: "Get System Account Tokens"
+      }
+    );
+  }
   /**
    * Registers tools with the provided register function.
    *