@smartbear/mcp 0.2.0 → 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
       }
   ]
@@ -113,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/insight-hub/client.js

@@ -6,6 +6,7 @@ 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";
@@ -35,6 +36,8 @@ export class InsightHubClient {
             headers: {
                 "User-Agent": `${MCP_SERVER_NAME}/${MCP_SERVER_VERSION}`,
                 "Content-Type": "application/json",
+                "X-Bugsnag-API": "true",
+                "X-Version": "2",
             },
             basePath: endpoint,
         });
@@ -117,9 +120,39 @@ export class InsightHubClient {
     }
     registerTools(server) {
         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"),
+            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();
@@ -143,9 +176,37 @@ export class InsightHubClient {
                 }
             });
         }
-        server.tool("get_insight_hub_error", "Get error details from a project", {
-            errorId: z.string().describe("ID of the error to fetch"),
-            ...(!this.projectApiKey ? { projectId: z.string().optional().describe("ID of the project") } : {}),
+        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") } : {}),
+            }
         }, async (args, _extra) => {
             try {
                 const projectId = typeof args.projectId === 'string' ? args.projectId : this.cache.get(cacheKeys.CURRENT_PROJECT)?.id;
@@ -161,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)
@@ -177,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)
@@ -208,12 +324,56 @@ export class InsightHubClient {
             }
         });
         // 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"),
+        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;
@@ -239,7 +399,26 @@ export class InsightHubClient {
                 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) => {
+        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)

package/dist/package.json

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

package/insight-hub/README.md

@@ -2,17 +2,20 @@
 
 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.
+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) 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_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

package/package.json

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