@smartbear/mcp 0.1.1 → 0.2.0

package/README.md

@@ -70,13 +70,6 @@ REFLECT_API_TOKEN=your_reflect_token INSIGHT_HUB_AUTH_TOKEN=your_insight_hub_tok
 
 This will open an inspector window in your browser, where you can test the tools.
 
-## 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.
-
 ## Supported Tools
 
 See individual guides for suggested prompts and supported tools and resources:
@@ -86,6 +79,15 @@ See individual guides for suggested prompts and supported tools and resources:
 - [Reflect](./reflect/README.md)
 - [API Hub](./api-hub/README.md)
 
+## 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.
+
 ## Local Development
 
 If you want to build and run the MCP server from source (for development or contribution):

package/dist/index.js

@@ -35,7 +35,8 @@ async function main() {
         reflectClient.registerResources(server);
     }
     if (insightHubToken) {
-        const insightHubClient = new InsightHubClient(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);
     }

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

@@ -2,7 +2,7 @@ import { BaseAPI, pickFieldsFromArray } from './base.js';
 // --- API Class ---
 export class CurrentUserAPI extends BaseAPI {
     static organizationFields = ['id', 'name'];
-    static projectFields = ['id', 'name', 'slug'];
+    static projectFields = ['id', 'name', 'slug', 'api_key'];
     constructor(configuration) {
         super(configuration);
     }

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

@@ -1,4 +1,5 @@
 import { BaseAPI } from './base.js';
+import { toQueryString } from './filters.js';
 // --- API Class ---
 export class ErrorAPI extends BaseAPI {
     constructor(configuration) {
@@ -58,4 +59,17 @@ export class ErrorAPI extends BaseAPI {
             url,
         }));
     }
+    /**
+     * List the Errors on a Project
+     * GET /projects/{project_id}/errors
+     */
+    async listProjectErrors(projectId, options = {}) {
+        const url = options.filters
+            ? `/projects/${projectId}/errors?${toQueryString(options.filters)}`
+            : `/projects/${projectId}/errors`;
+        return (await this.request({
+            method: 'GET',
+            url,
+        }));
+    }
 }

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

@@ -0,0 +1,28 @@
+import { BaseAPI, pickFieldsFromArray } from "./base.js";
+// --- API Class ---
+export class ProjectAPI extends BaseAPI {
+    static eventFieldFields = [
+        'custom',
+        'display_id',
+        'filter_options',
+        'pivot_options'
+    ];
+    constructor(configuration) {
+        super(configuration);
+    }
+    /**
+     * List the Event Fields for a Project
+     * GET /projects/{project_id}/event_fields
+     * @param projectId The project ID
+     * @returns A promise that resolves to the list of event fields
+     */
+    async listProjectEventFields(projectId) {
+        const url = `/projects/${projectId}/event_fields`;
+        const data = await this.request({
+            method: 'GET',
+            url,
+        });
+        // Only return allowed fields
+        return pickFieldsFromArray(data, ProjectAPI.eventFieldFields);
+    }
+}

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

