@smartbear/mcp 0.3.0 → 0.5.0

package/dist/common/info.js

@@ -1,3 +1,3 @@
-import packageJson from '../package.json' with { type: "json" };
+import packageJson from '../../package.json' with { type: "json" };
 export const MCP_SERVER_NAME = packageJson.config.mcpServerName;
 export const MCP_SERVER_VERSION = packageJson.version;

package/dist/common/server.js

@@ -0,0 +1,148 @@
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ZodAny, ZodArray, ZodBoolean, ZodEnum, ZodLiteral, ZodNumber, ZodObject, ZodString, ZodUnion, } from "zod";
+import Bugsnag from "../common/bugsnag.js";
+import { MCP_SERVER_NAME, MCP_SERVER_VERSION } from "./info.js";
+export class SmartBearMcpServer extends McpServer {
+    constructor() {
+        super({
+            name: MCP_SERVER_NAME,
+            version: MCP_SERVER_VERSION,
+        }, {
+            capabilities: {
+                resources: { listChanged: true }, // Server supports dynamic resource lists
+                tools: { listChanged: true }, // Server supports dynamic tool lists
+            },
+        });
+    }
+    addClient(client) {
+        client.registerTools((params, cb) => {
+            const toolName = `${client.prefix}_${params.title.replace(/\s+/g, "_").toLowerCase()}`;
+            const toolTitle = `${client.name}: ${params.title}`;
+            return super.registerTool(toolName, {
+                title: toolTitle,
+                description: this.getDescription(params),
+                inputSchema: this.getInputSchema(params),
+                annotations: this.getAnnotations(toolTitle, params),
+            }, async (args, extra) => {
+                try {
+                    return await cb(args, extra);
+                }
+                catch (e) {
+                    Bugsnag.notify(e);
+                    throw e;
+                }
+            });
+        }, (params, options) => {
+            return this.server.elicitInput(params, options);
+        });
+        if (client.registerResources) {
+            client.registerResources((name, path, cb) => {
+                return super.registerResource(name, new ResourceTemplate(`${client.prefix}://${name}/${path}`, { list: undefined }), {}, async (url, variables, extra) => {
+                    try {
+                        return await cb(url, variables, extra);
+                    }
+                    catch (e) {
+                        Bugsnag.notify(e);
+                        throw e;
+                    }
+                });
+            });
+        }
+    }
+    getAnnotations(toolTitle, params) {
+        const annotations = {
+            title: toolTitle,
+            readOnlyHint: params.readOnly ?? true,
+            destructiveHint: params.destructive ?? false,
+            idempotentHint: params.idempotent ?? true,
+            openWorldHint: params.openWorld ?? false,
+        };
+        return annotations;
+    }
+    getInputSchema(params) {
+        const args = {};
+        for (const param of params.parameters ?? []) {
+            args[param.name] = param.type;
+            if (param.description) {
+                args[param.name] = args[param.name].describe(param.description);
+            }
+            if (!param.required) {
+                args[param.name] = args[param.name].optional();
+            }
+        }
+        if (params.zodSchema && params.zodSchema instanceof ZodObject) {
+            for (const key of Object.keys(params.zodSchema.shape)) {
+                const field = params.zodSchema.shape[key];
+                args[key] = field;
+                if (field.description) {
+                    args[key] = args[key].describe(field.description);
+                }
+                if (field.isOptional()) {
+                    args[key] = args[key].optional();
+                }
+            }
+        }
+        return args;
+    }
+    getDescription(params) {
+        const { summary, useCases, examples, parameters, zodSchema, hints, outputFormat } = params;
+        let description = summary;
+        // Parameters if available otherwise use zodSchema
+        if ((parameters ?? []).length > 0) {
+            description += `\n\n**Parameters:**\n${parameters?.map(p => `- ${p.name} (${this.getReadableTypeName(p.type)})${p.required ? ' *required*' : ''}` +
+                `${p.description ? `: ${p.description}` : ''}` +
+                `${p.examples ? ` (e.g. ${p.examples.join(', ')})` : ''}` +
+                `${p.constraints ? `\n  - ${p.constraints.join('\n  - ')}` : ''}`).join('\n')}`;
+        }
+        if (zodSchema && zodSchema instanceof ZodObject) {
+            description += "\n\n**Parameters:**\n";
+            description += Object.keys(zodSchema.shape)
+                .map(key => this.formatParameterDescription(key, zodSchema.shape[key]))
+                .join('\n');
+        }
+        if (outputFormat) {
+            description += `\n\n**Output Format:** ${outputFormat}`;
+        }
+        // Use Cases
+        if (useCases && useCases.length > 0) {
+            description += `\n\n**Use Cases:** ${useCases.map((uc, i) => `${i + 1}. ${uc}`).join(' ')}`;
+        }
+        // Examples
+        if (examples && examples.length > 0) {
+            description += `\n\n**Examples:**\n` + examples.map((ex, idx) => `${idx + 1}. ${ex.description}\n\`\`\`json\n${JSON.stringify(ex.parameters, null, 2)}\n\`\`\`${ex.expectedOutput ? `\nExpected Output: ${ex.expectedOutput}` : ''}`).join('\n\n');
+        }
+        // Hints
+        if (hints && hints.length > 0) {
+            description += `\n\n**Hints:** ${hints.map((hint, i) => `${i + 1}. ${hint}`).join(' ')}`;
+        }
+        return description.trim();
+    }
+    formatParameterDescription(key, field) {
+        return `- ${key} (${this.getReadableTypeName(field)})` +
+            `${field.isOptional() ? '' : ' *required*'}` +
+            `${field.description ? `: ${field.description}` : ''}` +
+            `${key === "examples" && field instanceof ZodEnum ? ` (e.g. ${Object.keys(field.enum).join(', ')})` : ''}` +
+            `${key === "constraints" && field instanceof ZodEnum ? `\n  - ${Object.keys(field.enum).join('\n  - ')}` : ''}`;
+    }
+    getReadableTypeName(zodType) {
+        if (zodType instanceof ZodString)
+            return 'string';
+        if (zodType instanceof ZodNumber)
+            return 'number';
+        if (zodType instanceof ZodBoolean)
+            return 'boolean';
+        if (zodType instanceof ZodArray)
+            return 'array';
+        if (zodType instanceof ZodObject)
+            return 'object';
+        if (zodType instanceof ZodEnum)
+            return 'enum';
+        if (zodType instanceof ZodLiteral)
+            return 'literal';
+        if (zodType instanceof ZodUnion)
+            return 'union';
+        if (zodType instanceof ZodAny)
+            return 'any';
+        return 'any';
+    }
+}

