@smartbear/mcp 0.1.1 → 0.2.1

package/README.md

@@ -32,6 +32,7 @@ If setting up manually, add the following configuration to `.vscode/mcp.json`:
       ],
       "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}"
       }
@@ -41,19 +42,25 @@ If setting up manually, add the following configuration to `.vscode/mcp.json`:
       {
          "id": "insight_hub_auth_token",
          "type": "promptString",
-         "description": "Insight Hub Auth Token",
+         "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",
+         "description": "Reflect API Token - leave blank to disable Reflect tools",
          "password": true
       },
       {
          "id": "api_hub_api_key",
          "type": "promptString",
-         "description": "API Hub API Key",
+         "description": "API Hub API Key - leave blank to disable API Hub tools",
          "password": true
       }
   ]
@@ -70,13 +77,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 +86,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):
@@ -111,9 +120,7 @@ Update your `.vscode/mcp.json` to point to your local build:
       "command": "node",
       "args": ["<PATH_TO_SMARTBEAR_MCP>/dist/index.js"],
       "env": {
-        "INSIGHT_HUB_AUTH_TOKEN": "${input:insight_hub_auth_token}",
-        "REFLECT_API_TOKEN": "${input:reflect_api_token}",
-        "API_HUB_API_KEY": "${input:api_hub_api_key}"
+        // ...same as above...
       }
     }
   },

package/dist/common/templates.js

