@smartbear/mcp 0.6.0 → 0.8.0

package/dist/api-hub/client/registry-types.js

@@ -0,0 +1,69 @@
+import { z } from "zod";
+// Zod schemas for SwaggerHub Registry API validation
+export const ApiSearchParamsSchema = z.object({
+    query: z
+        .string()
+        .optional()
+        .describe("Search query to filter APIs by name, description, or content"),
+    state: z
+        .enum(["ALL", "PUBLISHED", "UNPUBLISHED"])
+        .optional()
+        .describe("Filter APIs by publication state - ALL (default), PUBLISHED, or UNPUBLISHED"),
+    tag: z.string().optional().describe("Filter APIs by tag"),
+    offset: z
+        .number()
+        .min(0)
+        .optional()
+        .describe("Offset for pagination (0-based, default 0)"),
+    limit: z
+        .number()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe("Number of results per page (1-100, default 20)"),
+    sort: z
+        .enum(["NAME", "UPDATED", "CREATED"])
+        .optional()
+        .describe("Sort field - NAME, UPDATED, or CREATED (default NAME)"),
+    order: z
+        .enum(["ASC", "DESC"])
+        .optional()
+        .describe("Sort order - ASC or DESC (default ASC)"),
+    owner: z
+        .string()
+        .optional()
+        .describe("Filter APIs by owner (organization or user)"),
+    specType: z
+        .enum(["API", "DOMAIN"])
+        .optional()
+        .describe("Filter by specification type - API or DOMAIN (default all types)"),
+});
+export const ApiDefinitionParamsSchema = z.object({
+    owner: z
+        .string()
+        .describe("API owner (organization or user, case-sensitive)"),
+    api: z.string().describe("API name (case-sensitive)"),
+    version: z.string().describe("Version identifier"),
+    resolved: z
+        .boolean()
+        .optional()
+        .describe("Set to true to get the resolved version with all external $refs included (default false)"),
+    flatten: z
+        .boolean()
+        .optional()
+        .describe("Set to true to create models from inline schemas in OpenAPI definition (default false)"),
+});
+export const CreateApiParamsSchema = z.object({
+    owner: z.string().describe("Organization name (owner of the API)"),
+    apiName: z.string().describe("API name"),
+    definition: z
+        .string()
+        .describe("API definition content (OpenAPI/AsyncAPI specification in JSON or YAML format). Format is automatically detected. API is created with fixed values: version 1.0.0, private visibility, automock disabled, and no project assignment."),
+});
+export const CreateApiFromTemplateParamsSchema = z.object({
+    owner: z.string().describe("Organization name (owner of the API)"),
+    apiName: z.string().describe("API name"),
+    template: z
+        .string()
+        .describe("Template name to use for creating the API. Format: owner/template-name/version (e.g., 'swagger-hub/petstore-template/1.0.0'). API is created with fixed values: private visibility, no project assignment, and reconciliation enabled."),
+});

package/dist/api-hub/client/tools.js

