@smartbear/mcp 0.2.1 → 0.3.0

package/README.md

@@ -1,24 +1,58 @@
 <div align="center">
   <a href="https://www.smartbear.com">
     <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="assets/smartbear-logo-light.svg">
-      <img alt="SmartBear logo" src="assets/smartbear-logo-dark.svg">
+      <source media="(prefers-color-scheme: dark)" srcset="https://assets.smartbear.com/m/79b99a7ff9c81a9a/original/SmartBear-Logo_Dark-Mode.svg">
+      <img alt="SmartBear logo" src="https://assets.smartbear.com/m/105001cc5db1e0bf/original/SmartBear-Logo_Light-Mode.svg">
     </picture>
   </a>
   <h1>SmartBear MCP server</h1>
+
+  <!-- Badges -->
+  <div>
+    <a href="https://github.com/SmartBear/smartbear-mcp/actions/workflows/test.yml"><img src="https://github.com/SmartBear/smartbear-mcp/workflows/Test%20Suite/badge.svg" alt="Test Status"></a>
+    <a href="https://smartbear.github.io/smartbear-mcp/"><img src="https://img.shields.io/badge/coverage-dynamic-brightgreen" alt="Coverage"></a>
+    <a href="https://www.npmjs.com/package/@smartbear/mcp"><img src="https://img.shields.io/npm/v/@smartbear/mcp" alt="npm version"></a>
+    <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-blue" alt="MCP Compatible"></a>
+    <a href="https://developer.smartbear.com/smartbear-mcp"><img src="https://img.shields.io/badge/documentation-latest-blue.svg" alt="Documentation"></a>
+  </div>
 </div>