package/dist/index.js

@@ -1,48 +1,57 @@
 #!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import Bugsnag from "./common/bugsnag.js";
-import { MCP_SERVER_NAME, MCP_SERVER_VERSION } from "./common/info.js";
-import { InsightHubClient } from "./insight-hub/client.js";
+import { BugsnagClient } from "./bugsnag/client.js";
 import { ReflectClient } from "./reflect/client.js";
 import { ApiHubClient } from "./api-hub/client.js";
+import { SmartBearMcpServer } from "./common/server.js";
+import { PactflowClient } from "./pactflow/client.js";
 // This is used to report errors in the MCP server itself
-// If you want to use your own BugSnag API key, set the MCP_SERVER_INSIGHT_HUB_API_KEY environment variable
-const McpServerBugsnagAPIKey = process.env.MCP_SERVER_INSIGHT_HUB_API_KEY;
+// If you want to use your own BugSnag API key, set the MCP_SERVER_BUGSNAG_API_KEY environment variable
+const McpServerBugsnagAPIKey = process.env.MCP_SERVER_BUGSNAG_API_KEY;
 if (McpServerBugsnagAPIKey) {
     Bugsnag.start(McpServerBugsnagAPIKey);
 }
 async function main() {
-    const server = new McpServer({
-        name: MCP_SERVER_NAME,
-        version: MCP_SERVER_VERSION,
-    }, {
-        capabilities: {
-            resources: { listChanged: true }, // Server supports dynamic resource lists
-            tools: { listChanged: true }, // Server supports dynamic tool lists
-        },
-    });
+    const server = new SmartBearMcpServer();
     const reflectToken = process.env.REFLECT_API_TOKEN;
-    const insightHubToken = process.env.INSIGHT_HUB_AUTH_TOKEN;
+    const bugsnagToken = process.env.BUGSNAG_AUTH_TOKEN;
     const apiHubToken = process.env.API_HUB_API_KEY;
-    if (!reflectToken && !insightHubToken && !apiHubToken) {
-        console.error("Please set one of REFLECT_API_TOKEN, INSIGHT_HUB_AUTH_TOKEN or API_HUB_API_KEY environment variables");
-        process.exit(1);
-    }
+    const pactBrokerToken = process.env.PACT_BROKER_TOKEN;
+    const pactBrokerUrl = process.env.PACT_BROKER_BASE_URL;
+    const pactBrokerUsername = process.env.PACT_BROKER_USERNAME;
+    const pactBrokerPassword = process.env.PACT_BROKER_PASSWORD;
+    let client_defined = false;
     if (reflectToken) {
-        const reflectClient = new ReflectClient(reflectToken);
-        reflectClient.registerTools(server);
-        reflectClient.registerResources(server);
+        server.addClient(new ReflectClient(reflectToken));
+        client_defined = true;
     }
-    if (insightHubToken) {
-        const insightHubClient = new InsightHubClient(insightHubToken, process.env.INSIGHT_HUB_PROJECT_API_KEY, process.env.INSIGHT_HUB_ENDPOINT);
-        await insightHubClient.initialize();
-        insightHubClient.registerTools(server);
-        insightHubClient.registerResources(server);
+    if (bugsnagToken) {
+        const bugsnagClient = new BugsnagClient(bugsnagToken, process.env.BUGSNAG_PROJECT_API_KEY, process.env.BUGSNAG_ENDPOINT);
+        await bugsnagClient.initialize();
+        server.addClient(bugsnagClient);
+        client_defined = true;
     }
     if (apiHubToken) {
-        const apiHubClient = new ApiHubClient(apiHubToken);
-        apiHubClient.registerTools(server);
+        server.addClient(new ApiHubClient(apiHubToken));
+        client_defined = true;
+    }
+    if (pactBrokerUrl) {
+        if (pactBrokerToken) {
+            server.addClient(new PactflowClient(pactBrokerToken, pactBrokerUrl, "pactflow"));
+            client_defined = true;
+        }
+        else if (pactBrokerUsername && pactBrokerPassword) {
+            server.addClient(new PactflowClient({ username: pactBrokerUsername, password: pactBrokerPassword }, pactBrokerUrl, "pact_broker"));
+            client_defined = true;
+        }
+        else {
+            console.error("If the Pact Broker base URL is specified, you must specify either (a) a PactFlow token, or (b) a Pact Broker username and password pair.");
+        }
+    }
+    if (!client_defined) {
+        console.error("Please set one of REFLECT_API_TOKEN, BUGSNAG_AUTH_TOKEN, API_HUB_API_KEY or PACT_BROKER_BASE_URL / (and relevant Pact auth) environment variables");
+        process.exit(1);
     }
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/pactflow/client/ai.js

@@ -0,0 +1,146 @@
+import { z } from "zod";
+import { addOpenAPISpecToSchema } from "./utils.js";
+// Type definitions for PactFlow AI API
+export const GenerationLanguages = [
+    "javascript",
+    "typescript",
+    "java",
+    "golang",
+    "dotnet",
+    "kotlin",
+    "swift",
+    "php",
+];
+export const HttpMethods = [
+    "GET",
+    "PUT",
+    "POST",
+    "DELETE",
+    "OPTIONS",
+    "HEAD",
+    "PATCH",
+    "TRACE",
+];
+// zod schemas
+export const FileInputSchema = z.object({
+    filename: z
+        .string()
+        .optional()
+        .describe("Filename (helps identify file type and context)"),
+    language: z
+        .string()
+        .optional()
+        .describe("Programming language (e.g., 'javascript', 'java', 'python') for better analysis"),
+    body: z
+        .string()
+        .describe("Complete file contents - client code, models, test files, etc."),
+});
+export const OpenAPISchema = z
+    .object({
+    openapi: z
+        .string()
+        .optional()
+        .describe("For OpenAPI version (e.g., '3.0.0')"),
+    swagger: z
+        .string()
+        .describe("For OpenAPI documents version 2.x (e.g., '2.0')")
+        .optional(),
+    paths: z
+        .record(z.string(), z.record(z.string(), z.any()))
+        .describe("OpenAPI paths object containing all API endpoints"),
+    components: z
+        .record(z.string(), z.record(z.string(), z.any()))
+        .optional()
+        .describe("OpenAPI components section (schemas, responses, etc.)"),
+})
+    .passthrough()
+    .describe("The complete OpenAPI document describing the API.")
+    .refine((data) => data.openapi || data.swagger, {
+    message: "Either 'openapi' (for v3+) or 'swagger' (for v2) must be provided",
+    path: ["openapi"],
+});
+export const EndpointMatcherSchema = z
+    .object({
+    path: z
+        .string()
+        .optional()
+        .describe("Path pattern to match specific endpoints (e.g., '/users/{id}', '/users/*', '/users/**'). Supports glob patterns: ? (single char), * (excluding /), ** (including /)"),
+    methods: z
+        .array(z.enum(HttpMethods))
+        .optional()
+        .describe("HTTP methods to include (e.g., ['GET', 'POST']). If not specified, all methods are matched"),
+    statusCodes: z
+        .array(z.union([z.number(), z.string()]))
+        .optional()
+        .describe("Response status codes to include (e.g., [200, '2XX', 404]). Use 'X' as wildcard (e.g., '2XX' for 200-299). Defaults to successful codes (2XX)"),
+    operationId: z
+        .string()
+        .optional()
+        .describe("OpenAPI operation ID to match (e.g., 'getUserById', 'get*'). Supports glob patterns"),
+})
+    .required()
+    .describe("REQUIRED: Matcher to specify which endpoints from the OpenAPI document to generate tests for. At least one matcher field must be provided");
+export const RemoteOpenAPIDocumentSchema = z
+    .object({
+    authToken: z
+        .string()
+        .describe("Auth Bearer Token if the OpenAPI spec requires authentication.")
+        .optional(),
+    authScheme: z
+        .string()
+        .describe("Authentication scheme (e.g., 'Bearer', 'Basic'). Default scheme passed should be Bearer if authToken is specified and this field is not set.")
+        .default("Bearer")
+        .optional(),
+    url: z
+        .string()
+        .url("Must be a valid openapi url")
+        .describe("URL of the remote OpenAPI document.")
+        .optional(),
+})
+    .describe("Use this schema to fetch openapi documents present over a url.");
+export const OpenAPIWithMatcherSchema = z
+    .object({
+    document: OpenAPISchema.describe("The OpenAPI document describing the API being tested. if document is not provided, don't add the field if remoteOpenAPIDocument is provided.").optional(),
+    matcher: EndpointMatcherSchema,
+    remoteDocument: RemoteOpenAPIDocumentSchema.optional().describe("The remote OpenAPI document to use for the review/generation in case openapi document is not provided. If provided do not include the document field under openapi."),
+})
+    .describe("If provided, the OpenAPI document which describes the API being tested and is accompanied by a matcher which will be used to identify the interactions in the OpenAPI document which are relevant to the Pact refinement process.").transform(addOpenAPISpecToSchema);
+export const RefineInputSchema = z.object({
+    pactTests: FileInputSchema.describe("Primary pact tests that needs to be refined."),
+    code: z
+        .array(FileInputSchema)
+        .describe("Collection of source code files to analyze and extract API interactions from. Include client code, data models, existing tests, or any code that makes API calls")
+        .optional(),
+    userInstructions: z
+        .string()
+        .describe("Optional free-form instructions that provide additional context or specify areas of focus during the refinement process of the Pact test.")
+        .optional(),
+    errorMessages: z
+        .array(z.string())
+        .describe("Optional error output from failed contract test runs. These can be used to better understand the context or failures observed and guide the recommendations toward resolving specific issues.")
+        .optional(),
+    openapi: OpenAPIWithMatcherSchema.optional(),
+});
+export const RequestResponsePairSchema = z
+    .object({
+    request: FileInputSchema,
+    response: FileInputSchema,
+})
+    .describe("Direct request/response pair for a specific interaction. Use this when you have concrete examples of API requests and responses");
+export const GenerationInputSchema = z.object({
+    language: z
+        .enum(GenerationLanguages)
+        .optional()
+        .describe("Target language for the generated Pact tests. If not provided, will be inferred from other inputs."),
+    requestResponse: RequestResponsePairSchema.optional(),
+    code: z
+        .array(FileInputSchema)
+        .optional()
+        .describe("Collection of source code files to analyze and extract API interactions from. Include client code, data models, existing tests, or any code that makes API calls"),
+    openapi: OpenAPIWithMatcherSchema.optional(),
+    additionalInstructions: z
+        .string()
+        .optional()
+        .describe("Optional free-form instructions to guide the generation process (e.g., 'Focus on error scenarios', 'Include authentication headers', 'Use specific test framework patterns')"),
+    testTemplate: FileInputSchema.optional().describe("Optional test template to use as a basis for generation. Helps ensure generated tests follow your specific patterns, frameworks, and coding standards"),
+});

package/dist/pactflow/client/base.js

@@ -0,0 +1,6 @@
+import { z } from "zod";
+export const CanIDeploySchema = z.object({
+    pacticipant: z.string(),
+    version: z.string(),
+    environment: z.string(),
+});

package/dist/pactflow/client/tools.js

@@ -0,0 +1,55 @@
+/**
+ * TOOLS
+ *
+ * Extends the default `ToolParams` with:
+ *  - `handler`: Name of the `PactflowClient` method to execute.
+ *  - `clients`: List of `ClientType`s allowed to use the tool.
+ *  - `formatResponse` (optional): Formats the tool's output before returning.
+ *
+ * In `PactflowClient.registerTools()`, tools are filtered by `clientType`
+ * and registered with their corresponding handler.
+ */
+import { z } from "zod";
+import { GenerationInputSchema, RefineInputSchema } from "./ai.js";
+import { CanIDeploySchema } from "./base.js";
+export const TOOLS = [
+    {
+        title: "Generate Pact Tests",
+        summary: "Generate Pact tests using PactFlow AI. You can provide one or more of the following input types: (1) request/response pairs for specific interactions, (2) code files to analyze and extract interactions from, and/or (3) OpenAPI document to generate tests for specific endpoints. When providing an OpenAPI document, a matcher is required to specify which endpoints to generate tests for.",
+        purpose: "Generate Pact tests for API interactions",
+        zodSchema: GenerationInputSchema,
+        handler: "generate",
+        clients: ["pactflow"], // ONLY pactflow
+    },
+    {
+        title: "Review Pact Tests",
+        summary: "Review Pact tests using PactFlow AI. You can provide the following inputs: (1) Pact tests to be reviewed along with metadata",
+        purpose: "Review Pact tests for API interactions",
+        zodSchema: RefineInputSchema,
+        handler: "review",
+        clients: ["pactflow"]
+    },
+    {
+        title: "Get Provider States",
+        summary: "Retrieve the states of a specific provider",
+        purpose: "A provider state in Pact defines the specific preconditions that must be met on the provider side before a consumer–provider interaction can be tested. It sets up the provider in the right context—such as ensuring a particular user or record exists—so that the provider can return the response the consumer expects. This makes contract tests reliable, repeatable, and isolated by injecting or configuring the necessary data and conditions directly into the provider before each test runs.",
+        parameters: [
+            {
+                name: "provider",
+                type: z.string(),
+                description: "name of the provider to retrieve states for",
+                required: true
+            }
+        ],
+        handler: "getProviderStates",
+        clients: ["pactflow", "pact_broker"]
+    },
+    {
+        title: "Can I Deploy",
+        summary: "Performs a comprehensive compatibility check to determine whether a specific version of a service (pacticipant) can be safely deployed into a given environment. It analyzes the complete contract matrix of consumer-provider relationships to confirm that all required integrations are verified and compatible.",
+        purpose: "To serve as a deployment safety check within the PactBroker and PactFlow ecosystem, leveraging contract testing results to validate whether a specific service / pacticipant version is compatible with all integrated services. This feature prevents unsafe releases, reduces integration risks, and enables teams to confidently automate deployments across environments with a clear, auditable record of verification results.",
+        zodSchema: CanIDeploySchema,
+        handler: "canIDeploy",
+        clients: ["pactflow", "pact_broker"]
+    }
+];

package/dist/pactflow/client/utils.js

@@ -0,0 +1,70 @@
+import { RemoteOpenAPIDocumentSchema, } from "./ai.js";
+import yaml from "js-yaml";
+// @ts-expect-error missing type declarations
+import Swagger from "swagger-client";
+/**
+ * Resolve the OpenAPI specification from the provided input.
+ *
+ * @param remoteOpenAPIDocument The remote OpenAPI document to resolve.
+ * @returns The resolved OpenAPI document.
+ * @throws Error if the resolution fails.
+ */
+export async function resolveOpenAPISpec(remoteOpenAPIDocument) {
+    const openAPISchema = RemoteOpenAPIDocumentSchema.safeParse(remoteOpenAPIDocument);
+    if (openAPISchema.error || !remoteOpenAPIDocument) {
+        throw new Error(`Invalid RemoteOpenAPIDocument: ${JSON.stringify(openAPISchema.error?.issues)}`);
+    }
+    const unresolvedSpec = await getRemoteSpecContents(openAPISchema.data);
+    const resolvedSpec = await Swagger.resolve({ spec: unresolvedSpec });
+    if (resolvedSpec.errors?.length) {
+        throw new Error(`Failed to resolve OpenAPI document: ${resolvedSpec.errors?.join(", ")}`);
+    }
+    return resolvedSpec.spec;
+}
+/**
+ * Fetch the contents of a remote OpenAPI document.
+ *
+ * @param openAPISchema The schema for the remote OpenAPI document.
+ * @returns A promise that resolves to a map of the OpenAPI document contents.
+ * @throws Error if the URL is not provided or the fetch fails.
+ */
+export async function getRemoteSpecContents(openAPISchema) {
+    if (!openAPISchema.url) {
+        throw new Error("'url' must be provided.");
+    }
+    let headers = {};
+    if (openAPISchema.authToken) {
+        headers = {
+            Authorization: `${openAPISchema.authScheme ?? "Bearer"} ${openAPISchema.authToken}`,
+        };
+    }
+    const remoteSpec = await fetch(openAPISchema.url, {
+        headers,
+        method: "GET",
+    });
+    const specRawBody = await remoteSpec.text();
+    try {
+        return JSON.parse(specRawBody);
+    }
+    catch (jsonError) {
+        try {
+            return yaml.load(specRawBody);
+        }
+        catch (yamlError) {
+            throw new Error(`Unsupported Content-Type: ${remoteSpec.headers.get("Content-Type")} for remote OpenAPI document. Found following parse errors:-\nJSON parse error: ${jsonError}\nYAML parse error: ${yamlError}`);
+        }
+    }
+}
+/**
+ * Adds the OpenAPI specification to the input schema if a remote document is provided.
+ *
+ * @param inputSchema The input schema to modify.
+ * @returns The modified input schema with the OpenAPI specification added.
+ */
+export async function addOpenAPISpecToSchema(inputSchema) {
+    if (inputSchema.remoteDocument) {
+        const resolvedSpec = await resolveOpenAPISpec(inputSchema.remoteDocument);
+        inputSchema.document = resolvedSpec;
+    }
+    return inputSchema;
+}