@smartbear/mcp 0.26.1 → 0.27.0

package/dist/swagger/client/api.js

@@ -1,4 +1,6 @@
 import { ToolError } from "../../common/tools.js";
+import { buildSubdomainCandidate, buildSuffixedSubdomain, buildPortalName, isConflictError, isOrganizationPortalConflict } from "./portal-utils.js";
+import { findTableOfContentsItem, buildPortalLiveUrl, normalizeSlug } from "./utils.js";
 const SWAGGER_URL_REGEX = /\/(apis|domains|templates)\/([^/]+)\/([^/]+)\/([^/]+)/;
 function hasId(value) {
   return typeof value === "object" && value !== null && "id" in value;
@@ -9,6 +11,9 @@ function hasMessage(value) {
 function hasErrorsFound(value) {
   return typeof value === "object" && value !== null && "errorsFound" in value;
 }
+function isStandardizationResult(value) {
+  return typeof value === "object" && value !== null && "validation" in value && Array.isArray(value.validation);
+}
 class SwaggerAPI {
   config;
   userAgent;
@@ -77,7 +82,9 @@ class SwaggerAPI {
         errorBody.detail ?? errorBody.message ?? ""
       ) || response.statusText;
       throw new ToolError(
-        `HTTP ${response.status}${detail ? `: ${detail}` : ""}`
+        `HTTP ${response.status}${detail ? `: ${detail}` : ""}`,
+        void 0,
+        /* @__PURE__ */ new Map([["status", response.status]])
       );
     }
     return this.parseResponse(
@@ -160,6 +167,158 @@ class SwaggerAPI {
     );
     return this.handleResponse(response);
   }
+  /**
+   * Resolve portal details and product list for a Swagger organization.
+   * Finds the portal mapped to the organization, creating one if it does not
+   * exist yet, and returns the portal ID, subdomain, and products.
+   * @param params Parameters containing the organization UUID
+   * @returns Portal details and product list for the organization
+   */
+  async resolveOrganizationPortal(params) {
+    const { organizationId } = params;
+    let portal = await this.findPortalByOrganizationId(organizationId);
+    let portalCreated = false;
+    if (!portal) {
+      const created = await this.createPortalForOrganization(organizationId);
+      portal = created.portal;
+      portalCreated = created.created;
+    }
+    const products = this.extractListItems(
+      await this.getPortalProducts(portal.id)
+    );
+    const customDomain = typeof portal.customDomain === "string" && portal.customDomain.length > 0 ? portal.customDomain : void 0;
+    return {
+      organizationId,
+      portalId: portal.id,
+      subdomain: typeof portal.subdomain === "string" ? portal.subdomain : "",
+      ...customDomain ? { customDomain } : {},
+      portalCreated,
+      products: products.map(
+        (product) => ({
+          productId: product.id,
+          productSlug: typeof product.slug === "string" ? product.slug : "",
+          productName: product.name
+        })
+      )
+    };
+  }
+  /**
+   * Extract item arrays from list responses that may be returned either as a
+   * plain array or as a paginated object with an 'items' property.
+   */
+  extractListItems(result) {
+    if (Array.isArray(result)) {
+      return result;
+    }
+    if (typeof result === "object" && result !== null && Array.isArray(result.items)) {
+      return result.items;
+    }
+    return [];
+  }
+  /**
+   * Find the portal mapped to a Swagger organization. The Portal API does not
+   * support filtering by organization, so pages are scanned client-side.
+   *
+   * Permission/role problems surface as thrown errors: handleResponse throws on
+   * any non-2xx status (e.g. 401/403), so a lack of access never masquerades as
+   * an empty result. An empty list therefore means the user can see portals but
+   * none is mapped to this organization, in which case a new portal is created.
+   */
+  async findPortalByOrganizationId(organizationId) {
+    const size = 100;
+    const maxPages = 20;
+    const target = organizationId.toLowerCase();
+    for (let page = 1; page <= maxPages; page++) {
+      const response = await fetch(
+        `${this.config.portalBasePath}/portals?page=${page}&size=${size}`,
+        {
+          method: "GET",
+          headers: this.headers
+        }
+      );
+      const result = await this.handleResponse(response, []);
+      const portals = this.extractListItems(result);
+      const match = portals.find(
+        (portal) => typeof portal.swaggerHubOrganizationId === "string" && portal.swaggerHubOrganizationId.toLowerCase() === target
+      );
+      if (match) {
+        return match;
+      }
+      if (portals.length < size) {
+        return void 0;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Find an organization by UUID using the User Management API, which only
+   * supports listing the user's organizations (no lookup by ID).
+   */
+  async findOrganizationById(organizationId) {
+    const pageSize = 100;
+    const maxPages = 10;
+    const target = organizationId.toLowerCase();
+    for (let page = 0; page < maxPages; page++) {
+      const result = await this.getOrganizations({ page, pageSize });
+      const items = result.items ?? [];
+      const match = items.find((org) => org.id?.toLowerCase() === target);
+      if (match) {
+        return match;
+      }
+      if (items.length < pageSize) {
+        return void 0;
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Create a portal for an organization that has none yet. The subdomain is
+   * derived from the organization name; on a subdomain conflict a candidate
+   * suffixed with part of the organization UUID is retried.
+   */
+  async createPortalForOrganization(organizationId) {
+    const organization = await this.findOrganizationById(organizationId);
+    const baseSubdomain = buildSubdomainCandidate(
+      organizationId,
+      organization?.name
+    );
+    const candidates = [
+      baseSubdomain,
+      buildSuffixedSubdomain(baseSubdomain, organizationId)
+    ];
+    const portalName = buildPortalName(organization?.name);
+    let lastError;
+    for (const subdomain of candidates) {
+      try {
+        const created = await this.createPortal({
+          subdomain,
+          swaggerHubOrganizationId: organizationId,
+          ...portalName ? { name: portalName } : {}
+        });
+        return {
+          portal: { ...created, subdomain: created.subdomain ?? subdomain },
+          created: true
+        };
+      } catch (error) {
+        if (!isConflictError(error)) {
+          throw error;
+        }
+        lastError = error;
+        const existing = await this.findPortalByOrganizationId(organizationId);
+        if (existing) {
+          return { portal: existing, created: false };
+        }
+        if (isOrganizationPortalConflict(error)) {
+          throw new ToolError(
+            `Access denied: a portal already exists for organization ${organizationId}, but you do not have permission to view it. A portal owner or designer role is required.`
+          );
+        }
+      }
+    }
+    throw lastError instanceof Error ? lastError : new ToolError(
+      `Failed to create portal for organization ${organizationId}`
+    );
+  }
   async getPortalProducts(portalId) {
     const response = await fetch(
       `${this.config.portalBasePath}/portals/${portalId}/products`,
@@ -226,7 +385,108 @@ class SwaggerAPI {
       success: true
     });
   }
-  async publishPortalProduct(productId, preview = false) {
+  /**
+   * Prepare publication metadata and URL for a portal product and page.
+   * Fetches product, portal, and section details step-by-step, gracefully handling failures.
+   * Product and portal details are essential for URL generation; sections are optional.
+   * @param productId - ID of the product to publish
+   * @param preview - Whether this is a preview publish
+   * @param tableOfContentsId - Optional table of contents UUID or identifier
+   * @returns Publication metadata with optional fields based on what could be fetched
+   */
+  async preparePublicationMetadata(productId, preview, tableOfContentsId) {
+    let productDetails = null;
+    try {
+      productDetails = await this.getPortalProduct(productId);
+    } catch (error) {
+      console.warn("Failed to fetch product details:", error);
+      return {
+        publicationUrl: null,
+        warning: {
+          step: "product",
+          message: `Product published ${preview ? "in preview mode" : "in live mode"} successfully, but failed to fetch product details for URL generation`
+        }
+      };
+    }
+    let portalDetails = null;
+    if (productDetails?.portalId) {
+      try {
+        portalDetails = await this.getPortal(String(productDetails.portalId));
+      } catch (error) {
+        console.warn("Failed to fetch portal details:", error);
+      }
+    }
+    if (!portalDetails) {
+      return {
+        publicationUrl: null,
+        product: productDetails ? {
+          id: productDetails.id,
+          name: productDetails.name,
+          slug: productDetails.slug
+        } : void 0,
+        warning: {
+          step: "portal",
+          message: `Product published ${preview ? "in preview mode" : "in live mode"} successfully, but failed to fetch portal details for URL generation`
+        }
+      };
+    }
+    let sections = null;
+    try {
+      sections = await this.getPortalProductSections(productId, {
+        embed: ["tableOfContents", "tableOfContents.swaggerhubApi"]
+      });
+    } catch (error) {
+      console.warn("Failed to fetch sections:", error);
+    }
+    const targetSection = sections?.items[0] ?? null;
+    const targetTocItem = tableOfContentsId && targetSection ? findTableOfContentsItem(
+      targetSection.tableOfContents ?? [],
+      tableOfContentsId
+    ) : null;
+    const publicationUrl = buildPortalLiveUrl(
+      this.config,
+      portalDetails,
+      productDetails.slug,
+      targetSection,
+      targetTocItem,
+      preview
+    );
+    return {
+      publicationUrl,
+      product: {
+        id: productDetails.id,
+        name: productDetails.name,
+        slug: productDetails.slug
+      },
+      portal: {
+        id: portalDetails.id,
+        name: portalDetails.name,
+        subdomain: portalDetails.subdomain,
+        customDomain: portalDetails.customDomain
+      },
+      ...targetTocItem ? {
+        tableOfContentsItem: {
+          id: targetTocItem.id,
+          slug: targetTocItem.slug,
+          title: targetTocItem.title,
+          order: targetTocItem.order,
+          parentId: targetTocItem.parentId
+        }
+      } : {}
+    };
+  }
+  /**
+   * Publish a portal product and generate a published URL with environment-specific domain.
+   * The publish operation always succeeds if the API call succeeds. URL generation is done separately and may fail gracefully.
+   * Returns `liveUrl` for live publishes and `previewUrl` for preview publishes (null if URL building fails).
+   * When metadata/URL building fails, response includes `success: true` (publish succeeded), `liveUrl/previewUrl: null`,
+   * and a `warning` object explaining which step failed (product/portal fetch or URL building).
+   * @param productId - ID of the product to publish
+   * @param preview - Whether to publish in preview mode (default: false)
+   * @param tableOfContentsId - Optional table of contents UUID, or identifier in the format 'portal-subdomain:product-slug:section-slug:table-of-contents-slug'
+   * @returns Complete publish response with `success: true`, optional URL/metadata, and optional warning details
+   */
+  async publishPortalProduct(productId, preview = false, tableOfContentsId = null) {
     const response = await fetch(
       `${this.config.portalBasePath}/products/${productId}/published-content?preview=${preview}`,
       {
@@ -234,9 +494,46 @@ class SwaggerAPI {
         headers: this.headers
       }
     );
-    return this.handleResponse(response, {
+    const result = await this.handleResponse(response, {
       success: true
     });
+    try {
+      const metadata = await this.preparePublicationMetadata(
+        productId,
+        preview,
+        tableOfContentsId
+      );
+      return {
+        ...result,
+        preview,
+        [preview ? "previewUrl" : "liveUrl"]: metadata.publicationUrl,
+        ...metadata.product ? { product: metadata.product } : {},
+        ...metadata.portal ? { portal: metadata.portal } : {},
+        ...metadata.tableOfContentsItem ? { tableOfContentsItem: metadata.tableOfContentsItem } : {},
+        ...metadata.warning ? {
+          warning: {
+            code: "METADATA_FETCH_FAILED",
+            step: metadata.warning.step,
+            message: metadata.warning.message
+          }
+        } : {}
+      };
+    } catch (error) {
+      console.warn(
+        "Failed to build publication metadata — returning publish success with empty URL:",
+        error
+      );
+      return {
+        ...result,
+        preview,
+        [preview ? "previewUrl" : "liveUrl"]: null,
+        warning: {
+          code: "METADATA_BUILD_FAILED",
+          step: "url_build",
+          message: `Product published ${preview ? "in preview mode" : "in live mode"} successfully, but failed to build publication URL`
+        }
+      };
+    }
   }
   async getPortalProductSections(productId, params) {
     const queryParameters = new URLSearchParams();
@@ -256,9 +553,18 @@ class SwaggerAPI {
       method: "GET",
       headers: this.headers
     });
+    const defaultResponse = {
+      page: {
+        number: 0,
+        size: 0,
+        totalElements: 0,
+        totalPages: 0
+      },
+      items: []
+    };
     const result = await this.handleResponse(
       response,
-      []
+      defaultResponse
     );
     return result;
   }
@@ -315,7 +621,10 @@ class SwaggerAPI {
       );
     }
     const result = await response.json();
-    return result.items;
+    if (Array.isArray(result)) {
+      return result;
+    }
+    return result.items ?? [];
   }
   /**
    * Get document content and metadata
@@ -359,6 +668,73 @@ class SwaggerAPI {
     }
     return { success: true };
   }
+  async createDocumentationPage(args) {
+    const {
+      portalId,
+      productId,
+      pageTitle,
+      pageContent,
+      contentType = "markdown",
+      source = "internal",
+      order = 0,
+      parentId = null
+    } = args;
+    if (contentType === "html" && source === "internal" && pageContent !== void 0) {
+      throw new ToolError(
+        "Cannot create an html + internal page with content via API. Use 'external' source for html, or 'markdown' with 'internal' source."
+      );
+    }
+    const portal = await this.getPortal(portalId);
+    const product = await this.getPortalProduct(productId);
+    const productSlug = product?.slug;
+    const sections = await this.getPortalProductSections(productId, {});
+    if (sections.items.length === 0) {
+      throw new ToolError(
+        `Product ${productId} has no sections. Create a section first before adding documentation pages.`
+      );
+    }
+    const section = sections.items[0];
+    const pageSlug = normalizeSlug(pageTitle);
+    const normalizedTitle = pageTitle.slice(0, 255);
+    const tocItem = await this.createTableOfContents(section.id, {
+      type: "new",
+      title: normalizedTitle,
+      slug: pageSlug,
+      order,
+      parentId,
+      content: {
+        type: contentType,
+        source
+      }
+    });
+    const documentId = tocItem.documentId;
+    if (pageContent !== void 0) {
+      await this.updateDocument({
+        documentId,
+        content: pageContent,
+        type: contentType
+      });
+    }
+    const host = portal?.customDomain ?? portal?.subdomain;
+    const portalUiDomain = portal?.customDomain ? "" : this.config.getPortalUiDomainSuffix();
+    const draftUrl = `https://${host}${portalUiDomain}/sp-admin/products/${productSlug}/edit/content/${tocItem.id}`;
+    return {
+      productId,
+      sectionId: section.id,
+      sectionSlug: section.slug,
+      pageDetails: {
+        tableOfContentsId: tocItem.id,
+        slug: pageSlug,
+        title: normalizedTitle,
+        content: {
+          type: contentType,
+          source,
+          documentId
+        }
+      },
+      draftUrl
+    };
+  }
   /**
    * Delete table of contents entry
    * @param args - Parameters for deleting table of contents entry
@@ -457,9 +833,10 @@ class SwaggerAPI {
   /**
    * Get API definition from SwaggerHub Registry
    * @param params Parameters including owner, api name, version, and options
+   * @param options Optional transport options
    * @returns API definition (OpenAPI/Swagger specification)
    */
-  async getApiDefinition(params) {
+  async getApiDefinition(params, options) {
     const searchParams = new URLSearchParams();
     if (params.resolved !== void 0)
       searchParams.append("resolved", params.resolved.toString());
@@ -468,7 +845,7 @@ class SwaggerAPI {
     const url = `${this.config.registryBasePath}/apis/${encodeURIComponent(params.owner)}/${encodeURIComponent(params.api)}/${encodeURIComponent(params.version)}${searchParams.toString() ? `?${searchParams.toString()}` : ""}`;
     const response = await fetch(url, {
       method: "GET",
-      headers: this.headers
+      headers: options?.accept ? { ...this.headers, Accept: options.accept } : this.headers
     });
     if (!response.ok) {
       throw new ToolError(
@@ -628,7 +1005,43 @@ class SwaggerAPI {
         `SwaggerHub Registry API scanStandardization failed - status: ${response.status} ${response.statusText}${errorText ? ` - ${errorText}` : ""}. URL: ${url}`
       );
     }
-    return await this.handleResponse(response);
+    const results = await this.handleResponse(response);
+    if (isStandardizationResult(results)) {
+      const errors = results.validation ?? [];
+      const countsBySeverity = {};
+      for (const error of errors) {
+        const severity = error.severity ?? "Unknown";
+        countsBySeverity[severity] = (countsBySeverity[severity] ?? 0) + 1;
+      }
+      return { ...results, count: errors.length, countsBySeverity };
+    }
+    return results;
+  }
+  /**
+   * Fetch an API definition from the registry and run a standardization scan
+   * @param params Parameters including organization name, API name, and version
+   * @returns Scan results with total count and counts grouped by severity
+   */
+  async scanApiStandardizationFromRegistry(params) {
+    const definition = await this.getApiDefinition(
+      {
+        owner: params.orgName,
+        api: params.apiName,
+        version: params.version
+      },
+      { accept: "text/plain" }
+    );
+    const results = await this.scanStandardization({
+      orgName: params.orgName,
+      definition
+    });
+    if (isStandardizationResult(results)) {
+      return {
+        ...results,
+        url: `${this.config.uiBasePath}/apis/${params.orgName}/${params.apiName}/${params.version}`
+      };
+    }
+    return results;
   }
   /**
    * Standardize and fix an API definition using AI

package/dist/swagger/client/configuration.js

@@ -34,6 +34,15 @@ class SwaggerConfiguration {
       "User-Agent": userAgent
     };
   }
+  getPortalUiDomainSuffix() {
+    const match = this.portalBasePath.match(
+      /https?:\/\/api(\..*\.portal\.swaggerhub\.com)/
+    );
+    if (match?.[1]) {
+      return match[1];
+    }
+    return ".portal.swaggerhub.com";
+  }
 }
 export {
   SwaggerConfiguration

package/dist/swagger/client/functional-testing-api.js

@@ -2,10 +2,12 @@ import { ToolError } from "../../common/tools.js";
 const API_HOSTNAME = "api.reflect.run";
 const FUNCTIONAL_TESTING_API_KEY_HEADER = "X-API-KEY";
 class FunctionalTestingAPI {
-  constructor(getToken, userAgent) {
+  constructor(getToken, userAgent, baseUrl) {
     this.getToken = getToken;
     this.userAgent = userAgent;
+    this.baseUrl = baseUrl || `https://${API_HOSTNAME}/v1`;
   }
+  baseUrl;
   getFtHeaders() {
     const token = this.getToken();
     if (!token) {
@@ -18,7 +20,7 @@ class FunctionalTestingAPI {
     };
   }
   async listTests() {
-    const response = await fetch(`https://${API_HOSTNAME}/v1/tests`, {
+    const response = await fetch(`${this.baseUrl}/tests`, {
       method: "GET",
       headers: this.getFtHeaders()
     });
@@ -29,6 +31,40 @@ class FunctionalTestingAPI {
     }
     return response.json();
   }
+  async runTest(args) {
+    if (!args.testId) throw new ToolError("testId argument is required");
+    const response = await fetch(
+      `${this.baseUrl}/tests/${args.testId}/executions`,
+      {
+        method: "POST",
+        headers: this.getFtHeaders()
+      }
+    );
+    if (!response.ok) {
+      throw new ToolError(
+        `Failed to run test: ${response.status} ${response.statusText}`
+      );
+    }
+    return response.json();
+  }
+  async getTestExecution(args) {
+    if (!args.executionId) {
+      throw new ToolError("executionId argument is required");
+    }
+    const response = await fetch(
+      `${this.baseUrl}/executions/${args.executionId}`,
+      {
+        method: "GET",
+        headers: this.getFtHeaders()
+      }
+    );
+    if (!response.ok) {
+      throw new ToolError(
+        `Failed to get test status: ${response.status} ${response.statusText}`
+      );
+    }
+    return response.json();
+  }
 }
 export {
   FUNCTIONAL_TESTING_API_KEY_HEADER,

package/dist/swagger/client/functional-testing-tools.js

@@ -1,9 +1,27 @@
+import { RunFunctionalTestingTestParamsSchema, GetFunctionalTestingExecutionTestSchema } from "./functional-testing-types.js";
 const FUNCTIONAL_TESTING_TOOLS = [
   {
     title: "List Tests",
     toolset: "Functional Testing",
     summary: "Lists all API tests available in your Swagger Functional Testing account. Use this tool when you need to discover available tests before running them or checking their status. Do not use this tool to retrieve test execution results or history.",
     handler: "listFunctionalTestingTests"
+  },
+  {
+    title: "Run Test",
+    toolset: "Functional Testing",
+    summary: "Runs a specific API test in your Swagger Functional Testing workspace. The execution is asynchronous — it returns an executionId, not the result directly. Use swagger_get_test_status with that executionId to track progress and retrieve the final result.",
+    inputSchema: RunFunctionalTestingTestParamsSchema,
+    handler: "runFunctionalTestingTest",
+    idempotent: false,
+    readOnly: false
+  },
+  {
+    title: "Get Test Status",
+    toolset: "Functional Testing",
+    summary: "Get the status of a Swagger Functional Testing test execution. It returns information about the execution such as its status (running, passed or failed), run time, as well as the break down of the status of each test step.",
+    inputSchema: GetFunctionalTestingExecutionTestSchema,
+    handler: "getFunctionalTestingExecution",
+    idempotent: false
   }
 ];
 export {

package/dist/swagger/client/functional-testing-types.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+const RunFunctionalTestingTestParamsSchema = z.object({
+  testId: z.string().describe("ID of the Functional Testing test to run").trim().min(1)
+});
+const GetFunctionalTestingExecutionTestSchema = z.object({
+  executionId: z.string().describe("ID of the Functional Testing execution").trim().min(1)
+});
+export {
+  GetFunctionalTestingExecutionTestSchema,
+  RunFunctionalTestingTestParamsSchema
+};