@@ -0,0 +1,54 @@
+export function toolDescriptionTemplate(params) {
+    const { summary, useCases, examples, parameters, hints } = 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(', ')}`;
+    }
+    // Use Cases
+    if (useCases.length > 0) {
+        description += `\n\n**Use Cases:** ${useCases.map((uc, i) => `${i + 1}. ${uc}`).join(' ')}`;
+    }
+    // Examples
+    if (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.length > 0) {
+        description += `\n\n**Tips:** ${hints.map((hint, i) => `${i + 1}. ${hint}`).join(' ')}`;
+    }
+    return description.trim();
+}
+// Backward-compatible version of the original function
+export function simpleToolDescriptionTemplate(summary, useCases, examples, hints) {
+    return toolDescriptionTemplate({
+        summary,
+        purpose: summary,
+        useCases,
+        examples: examples.map(example => ({
+            description: example,
+            parameters: {}
+        })),
+        parameters: [],
+        hints
+    });
+}
+// Helper function to create parameter descriptions
+export function createParameter(name, type, required, description, options = {}) {
+    return {
+        name,
+        type,
+        required,
+        description,
+        examples: options.examples,
+        constraints: options.constraints
+    };
+}
+// Helper function to create examples with proper structure
+export function createExample(description, parameters, expectedOutput) {
+    return {
+        description,
+        parameters,
+        expectedOutput
+    };
+}

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,74 @@ 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";
+import { toolDescriptionTemplate, createParameter, createExample } from "../common/templates.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",
+                "X-Bugsnag-API": "true",
+                "X-Version": "2",
             },
-            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 +82,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 +115,104 @@ 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.registerTool("list_insight_hub_projects", {
+                description: toolDescriptionTemplate({
+                    summary: "List all projects in the organization with optional pagination",
+                    purpose: "Retrieve available projects for browsing and selecting which project to analyze",
+                    useCases: [
+                        "Browse available projects when no specific project API key is configured",
+                        "Find project IDs needed for other tools",
+                        "Get an overview of all projects in the organization"
+                    ],
+                    parameters: [
+                        createParameter("page_size", "number", false, "Number of projects to return per page for pagination", {
+                            examples: ["10", "25", "50"]
+                        }),
+                        createParameter("page", "number", false, "Page number to return (starts from 1)", {
+                            examples: ["1", "2", "3"]
+                        })
+                    ],
+                    examples: [
+                        createExample("Get first 10 projects", {
+                            page_size: 10,
+                            page: 1
+                        }, "JSON array of project objects with IDs, names, and metadata"),
+                        createExample("Get all projects (no pagination)", {}, "JSON array of all available projects")
+                    ],
+                    hints: [
+                        "Use pagination for organizations with many projects to avoid large responses",
+                        "Project IDs from this list can be used with other tools when no project API key is configured"
+                    ]
+                }),
+                inputSchema: {
+                    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.registerTool("get_insight_hub_error", {
+            description: toolDescriptionTemplate({
+                summary: "Get detailed information about a specific error from a project",
+                purpose: "Retrieve error details including metadata, events, and context for debugging",
+                useCases: [
+                    "Investigate a specific error found through list_insight_hub_project_errors",
+                    "Get error details for debugging and root cause analysis",
+                    "Retrieve error metadata for incident reports and documentation"
+                ],
+                parameters: [
+                    createParameter("errorId", "string", true, "Unique identifier of the error to retrieve", {
+                        examples: ["6863e2af8c857c0a5023b411"]
+                    }),
+                    ...(!this.projectApiKey ? [
+                        createParameter("projectId", "string", false, "ID of the project containing the error (optional if project API key is configured)")
+                    ] : [])
+                ],
+                examples: [
+                    createExample("Get details for a specific error", {
+                        errorId: "6863e2af8c857c0a5023b411"
+                    }, "JSON object with error details including message, stack trace, occurrence count, and metadata")
+                ],
+                hints: [
+                    "Error IDs can be found using the list_insight_hub_project_errors tool",
+                    "Use this after filtering errors to get detailed information about specific errors"
+                ]
+            }),
+            inputSchema: {
+                errorId: z.string().describe("ID of the error to fetch"),
+                ...(!this.projectApiKey ? { projectId: z.string().optional().describe("ID of the project") } : {}),
             }
-        });
-        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"),
         }, 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) }],
                 };
@@ -74,8 +222,33 @@ export class InsightHubClient {
                 throw e;
             }
         });
-        server.tool("get_insight_hub_error_latest_event", "Get the latest event for an error", {
-            errorId: z.string().describe("ID of the error to get the latest event for"),
+        server.registerTool("get_insight_hub_error_latest_event", {
+            description: toolDescriptionTemplate({
+                summary: "Get the most recent event of a specific error",
+                purpose: "Retrieve the latest event (occurrence) of an error to understand when it last happened and its details",
+                useCases: [
+                    "Get the most recent occurrence of an error for immediate debugging",
+                    "Understand the latest context and stack trace for an ongoing issue",
+                    "Check when an error last occurred and with what parameters"
+                ],
+                parameters: [
+                    createParameter("errorId", "string", true, "Unique identifier of the error to get the latest event for", {
+                        examples: ["6863e2af8c857c0a5023b411"]
+                    })
+                ],
+                examples: [
+                    createExample("Get the latest event for an error", {
+                        errorId: "6863e2af8c857c0a5023b411"
+                    }, "JSON object with the most recent event details including timestamp, stack trace, and context")
+                ],
+                hints: [
+                    "This shows the most recent occurrence - use get_insight_hub_error for aggregated details of all events grouped into the error",
+                    "The event includes detailed context like user information, request data, and environment details"
+                ]
+            }),
+            inputSchema: {
+                errorId: z.string().describe("ID of the error to get the latest event for"),
+            }
         }, async (args, _extra) => {
             try {
                 if (!args.errorId)
@@ -90,8 +263,38 @@ export class InsightHubClient {
                 throw e;
             }
         });
-        server.tool("get_insight_hub_event_details", "Get details of a specific event on Insight Hub", {
-            link: z.string().describe("Link to the event details"),
+        server.registerTool("get_insight_hub_event_details", {
+            description: toolDescriptionTemplate({
+                summary: "Get detailed information about a specific event using its Insight Hub dashboard URL",
+                purpose: "Retrieve event details directly from an Insight Hub web interface URL for quick debugging",
+                useCases: [
+                    "Get event details when given an Insight Hub dashboard URL from a user or notification",
+                    "Extract event information from shared links or browser URLs",
+                    "Quick lookup of event details without needing separate project and event IDs"
+                ],
+                parameters: [
+                    createParameter("link", "string", true, "Full URL to the event details page in the Insight Hub dashboard (web interface)", {
+                        examples: [
+                            "https://app.bugsnag.com/my-org/my-project/errors/6863e2af8c857c0a5023b411?event_id=6863e2af012caf1d5c320000"
+                        ],
+                        constraints: [
+                            "Must be a valid Insight Hub dashboard URL containing project slug and event_id parameter"
+                        ]
+                    })
+                ],
+                examples: [
+                    createExample("Get event details from Insight Hub URL", {
+                        link: "https://app.bugsnag.com/my-org/my-project/errors/6863e2af8c857c0a5023b411?event_id=6863e2af012caf1d5c320000"
+                    }, "JSON object with complete event details including stack trace, metadata, and context")
+                ],
+                hints: [
+                    "The URL must contain both project slug in the path and event_id in query parameters",
+                    "This is useful when users share Insight Hub dashboard URLs and you need to extract the event data"
+                ]
+            }),
+            inputSchema: {
+                link: z.string().describe("Link to the event details"),
+            }
         }, async (args, _extra) => {
             try {
                 if (!args.link)
@@ -102,9 +305,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 +323,75 @@ 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.registerTool("list_insight_hub_project_errors", {
+            description: toolDescriptionTemplate({
+                summary: "List and search errors in a project using customizable filters",
+                purpose: "Retrieve filtered list of errors from a project for analysis, debugging, and reporting",
+                useCases: [
+                    "Debug recent application errors by filtering for open errors in the last 7 days",
+                    "Generate error reports for stakeholders by filtering specific error types or severity levels",
+                    "Monitor error trends over time using date range filters",
+                    "Find errors affecting specific users or environments using metadata filters"
+                ],
+                parameters: [
+                    createParameter("filters", "FilterObject", false, "Apply filters to narrow down the error list. Use get_project_event_filters to discover available filter fields", {
+                        examples: [
+                            '{"error.status": [{"type": "eq", "value": "open"}]}',
+                            '{"event.since": [{"type": "eq", "value": "7d"}]} // Relative time: last 7 days',
+                            '{"event.since": [{"type": "eq", "value": "2018-05-20T00:00:00Z"}]} // ISO 8601 UTC format',
+                            '{"user.email": [{"type": "eq", "value": "user@example.com"}]}'
+                        ],
+                        constraints: [
+                            "Time filters support ISO 8601 format (e.g. 2018-05-20T00:00:00Z) or relative format (e.g. 7d, 24h)",
+                            "ISO 8601 times must be in UTC and use extended format",
+                            "Relative time periods: h (hours), d (days)"
+                        ]
+                    }),
+                    ...(this.projectApiKey ? [] : [
+                        createParameter("projectId", "string", true, "ID of the project to query for errors")
+                    ])
+                ],
+                examples: [
+                    createExample("Find errors affecting a specific user in the last 24 hours", {
+                        filters: {
+                            "user.email": [{ "type": "eq", "value": "user@example.com" }],
+                            "event.since": [{ "type": "eq", "value": "24h" }]
+                        }
+                    })
+                ],
+                hints: [
+                    "Use get_project_event_filters tool first to discover valid filter field names for your project",
+                    "Combine multiple filters to narrow results - filters are applied with AND logic",
+                    "For time filters: use relative format (7d, 24h) for recent periods or ISO 8601 UTC format (2018-05-20T00:00:00Z) for specific dates",
+                    "Common time filters: event.since (from this time), event.before (until this time)"
+                ]
+            }),
+            inputSchema: {
+                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) {
@@ -131,6 +399,41 @@ export class InsightHubClient {
                 throw e;
             }
         });
+        server.registerTool("get_project_event_filters", {
+            description: toolDescriptionTemplate({
+                summary: "Get available event filter fields for the current project",
+                purpose: "Discover valid filter field names and options that can be used with list_insight_hub_project_errors",
+                useCases: [
+                    "Discover what filter fields are available before searching for errors",
+                    "Find the correct field names for filtering by user, environment, or custom metadata",
+                    "Understand filter options and data types for building complex queries"
+                ],
+                parameters: [],
+                examples: [
+                    createExample("Get all available filter fields", {}, "JSON array of EventField objects containing display_id, custom flag, and filter/pivot options")
+                ],
+                hints: [
+                    "Use this tool before list_insight_hub_project_errors to understand available filters",
+                    "Look for display_id field in the response - these are the field names to use in filters"
+                ]
+            }),
+            inputSchema: {}
+        }, 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) {
+                Bugsnag.notify(e);
+                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.1",
     "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.15.0",
+        "node-cache": "^5.1.2"
     },
     "devDependencies": {
         "@eslint/js": "^9.29.0",

package/insight-hub/README.md

@@ -2,34 +2,40 @@
 
 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. This allows the MCP server to pre-cache your project's custom filters for better filtering prompts.
+
 ## Example prompts
 
-- "Help me fix this crash from Insight Hub: https://app.bugsnag.com/my-org/my-project/errors/1a2b3c4d5e6f7g8h9i0j1k2l?&event_id=1a2b3c4d5e6f7g8h9i0j1k2l"
-- "What are my top events for the 'example' project in insight hub?"
+- "Help me fix this crash: https://app.bugsnag.com/my-org/my-project/errors/1a2b3c4d5e6f7g8h9i0j1k2l?&event_id=1a2b3c4d5e6f7g8h9i0j1k2l"
+- "What are my latest events my project?"
+- "Which errors occurred in the last 7 days?"
 
 ## 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`: (Recommended) 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.1",
   "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.15.0",
+    "node-cache": "^5.1.2"
   },
   "devDependencies": {
     "@eslint/js": "^9.29.0",