@jupiterone/jupiterone-mcp 0.0.2 → 0.0.4

package/dist/descriptions/get-integration-instances.md

@@ -0,0 +1,35 @@
+# Get Integration Instances Tool
+
+Get all integration instances in your JupiterOne account. This tool returns a list of configured integration instances, including their configuration, status, and recent job information. Integration instances are the actual configured connections to external services like AWS accounts, GitHub repositories, etc. Unless you have an integration definition id, you typically will not want to query this yet. To get an integration definition id, use the `get-integration-definitions` tool. If you need an integration instance id for another task (such as creating a rule action), ask the user which of the possible integrations they want you to use.
+
+## Parameters
+- `definitionId` (optional): Filter instances by a specific integration definition ID. Use this to get only instances of a particular integration type.
+- `limit` (optional): Maximum number of instances to return (between 1 and 1000).
+
+## Example Usage
+Get all integration instances:
+```json
+{}
+```
+
+Get the first 10 integration instances:
+```json
+{
+  "limit": 10
+}
+```
+
+Get all instances of a specific integration type:
+```json
+{
+  "definitionId": "integration-definition-id-here"
+}
+```
+
+Get the first 5 instances of a specific integration type:
+```json
+{
+  "definitionId": "integration-definition-id-here",
+  "limit": 5
+}
+```

package/dist/descriptions/list-rules.md

@@ -1,14 +1,53 @@
 # List Rules Tool
 
-List all rules in your JupiterOne account. This tool returns a list of rule instances, including their IDs, names, descriptions, versions, polling intervals, and other metadata. You can optionally specify a limit to restrict the number of rules returned. This does not get alerts, but rather the configuration behind what may generate an alert, or other workflow action.
+List rules in your JupiterOne account using cursor pagination. This tool returns a page of rule instances, including their IDs, names, descriptions, versions, polling intervals, and other metadata. Use the cursor parameter to navigate through pages of results. This does not get alerts, but rather the configuration behind what may generate an alert, or other workflow action.
 
 ## Parameters
-- `limit` (optional): Maximum number of rules to return (between 1 and 1000).
+- `limit` (optional): Maximum number of rules to return per page (between 1 and 1000). Defaults to 100 if not specified.
+- `cursor` (optional): Pagination cursor to get the next page of results. Use the `endCursor` from a previous response's `pageInfo`. Omit this parameter to get the first page.
 
 ## Example Usage