@@ -0,0 +1,98 @@
+/**
+ * TOOLS
+ *
+ * Defines tool configurations for API Hub operations.
+ * Each tool includes parameters, descriptions, and handler method names.
+ * This follows the pattern established in the pactflow module.
+ */
+import { CreatePortalArgsSchema, CreateProductArgsSchema, PortalArgsSchema, ProductArgsSchema, UpdatePortalArgsSchema, UpdateProductArgsSchema, } from "./portal-types.js";
+import { ApiDefinitionParamsSchema, ApiSearchParamsSchema, CreateApiFromTemplateParamsSchema, CreateApiParamsSchema, } from "./registry-types.js";
+export const TOOLS = [
+    {
+        title: "List Portals",
+        summary: "Search for available portals within API Hub. Only portals where you have at least a designer role, either at the product level or organization level, are returned.",
+        parameters: [],
+        handler: "getPortals",
+    },
+    {
+        title: "Create Portal",
+        summary: "Create a new portal within API Hub.",
+        zodSchema: CreatePortalArgsSchema,
+        handler: "createPortal",
+    },
+    {
+        title: "Get Portal",
+        summary: "Retrieve information about a specific portal.",
+        zodSchema: PortalArgsSchema,
+        handler: "getPortal",
+    },
+    {
+        title: "Delete Portal",
+        summary: "Delete a specific portal.",
+        zodSchema: PortalArgsSchema,
+        handler: "deletePortal",
+        formatResponse: () => "Portal deleted successfully.",
+    },
+    {
+        title: "Update Portal",
+        summary: "Update a specific portal's configuration.",
+        zodSchema: UpdatePortalArgsSchema,
+        handler: "updatePortal",
+    },
+    {
+        title: "List Portal Products",
+        summary: "Get products for a specific portal that match your criteria.",
+        zodSchema: PortalArgsSchema,
+        handler: "getPortalProducts",
+    },
+    {
+        title: "Create Portal Product",
+        summary: "Create a new product for a specific portal.",
+        zodSchema: CreateProductArgsSchema,
+        handler: "createPortalProduct",
+    },
+    {
+        title: "Get Portal Product",
+        summary: "Retrieve information about a specific product resource.",
+        zodSchema: ProductArgsSchema,
+        handler: "getPortalProduct",
+    },
+    {
+        title: "Delete Portal Product",
+        summary: "Delete a product from a specific portal",
+        zodSchema: ProductArgsSchema,
+        handler: "deletePortalProduct",
+        formatResponse: () => "Product deleted successfully.",
+    },
+    {
+        title: "Update Portal Product",
+        summary: "Update a product's settings within a specific portal.",
+        zodSchema: UpdateProductArgsSchema,
+        handler: "updatePortalProduct",
+    },
+    // Registry API tools for SwaggerHub Design functionality
+    {
+        title: "Search APIs and Domains",
+        summary: "Search for APIs and Domains in SwaggerHub Registry using the comprehensive /specs endpoint and retrieve metadata including owner, name, description, summary, version, and specification.",
+        zodSchema: ApiSearchParamsSchema,
+        handler: "searchApis",
+    },
+    {
+        title: "Get API Definition",
+        summary: "Fetch resolved API definition from SwaggerHub Registry based on owner, API name, and version.",
+        zodSchema: ApiDefinitionParamsSchema,
+        handler: "getApiDefinition",
+    },
+    {
+        title: "Create or Update API",
+        summary: "Create a new API or update an existing API in SwaggerHub Registry for API Hub for Design. The API specification type (OpenAPI, AsyncAPI) is automatically detected from the definition content. APIs are always created with fixed values: version 1.0.0, private visibility, and automock disabled (these values cannot be changed). Returns HTTP 201 for creation, HTTP 200 for update. Response includes 'operation' field indicating whether it was a 'create' or 'update' operation along with API details and SwaggerHub URL.",
+        zodSchema: CreateApiParamsSchema,
+        handler: "createOrUpdateApi",
+    },
+    {
+        title: "Create API from Template",
+        summary: "Create a new API in SwaggerHub Registry using a predefined template. This endpoint creates APIs based on existing templates without requiring manual definition content. APIs are always created with fixed values: private visibility, no project assignment, and reconciliation enabled (these values cannot be changed). Returns HTTP 201 for creation, HTTP 200 for update. Response includes 'operation' field and API details with SwaggerHub URL.",
+        zodSchema: CreateApiFromTemplateParamsSchema,
+        handler: "createApiFromTemplate",
+    },
+];

package/dist/api-hub/client.js

@@ -1,429 +1,95 @@
-import { z } from "zod";
 import { MCP_SERVER_NAME, MCP_SERVER_VERSION } from "../common/info.js";