+<br />
+
+A Model Context Protocol (MCP) server which provides AI assistants with seamless access to SmartBear's suite of testing and monitoring tools, including [Insight Hub](https://www.smartbear.com/insight-hub), [Reflect](https://reflect.run), and [API Hub](https://www.smartbear.com/api-hub).
+
+## What is MCP?
+
+The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) is an open standard that enables AI assistants to securely connect to external data sources and tools. This server exposes SmartBear's APIs through natural language interfaces, allowing you to query your testing data, analyze performance metrics, and manage test automation directly from your AI workflow.
+
+## Supported Tools
+
+See individual guides for suggested prompts and supported tools and resources:
+
+- [Insight Hub](https://developer.smartbear.com/smartbear-mcp/docs/insight-hub-integration) - Comprehensive error monitoring and debugging capabilities
+- [Test Hub](https://developer.smartbear.com/smartbear-mcp/docs/test-hub-integration) - Test management and execution capabilities
+- [API Hub](https://developer.smartbear.com/smartbear-mcp/docs/api-hub-integration) - Portal management capabilities
+
+
+## Prerequisites
+
+- Node.js 20+ and npm
+- Access to SmartBear products (Insight Hub, Reflect, or API Hub)
+- Valid API tokens for the products you want to integrate
+
+## Installation
 
-An [MCP](https://modelcontextprotocol.io) server for SmartBear's API Hub, Test Hub and Insight Hub.
+The MCP server is distributed as an npm package [`@smartbear/mcp`](https://www.npmjs.com/package/@smartbear/mcp), making it easy to integrate into your development workflow.
 
-## Usage
+The server is started with the API key or auth token that you use with your SmartBear product(s). They are optional and can be removed from your configuration if you aren't using the product. For Insight Hub, if you provide a project API key it will narrow down all searches to a single project in your Insight Hub dashboard. Leave this field blank if you wish to interact across multiple projects at a time.
 
-The server is started with the API key or auth token that you use with your product(s). They are optional and can be removed from your configuration if you aren't using the product.
+### VS Code with Copilot
 
-### VS Code
+For the quickest setup, use the "MCP: Add server…" command in the Command Palette to add the `@smartbear/mcp` npm package.
 
-Add the [`@smartbear/mcp`](https://www.npmjs.com/package/@smartbear/mcp) package to your project via NPM or via the "MCP: Add server…" command in VS Code.
+<details>
+<summary><strong>📋 Manual installation</strong></summary>
 
-If setting up manually, add the following configuration to `.vscode/mcp.json`:
+Alternatively, you can use `npx` (or globally install) the `@smartbear/mcp` package to run the server and add the following to your `.vscode/mcp.json` file:
 
 ```json
 {
@@ -66,76 +100,128 @@ If setting up manually, add the following configuration to `.vscode/mcp.json`:
   ]
 }
 ```
+</details>
 
-### MCP Inspector
+### Claude Desktop
 
-To test the MCP server using the npm package, run:
+Add the following configuration to your `claude_desktop_config.json` to launch the MCP server via `npx`:
 
-```bash
-REFLECT_API_TOKEN=your_reflect_token INSIGHT_HUB_AUTH_TOKEN=your_insight_hub_token API_HUB_API_KEY=your_api_hub_api_key npx @smartbear/mcp
+```json
+{
+  "mcpServers": {
+    "smartbear": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@smartbear/mcp@latest"
+      ],
+      "env": {
+        "INSIGHT_HUB_AUTH_TOKEN": "your_personal_auth_token",
+        "INSIGHT_HUB_PROJECT_API_KEY": "your_project_api_key",
+        "REFLECT_API_TOKEN": "your_reflect_token",
+        "API_HUB_API_KEY": "your_api_hub_key"
+      }
+    }
+  }
+}
 ```
 
-This will open an inspector window in your browser, where you can test the tools.
-
-## Supported Tools
-
-See individual guides for suggested prompts and supported tools and resources:
-
-- [Insight Hub](./insight-hub/README.md)\
-  Get your top events and invite your LLM to help you fix them.
-- [Reflect](./reflect/README.md)
-- [API Hub](./api-hub/README.md)
+## Documentation
 
-## Environment Variables
-
-- `INSIGHT_HUB_AUTH_TOKEN`: Required for Insight Hub tools. The Auth Token for Insight Hub.
-- `REFLECT_API_TOKEN`: Required for Reflect tools. The Reflect Account API Key for Reflect-based tools.
-- `API_HUB_API_KEY`: Required for API Hub tools. The API Key for API Hub tools.
-- `MCP_SERVER_INSIGHT_HUB_API_KEY`: Optional. If set, enables error reporting of the _MCP_server_ code via the BugSnag SDK. This is useful for debugging and monitoring of the MCP server itself and shouldn't be set to the same API key as your app.
-
-See individual guides for product-specific configuration via environment variables.
+For detailed introduction, examples, and advanced configuration visit our 📖 [Full Documentation](https://developer.smartbear.com/smartbear-mcp)
 
 ## Local Development
 
-If you want to build and run the MCP server from source (for development or contribution):
-
-### Build
+For developers who want to contribute to the SmartBear MCP server, customize its functionality, or work with the latest development features, you can build and run the server directly from source code. This approach gives you full control over the implementation and allows you to make modifications as needed.
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/SmartBear/smartbear-mcp.git
+   cd smartbear-mcp
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   npm install
+   ```
+
+3. **Build the server:**
+   ```bash
+   npm run build
+   ```
+
+4. **Add the server to your IDE** configuration updating `.vscode/mcp.json` (or equivalent) to point to your local build
+
+    <details>
+    <summary><strong>📋 VSCode (mcp.json)</strong></summary>
+
+    ```json
+    {
+      "servers": {
+        "smartbear": {
+        "type": "stdio",
+        "command": "node",
+        "dev": {                            // <-- To allow debugging in VS Code
+          "watch": "dist/**/*.js",
+          "debug": {
+              "type": "node"
+          },
+        },
+        "args": ["<PATH_TO_SMARTBEAR_MCP_REPO>/dist/index.js"],
+        "env": {
+            "INSIGHT_HUB_AUTH_TOKEN": "${input:insight_hub_auth_token}",
+            "INSIGHT_HUB_PROJECT_API_KEY": "${input:insight_hub_project_api_key}",
+            "REFLECT_API_TOKEN": "${input:reflect_api_token}",
+            "API_HUB_API_KEY": "${input:api_hub_api_key}"
+          }
+        }
+      },
+      "inputs": [
+        {
+          "id": "insight_hub_auth_token",
+          "type": "promptString",
+          "description": "Insight Hub Auth Token - leave blank to disable Insight Hub tools",
+          "password": true
+        },
+        {
+          "id": "insight_hub_project_api_key",
+          "type": "promptString",
+          "description": "Insight Hub Project API Key - for single project interactions",
+          "password": false
+        },
+        {
+          "id": "reflect_api_token",
+          "type": "promptString",
+          "description": "Reflect API Token - leave blank to disable Reflect tools",
+          "password": true
+        },
+        {
+          "id": "api_hub_api_key",
+          "type": "promptString",
+          "description": "API Hub API Key - leave blank to disable API Hub tools",
+          "password": true
+        }
+      ]
+    }
+    ```
+    </details>
 
-Clone this repository and run:
+5. **Local testing** using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) web interface:
 
-```bash
-npm install
-npm run build
-```
+    ```bash
+    INSIGHT_HUB_AUTH_TOKEN="your_token" REFLECT_API_TOKEN="your_reflect_token" API_HUB_API_KEY="your_api_hub_key" npx @modelcontextprotocol/inspector npx @smartbear/mcp@latest
+    ```
 
-### Usage (Local Build)
+## License
 
-Update your `.vscode/mcp.json` to point to your local build:
+This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the [LICENSE](LICENSE.txt) file in the project repository.
 
-```json
-{
-  "servers": {
-    "smartbear": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["<PATH_TO_SMARTBEAR_MCP>/dist/index.js"],
-      "env": {
-        // ...same as above...
-      }
-    }
-  },
-  "inputs": [
-    // ...same as above...
-  ]
-}
-```
+## Support
 
-Or run the server directly:
+* [Search open and closed issues](https://github.com/SmartBear/smartbear-mcp/issues?utf8=✓&q=is%3Aissue) for similar problems
+* [Report a bug or request a feature](https://github.com/SmartBear/smartbear-mcp/issues/new)
 
-```bash
-REFLECT_API_TOKEN=your_reflect_token INSIGHT_HUB_AUTH_TOKEN=your_insight_hub_token API_HUB_API_KEY=your_api_hub_api_key node dist/index.js
-```
 
-## License
+---
 
-This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
+**SmartBear MCP Server** - Bringing the power of SmartBear's testing and monitoring ecosystem to your AI-powered development workflow.

package/dist/api-hub/client.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { MCP_SERVER_NAME, MCP_SERVER_VERSION } from "../common/info.js";
 // Tool definitions for API Hub API client
 export class ApiHubClient {
     headers;
@@ -6,6 +7,7 @@ export class ApiHubClient {
         this.headers = {
             "Authorization": `Bearer ${token}`,
             "Content-Type": "application/json",
+            "User-Agent": `${MCP_SERVER_NAME}/${MCP_SERVER_VERSION}`,
         };
     }
     async getPortals() {

package/dist/common/templates.js

@@ -1,10 +1,13 @@
 export function toolDescriptionTemplate(params) {
-    const { summary, useCases, examples, parameters, hints } = params;
+    const { summary, useCases, examples, parameters, hints, outputFormat } = params;
     let description = summary;
     // Parameters (essential)
     if (parameters.length > 0) {
         description += `\n\n**Parameters:** ${parameters.map(p => `${p.name} (${p.type})${p.required ? ' *required*' : ''}`).join(', ')}`;
     }
+    if (outputFormat) {
+        description += `\n\n**Output Format:** ${outputFormat}`;
+    }
     // Use Cases
     if (useCases.length > 0) {
         description += `\n\n**Use Cases:** ${useCases.map((uc, i) => `${i + 1}. ${uc}`).join(' ')}`;

package/dist/insight-hub/client/api/CurrentUser.js

@@ -1,7 +1,7 @@
 import { BaseAPI, pickFieldsFromArray } from './base.js';
 // --- API Class ---
 export class CurrentUserAPI extends BaseAPI {
-    static organizationFields = ['id', 'name'];
+    static organizationFields = ['id', 'name', 'slug'];
     static projectFields = ['id', 'name', 'slug', 'api_key'];
     constructor(configuration) {
         super(configuration);
@@ -25,7 +25,10 @@ export class CurrentUserAPI extends BaseAPI {
             url,
         }, paginate);
         // Only return allowed fields
-        return pickFieldsFromArray(data, CurrentUserAPI.organizationFields);
+        return {
+            ...data,
+            body: pickFieldsFromArray(data.body || [], CurrentUserAPI.organizationFields)
+        };
     }
     /**
      * List projects for a given organization
@@ -49,6 +52,9 @@ export class CurrentUserAPI extends BaseAPI {
             url,
         }, paginate);
         // Only return allowed fields
-        return pickFieldsFromArray(data, CurrentUserAPI.projectFields);
+        return {
+            ...data,
+            body: pickFieldsFromArray(data.body || [], CurrentUserAPI.projectFields)
+        };
     }
 }

package/dist/insight-hub/client/api/Error.js

@@ -1,5 +1,25 @@
 import { BaseAPI } from './base.js';
 import { toQueryString } from './filters.js';
+export const ErrorOperations = [
+    'override_severity',
+    'assign',
+    'create_issue',
+    'link_issue',
+    'unlink_issue',
+    'open',
+    'snooze',
+    'fix',
+    'ignore',
+    'delete',
+    'discard',
+    'undiscard'
+];
+export const ReopenConditions = [
+    'occurs_after',
+    'n_occurrences_in_m_hours',
+    'n_additional_occurrences',
+    'n_additional_users'
+];
 // --- API Class ---
 export class ErrorAPI extends BaseAPI {
     constructor(configuration) {
@@ -41,6 +61,17 @@ export class ErrorAPI extends BaseAPI {
             url,
         }));
     }
+    /**
+     * List the Events on a Project
+     * GET /projects/{project_id}/events
+     */
+    async listEventsOnProject(projectId, queryString = '') {
+        const url = `/projects/${projectId}/events${queryString}`;
+        return await this.request({
+            method: 'GET',
+            url,
+        });
+    }
     /**
      * View an Event by ID
      * GET /projects/{project_id}/events/{event_id}
@@ -72,4 +103,54 @@ export class ErrorAPI extends BaseAPI {
             url,
         }));
     }
+    /**
+     * Update an Error on a Project
+     * PATCH /projects/{project_id}/errors/{error_id}
+     */
+    async updateErrorOnProject(projectId, errorId, data, options = {}) {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(options)) {
+            if (value !== undefined)
+                params.append(key, String(value));
+        }
+        const url = params.toString()
+            ? `/projects/${projectId}/errors/${errorId}?${params}`
+            : `/projects/${projectId}/errors/${errorId}`;
+        return (await this.request({
+            method: 'PATCH',
+            url,
+            body: data,
+        }));
+    }
+    /**
+     * List Pivots on an Error
+     * GET /projects/{project_id}/errors/{error_id}/pivots
+     */
+    async listErrorPivots(projectId, errorId, options = {}) {
+        const params = new URLSearchParams();
+        if (options.filters) {
+            const filterParams = new URLSearchParams(toQueryString(options.filters));
+            filterParams.forEach((value, key) => {
+                params.append(key, value);
+            });
+        }
+        if (options.summary_size !== undefined) {
+            params.append('summary_size', options.summary_size.toString());
+        }
+        if (options.pivots && options.pivots.length > 0) {
+            options.pivots.forEach(pivot => {
+                params.append('pivots[]', pivot);
+            });
+        }
+        if (options.per_page !== undefined) {
+            params.append('per_page', options.per_page.toString());
+        }
+        const url = params.toString()
+            ? `/projects/${projectId}/errors/${errorId}/pivots?${params}`
+            : `/projects/${projectId}/errors/${errorId}/pivots`;
+        return await this.request({
+            method: 'GET',
+            url,
+        });
+    }
 }

package/dist/insight-hub/client/api/Project.js

@@ -23,6 +23,24 @@ export class ProjectAPI extends BaseAPI {
             url,
         });
         // Only return allowed fields
-        return pickFieldsFromArray(data, ProjectAPI.eventFieldFields);
+        return {
+            ...data,
+            body: pickFieldsFromArray(data.body || [], ProjectAPI.eventFieldFields)
+        };
+    }
+    /**
+     * Create a Project in an Organization
+     * POST /organizations/{organization_id}/projects
+     * @param organizationId The organization ID
+     * @param data The project creation request body
+     * @returns A promise that resolves to the created project
+     */
+    async createProject(organizationId, data) {
+        const url = `/organizations/${organizationId}/projects`;
+        return await this.request({
+            method: 'POST',
+            url,
+            body: data,
+        });
     }
 }

package/dist/insight-hub/client/api/base.js

@@ -31,12 +31,17 @@ export class BaseAPI {
         const url = options.url.startsWith('http') ? options.url : `${this.configuration.basePath || ''}${options.url}`;
         let results = [];
         let nextUrl = url;
+        let apiResponse;
         do {
             const response = await fetch(nextUrl, fetchOptions);
             if (!response.ok) {
                 const errorText = await response.text();
                 throw new Error(`Request failed with status ${response.status}: ${errorText}`);
             }
+            apiResponse = {
+                status: response.status,
+                headers: response.headers
+            };
             const data = await response.json();
             if (paginate) {
                 results = results.concat(data);
@@ -50,9 +55,12 @@ export class BaseAPI {
                 }
             }
             else {
-                return data;
+                apiResponse.body = data;
             }
         } while (paginate && nextUrl);
-        return results;
+        if (paginate) {
+            apiResponse.body = results;
+        }
+        return apiResponse;
     }
 }