@@ -33,6 +33,10 @@ export class BaseAPI {
         let nextUrl = url;
         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}`);
+            }
             const data = await response.json();
             if (paginate) {
                 results = results.concat(data);

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

@@ -0,0 +1,167 @@
+/**
+ * Filters utility for Insight Hub API
+ *
+ * This file provides utility functions for creating filter URL parameters
+ * based on the Insight Hub filtering specification described in the Filtering.md document.
+ */
+import { z } from "zod";
+export const FilterValueSchema = z.object({
+    type: z.enum(['eq', 'ne', 'empty']),
+    value: z.union([z.string(), z.boolean(), z.number()]),
+});
+export const FilterObjectSchema = z.record(z.array(FilterValueSchema));
+/**
+ * Creates a filter value object for equality comparison
+ *
+ * @param value The value to compare against
+ * @returns FilterValue with type 'eq'
+ */
+export function equals(value) {
+    return {
+        type: 'eq',
+        value,
+    };
+}
+/**
+ * Creates a filter value object for inequality comparison
+ *
+ * @param value The value to compare against
+ * @returns FilterValue with type 'ne'
+ */
+export function notEquals(value) {
+    return {
+        type: 'ne',
+        value,
+    };
+}
+/**
+ * Creates a filter value object for checking if a field is empty or not
+ *
+ * @param isEmpty Whether the field should be empty (true) or not (false)
+ * @returns FilterValue with type 'empty'
+ */
+export function empty(isEmpty) {
+    return {
+        type: 'empty',
+        value: isEmpty.toString(),
+    };
+}
+/**
+ * Creates a relative time filter for event.since or event.before
+ *
+ * @param value The amount of time
+ * @param unit The time unit ('h' for hours, 'd' for days)
+ * @returns FilterValue for the relative time
+ */
+export function relativeTime(value, unit) {
+    return {
+        type: 'eq',
+        value: `${value}${unit}`,
+    };
+}
+/**
+ * Creates an ISO 8601 time filter (must be in UTC format like 2018-05-20T00:00:00Z)
+ *
+ * @param date The date object to convert to ISO string
+ * @returns FilterValue for the ISO time
+ */
+export function isoTime(date) {
+    return {
+        type: 'eq',
+        value: date.toISOString(),
+    };
+}
+/**
+ * Converts a FilterObject to URL search parameters
+ *
+ * @param filters The filter object to convert
+ * @returns URLSearchParams object with the encoded filters
+ */
+export function toUrlSearchParams(filters) {
+    const params = new URLSearchParams();
+    Object.entries(filters).forEach(([field, filterValues]) => {
+        filterValues.forEach((filterValue) => {
+            params.append(`filters[${field}][][type]`, filterValue.type);
+            params.append(`filters[${field}][][value]`, filterValue.value.toString());
+        });
+    });
+    return params;
+}
+/**
+ * Converts a FilterObject to a query string
+ *
+ * @param filters The filter object to convert
+ * @returns Query string representation of the filters
+ */
+export function toQueryString(filters) {
+    return toUrlSearchParams(filters).toString();
+}
+/**
+ * Helper to build a FilterObject with type safety
+ *
+ * @returns An empty FilterObject that can be built upon
+ */
+export function createFilter() {
+    return {};
+}
+/**
+ * Adds a field filter to an existing FilterObject
+ *
+ * @param filters The FilterObject to add to
+ * @param field The field name (e.g., 'error.status', 'event.since')
+ * @param filterValue The FilterValue to add
+ * @returns The updated FilterObject for chaining
+ */
+export function addFilter(filters, field, filterValue) {
+    if (!filters[field]) {
+        filters[field] = [];
+    }
+    filters[field].push(filterValue);
+    return filters;
+}
+/**
+ * Utility to create a time range filter between two dates
+ *
+ * @param filters The FilterObject to add to
+ * @param since Start date
+ * @param before End date
+ * @returns The updated FilterObject for chaining
+ */
+export function addTimeRange(filters, since, before) {
+    addFilter(filters, 'event.since', isoTime(since));
+    addFilter(filters, 'event.before', isoTime(before));
+    return filters;
+}
+/**
+ * Utility to create a relative time range filter
+ *
+ * @param filters The FilterObject to add to
+ * @param amount The amount of time (e.g., 7 for 7 days)
+ * @param unit The time unit ('h' for hours, 'd' for days)
+ * @returns The updated FilterObject for chaining
+ */
+export function addRelativeTimeRange(filters, amount, unit) {
+    addFilter(filters, 'event.since', relativeTime(amount, unit));
+    return filters;
+}
+/**
+ * Usage examples:
+ *
+ * // Example 1: Open errors with events in the last day
+ * const filters = createFilter();
+ * addRelativeTimeRange(filters, 1, 'd');
+ * addFilter(filters, 'error.status', equals('open'));
+ * const queryString = toQueryString(filters);
+ *
+ * // Example 2: Events affecting specific users on a specific day
+ * const filters = createFilter();
+ * addTimeRange(filters, new Date('2017-01-01'), new Date('2017-01-02'));
+ * addFilter(filters, 'user.email', equals('user1@example.com'));
+ * addFilter(filters, 'user.email', equals('user2@example.com'));
+ * const queryString = toQueryString(filters);
+ *
+ * // Example 3: Events that have user data
+ * const filters = createFilter();
+ * addFilter(filters, 'user.id', empty(false));
+ * const queryString = toQueryString(filters);
+ */

package/dist/insight-hub/client.js

@@ -3,20 +3,71 @@ import { MCP_SERVER_NAME, MCP_SERVER_VERSION } from "../common/info.js";
 import { CurrentUserAPI, ErrorAPI, Configuration } from "./client/index.js";
 import { z } from "zod";
 import Bugsnag from "../common/bugsnag.js";
+import NodeCache from "node-cache";
+import { ProjectAPI } from "./client/api/Project.js";
+import { FilterObjectSchema } from "./client/api/filters.js";
+const HUB_PREFIX = "00000";
+const HUB_API_ENDPOINT = "https://api.insighthub.smartbear.com";
+const DEFAULT_API_ENDPOINT = "https://api.bugsnag.com";
+const cacheKeys = {
+    ORG: "insight_hub_org",
+    PROJECTS: "insight_hub_projects",
+    CURRENT_PROJECT: "insight_hub_current_project",
+    PROJECT_EVENT_FILTERS: "insight_hub_project_event_filters",
+};
 export class InsightHubClient {
     currentUserApi;
     errorsApi;
-    constructor(token) {
+    cache;
+    projectApi;
+    projectApiKey;
+    constructor(token, projectApiKey, endpoint) {
+        if (!endpoint) {
+            if (projectApiKey && projectApiKey.startsWith(HUB_PREFIX)) {
+                endpoint = HUB_API_ENDPOINT;
+            }
+            else {
+                endpoint = DEFAULT_API_ENDPOINT;
+            }
+        }
         const config = new Configuration({
             authToken: token,
             headers: {
                 "User-Agent": `${MCP_SERVER_NAME}/${MCP_SERVER_VERSION}`,
                 "Content-Type": "application/json",
             },
-            basePath: "https://api.bugsnag.com",
+            basePath: endpoint,
         });
         this.currentUserApi = new CurrentUserAPI(config);
         this.errorsApi = new ErrorAPI(config);
+        this.cache = new NodeCache();
+        this.projectApi = new ProjectAPI(config);
+        this.projectApiKey = projectApiKey;
+    }
+    async initialize() {
+        const orgs = await this.listOrgs();
+        if (!orgs || orgs.length === 0) {
+            throw new Error("No organizations found for the current user.");
+        }
+        // We should only have one org
+        this.cache.set(cacheKeys.ORG, orgs[0]);
+        const projects = await this.listProjects(orgs[0].id);
+        this.cache.set(cacheKeys.PROJECTS, projects);
+        if (this.projectApiKey) {
+            const project = projects.find((project) => project.api_key === this.projectApiKey);
+            if (!project) {
+                throw new Error(`Project with API key ${this.projectApiKey} not found in organization ${orgs[0].name}.`);
+            }
+            this.cache.set(cacheKeys.CURRENT_PROJECT, project);
+            const projectFields = await this.listProjectEventFields(project.id);
+            if (!projectFields || projectFields.length === 0) {
+                throw new Error(`No event fields found for project ${project.name}.`);
+            }
+            this.cache.set(cacheKeys.PROJECT_EVENT_FILTERS, projectFields);
+        }
+    }
+    async listProjectEventFields(projectId) {
+        return this.projectApi.listProjectEventFields(projectId);
     }
     async listOrgs() {
         return this.currentUserApi.listUserOrganizations();
@@ -28,6 +79,25 @@ export class InsightHubClient {
         };
         return this.currentUserApi.getOrganizationProjects(orgId, options);
     }
+    // This method retrieves all projects for the organization stored in the cache.
+    // If no projects are found in the cache, it fetches them from the API and
+    // stores them in the cache for future use.
+    // It throws an error if no organizations are found in the cache.
+    async getProjects() {
+        let projects = this.cache.get(cacheKeys.PROJECTS);
+        if (!projects) {
+            const org = this.cache.get(cacheKeys.ORG);
+            if (!org) {
+                throw new Error("No organization found in cache.");
+            }
+            projects = await this.listProjects(org.id);
+            this.cache.set(cacheKeys.PROJECTS, projects);
+        }
+        if (!projects) {
+            throw new Error("No projects found.");
+        }
+        return projects;
+    }
     async getErrorDetails(projectId, errorId) {
         return this.errorsApi.viewErrorOnProject(projectId, errorId);
     }
@@ -42,29 +112,46 @@ export class InsightHubClient {
         const eventDetails = await Promise.all(projects.map((p) => this.getProjectEvent(p.id, eventId).catch(_e => null)));
         return eventDetails.find(event => !!event);
     }
+    async listProjectErrors(projectId, filters) {
+        return this.errorsApi.listProjectErrors(projectId, { filters });
+    }
     registerTools(server) {
-        server.tool("list_insight_hub_projects", "List all projects in an organization", { orgId: z.string().describe("ID of the organization to list projects for") }, async (args, _extra) => {
-            try {
-                if (!args.orgId)
-                    throw new Error("orgId argument is required");
-                const response = await this.listProjects(args.orgId);
-                return {
-                    content: [{ type: "text", text: JSON.stringify(response) }],
-                };
-            }
-            catch (e) {
-                Bugsnag.notify(e);
-                throw e;
-            }
-        });
+        if (!this.projectApiKey) {
+            server.tool("list_insight_hub_projects", "List all projects in an organization.", {
+                page_size: z.number().optional().describe("Number of projects to return per page"),
+                page: z.number().optional().describe("Page number to return"),
+            }, async (args, _extra) => {
+                try {
+                    let projects = await this.getProjects();
+                    if (!projects || projects.length === 0) {
+                        return {
+                            content: [{ type: "text", text: "No projects found." }],
+                        };
+                    }
+                    if (args.page_size || args.page) {
+                        const pageSize = args.page_size || 10;
+                        const page = args.page || 1;
+                        projects = projects.slice((page - 1) * pageSize, page * pageSize);
+                    }
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(projects) }],
+                    };
+                }
+                catch (e) {
+                    Bugsnag.notify(e);
+                    throw e;
+                }
+            });
+        }
         server.tool("get_insight_hub_error", "Get error details from a project", {
-            projectId: z.string().describe("ID of the project"),
             errorId: z.string().describe("ID of the error to fetch"),
+            ...(!this.projectApiKey ? { projectId: z.string().optional().describe("ID of the project") } : {}),
         }, async (args, _extra) => {
             try {
-                if (!args.projectId || !args.errorId)
+                const projectId = typeof args.projectId === 'string' ? args.projectId : this.cache.get(cacheKeys.CURRENT_PROJECT)?.id;
+                if (!projectId || !args.errorId)
                     throw new Error("Both projectId and errorId arguments are required");
-                const response = await this.getErrorDetails(args.projectId, args.errorId);
+                const response = await this.getErrorDetails(projectId, args.errorId);
                 return {
                     content: [{ type: "text", text: JSON.stringify(response) }],
                 };
@@ -102,9 +189,14 @@ export class InsightHubClient {
                 if (!projectSlug || !eventId)
                     throw new Error("Both projectSlug and eventId must be present in the link");
                 // get the project id from list of projects
-                // limitation: this assumes a single page of results, so will not work for orgs with >100 projects
-                const orgId = await this.currentUserApi.listUserOrganizations().then(orgs => orgs[0].id);
-                const projectId = await this.listProjects(orgId).then(projects => projects.find((p) => p.slug === projectSlug)?.id);
+                const projects = this.cache.get("insight_hub_projects");
+                if (!projects) {
+                    throw new Error("No projects found in cache.");
+                }
+                const projectId = projects.find((p) => p.slug === projectSlug)?.id;
+                if (!projectId) {
+                    throw new Error("Project with the specified slug not found.");
+                }
                 const response = await this.getProjectEvent(projectId, eventId);
                 return {
                     content: [{ type: "text", text: JSON.stringify(response) }],
@@ -115,15 +207,45 @@ export class InsightHubClient {
                 throw e;
             }
         });
-    }
-    registerResources(server) {
-        server.resource("insight_hub_orgs", "insighthub://orgs", { description: "List all organizations in Insight Hub", mimeType: "application/json" }, async (uri) => {
+        // Dynamically infer the filters schema from cached project event fields
+        server.tool("list_insight_hub_project_errors", "List errors in the current project based on a set of event filters. Use this tool to find or list errors based on user-provided search filters. You can use the `get_project_event_filters` tool to find valid filters for the current project.", {
+            filters: FilterObjectSchema.optional().describe("Filters to apply to the error list. Valid filters for a project can be found in the `get_project_event_filters` tool."),
+            // Conditionally add projectId only when no project API key is configured
+            ...(this.projectApiKey ? {} : {
+                projectId: z.string().describe("ID of the project"),
+            }),
+        }, async (args, _extra) => {
             try {
+                const projectId = typeof args.projectId === 'string' ? args.projectId : this.cache.get(cacheKeys.CURRENT_PROJECT)?.id;
+                if (!projectId)
+                    throw new Error("projectId argument is required");
+                // Optionally, validate filter keys against cached event fields
+                const eventFields = this.cache.get(cacheKeys.PROJECT_EVENT_FILTERS) || [];
+                if (args.filters) {
+                    const validKeys = new Set(eventFields.map(f => f.display_id));
+                    for (const key of Object.keys(args.filters)) {
+                        if (!validKeys.has(key)) {
+                            throw new Error(`Invalid filter key: ${key}`);
+                        }
+                    }
+                }
+                const response = await this.listProjectErrors(projectId, args.filters);
                 return {
-                    contents: [{
-                            uri: uri.href,
-                            text: JSON.stringify(await this.listOrgs())
-                        }]
+                    content: [{ type: "text", text: JSON.stringify(response) }],
+                };
+            }
+            catch (e) {
+                Bugsnag.notify(e);
+                throw e;
+            }
+        });
+        server.tool("get_project_event_filters", "Get the available event filters for the current project. Use this tool to find valid filters for the `list_insight_hub_project_errors` tool.", {}, async (_args, _extra) => {
+            try {
+                const eventFields = this.cache.get(cacheKeys.PROJECT_EVENT_FILTERS);
+                if (!eventFields)
+                    throw new Error("No event filters found in cache.");
+                return {
+                    content: [{ type: "text", text: JSON.stringify(eventFields) }],
                 };
             }
             catch (e) {
@@ -131,6 +253,8 @@ export class InsightHubClient {
                 throw e;
             }
         });
+    }
+    registerResources(server) {
         server.resource("insight_hub_event", new ResourceTemplate("insighthub://event/{id}", { list: undefined }), async (uri, { id }) => {
             try {
                 return {

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@smartbear/mcp",
-    "version": "0.1.1",
+    "version": "0.2.0",
     "description": "MCP server for interacting SmartBear Products",
     "keywords": [
         "smartbear",
@@ -35,7 +35,8 @@
     },
     "dependencies": {
         "@bugsnag/js": "^8.2.0",
-        "@modelcontextprotocol/sdk": "1.12.1"
+        "@modelcontextprotocol/sdk": "1.12.1",
+        "node-cache": "^5.1.2"
     },
     "devDependencies": {
         "@eslint/js": "^9.29.0",

package/insight-hub/README.md

@@ -2,6 +2,8 @@
 
 Fetch details of your app crashes and errors from your [Insight Hub](https://www.smartbear.com/insight-hub) dashboard for your LLM to help you diagnose and fix.
 
+To connect an MCP server, you will need to create a personal auth token from the user settings page on your Insight Hub dashboard. If you wish to interact with only one Insight Hub project, we also recommend setting `INSIGHT_HUB_PROJECT_API_KEY` to reduce the scope of the conversation.
+
 ## Example prompts
 
 - "Help me fix this crash from Insight Hub: https://app.bugsnag.com/my-org/my-project/errors/1a2b3c4d5e6f7g8h9i0j1k2l?&event_id=1a2b3c4d5e6f7g8h9i0j1k2l"
@@ -9,27 +11,28 @@ Fetch details of your app crashes and errors from your [Insight Hub](https://www
 
 ## Environment Variables
 
-- `INSIGHT_HUB_AUTH_TOKEN`: Required for this client. The auth token for your account from your Insight Hub dashboard, under **Personal auth tokens** in user settings.
-- `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.
+- `INSIGHT_HUB_AUTH_TOKEN`: (Required) The auth token for your account from your Insight Hub dashboard, under **Personal auth tokens** in user settings.
+- `INSIGHT_HUB_PROJECT_API_KEY`: (Optional) The API key for the Insight Hub project you wish to interact with. Use this to scope all operations to a single project.
+- `INSIGHT_HUB_ENDPOINT`: (Optional) The API server to connect to. Use this for on-premise installations to point to your own endpoint (e.g. `https://your.api.server`).
 
 ## Tools
 
 1. `list_insight_hub_projects`
    - List all projects in an organization.