+import { ApiHubAPI, ApiHubConfiguration, TOOLS, } from "./client/index.js";
 // Tool definitions for API Hub API client
 export class ApiHubClient {
-    headers;
+    config;
+    api;
     name = "API Hub";
     prefix = "api_hub";
     constructor(token) {
-        this.headers = {
-            "Authorization": `Bearer ${token}`,
-            "Content-Type": "application/json",
-            "User-Agent": `${MCP_SERVER_NAME}/${MCP_SERVER_VERSION}`,
-        };
+        this.config = new ApiHubConfiguration({ token });
+        this.api = new ApiHubAPI(this.config, `${MCP_SERVER_NAME}/${MCP_SERVER_VERSION}`);
     }
+    // Delegate API methods to the ApiHubAPI instance
     async getPortals() {
-        const response = await fetch("https://api.portal.swaggerhub.com/v1/portals", {
-            method: "GET",
-            headers: this.headers,
-        });
-        return response.json();
+        return this.api.getPortals();
     }
     async createPortal(body) {
-        const response = await fetch(`https://api.portal.swaggerhub.com/v1/portals`, {
-            method: "POST",
-            headers: this.headers,
-            body: JSON.stringify(body),
-        });
-        return response.json();
+        return this.api.createPortal(body);
     }
-    async getPortal(portalId) {
-        const response = await fetch(`https://api.portal.swaggerhub.com/v1/portals/${portalId}`, {
-            method: "GET",
-            headers: this.headers,
-        });
-        return response.json();
+    async getPortal(args) {
+        return this.api.getPortal(args.portalId);
     }
-    async deletePortal(portalId) {
-        await fetch(`https://api.portal.swaggerhub.com/v1/portals/${portalId}`, {
-            method: "DELETE",
-            headers: this.headers,
-        });
+    async deletePortal(args) {
+        return this.api.deletePortal(args.portalId);
     }
-    async updatePortal(portalId, body) {
-        const response = await fetch(`https://api.portal.swaggerhub.com/v1/portals/${portalId}`, {
-            method: "PATCH",
-            headers: this.headers,
-            body: JSON.stringify(body),
-        });
-        return response.json();
+    async updatePortal(args) {
+        const { portalId, ...body } = args;
+        return this.api.updatePortal(portalId, body);
     }
-    async getPortalProducts(portalId) {
-        const response = await fetch(`https://api.portal.swaggerhub.com/v1/portals/${portalId}/products`, {
-            method: "GET",
-            headers: this.headers,
-        });
-        return response.json();
+    async getPortalProducts(args) {
+        return this.api.getPortalProducts(args.portalId);
     }
-    async createPortalProduct(portalId, body) {
-        const response = await fetch(`https://api.portal.swaggerhub.com/v1/portals/${portalId}/products`, {
-            method: "POST",
-            headers: this.headers,
-            body: JSON.stringify(body),
-        });
-        return response.json();
+    async createPortalProduct(args) {
+        const { portalId, ...body } = args;
+        return this.api.createPortalProduct(portalId, body);
     }
-    async getPortalProduct(productId) {
-        const response = await fetch(`https://api.portal.swaggerhub.com/v1/products/${productId}`, {
-            method: "GET",
-            headers: this.headers,
-        });
-        return response.json();
+    async getPortalProduct(args) {
+        return this.api.getPortalProduct(args.productId);
     }
-    async deletePortalProduct(productId) {
-        await fetch(`https://api.portal.swaggerhub.com/v1/products/${productId}`, {
-            method: "DELETE",
-            headers: this.headers,
-        });
+    async deletePortalProduct(args) {
+        return this.api.deletePortalProduct(args.productId);
     }
-    async updatePortalProduct(productId, body) {
-        const response = await fetch(`https://api.portal.swaggerhub.com/v1/products/${productId}`, {
-            method: "PATCH",
-            headers: this.headers,
-            body: JSON.stringify(body),
-        });
-        return response.json();
+    async updatePortalProduct(args) {
+        const { productId, ...body } = args;
+        return this.api.updatePortalProduct(productId, body);
+    }
+    // Registry API methods for SwaggerHub Design functionality
+    async searchApis(args = {}) {
+        return this.api.searchApis(args);
+    }
+    async getApiDefinition(args) {
+        return this.api.getApiDefinition(args);
+    }
+    async createOrUpdateApi(args) {
+        return this.api.createOrUpdateApi(args);
+    }
+    async createApiFromTemplate(args) {
+        return this.api.createApiFromTemplate(args);
     }
     registerTools(register, _getInput) {
-        register({
-            title: "List Portals",
-            summary: "Search for available portals within API Hub. Only portals where you have at least a designer role, either at the product level or organization level, are returned.",
-            parameters: [],
-        }, async (_args, _extra) => {
-            const response = await this.getPortals();
-            return {
-                content: [{ type: "text", text: JSON.stringify(response) }],
-            };
-        });
-        register({
-            title: "Create Portal",
-            summary: "Create a new portal within API Hub.",
-            parameters: [
-                {
-                    name: "name",
-                    type: z.string(),
-                    required: false,
-                    description: "The portal name.",
-                },
-                {
-                    name: "subdomain",
-                    type: z.string(),
-                    required: true,
-                    description: "The portal subdomain.",
-                },
-                {
-                    name: "offline",
-                    type: z.boolean(),
-                    required: false,
-                    description: "If set to true the portal will not be visible to customers.",
-                },
-                {
-                    name: "routing",
-                    type: z.string(),
-                    required: false,
-                    description: "Determines the routing strategy ('browser' or 'proxy').",
-                },
-                {
-                    name: "credentialsEnabled",
-                    type: z.string(),
-                    required: false,
-                    description: "Indicates if credentials are enabled for the portal.",
-                },
-                {
-                    name: "swaggerHubOrganizationId",
-                    type: z.string(),
-                    required: true,
-                    description: "The corresponding API Hub (formerly SwaggerHub) organization UUID.",
-                },
-                {
-                    name: "openapiRenderer",
-                    type: z.string(),
-                    required: false,
-                    description: "Portal level setting for the OpenAPI renderer. SWAGGER_UI - Use the Swagger UI renderer. ELEMENTS - Use the Elements renderer. TOGGLE - Switch between the two renderers with elements set as the default.",
-                },
-                {
-                    name: "pageContentFormat",
-                    type: z.string(),
-                    required: false,
-                    description: "The format of the page content.",
+        TOOLS.forEach((tool) => {
+            const { handler, formatResponse, ...toolParams } = tool;
+            register(toolParams, async (args, _extra) => {
+                try {
+                    // Dynamic method invocation
+                    const handlerFn = this[handler];
+                    if (typeof handlerFn !== "function") {
+                        throw new Error(`Handler '${handler}' not found on ApiHubClient`);
+                    }
+                    const result = await handlerFn.call(this, args);
+                    // Use custom formatter if available, otherwise return JSON
+                    const formattedResult = formatResponse
+                        ? formatResponse(result)
+                        : result;
+                    const responseText = typeof formattedResult === "string"
+                        ? formattedResult
+                        : JSON.stringify(formattedResult);
+                    return {
+                        content: [{ type: "text", text: responseText }],
+                    };
                 }
-            ],
-        }, async (args, _extra) => {
-            const createPortalArgs = args;
-            const response = await this.createPortal(createPortalArgs);
-            return {
-                content: [{ type: "text", text: JSON.stringify(response) }],
-            };
-        });
-        register({
-            title: "Get Portal",
-            summary: "Retrieve information about a specific portal.",
-            parameters: [
-                {
-                    name: "portalId",
-                    type: z.string(),
-                    description: "Portal UUID or subdomain.",
-                    required: true
-                },
-            ],
-        }, async (args, _extra) => {
-            const portalArgs = args;
-            const response = await this.getPortal(portalArgs.portalId);
-            return {
-                content: [{ type: "text", text: JSON.stringify(response) }],
-            };
-        });
-        register({
-            title: "Delete Portal",
-            summary: "Delete a specific portal.",
-            parameters: [
-                {
-                    name: "portalId",
-                    type: z.string(),
-                    description: "Portal UUID or subdomain.",
-                    required: true
-                }
-            ],
-        }, async (args, _extra) => {
-            const portalArgs = args;
-            await this.deletePortal(portalArgs.portalId);
-            return {
-                content: [{ type: "text", text: "Portal deleted successfully." }],
-            };
-        });
-        register({
-            title: "Update Portal",
-            summary: "Update a specific portal's configuration.",
-            parameters: [
-                {
-                    name: "portalId",
-                    type: z.string(),
-                    description: "Portal UUID or subdomain.",
-                    required: true
-                },
-                {
-                    name: "name",
-                    type: z.string(),
-                    description: "The portal name.",
-                    required: false
-                },
-                {
-                    name: "subdomain",
-                    type: z.string(),
-                    description: "The portal subdomain.",
-                    required: false
-                },
-                {
-                    name: "customDomain",
-                    type: z.boolean(),
-                    description: "Indicates if the portal has a custom domain.",
-                    required: false
-                },
-                {
-                    name: "gtmKey",
-                    type: z.string(),
-                    description: "Google Tag Manager key for the portal.",
-                    required: false
-                },
-                {
-                    name: "offline",
-                    type: z.boolean(),
-                    description: "If set to true the portal will not be visible to customers.",
-                    required: false
-                },
-                {
-                    name: "routing",
-                    type: z.string(),
-                    description: "Determines the routing strategy ('browser' or 'proxy').",
-                    required: false
-                },
-                {
-                    name: "credentialsEnabled",
-                    type: z.boolean(),
-                    description: "Indicates if credentials are enabled for the portal.",
-                    required: false
-                },
-                {
-                    name: "openapiRenderer",
-                    type: z.string(),
-                    description: "Portal level setting for the OpenAPI renderer. SWAGGER_UI - Use the Swagger UI renderer. ELEMENTS - Use the Elements renderer. TOGGLE - Switch between the two renderers with elements set as the default.",
-                    required: false
-                },
-                {
-                    name: "pageContentFormat",
-                    type: z.string(),
-                    description: "The format of the page content.",
-                    required: false
-                }
-            ],
-        }, async (args, _extra) => {
-            const updatePortalArgs = args;
-            const response = await this.updatePortal(updatePortalArgs.portalId, updatePortalArgs);
-            return {
-                content: [{ type: "text", text: JSON.stringify(response) }],
-            };
-        });
-        register({
-            title: "List Portal Products",
-            summary: "Get products for a specific portal that match your criteria.",
-            parameters: [
-                {
-                    name: "portalId",
-                    type: z.string(),
-                    description: "Portal UUID or subdomain.",
-                    required: true
-                }
-            ],
-        }, async (args, _extra) => {
-            const portalArgs = args;
-            const response = await this.getPortalProducts(portalArgs.portalId);
-            return {
-                content: [{ type: "text", text: JSON.stringify(response) }],
-            };
-        });
-        register({
-            title: "Create Portal Product",
-            summary: "Create a new product for a specific portal.",
-            parameters: [
-                {
-                    name: "portalId",
-                    type: z.string(),
-                    description: "Portal UUID or subdomain.",
-                    required: true
-                },
-                {
-                    name: "type",
-                    type: z.string(),
-                    description: "Product type (Allowed values: 'new', 'copy').",
-                    required: true
-                },
-                {
-                    name: "name",
-                    type: z.string(),
-                    description: "Product name.",
-                    required: true
-                },
-                {
-                    name: "slug",
-                    type: z.string(),
-                    description: "URL component for this product. Must be unique within the portal.",
-                    required: true
-                },
-                {
-                    name: "description",
-                    type: z.string(),
-                    description: "Product description.",
-                    required: false
-                },
-                {
-                    name: "public",
-                    type: z.boolean(),
-                    description: "Indicates if the product is public.",
-                    required: false
-                },
-                {
-                    name: "hidden",
-                    type: z.string(),
-                    description: "Indicates if the product is hidden.",
-                    required: false
-                },
-                {
-                    name: "role",
-                    type: z.boolean(),
-                    description: "Indicates if the product has a role.",
-                    required: false
-                }
-            ],
-        }, async (args, _extra) => {
-            const createProductArgs = args;
-            const response = await this.createPortalProduct(createProductArgs.portalId, createProductArgs);
-            return {
-                content: [{ type: "text", text: JSON.stringify(response) }],
-            };
-        });
-        register({
-            title: "Get Portal Product",
-            summary: "Retrieve information about a specific product resource.",
-            parameters: [
-                {
-                    name: "productId",
-                    type: z.string(),
-                    description: "Product UUID, or identifier in the format.",
-                    required: true
-                }
-            ],
-        }, async (args, _extra) => {
-            const productArgs = args;
-            const response = await this.getPortalProduct(productArgs.productId);
-            return {
-                content: [{ type: "text", text: JSON.stringify(response) }],
-            };
-        });
-        register({
-            title: "Delete Portal Product",
-            summary: "Delete a product from a specific portal",
-            parameters: [
-                {
-                    name: "productId",
-                    type: z.string(),
-                    description: "Product UUID, or identifier in the format.",
-                    required: true
-                }
-            ],
-        }, async (args, _extra) => {
-            const productArgs = args;
-            await this.deletePortalProduct(productArgs.productId);
-            return {
-                content: [{ type: "text", text: "Product deleted successfully." }],
-            };
-        });
-        register({
-            title: "Update Portal Product",
-            summary: "Update a product's settings within a specific portal.",
-            parameters: [
-                {
-                    name: "productId",
-                    type: z.string(),
-                    description: "Product UUID, or identifier in the format.",
-                    required: true
-                },
-                {
-                    name: "name",
-                    type: z.string(),
-                    description: "Product name.",
-                    required: false
-                },
-                {
-                    name: "slug",
-                    type: z.string(),
-                    description: "URL component for this product. Must be unique within the portal.",
-                    required: false
-                },
-                {
-                    name: "description",
-                    type: z.string(),
-                    description: "Product description.",
-                    required: false
-                },
-                {
-                    name: "public",
-                    type: z.boolean(),
-                    description: "Indicates if the product is public.",
-                    required: false
-                },
-                {
-                    name: "hidden",
-                    type: z.string(),
-                    description: "Indicates if the product is hidden.",
-                    required: false
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                            },
+                        ],
+                    };
                 }
-            ],
-        }, async (args, _extra) => {
-            const updateProductArgs = args;
-            const response = await this.updatePortalProduct(updateProductArgs.productId, updateProductArgs);
-            return {
-                content: [{ type: "text", text: JSON.stringify(response) }],
-            };
+            });
         });
     }
 }