-Request the first 10 rules:
+Get the first page of rules (default page size):
+```json
+{}
+```
+
+Get the first page with specific limit:
+```json
+{
+  "limit": 50
+}
+```
+
+Get the next page using a cursor:
 ```json
 {
-  "limit": 10
+  "limit": 50,
+  "cursor": "cursor_value_from_previous_response"
 }
-```
+```
+
+## Response Format
+All responses include pagination information:
+```json
+{
+  "returned": 50,
+  "rules": [...],
+  "pageInfo": {
+    "hasNextPage": true,
+    "endCursor": "cursor_for_next_page"
+  }
+}
+```
+
+- `returned`: Number of rules in this page
+- `rules`: Array of rule objects
+- `pageInfo.hasNextPage`: Whether there are more pages available
+- `pageInfo.endCursor`: Cursor to use for the next page (if `hasNextPage` is true)
+
+## Pagination Pattern
+To get all rules across multiple pages:
+1. Call with no cursor to get the first page
+2. Check if `pageInfo.hasNextPage` is true
+3. If true, call again with `cursor` set to `pageInfo.endCursor`
+4. Repeat until `hasNextPage` is false

package/dist/descriptions/update-inline-question-rule.md

@@ -0,0 +1,363 @@
+# JupiterOne Rule Update Tool - Complete Guide
+
+**Purpose**: Updates existing inline question-based alert rules in JupiterOne. This tool modifies the configuration of an existing rule while preserving its identity and version history.
+
+**Important**: Before updating a rule, use the `get-rule-details` tool to retrieve the current configuration. This ensures you have all required fields and can see what needs to be changed.
+
+## Key Requirements for Updates
+
+### 1. Required Fields for Updates
+When updating a rule, you must provide **ALL** fields, not just the ones you want to change. The update operation replaces the entire rule configuration, so missing fields will result in errors.
+
+**Critical Required Fields**:
+- `id`: The existing rule ID (from `get-rule-details`)
+- `version`: The current version number (from `get-rule-details`)
+- `specVersion`: Usually 1
+- `ignorePreviousResults`: Must be included
+- `templates`: Must be included (use `{}` if empty)
+- `tags`: Must be included but should always be empty `[]` (deprecated)
+- `labels`: Use this for actual tagging functionality
+- `resourceGroupId`: Must be included (can be null)
+- `remediationSteps`: Must be included (can be null)
+
+### 2. Condition Format (Critical)
+The `condition` parameter must use JupiterOne's specific array format:
+- **Structure**: `["LOGICAL_OPERATOR", [left_value, operator, right_value]]`
+- **Example**: `["AND", ["queries.queryName.total", ">", 0]]`
+- **Supported operators**: `>`, `<`, `>=`, `<=`, `=`, `!=`
+- **Logical operators**: `"AND"`, `"OR"`
+
+### 3. Operations Structure
+The `when` clause should only contain:
+- `type`: Always `"FILTER"`
+- `condition`: The array format described above
+- **Do NOT include**: `version`, `specVersion` (these belong at the rule level, not in the when clause)
+
+### 4. Query Naming Convention
+- Query names in the `queries` array must match the references in conditions
+- Example: If query name is `"users"`, reference it as `"queries.users.total"`
+- **IMPORTANT**: Use `"query0"` as the standard query name for compatibility with existing patterns
+
+### 5. Version Management
+- The `version` field will be automatically incremented by JupiterOne
+- You must provide the current version number in your update request
+- Get the current version using `get-rule-details` before updating
+
+### 6. Tags vs Labels (Important)
+- **DEPRECATED**: The `tags` array field is deprecated and should always be set to an empty array `[]`
+- **USE INSTEAD**: For tagging functionality, use the `labels` field with key-value pairs
+- **Format**: `labels: [{"labelName": "key", "labelValue": "value"}]`
+- **When users ask for tagging**: Always use the `labels` field to meet their needs
+- **Note**: The `tags` field is still required in the schema for compatibility but should remain empty
+
+## Update Workflow
+
+### Step 1: Get Current Rule Configuration
+```
+Use get-rule-details with the rule ID to get the current configuration
+```
+
+### Step 2: Modify Required Fields
+Update only the fields you need to change while preserving all other required fields.
+
+### Step 3: Submit Update
+Use this tool with the complete configuration including your changes.
+
+## Required Schema Fields for Updates
+
+### Complete Required Parameters for update-inline-question-rule
+**CRITICAL**: All of these fields must be included for successful rule updates:
+
+```json
+{
+  "id": "existing-rule-id",
+  "name": "Updated Rule Name",
+  "description": "Updated rule description",
+  "notifyOnFailure": true,
+  "triggerActionsOnNewEntitiesOnly": true,
+  "ignorePreviousResults": false,
+  "pollingInterval": "ONE_DAY",
+  "specVersion": 1,
+  "version": 2,
+  "templates": {},
+  "outputs": ["alertLevel"],
+  "tags": [],
+  "labels": [
+    {"labelName": "environment", "labelValue": "production"},
+    {"labelName": "team", "labelValue": "security"}
+  ],
+  "resourceGroupId": null,
+  "remediationSteps": null,
+  "question": {
+    "queries": [
+      {
+        "query": "FIND Entity...",
+        "name": "query0",
+        "version": "v1",
+        "includeDeleted": false
+      }
+    ]
+  },
+  "operations": [
+    {
+      "when": {
+        "type": "FILTER",
+        "condition": ["AND", ["queries.query0.total", ">", 0]]
+      },
+      "actions": [...]
+    }
+  ]
+}
+```
+
+**Key Update Requirements**:
+- `id`: Must match the existing rule ID
+- `version`: Must be the current version number from the existing rule
+- `ignorePreviousResults`: Must be included (typically `false`)
+- `templates`: Must be included (use `{}` if empty)
+- `tags`: Must be included but should always be empty `[]` (deprecated field)
+- `labels`: Use this for actual tagging functionality with key-value pairs
+- `resourceGroupId`: Must be included (can be null)
+- `remediationSteps`: Must be included (can be null)
+- Query `name`: Use `"query0"` for primary query
+- Query `version`: Include `"v1"` for compatibility
+- Query `includeDeleted`: Must be explicitly set to `false`
+
+## Available Action Types
+
+### 1. SET_PROPERTY
+Sets a property value on the alert (commonly used for alert severity levels).
+
+**Configuration**:
+```json
+{
+  "type": "SET_PROPERTY",
+  "targetProperty": "alertLevel",
+  "targetValue": "CRITICAL"
+}
+```
+
+**Common Values for alertLevel**: `"LOW"`, `"MEDIUM"`, `"HIGH"`, `"CRITICAL"`, `"INFO"`
+
+### 2. CREATE_ALERT
+Creates a basic alert in JupiterOne.
+
+**Configuration**:
+```json
+{
+  "type": "CREATE_ALERT"
+}
+```
+
+**Note**: This is the most basic action and should almost always be included.
+
+### 3. SEND_EMAIL
+Sends email notifications to specified recipients.
+
+**Configuration**:
+```json
+{
+  "type": "SEND_EMAIL",
+  "recipients": ["user1@company.com", "user2@company.com"],
+  "body": "Affected Items: <br><br>* {{queries.query0.data|mapProperty('displayName')|join('<br>* ')}}"
+}
+```
+
+### 4. TAG_ENTITIES
+Adds or removes tags from entities that triggered the rule.
+
+**Configuration**:
+```json
+{
+  "type": "TAG_ENTITIES",
+  "entities": "{{queries.query0.data}}",
+  "tags": [
+    {"name": "existing tag to remove", "value": null},
+    {"name": "new tag", "value": "tag value"}
+  ]
+}
+```
+
+### 5. SEND_SLACK_MESSAGE
+Sends messages to Slack channels (requires Slack integration).
+
+**Configuration**:
+```json
+{
+  "integrationInstanceId": "d97d9127-c532-410a-bf0a-9ea93f66c3d2",
+  "type": "SEND_SLACK_MESSAGE",
+  "channels": ["#security-alerts", "#general"],
+  "body": "*Affected Items:* \n\n- {{queries.query0.data|mapProperty('displayName')|join('\n- ')}}"
+}
+```
+
+### 6. SEND_TO_S3
+Sends alert data to an S3 bucket (requires AWS S3 integration).
+
+**Configuration**:
+```json
+{
+  "integrationInstanceId": "f89568b4-2a1b-4bd8-8abd-aee21270df75",
+  "type": "SEND_TO_S3",
+  "bucket": "security-alerts-bucket",
+  "region": "us-east-1",
+  "data": {
+    "description": "{{alertWebLink}}\n\n**Affected Items:**\n\n* {{queries.query0.data|mapProperty('displayName')|join('\n* ')}}"
+  }
+}
+```
+
+### 7. CREATE_JIRA_TICKET
+Creates a Jira ticket for the alert (requires Jira integration).
+
+**Configuration**:
+```json
+{
+  "integrationInstanceId": "53a99eaa-18a5-45ef-b748-2de39d642a91",
+  "type": "CREATE_JIRA_TICKET",
+  "entityClass": "Finding",
+  "summary": "Security Alert: Critical Unencrypted Data Found",
+  "issueType": "Bug",
+  "project": "SEC",
+  "updateContentOnChanges": false,
+  "additionalFields": {
+    "description": {
+      "type": "doc",
+      "version": 1,
+      "content": [
+        {
+          "type": "paragraph",
+          "content": [
+            {
+              "type": "text",
+              "text": "{{alertWebLink}}\n\n**Affected Items:**\n\n* {{queries.query0.data|mapProperty('displayName')|join('\n* ')}}"
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+## Template Variables and Formatting
+
+### Available Variables
+- `{{alertWebLink}}` - Direct link to the alert in JupiterOne
+- `{{queries.queryName.data}}` - Array of entities from the specified query
+- `{{queries.queryName.total}}` - Count of entities from the query
+
+### Data Formatting
+- `|mapProperty('fieldName')` - Extract specific field from each entity
+- `|join('separator')` - Join array elements with specified separator
+- Example: `{{queries.users.data|mapProperty('displayName')|join(', ')}}` - Creates comma-separated list of user names
+
+## Integration Dependencies
+
+For actions requiring integrations, you may need to:
+1. Query available integration instances using `get-integration-instances`
+2. Ask the user which integration to use
+3. Use the integration's `id` as the `integrationInstanceId`
+
+**Actions requiring integrations**:
+- `SEND_SLACK_MESSAGE` (Slack integration)
+- `SEND_TO_S3` (AWS S3 integration)
+- `CREATE_JIRA_TICKET` (Jira integration)
+
+## Working Example Update
+
+### Complete Working Rule Update Structure
+```json
+{
+  "id": "12345678-1234-1234-1234-123456789abc",
+  "name": "Updated Rule Name",
+  "description": "Updated rule description",
+  "notifyOnFailure": true,
+  "triggerActionsOnNewEntitiesOnly": true,
+  "ignorePreviousResults": false,
+  "pollingInterval": "ONE_DAY",
+  "specVersion": 1,
+  "version": 3,
+  "templates": {},
+  "outputs": ["alertLevel"],
+  "tags": [],
+  "labels": [
+    {"labelName": "severity", "labelValue": "high"},
+    {"labelName": "category", "labelValue": "security"}
+  ],
+  "resourceGroupId": null,
+  "remediationSteps": "1. Review the affected entities\n2. Apply security patches\n3. Update configurations",
+  "question": {
+    "queries": [
+      {
+        "query": "FIND Entity WITH condition",
+        "name": "query0",
+        "version": "v1",
+        "includeDeleted": false
+      }
+    ]
+  },
+  "operations": [
+    {
+      "when": {
+        "type": "FILTER",
+        "condition": ["AND", ["queries.query0.total", ">", 0]]
+      },
+      "actions": [
+        {
+          "type": "SET_PROPERTY",
+          "targetProperty": "alertLevel",
+          "targetValue": "CRITICAL"
+        },
+        {
+          "type": "CREATE_ALERT"
+        },
+        {
+          "type": "SEND_EMAIL",
+          "recipients": ["updated-user@company.com"],
+          "body": "Updated notification: {{alertWebLink}}"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Common Update Scenarios
+
+### 1. Changing Notification Recipients
+Update only the `recipients` array in the `SEND_EMAIL` action while preserving all other fields.
+
+### 2. Modifying Polling Interval
+Update the `pollingInterval` field while keeping all other configuration the same.
+
+### 3. Adding New Actions
+Add new actions to the `actions` array in the operations.
+
+### 4. Updating Query Logic
+Modify the `query` string in the queries array or adjust the `condition` in operations.
+
+### 5. Changing Labels
+Update the `labels` array to add, remove, or modify rule labels.
+
+## Debugging Tips
+- Always start by getting the current rule configuration with `get-rule-details`
+- Ensure the `version` number matches the current rule version
+- Include ALL required fields, even if they're not changing
+- If you get "Invalid conjunction operator" errors, check the condition array format
+- If you get "additional properties" errors, remove extra fields from the `when` clause
+- If you get missing property errors, ensure all required schema fields are included
+- **Always include**: `id`, `version`, `ignorePreviousResults`, `templates`, `tags`, `labels`, `resourceGroupId`, `remediationSteps`
+- Use `"query0"` as the standard query name for compatibility
+
+## Best Practices for Updates
+- Always retrieve the current rule configuration first using `get-rule-details`
+- Only modify the fields that actually need to change
+- Preserve the existing `version` number (it will be auto-incremented)
+- Use the `labels` field for rule organization and tagging (not the deprecated `tags` field)
+- Test rule changes with simple modifications first
+- Document changes in the `description` field if significant
+- When users request tagging functionality, use the `labels` field with key-value pairs
+- Always include `CREATE_ALERT` action as a baseline unless specifically removing it
+
+This format ensures reliable rule updates and helps avoid common pitfalls encountered during rule modification.

package/dist/server/mcp-server.d.ts

@@ -2,8 +2,13 @@ import { JupiterOneConfig } from '../types/jupiterone.js';
 export declare class JupiterOneMcpServer {
     private server;
     private client;
+    private validator;
     constructor(config: JupiterOneConfig);
     private setupTools;
+    private validateQueries;
+    private validateWidgetQueries;
+    private createValidationErrorResponse;
+    private createQueryErrorResponse;
     start(): Promise<void>;
     stop(): Promise<void>;
 }

package/dist/server/mcp-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../../src/server/mcp-server.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAW1D,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,MAAM,CAAmB;gBAErB,MAAM,EAAE,gBAAgB;IAUpC,OAAO,CAAC,UAAU;IA2tDZ,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../../src/server/mcp-server.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAY1D,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,SAAS,CAAgB;gBAErB,MAAM,EAAE,gBAAgB;IAWpC,OAAO,CAAC,UAAU;YA4uDJ,eAAe;YAqBf,qBAAqB;IAOnC,OAAO,CAAC,6BAA6B;IAkBrC,OAAO,CAAC,wBAAwB;IAc1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}

package/dist/server/mcp-server.js

@@ -3,11 +3,14 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { JupiterOneClient } from '../client/jupiterone-client.js';
 import { loadDescription } from '../utils/load-description.js';
+import { J1QLValidator } from '../utils/j1ql-validator.js';
 export class JupiterOneMcpServer {
     server;
     client;
+    validator;
     constructor(config) {
         this.client = new JupiterOneClient(config);
+        this.validator = new J1QLValidator(this.client.j1qlService);
         this.server = new McpServer({
             name: 'jupiterone-mcp',
             version: '1.0.0',
@@ -18,18 +21,18 @@ export class JupiterOneMcpServer {
         // Tool: List all rules
         this.server.tool('list-rules', loadDescription('list-rules.md'), {
             limit: z.number().min(1).max(1000).optional(),
-        }, async ({ limit }) => {
+            cursor: z.string().optional(),
+        }, async ({ limit, cursor }) => {
             try {
-                const instances = await this.client.getAllRuleInstances();
-                const limitedInstances = limit ? instances.slice(0, limit) : instances;
+                const response = await this.client.listRuleInstances(limit, cursor);
+                const instances = response.questionInstances || [];
                 return {
                     content: [
                         {
                             type: 'text',
                             text: JSON.stringify({
-                                total: instances.length,
-                                returned: limitedInstances.length,
-                                rules: limitedInstances.map((instance) => ({
+                                returned: instances.length,
+                                rules: instances.map((instance) => ({
                                     id: instance.id,
                                     name: instance.name,
                                     description: instance.description,
@@ -43,6 +46,7 @@ export class JupiterOneMcpServer {
                                     tags: instance.tags,
                                     outputs: instance.outputs,
                                 })),
+                                pageInfo: response.pageInfo,
                             }, null, 2),
                         },
                     ],
@@ -469,11 +473,12 @@ export class JupiterOneMcpServer {
             }
         });
         // Tool: Get integration definitions
-        this.server.tool('get-integration-definitions', {
+        this.server.tool('get-integration-definitions', loadDescription('get-integration-definitions.md'), {
+            cursor: z.string().optional().describe('Optional cursor for pagination'),
             includeConfig: z.boolean().optional().describe('Whether to include configuration fields'),
-        }, async ({ includeConfig }) => {
+        }, async ({ cursor, includeConfig }) => {
             try {
-                const definitions = await this.client.getIntegrationDefinitions(undefined, includeConfig);
+                const definitions = await this.client.getIntegrationDefinitions(cursor, includeConfig);
                 return {
                     content: [
                         {
@@ -524,7 +529,7 @@ export class JupiterOneMcpServer {
             }
         });
         // Tool: Get integration instances
-        this.server.tool('get-integration-instances', {
+        this.server.tool('get-integration-instances', loadDescription('get-integration-instances.md'), {
             definitionId: z
                 .string()
                 .optional()
@@ -762,6 +767,11 @@ export class JupiterOneMcpServer {
                 .describe('Operations to perform when conditions are met'),
         }, async ({ name, description, notifyOnFailure, triggerActionsOnNewEntitiesOnly, ignorePreviousResults, pollingInterval, outputs, specVersion, tags, templates, queries, operations, }) => {
             try {
+                // Validate all queries before creating the rule
+                const validationResults = await this.validateQueries(queries);
+                if (validationResults.length > 0) {
+                    return this.createValidationErrorResponse(validationResults);
+                }
                 const instance = {
                     name,
                     description,
@@ -820,7 +830,7 @@ export class JupiterOneMcpServer {
             }
         });
         // Tool: Update inline question rule instance
-        this.server.tool('update-inline-question-rule', {
+        this.server.tool('update-inline-question-rule', loadDescription('update-inline-question-rule.md'), {
             id: z.string().describe('ID of the rule to update'),
             name: z.string().describe('Name of the rule'),
             description: z.string().describe('Description of the rule'),
@@ -933,6 +943,11 @@ export class JupiterOneMcpServer {
                 .describe('Operations that define when and what actions to take'),
         }, async ({ id, name, description, notifyOnFailure, triggerActionsOnNewEntitiesOnly, ignorePreviousResults, pollingInterval, outputs, specVersion, version, tags, templates, labels, resourceGroupId, remediationSteps, question, operations, }) => {
             try {
+                // Validate all queries before updating the rule
+                const validationResults = await this.validateQueries(question?.queries);
+                if (validationResults.length > 0) {
+                    return this.createValidationErrorResponse(validationResults);
+                }
                 const instance = {
                     id,
                     name,
@@ -1316,6 +1331,11 @@ export class JupiterOneMcpServer {
                         throw new Error('Input must be a valid object or JSON string');
                     }
                 }
+                // Validate queries before creating widget
+                const validationResults = await this.validateWidgetQueries(widgetInput.config?.queries);
+                if (validationResults.length > 0) {
+                    return this.createValidationErrorResponse(validationResults);
+                }
                 const widget = await this.client.createDashboardWidget(dashboardId, widgetInput);
                 return {
                     content: [
@@ -1473,18 +1493,58 @@ export class JupiterOneMcpServer {
                 };
             }
             catch (error) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `Error executing J1QL query: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                        },
-                    ],
-                    isError: true,
-                };
+                return this.createQueryErrorResponse(error, query);
             }
         });
     }
