@smartbear/mcp 0.26.0 → 0.27.0

package/dist/swagger/client/portal-types.js

@@ -20,7 +20,7 @@ const GetProductSectionsArgsSchema = z.object({
     "Page number for paginated results - specifies which page of results to retrieve (default is 1)"
   ),
   size: z.number().optional().describe(
-    "Number of items per page for pagination - controls how many results are returned per page (default is 20)"
+    "Number of items per page for pagination - controls how many results are returned per page (default is 10)"
   )
 });
 const GetTableOfContentsArgsSchema = z.object({
@@ -176,7 +176,15 @@ const UpdateProductArgsSchema = ProductArgsSchema.extend({
     "Change navigation visibility - true hides from portal landing page menus while keeping the product accessible via direct links"
   )
 });
+const ResolveOrganizationPortalArgsSchema = z.object({
+  organizationId: z.string().uuid().describe(
+    "Swagger organization UUID - the organization to resolve portal details for"
+  )
+});
 const PublishProductArgsSchema = ProductArgsSchema.extend({
+  tableOfContentsId: z.string().optional().describe(
+    "Optional table of contents UUID, or identifier in the format 'portal-subdomain:product-slug:section-slug:table-of-contents-slug'. When provided, publishPortalProduct uses it to resolve the published URL path for the returned preview/live link."
+  ),
   preview: z.boolean().optional().default(false).describe(
     "Whether to publish as preview (true) or live (false). Preview allows testing before going live. Defaults to false (live publication)"
   )
@@ -190,10 +198,10 @@ const UpdateDocumentArgsSchema = z.object({
     "The document content to update (HTML or Markdown based on document type)"
   ),
   type: z.enum(["html", "markdown"]).optional().describe(
-    "Content type - 'html' for HTML content or 'markdown' for Markdown content"
+    "Content type of the document. Note: documents with type 'html' and source 'internal' cannot be edited via API — only 'html' + 'external' and all 'markdown' combinations are supported."
   ),
   source: z.enum(["internal", "external"]).optional().describe(
-    "Source of the document content - 'internal' allows to edit content in both UI and API, 'external' enables editing only via API."
+    "Where the document content is managed. 'internal': editable in both portal UI and API. 'external': editable via API only. Note: 'html' + 'internal' documents cannot be updated via API."
   )
 });
 const DeleteTableOfContentsArgsSchema = z.object({
@@ -204,7 +212,30 @@ const DeleteTableOfContentsArgsSchema = z.object({
     "Flag to include all the nested tables of contents (default: false)"
   )
 });
+const CreateDocumentationPageArgsSchema = z.object({
+  portalId: z.string().describe("Portal UUID or subdomain - unique identifier for the portal"),
+  productId: z.string().uuid().describe("Product UUID - unique identifier for the product"),
+  pageTitle: z.string().describe(
+    "Title of the documentation page - will be displayed in navigation (3-255 characters, used to generate the page slug)"
+  ),
+  pageContent: z.string().optional().describe(
+    "Content of the documentation page. Provide HTML when contentType is 'html', Markdown when contentType is 'markdown'."
+  ),
+  contentType: z.enum(["markdown", "html"]).default("markdown").optional().describe(
+    "Content type of the documentation page. 'markdown' works with both 'internal' and 'external' source. 'html' only works with 'external' source — html + internal is not supported by the API and will return an error."
+  ),
+  source: z.enum(["internal", "external"]).default("internal").optional().describe(
+    "Where the document content is managed. 'internal': editable in both the portal UI and via API. 'external': editable via API only, not in the portal UI. Constraint: 'html' content type only supports 'external' source."
+  ),
+  order: z.number().optional().default(0).describe(
+    "Order position of the documentation page within its parent section or item"
+  ),
+  parentId: z.string().nullable().optional().default(null).describe(
+    "Parent table of contents item ID - null for top-level pages, or ID of parent item for nested structure"
+  )
+});
 export {
+  CreateDocumentationPageArgsSchema,
   CreatePortalArgsSchema,
   CreateProductArgsSchema,
   CreateTableOfContentsArgsSchema,
@@ -215,6 +246,7 @@ export {
   PortalArgsSchema,
   ProductArgsSchema,
   PublishProductArgsSchema,
+  ResolveOrganizationPortalArgsSchema,
   UpdateDocumentArgsSchema,
   UpdatePortalArgsSchema,
   UpdateProductArgsSchema

package/dist/swagger/client/portal-utils.js

@@ -0,0 +1,50 @@
+import { ToolError } from "../../common/tools.js";
+const SUBDOMAIN_MIN_LENGTH = 3;
+const SUBDOMAIN_MAX_LENGTH = 20;
+const PORTAL_NAME_MIN_LENGTH = 3;
+const PORTAL_NAME_MAX_LENGTH = 40;
+function slugify(value, maxLength) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, maxLength).replace(/-+$/, "");
+}
+function buildSubdomainCandidate(organizationId, organizationName) {
+  const fallback = `portal-${organizationId.toLowerCase().replace(/[^a-z0-9]/g, "").slice(0, 8)}`;
+  if (!organizationName) {
+    return fallback;
+  }
+  const sanitized = slugify(organizationName, SUBDOMAIN_MAX_LENGTH);
+  return sanitized.length >= SUBDOMAIN_MIN_LENGTH ? sanitized : fallback;
+}
+function buildSuffixedSubdomain(baseSubdomain, organizationId) {
+  const idSuffix = organizationId.toLowerCase().replace(/[^a-z0-9]/g, "").slice(0, 4);
+  const trimmedBase = baseSubdomain.slice(0, SUBDOMAIN_MAX_LENGTH - idSuffix.length - 1).replace(/-+$/, "");
+  return `${trimmedBase}-${idSuffix}`;
+}
+function buildPortalName(organizationName) {
+  const trimmed = organizationName?.trim();
+  if (!trimmed || trimmed.length < PORTAL_NAME_MIN_LENGTH) {
+    return void 0;
+  }
+  return trimmed.slice(0, PORTAL_NAME_MAX_LENGTH);
+}
+function isConflictError(error) {
+  return error instanceof ToolError && (error.metadata?.get("status") === 409 || error.message.startsWith("HTTP 409"));
+}
+function isOrganizationPortalConflict(error) {
+  if (!(error instanceof ToolError)) {
+    return false;
+  }
+  const message = error.message.toLowerCase();
+  return message.includes("already exists") && message.includes("organization");
+}
+export {
+  PORTAL_NAME_MAX_LENGTH,
+  PORTAL_NAME_MIN_LENGTH,
+  SUBDOMAIN_MAX_LENGTH,
+  SUBDOMAIN_MIN_LENGTH,
+  buildPortalName,
+  buildSubdomainCandidate,
+  buildSuffixedSubdomain,
+  isConflictError,
+  isOrganizationPortalConflict,
+  slugify
+};

package/dist/swagger/client/registry-types.js

@@ -38,6 +38,13 @@ const ScanStandardizationParamsSchema = z.object({
     "API definition content (OpenAPI/AsyncAPI specification in JSON or YAML format) to scan for standardization errors"
   )
 });
+const ScanApiStandardizationFromRegistryParamsSchema = z.object({
+  orgName: z.string().describe(
+    "The organization name that owns the API and provides the standardization rules (case-sensitive)"
+  ),
+  apiName: z.string().describe("API name (case-sensitive)"),
+  version: z.string().describe("Version identifier")
+});
 const CreateApiFromPromptParamsSchema = z.object({
   owner: z.string().describe("API owner (organization or user, case-sensitive)"),
   apiName: z.string().describe("API name"),
@@ -67,6 +74,7 @@ export {
   ApiSearchParamsSchema,
   CreateApiFromPromptParamsSchema,
   CreateApiParamsSchema,
+  ScanApiStandardizationFromRegistryParamsSchema,
   ScanStandardizationParamsSchema,
   StandardizeApiParamsSchema
 };

package/dist/swagger/client/tools.js

@@ -1,6 +1,6 @@
 import { FUNCTIONAL_TESTING_TOOLS } from "./functional-testing-tools.js";
-import { CreatePortalArgsSchema, PortalArgsSchema, UpdatePortalArgsSchema, CreateProductArgsSchema, ProductArgsSchema, UpdateProductArgsSchema, PublishProductArgsSchema, GetProductSectionsArgsSchema, CreateTableOfContentsArgsSchema, GetTableOfContentsArgsSchema, DeleteTableOfContentsArgsSchema, GetDocumentArgsSchema, UpdateDocumentArgsSchema } from "./portal-types.js";
-import { ApiSearchParamsSchema, ApiDefinitionParamsSchema, CreateApiParamsSchema, ScanStandardizationParamsSchema, CreateApiFromPromptParamsSchema, StandardizeApiParamsSchema } from "./registry-types.js";
+import { CreatePortalArgsSchema, PortalArgsSchema, UpdatePortalArgsSchema, ResolveOrganizationPortalArgsSchema, CreateProductArgsSchema, ProductArgsSchema, UpdateProductArgsSchema, PublishProductArgsSchema, GetProductSectionsArgsSchema, CreateTableOfContentsArgsSchema, GetTableOfContentsArgsSchema, DeleteTableOfContentsArgsSchema, CreateDocumentationPageArgsSchema, GetDocumentArgsSchema, UpdateDocumentArgsSchema } from "./portal-types.js";
+import { ApiSearchParamsSchema, ApiDefinitionParamsSchema, CreateApiParamsSchema, ScanStandardizationParamsSchema, ScanApiStandardizationFromRegistryParamsSchema, CreateApiFromPromptParamsSchema, StandardizeApiParamsSchema } from "./registry-types.js";
 import { OrganizationsQuerySchema } from "./user-management-types.js";
 const TOOLS = [
   {
@@ -30,6 +30,13 @@ const TOOLS = [
     inputSchema: UpdatePortalArgsSchema,
     handler: "updatePortal"
   },
+  {
+    title: "Resolve Organization Portal",
+    toolset: "Portals",
+    summary: "Resolve portal details for a Swagger organization in a single step. Given an organization UUID, returns the portal ID, subdomain, customDomain (when configured), and the list of products (with productId, productSlug, and productName) for the organization's portal. If the organization has no portal yet, a new portal is created automatically. Use this tool to obtain all portal context needed for subsequent portal and product operations.",
+    inputSchema: ResolveOrganizationPortalArgsSchema,
+    handler: "resolveOrganizationPortal"
+  },
   {
     title: "List Portal Products",
     toolset: "Products",
@@ -69,7 +76,7 @@ const TOOLS = [
   {
     title: "Publish Portal Product",
     toolset: "Products",
-    summary: "Publish a product's content to make it live or as preview. This endpoint publishes the current content of a product, making it visible to portal visitors. Use preview mode to test before going live.",
+    summary: "Publish a product's content to make it live or as preview. This endpoint publishes the current content of a product, making it visible to portal visitors. Use preview mode to test before going live. Optionally provide `tableOfContentsId` to get a page-specific URL. Returns publication status, a live or preview URL (null if URL building fails), product and portal metadata, and an optional `warning` when metadata/URL building failed — a warning does NOT mean the publish failed.",
     inputSchema: PublishProductArgsSchema,
     handler: "publishPortalProduct"
   },
@@ -102,6 +109,13 @@ const TOOLS = [
     handler: "deleteTableOfContents"
   },
   // Document management tools
+  {
+    title: "Create Documentation Page",
+    toolset: "Documents",
+    summary: "Create a documentation page in a portal product in a single tool call. Supports markdown and html content types. Returns the page location details (productId, sectionId, slug) and a draftUrl to edit it in the portal.",
+    inputSchema: CreateDocumentationPageArgsSchema,
+    handler: "createDocumentationPage"
+  },
   {
     title: "Get Document",
     toolset: "Documents",
@@ -149,10 +163,17 @@ const TOOLS = [
   {
     title: "Scan API Standardization",
     toolset: "Registry API",
-    summary: "Run a standardization scan against an API definition using the organization's governance and standardization rules. Accepts a YAML or JSON OpenAPI/AsyncAPI definition and returns a list of standardization errors and validation issues. Use this tool when users ask to validate, scan, or check API governance or standardization.",
+    summary: "Run a standardization scan against an API definition using the organization's governance and standardization rules. Accepts a raw YAML or JSON OpenAPI/AsyncAPI definition and returns a list of validation errors, the total issue count, and counts grouped by severity. Use this tool when the user provides the API definition content directly (as raw YAML or JSON) and asks to validate, scan, or check the governance or standardization of the API.",
     inputSchema: ScanStandardizationParamsSchema,
     handler: "scanStandardization"
   },
+  {
+    title: "Scan API Standardization from Registry",
+    toolset: "Registry API",
+    summary: "Run a standardization scan on an API that already exists in SwaggerHub Registry, identified by organization name, API name, and version. Fetches the API definition from the registry internally and scans it against the organization's governance and standardization rules. Returns a list of validation errors, total issue count, counts grouped by severity, and a SwaggerHub UI URL for the scanned API. Use this tool when the user identifies the API by org name, API name, and version and asks to validate, scan, or check the governance or standardization of an existing API.",
+    inputSchema: ScanApiStandardizationFromRegistryParamsSchema,
+    handler: "scanApiStandardizationFromRegistry"
+  },
   {
     title: "Create API from Prompt",
     toolset: "Registry API",

package/dist/swagger/client/utils.js

@@ -0,0 +1,37 @@
+function normalizeSlug(value) {
+  const slug = value.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  if (slug.length < 3) {
+    throw new Error(`Slug "${slug}" is too short (minimum 3 characters).`);
+  }
+  return slug;
+}
+function findTableOfContentsItem(items, targetId) {
+  for (const item of items) {
+    if (item.id === targetId) {
+      return item;
+    }
+    const nestedMatch = findTableOfContentsItem(item.children ?? [], targetId);
+    if (nestedMatch) {
+      return nestedMatch;
+    }
+  }
+  return null;
+}
+function buildPortalLiveUrl(config, portal, productSlug, section, tocItem, preview = false) {
+  const host = portal?.customDomain ?? portal?.subdomain;
+  const portalUiDomain = portal?.customDomain ? "" : config.getPortalUiDomainSuffix();
+  if (!host || !productSlug) {
+    return "";
+  }
+  const baseUrl = `https://${host}${portalUiDomain}/${productSlug}`;
+  const previewSuffix = preview ? "?preview=product" : "";
+  if (section?.slug && tocItem?.slug) {
+    return `${baseUrl}/${section.slug}/${tocItem.slug}${previewSuffix}`;
+  }
+  return `${baseUrl}${previewSuffix}`;
+}
+export {
+  buildPortalLiveUrl,
+  findTableOfContentsItem,
+  normalizeSlug
+};

package/dist/swagger/client.js

@@ -17,6 +17,9 @@ const ConfigurationSchema = z.object({
   ui_base_path: z.string().optional().describe("Base URL for the SwaggerHub UI (optional)"),
   functional_testing_api_token: z.string().optional().describe(
     "Swagger Functional Testing API token. Leave empty to disable Functional Testing tools."
+  ),
+  functional_testing_base_path: z.string().optional().describe(
+    "Base URL for Swagger Functional Testing API requests (optional)"
   )
 });
 class SwaggerClient {
@@ -29,7 +32,8 @@ class SwaggerClient {
   configPrefix = "Swagger";
   config = ConfigurationSchema;
   async configure(_server, config, _cache) {
-    if (config.api_key) {
+    const hasSwaggerAuth = !!config.api_key || !!getRequestHeader("Swagger-Api-Key") || !!getRequestHeader("Authorization");
+    if (hasSwaggerAuth) {
       this._apiKey = config.api_key;
       this.api = new SwaggerAPI(
         new SwaggerConfiguration({
@@ -45,7 +49,8 @@ class SwaggerClient {
       this._ftApiToken = config.functional_testing_api_token;
       this.ftApi = new FunctionalTestingAPI(
         () => this.getFtAuthToken(),
-        USER_AGENT
+        USER_AGENT,
+        config.functional_testing_base_path
       );
     }
   }
@@ -89,6 +94,9 @@ class SwaggerClient {
     const { portalId, ...body } = args;
     return this.getApi().updatePortal(portalId, body);
   }
+  async resolveOrganizationPortal(args) {
+    return this.getApi().resolveOrganizationPortal(args);
+  }
   async getPortalProducts(args) {
     return this.getApi().getPortalProducts(args.portalId);
   }
@@ -107,8 +115,12 @@ class SwaggerClient {
     return this.getApi().updatePortalProduct(productId, body);
   }
   async publishPortalProduct(args) {
-    const { productId, preview } = args;
-    return this.getApi().publishPortalProduct(productId, preview);
+    const { productId, preview, tableOfContentsId } = args;
+    return this.getApi().publishPortalProduct(
+      productId,
+      preview,
+      tableOfContentsId ?? null
+    );
   }
   async getPortalProductSections(args) {
     const { productId, ...params } = args;
@@ -130,6 +142,9 @@ class SwaggerClient {
   async deleteTableOfContents(args) {
     return this.getApi().deleteTableOfContents(args);
   }
+  async createDocumentationPage(args) {
+    return this.getApi().createDocumentationPage(args);
+  }
   // Registry API methods for SwaggerHub Design functionality
   async searchApis(args = {}) {
     return this.getApi().searchApis(args);
@@ -150,14 +165,31 @@ class SwaggerClient {
   async scanStandardization(args) {
     return this.getApi().scanStandardization(args);
   }
+  async scanApiStandardizationFromRegistry(args) {
+    return this.getApi().scanApiStandardizationFromRegistry(args);
+  }
   async standardizeApi(args) {
     return this.getApi().standardizeApi(args);
   }
+  // Functional Testing methods
   async listFunctionalTestingTests() {
+    return this.withFunctionalTesting((ftApi) => ftApi.listTests());
+  }
+  async runFunctionalTestingTest(args) {
+    return this.withFunctionalTesting((ftApi) => ftApi.runTest(args));
+  }
+  async getFunctionalTestingExecution(args) {
+    return this.withFunctionalTesting((ftApi) => ftApi.getTestExecution(args));
+  }
+  /**
+   * Perform an operation with the Functional Testing API.
+   * Throws a ToolError if Functional Testing is not configured
+   */
+  async withFunctionalTesting(fn) {
     if (!this.ftApi) {
       throw new ToolError("Functional Testing API not configured");
     }
-    return this.ftApi.listTests();
+    return fn(this.ftApi);
   }
   async registerTools(register, _getInput) {
     TOOLS.forEach((tool) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartbear/mcp",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "MCP server for interacting SmartBear Products",
   "keywords": [
     "smartbear",