+   - Multi-project mode only.
 2. `get_insight_hub_error`
    - Get error details from a project.
 3. `get_insight_hub_error_latest_event`
    - Get the latest event for an error.
 4. `get_insight_hub_event_details`
-   - Get details of a specific event on Insight Hub.
+   - Get details of a specific event.
+5. `get_project_event_filters`
+   - List the filters available for a project.
+6. `list_insight_hub_project_errors`
+   - List and filter the errors from a project.
 
 ## Resources
 
-- **insight_hub_orgs**
-  - URI: `insighthub://orgs`
-  - Description: Lists all organizations available to your Insight Hub account in JSON format.
-  - Example usage: Retrieve a list of all organizations to get their IDs for use with other tools.
-
 - **insight_hub_event**
   - URI Template: `insighthub://event/{id}`
   - Description: Fetches details for a specific event by its event ID. Returns the event details in JSON format.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartbear/mcp",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "MCP server for interacting SmartBear Products",
   "keywords": [
     "smartbear",
@@ -35,7 +35,8 @@
   },
   "dependencies": {
     "@bugsnag/js": "^8.2.0",
-    "@modelcontextprotocol/sdk": "1.12.1"
+    "@modelcontextprotocol/sdk": "1.12.1",
+    "node-cache": "^5.1.2"
   },
   "devDependencies": {
     "@eslint/js": "^9.29.0",