+    // Helper methods for validation
+    async validateQueries(queries) {
+        if (!queries || !Array.isArray(queries))
+            return [];
+        const validationResults = [];
+        for (const queryObj of queries) {
+            if (queryObj.query) {
+                const validation = await this.validator.validateQuery(queryObj.query);
+                if (!validation.isValid) {
+                    validationResults.push({
+                        queryName: queryObj.name || 'Unnamed query',
+                        error: validation.error || 'Query validation failed',
+                        suggestion: validation.suggestion || 'Please check the query syntax and try again',
+                    });
+                }
+            }
+        }
+        return validationResults;
+    }
+    async validateWidgetQueries(queries) {
+        // Use the same validation logic as rules - actually execute the queries
+        return this.validateQueries(queries);
+    }
+    createValidationErrorResponse(validationResults) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Query validation failed. Please fix the following issues:\n\n${validationResults
+                        .map((r) => `Query: ${r.queryName}\nError: ${r.error}\nSuggestion: ${r.suggestion}`)
+                        .join('\n\n')}\n\nUse the execute-j1ql-query tool to test and refine your queries first.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    createQueryErrorResponse(error, query) {
+        const errorResult = this.validator.handleQueryError(error, query);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error executing J1QL query:\n\n${errorResult.error}\n\nSuggestion: ${errorResult.suggestion}\n\nDebugging tips:\n1. Modify existing queries that are already working as expected.\n2. Use discovery queries to understand available data\n3. Verify entity classes exist (use proper capitalization)\n4. Check property names match exactly\n5. Use single quotes for strings, not double quotes\n6. Place aliases after WITH statements\n7. Add LIMIT clause to prevent timeouts`,
+                },
+            ],
+            isError: true,
+        };
+    }
     async start() {
         const transport = new StdioServerTransport();
         await this.server.connect(transport);