@dynatrace-oss/dynatrace-mcp-server 0.5.0 → 0.6.0-rc.2

package/README.md

@@ -1,9 +1,31 @@
 # Dynatrace MCP Server
 
+<h4 align="center">
+  <a href="https://github.com/dynatrace-oss/dynatrace-mcp/releases">
+    <img src="https://img.shields.io/github/release/dynatrace-oss/dynatrace-mcp" />
+  </a>
+  <a href="https://github.com/dynatrace-oss/dynatrace-mcp/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/license-mit-blue.svg" alt="Dynatrace MCP Server is released under the MIT License" />
+  </a>
+  <a href="https://www.npmjs.com/package/@dynatrace-oss/dynatrace-mcp-server">
+    <img src="https://img.shields.io/npm/dm/@dynatrace-oss/dynatrace-mcp-server?logo=npm&style=flat&color=red" alt="npm" />
+  </a>
+  <a href="https://github.com/dynatrace-oss/dynatrace-mcp">
+    <img src="https://img.shields.io/github/stars/dynatrace-oss/dynatrace-mcp" alt="Dynatrace MCP Server Stars on GitHub" />
+  </a>
+  <a href="https://github.com/dynatrace-oss/dynatrace-mcp">
+    <img src="https://img.shields.io/github/contributors/dynatrace-oss/dynatrace-mcp?color=green" alt="Dynatrace MCP Server Contributors on GitHub" />
+  </a>
+</h4>
+
 This local MCP server allows interaction with the [Dynatrace](https://www.dynatrace.com/) observability platform.
 Bring real-time observability data directly into your development workflow.
 
-<img width="1046" alt="image" src="/assets/dynatrace-mcp-arch.png" />
+> Note: This product is not officially supported by Dynatrace.
+
+Please contact us via [GitHub Issues](https://github.com/dynatrace-oss/dynatrace-mcp/issues) if you have feature requests, questions, or need help.
+
+![Architecture](https://github.com/dynatrace-oss/dynatrace-mcp/blob/main/assets/dynatrace-mcp-arch.png?raw=true)
 
 ## Use cases
 
@@ -27,19 +49,40 @@ Bring real-time observability data directly into your development workflow.
 - Get more information about a monitored entity
 - Get Ownership of an entity
 
-## Costs
+### Costs
 
-**Important:** While this local MCP server is provided for free, using it to access data in Dynatrace Grail may incur additional costs based
+**Important:** While this local MCP server is provided for free, using certain capabilities to access data in Dynatrace Grail may incur additional costs based
 on your Dynatrace consumption model. This affects `execute_dql` tool and other capabilities that **query** Dynatrace Grail storage, and costs
-depend on the volume (GB scanned/billed).
+depend on the volume (GB scanned).
 
 **Before using this MCP server extensively, please:**
 
 1. Review your current Dynatrace consumption model and pricing
 2. Understand the cost implications of the specific data you plan to query (logs, events, metrics) - see [Dynatrace Pricing and Rate Card](https://www.dynatrace.com/pricing/)
 3. Start with smaller timeframes (e.g., 12h-24h) and make use of [buckets](https://docs.dynatrace.com/docs/discover-dynatrace/platform/grail/data-model#built-in-grail-buckets) to reduce the cost impact
+4. Set an appropriate `DT_GRAIL_QUERY_BUDGET_GB` environment variable (default: 1000 GB) to control and monitor your Grail query consumption
+
+**Grail Budget Tracking:**
+
+The MCP server includes built-in budget tracking for Grail queries to help you monitor and control costs:
 
-**Note**: We will be providing a way to monitor Query Usage of the dynatrace-mcp-server in the future.
+- Set `DT_GRAIL_QUERY_BUDGET_GB` (default: 1000 GB) to define your session budget limit
+- The server tracks bytes scanned across all Grail queries in the current session
+- You'll receive warnings when approaching 80% of your budget
+- Budget exceeded alerts help prevent unexpected high consumption
+- Budget resets when you restart the MCP server session
+
+**To understand costs that occured:**
+
+Execute the following DQL statement in a notebook to see how much bytes have been queried from Grail (Logs, Events, etc...):
+
+```
+fetch dt.system.events
+| filter event.kind == "QUERY_EXECUTION_EVENT" and contains(client.client_context, "dynatrace-mcp")
+| sort timestamp desc
+| fields timestamp, query_id, query_string, scanned_bytes, table, bucket, user.id, user.email, client.client_context
+| maketimeSeries sum(scanned_bytes), by: { user.email, user.id, table }
+```
 
 ### AI-Powered Assistance (Preview)
 
@@ -56,7 +99,7 @@ Enhance your AI assistant with comprehensive Dynatrace observability analysis ca
 
 ### **🚀 Quick Setup for AI Assistants**
 
-Copy the comprehensive rule files from the [`rules/`](./rules/) directory to your AI assistant's rules directory:
+Copy the comprehensive rule files from the [`dynatrace-agent-rules/rules/`](./dynatrace-agent-rules/rules/) directory to your AI assistant's rules directory:
 
 **IDE-Specific Locations:**
 
@@ -139,7 +182,7 @@ rules/
 - **Eliminated circular references** - No more confusing cross-referencing webs
 - **DQL-first approach** - Prefer flexible queries over rigid MCP calls
 
-For detailed information about the workshop rules, see the [Rules README](./rules/README.md).
+For detailed information about the workshop rules, see the [Rules README](./dynatrace-agent-rules/rules/README.md).
 
 ## Quickstart
 
@@ -172,8 +215,7 @@ This only works if the config is stored in the current workspaces, e.g., `<your-
       "command": "npx",
       "args": ["-y", "@dynatrace-oss/dynatrace-mcp-server@latest"],
       "env": {
-        "OAUTH_CLIENT_ID": "",
-        "OAUTH_CLIENT_SECRET": "",
+        "DT_PLATFORM_TOKEN": "",
         "DT_ENVIRONMENT": ""
       }
     }
@@ -186,12 +228,11 @@ This only works if the config is stored in the current workspaces, e.g., `<your-
 ```json
 {
   "mcpServers": {
-    "mobile-mcp": {
+    "dynatrace-mcp-server": {
       "command": "npx",
       "args": ["-y", "@dynatrace-oss/dynatrace-mcp-server@latest"],
       "env": {
-        "OAUTH_CLIENT_ID": "",
-        "OAUTH_CLIENT_SECRET": "",
+        "DT_PLATFORM_TOKEN": "",
         "DT_ENVIRONMENT": ""
       }
     }
@@ -206,12 +247,11 @@ The [Amazon Q Developer CLI](https://docs.aws.amazon.com/amazonq/latest/qdevelop
 ```json
 {
   "mcpServers": {
-    "mobile-mcp": {
+    "dynatrace-mcp-server": {
       "command": "npx",
       "args": ["-y", "@dynatrace-oss/dynatrace-mcp-server@latest"],
       "env": {
-        "OAUTH_CLIENT_ID": "",
-        "OAUTH_CLIENT_SECRET": "",
+        "DT_PLATFORM_TOKEN": "",
         "DT_ENVIRONMENT": ""
       }
     }
@@ -229,34 +269,21 @@ For scenarios where you need to run the MCP server as an HTTP service instead of
 
 ```bash
 # Get help and see all available options
-npx -y @dynatrace-oss/dynatrace-mcp-server --help
+npx -y @dynatrace-oss/dynatrace-mcp-server@latest --help
 
 # Run with HTTP server on default port 3000
-npx -y @dynatrace-oss/dynatrace-mcp-server --http
+npx -y @dynatrace-oss/dynatrace-mcp-server@latest --http
 
 # Run with custom port (using short or long flag)
-npx -y @dynatrace-oss/dynatrace-mcp-server --server -p 8080
-npx -y @dynatrace-oss/dynatrace-mcp-server --http --port 3001
+npx -y @dynatrace-oss/dynatrace-mcp-server@latest --server -p 8080
+npx -y @dynatrace-oss/dynatrace-mcp-server@latest --http --port 3001
 
 # Run with custom host/IP (using short or long flag)
-npx -y @dynatrace-oss/dynatrace-mcp-server --http --host 127.0.0.1
-npx -y @dynatrace-oss/dynatrace-mcp-server --http -H 192.168.0.1
+npx -y @dynatrace-oss/dynatrace-mcp-server@latest --http --host 127.0.0.1
+npx -y @dynatrace-oss/dynatrace-mcp-server@latest --http -H 192.168.0.1
 
 # Check version
-npx -y @dynatrace-oss/dynatrace-mcp-server --version
-```
-
-**Configuration for MCP clients that support HTTP transport:**
-
-```json
-{
-  "mcpServers": {
-    "dynatrace-http": {
-      "url": "http://localhost:3000",
-      "transport": "http"
-    }
-  }
-}
+npx -y @dynatrace-oss/dynatrace-mcp-server@latest --version
 ```
 
 **Configuration for MCP clients that support HTTP transport:**
@@ -299,16 +326,19 @@ For fetching just error-logs, add `| filter loglevel == "ERROR"`.
 
 ## Environment Variables
 
-You can set up authentication via **OAuth Client** or **Platform Tokens** (v0.5.0 and newer) via the following environment variables:
+You can set up authentication via **Platform Tokens** (recommended) or **OAuth Client** via the following environment variables:
 
 - `DT_ENVIRONMENT` (string, e.g., https://abc12345.apps.dynatrace.com) - URL to your Dynatrace Platform (do not use Dynatrace classic URLs like `abc12345.live.dynatrace.com`)
-- `OAUTH_CLIENT_ID` (string, e.g., `dt0s02.SAMPLE`) - Dynatrace OAuth Client ID
-- `OAUTH_CLIENT_SECRET` (string, e.g., `dt0s02.SAMPLE.abcd1234`) - Dynatrace OAuth Client Secret
-- With v0.5.0 and newer: `DT_PLATFORM_TOKEN` (string, e.g., `dt0s16.SAMPLE.abcd1234`) - Dynatrace Platform Token (limited support, as not all scopes are available; see below)
+- `DT_PLATFORM_TOKEN` (string, e.g., `dt0s16.SAMPLE.abcd1234`) - **Recommended**: Dynatrace Platform Token
+- `OAUTH_CLIENT_ID` (string, e.g., `dt0s02.SAMPLE`) - Alternative: Dynatrace OAuth Client ID (for advanced use cases)
+- `OAUTH_CLIENT_SECRET` (string, e.g., `dt0s02.SAMPLE.abcd1234`) - Alternative: Dynatrace OAuth Client Secret (for advanced use cases)
+- `DT_GRAIL_QUERY_BUDGET_GB` (number, default: 1000) - Budget limit in GB (base 1000) for Grail query bytes scanned per session. The MCP server tracks your Grail usage and warns when approaching or exceeding this limit.
+
+**Platform Tokens are recommended** for most use cases as they provide a simpler authentication flow. OAuth Clients should only be used when specific OAuth features are required.
 
 For more information, please have a look at the documentation about
-[creating an Oauth Client in Dynatrace](https://docs.dynatrace.com/docs/manage/identity-access-management/access-tokens-and-oauth-clients/oauth-clients), as well as
-[creating a Platform Token in Dynatrace](https://docs.dynatrace.com/docs/manage/identity-access-management/access-tokens-and-oauth-clients/platform-tokens).
+[creating a Platform Token in Dynatrace](https://docs.dynatrace.com/docs/manage/identity-access-management/access-tokens-and-oauth-clients/platform-tokens), as well as
+[creating an OAuth Client in Dynatrace](https://docs.dynatrace.com/docs/manage/identity-access-management/access-tokens-and-oauth-clients/oauth-clients) for advanced scenarios.
 
 In addition, depending on the features you use, the following variables can be configured:
 
@@ -318,6 +348,8 @@ In addition, depending on the features you use, the following variables can be c
 
 Depending on the features you are using, the following scopes are needed:
 
+**Available for both Platform Tokens and OAuth Clients:**
+
 - `app-engine:apps:run` - needed for almost all tools
 - `app-engine:functions:run` - needed for for almost all tools
 - `environment-api:entities:read` - for retrieving ownership details from monitored entities (_currently not available for Platform Tokens_)
@@ -338,10 +370,13 @@ Depending on the features you are using, the following scopes are needed:
 - `davis-copilot:conversations:execute` - execute conversational skill (chat with Copilot)
 - `davis-copilot:nl2dql:execute` - execute Davis Copilot Natural Language (NL) to DQL skill
 - `davis-copilot:dql2nl:execute` - execute DQL to Natural Language (NL) skill
+- `email:emails:send` - needed for `send_email` tool to send emails
 - `settings:objects:read` - needed for reading ownership information and Guardians (SRG) from settings
 
   **Note**: Please ensure that `settings:objects:read` is used, and _not_ the similarly named scope `app-settings:objects:read`.
 
+**Important**: Some features requiring `environment-api:entities:read` will only work with OAuth Clients. For most use cases, Platform Tokens provide all necessary functionality.
+
 ## ✨ Example prompts ✨
 
 Use these example prompts as a starting point. Just copy them into your IDE or agent setup, adapt them to your services/stack/architecture,
@@ -368,6 +403,12 @@ fetch logs | filter dt.source_entity == 'SERVICE-123' | summarize count(), by:{s
 How can I investigate slow database queries in Dynatrace?
 ```
 
+**Send email notifications:**
+
+```
+Send an email notification about the incident to the responsible team at team@example.com with CC to manager@example.com
+```
+
 ### **Advanced Incident Investigation**
 
 **Multi-phase incident response:**
@@ -493,12 +534,18 @@ to help identify what might be causing these deployment issues?
 
 ### Authentication Issues
 
-In most cases, something is wrong with the OAuth Client. Please ensure that you have added all scopes as requested above.
-In addition, please ensure that your user also has all necessary permissions on your Dynatrace Environment.
+In most cases, authentication issues are related to missing scopes or invalid tokens. Please ensure that you have added all required scopes as listed above.
+
+**For Platform Tokens:**
+
+1. Verify your Platform Token has all the necessary scopes listed in the "Scopes for Authentication" section
+2. Ensure your token is valid and not expired
+3. Check that your user has the required permissions in your Dynatrace Environment
 
-In case of any problems, you can troubleshoot SSO/OAuth issues based on our [Dynatrace Developer Documentation](https://developer.dynatrace.com/develop/access-platform-apis-from-outside/#get-bearer-token-and-call-app-function) and providing the list of scopes.
+**For OAuth Clients:**
+In case of OAuth-related problems, you can troubleshoot SSO/OAuth issues based on our [Dynatrace Developer Documentation](https://developer.dynatrace.com/develop/access-platform-apis-from-outside/#get-bearer-token-and-call-app-function).
 
-It is recommended to try access the following API (which requires minimal scopes `app-engine:apps:run` and `app-engine:functions:run`):
+It is recommended to test access with the following API (which requires minimal scopes `app-engine:apps:run` and `app-engine:functions:run`):
 
 1. Use OAuth Client ID and Secret to retrieve a Bearer Token (only valid for a couple of minutes):
 
@@ -534,6 +581,34 @@ curl -X GET https://abc12345.apps.dynatrace.com/platform/management/v1/environme
 
 Grail has a dedicated section about permissions in the Dynatrace Docs. Please refer to https://docs.dynatrace.com/docs/discover-dynatrace/platform/grail/data-model/assign-permissions-in-grail for more details.
 
+## Telemetry
+
+The Dynatrace MCP Server includes sending Telemetry Data via Dynatrace OpenKit to help improve the product. This includes:
+
+- Server start events
+- Tool usage (which tools are called, success/failure, execution duration)
+- Error tracking for debugging and improvement
+
+**Privacy and Opt-out:**
+
+- Telemetry is **enabled by default** but can be disabled by setting `DT_MCP_DISABLE_TELEMETRY=true`
+- No sensitive data from your Dynatrace environment is tracked
+- Only anonymous usage statistics and error information are collected
+- Usage statistics and error data are transmitted to Dynatrace’s analytics endpoint
+
+**Configuration options:**
+
+- `DT_MCP_DISABLE_TELEMETRY` (boolean, default: `false`) - Disable Telemetry
+- `DT_MCP_TELEMETRY_APPLICATION_ID` (string, default: `dynatrace-mcp-server`) - Application ID for tracking
+- `DT_MCP_TELEMETRY_ENDPOINT_URL` (string, default: Dynatrace endpoint) - OpenKit endpoint URL
+- `DT_MCP_TELEMETRY_DEVICE_ID` (string, default: auto-generated) - Device identifier for tracking
+
+To disable usage tracking, add this to your environment:
+
+```bash
+DT_MCP_DISABLE_TELEMETRY=true
+```
+
 ## Development
 
 For local development purposes, you can use VSCode and GitHub Copilot.
@@ -581,8 +656,3 @@ This will
 - prepare the [changelog](CHANGELOG.md),
 - update the version number in [package.json](package.json),
 - commit the changes.
-
-## Notes
-
-This product is not officially supported by Dynatrace.
-Please contact us via [GitHub Issues](https://github.com/dynatrace-oss/dynatrace-mcp/issues) if you have feature requests, questions, or need help.

package/dist/authentication/dynatrace-clients.js

@@ -10,7 +10,7 @@ const user_agent_1 = require("../utils/user-agent");
  * @param clientSecret - Oauth Client Secret for Dynatrace
  * @param ssoAuthUrl - SSO Authentication URL
  * @param scopes - List of requested scopes
- * @returns
+ * @returns Response of the OAuth Endpoint (which, in the best case includes a token)
  */
 const requestToken = async (clientId, clientSecret, ssoAuthUrl, scopes) => {
     const res = await fetch(ssoAuthUrl, {
@@ -40,7 +40,7 @@ const requestToken = async (clientId, clientSecret, ssoAuthUrl, scopes) => {
  * @param clientId
  * @param clientSecret
  * @param dtPlatformToken
- * @returns
+ * @returns an authenticated HttpClient
  */
 const createDtHttpClient = async (environmentUrl, scopes, clientId, clientSecret, dtPlatformToken) => {
     if (clientId && clientSecret) {

package/dist/capabilities/davis-copilot.js

@@ -1,7 +1,23 @@
 "use strict";
+/**
+ * Davis CoPilot API Integration
+ *
+ * This module provides access to Davis CoPilot AI capabilities including:
+ * - Natural Language to DQL conversion
+ * - DQL explanation in plain English
+ * - AI-powered conversation assistance
+ * - Feedback submission for continuous improvement
+ *
+ * Note: While Davis CoPilot AI is generally available (GA),
+ * the Davis CoPilot APIs are currently in preview.
+ * For more information: https://dt-url.net/copilot-community
+ *
+ * DQL (Dynatrace Query Language) is the most powerful way to query any data
+ * in Dynatrace, including problem events, security issues, logs, metrics, and spans.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.chatWithDavisCopilot = exports.explainDqlInNaturalLanguage = exports.generateDqlFromNaturalLanguage = void 0;
-// API Functions
+const client_davis_copilot_1 = require("@dynatrace-sdk/client-davis-copilot");
 /**
  * Generate DQL from natural language
  * Converts plain English descriptions into powerful Dynatrace Query Language (DQL) statements.
@@ -9,17 +25,10 @@ exports.chatWithDavisCopilot = exports.explainDqlInNaturalLanguage = exports.gen
  * security issues, logs, metrics, spans, and custom data.
  */
 const generateDqlFromNaturalLanguage = async (dtClient, text) => {
-    const request = { text };
-    const response = await dtClient.send({
-        method: 'POST',
-        url: '/platform/davis/copilot/v0.2/skills/nl2dql:generate',
-        headers: {
-            'Content-Type': 'application/json',
-            'Accept': 'application/json',
-        },
-        body: JSON.stringify(request),
+    const client = new client_davis_copilot_1.PublicClient(dtClient);
+    return await client.nl2dql({
+        body: { text },
     });
-    return await response.body('json');
 };
 exports.generateDqlFromNaturalLanguage = generateDqlFromNaturalLanguage;
 /**
@@ -29,35 +38,27 @@ exports.generateDqlFromNaturalLanguage = generateDqlFromNaturalLanguage;
  * queries for problem events, security issues, and performance metrics.
  */
 const explainDqlInNaturalLanguage = async (dtClient, dql) => {
-    const request = { dql };
-    const response = await dtClient.send({
-        method: 'POST',
-        url: '/platform/davis/copilot/v0.2/skills/dql2nl:explain',
-        headers: {
-            'Content-Type': 'application/json',
-            'Accept': 'application/json',
-        },
-        body: request, // Not sure why this does not need JSON.stringify, but it only works like this; once we have the SDK, this will be consistent
+    const client = new client_davis_copilot_1.PublicClient(dtClient);
+    return await client.dql2nl({
+        body: { dql },
     });
-    return await response.body('json');
 };
 exports.explainDqlInNaturalLanguage = explainDqlInNaturalLanguage;
 const chatWithDavisCopilot = async (dtClient, text, context, annotations, state) => {
-    const request = {
-        text,
-        context,
-        annotations,
-        state,
-    };
-    const response = await dtClient.send({
-        method: 'POST',
-        url: '/platform/davis/copilot/v0.2/skills/conversations:message',
-        headers: {
-            'Content-Type': 'application/json',
-            'Accept': 'application/json',
+    const client = new client_davis_copilot_1.PublicClient(dtClient);
+    const response = await client.recommenderConversation({
+        body: {
+            text,
+            context,
+            annotations,
+            state,
         },
-        body: JSON.stringify(request),
     });
-    return await response.body('json');
+    // Type guard: RecommenderResponse is ConversationResponse | EventArray
+    // In practice, the SDK defaults to non-streaming and returns ConversationResponse
+    if (Array.isArray(response)) {
+        throw new Error('Unexpected streaming response format. Please raise an issue at https://github.com/dynatrace-oss/dynatrace-mcp/issues.');
+    }
+    return response;
 };
 exports.chatWithDavisCopilot = chatWithDavisCopilot;

package/dist/capabilities/execute-dql.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeDql = exports.verifyDqlStatement = void 0;
 const client_query_1 = require("@dynatrace-sdk/client-query");
 const user_agent_1 = require("../utils/user-agent");
+const grail_budget_tracker_1 = require("../utils/grail-budget-tracker");
 const verifyDqlStatement = async (dtClient, dqlStatement) => {
     const queryAssistanceClient = new client_query_1.QueryAssistanceClient(dtClient);
     const response = await queryAssistanceClient.queryVerify({
@@ -13,25 +14,71 @@ const verifyDqlStatement = async (dtClient, dqlStatement) => {
     return response;
 };
 exports.verifyDqlStatement = verifyDqlStatement;
+/**
+ * Helper function to create a DQL execution result and log metadata information.
+ * @param queryResult - The query result from Dynatrace API
+ * @param logPrefix - Prefix for the log message (e.g., "DQL Execution Metadata" or "DQL Execution Metadata (Polled)")
+ * @param budgetLimitGB - Budget limit in GB for tracking purposes
+ * @returns DqlExecutionResult with extracted metadata
+ */
+const createResultAndLog = (queryResult, logPrefix, budgetLimitGB) => {
+    const scannedBytes = queryResult.metadata?.grail?.scannedBytes || 0;
+    // Track budget if limit is provided
+    let budgetState;
+    let budgetWarning;
+    if (budgetLimitGB !== undefined) {
+        const tracker = (0, grail_budget_tracker_1.getGrailBudgetTracker)(budgetLimitGB);
+        budgetState = tracker.addBytesScanned(scannedBytes);
+        budgetWarning = (0, grail_budget_tracker_1.generateBudgetWarning)(budgetState, scannedBytes) || undefined;
+    }
+    const result = {
+        records: queryResult.records,
+        metadata: queryResult.metadata,
+        scannedBytes,
+        scannedRecords: queryResult.metadata?.grail?.scannedRecords,
+        executionTimeMilliseconds: queryResult.metadata?.grail?.executionTimeMilliseconds,
+        queryId: queryResult.metadata?.grail?.queryId,
+        sampled: queryResult.metadata?.grail?.sampled,
+        budgetState,
+        budgetWarning,
+    };
+    console.error(`${logPrefix} scannedBytes=${result.scannedBytes} scannedRecords=${result.scannedRecords} executionTime=${result.executionTimeMilliseconds} queryId=${result.queryId}`);
+    return result;
+};
 /**
  * Execute a DQL statement against the Dynatrace API.
  * If the result is immediately available, it will be returned.
  * If the result is not immediately available, it will poll for the result until it is available.
  * @param dtClient
  * @param body - Contains the DQL statement to execute, and optional parameters like maxResultRecords and maxResultBytes
- * @returns the result without metadata and without notifications, or undefined if the query failed or no result was returned.
+ * @param budgetLimitGB - Optional budget limit in GB for tracking bytes scanned
+ * @returns the result with records, metadata and cost information, or undefined if the query failed or no result was returned.
  */
-const executeDql = async (dtClient, body) => {
+const executeDql = async (dtClient, body, budgetLimitGB) => {
+    // Check budget before executing the query if budget limit is provided
+    if (budgetLimitGB !== undefined) {
+        const tracker = (0, grail_budget_tracker_1.getGrailBudgetTracker)(budgetLimitGB);
+        const currentState = tracker.getState();
+        if (currentState.isBudgetExceeded) {
+            console.error('DQL execution aborted: Grail budget has been exceeded');
+            const budgetWarning = (0, grail_budget_tracker_1.generateBudgetWarning)(currentState, 0);
+            throw new Error(budgetWarning || 'DQL execution aborted: Grail budget has been exceeded');
+        }
+    }
+    // create a Dynatrace QueryExecutionClient
     const queryExecutionClient = new client_query_1.QueryExecutionClient(dtClient);
+    // and execute the query (part of body)
     const response = await queryExecutionClient.queryExecute({
         body,
+        // define a dedicated user agent to enable tracking of DQL queries executed by the dynatrace-mcp-server
         dtClientContext: (0, user_agent_1.getUserAgent)(),
     });
+    // check if we already got a result back
     if (response.result) {
-        // return response result immediately
-        return response.result.records;
+        // yes - return response result immediately
+        return createResultAndLog(response.result, 'execute_dql - Metadata:', budgetLimitGB);
     }
-    // else: We might have to poll
+    // no result yet? we have wait and poll (this requires requestToken to be set)
     if (response.requestToken) {
         // poll for the result
         let pollResponse;
@@ -42,13 +89,18 @@ const executeDql = async (dtClient, body) => {
                 requestToken: response.requestToken,
                 dtClientContext: (0, user_agent_1.getUserAgent)(),
             });
-            // done - let's return it
+            // check if we got a result from the polling endpoint
             if (pollResponse.result) {
-                return pollResponse.result.records;
+                // yes - let's return the polled result
+                return createResultAndLog(pollResponse.result, 'execute_dql Metadata (polled):', budgetLimitGB);
             }
         } while (pollResponse.state === 'RUNNING' || pollResponse.state === 'NOT_STARTED');
+        // state != RUNNING and != NOT_STARTED - we should log that
+        console.error(`execute_dql with requestToken ${response.requestToken} ended with state ${pollResponse.state}, stopping...`);
+        return undefined;
     }
-    // else: whatever happened - we have an error
+    // no requestToken set? This should not happen, but just in case, let's log it
+    console.error(`execute_dql did not respond with a requestToken, stopping...`);
     return undefined;
 };
 exports.executeDql = executeDql;

package/dist/capabilities/execute-dql.test.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const execute_dql_1 = require("./execute-dql");
+const client_query_1 = require("@dynatrace-sdk/client-query");
+const grail_budget_tracker_1 = require("../utils/grail-budget-tracker");
+// Mock the external dependencies
+jest.mock('@dynatrace-sdk/client-query');
+jest.mock('../utils/user-agent', () => ({
+    getUserAgent: () => 'test-user-agent',
+}));
+describe('executeDql Budget Check', () => {
+    let mockHttpClient;
+    let mockQueryExecutionClient;
+    beforeEach(() => {
+        // Reset budget tracker before each test
+        (0, grail_budget_tracker_1.resetGrailBudgetTracker)();
+        // Create mock HTTP client
+        mockHttpClient = {
+        // Add any necessary properties/methods for HttpClient mock
+        };
+        // Create mock QueryExecutionClient
+        mockQueryExecutionClient = {
+            queryExecute: jest.fn(),
+            queryPoll: jest.fn(),
+            queryCancel: jest.fn(),
+        };
+        // Mock the QueryExecutionClient constructor
+        client_query_1.QueryExecutionClient.mockImplementation(() => mockQueryExecutionClient);
+    });
+    afterEach(() => {
+        jest.clearAllMocks();
+        (0, grail_budget_tracker_1.resetGrailBudgetTracker)();
+    });
+    it('should prevent execution when budget is exceeded', async () => {
+        const budgetLimitGB = 0.001; // Very small budget limit (1 MB)
+        // First, exhaust the budget by adding bytes to tracker
+        const tracker = (0, grail_budget_tracker_1.getGrailBudgetTracker)(budgetLimitGB);
+        tracker.addBytesScanned(2 * 1000 * 1000); // Add 2 MB, exceeding the 1 MB limit
+        const dqlStatement = 'fetch logs | limit 10';
+        const body = { query: dqlStatement };
+        // Execute DQL with budget limit and expect it to throw
+        await expect((0, execute_dql_1.executeDql)(mockHttpClient, body, budgetLimitGB)).rejects.toThrow(/budget/);
+        // Verify that queryExecute was NOT called
+        expect(mockQueryExecutionClient.queryExecute).not.toHaveBeenCalled();
+    });
+    it('should allow execution when budget is not exceeded', async () => {
+        const budgetLimitGB = 1; // 1 GB budget limit
+        const dqlStatement = 'fetch logs | limit 10';
+        const body = { query: dqlStatement };
+        // Mock successful response
+        const mockResponse = {
+            state: 'RUNNING',
+            result: {
+                records: [{ field1: 'value1' }],
+                types: [],
+                metadata: {
+                    grail: {
+                        scannedBytes: 1000,
+                        scannedRecords: 1,
+                        executionTimeMilliseconds: 100,
+                        queryId: 'test-query-id',
+                    },
+                },
+            },
+        };
+        mockQueryExecutionClient.queryExecute.mockResolvedValue(mockResponse);
+        // Execute DQL with budget limit
+        const result = await (0, execute_dql_1.executeDql)(mockHttpClient, body, budgetLimitGB);
+        // Verify that queryExecute WAS called
+        expect(mockQueryExecutionClient.queryExecute).toHaveBeenCalledWith({
+            body,
+            dtClientContext: 'test-user-agent',
+        });
+        // Verify the result is returned correctly
+        expect(result).toBeDefined();
+        expect(result?.records).toEqual([{ field1: 'value1' }]);
+        expect(result?.scannedBytes).toBe(1000);
+        expect(result?.budgetState?.isBudgetExceeded).toBe(false);
+    });
+    it('should allow execution when no budget limit is provided', async () => {
+        const dqlStatement = 'fetch logs | limit 10';
+        const body = { query: dqlStatement };
+        // Mock successful response
+        const mockResponse = {
+            state: 'RUNNING',
+            result: {
+                records: [{ field1: 'value1' }],
+                types: [],
+                metadata: {
+                    grail: {
+                        scannedBytes: 1000000000, // 1 GB - would exceed small budgets
+                        scannedRecords: 1000,
+                        executionTimeMilliseconds: 100,
+                        queryId: 'test-query-id',
+                    },
+                },
+            },
+        };
+        mockQueryExecutionClient.queryExecute.mockResolvedValue(mockResponse);
+        // Execute DQL without budget limit
+        const result = await (0, execute_dql_1.executeDql)(mockHttpClient, body);
+        // Verify that queryExecute WAS called
+        expect(mockQueryExecutionClient.queryExecute).toHaveBeenCalledWith({
+            body,
+            dtClientContext: 'test-user-agent',
+        });
+        // Verify the result is returned correctly
+        expect(result).toBeDefined();
+        expect(result?.records).toEqual([{ field1: 'value1' }]);
+        expect(result?.scannedBytes).toBe(1000000000);
+        expect(result?.budgetState).toBeUndefined(); // No budget tracking
+    });
+});

package/dist/capabilities/find-monitored-entity-by-name.js

@@ -35,10 +35,10 @@ const findMonitoredEntityByName = async (dtClient, entityName) => {
     // Get response from API
     // Note: This may be slow, as we are appending multiple entity types above
     const dqlResponse = await (0, execute_dql_1.executeDql)(dtClient, { query: dql });
-    if (dqlResponse && dqlResponse.length > 0) {
+    if (dqlResponse && dqlResponse.records && dqlResponse.records.length > 0) {
         let resp = 'The following monitored entities were found:\n';
         // iterate over dqlResponse and create a string with the entity names
-        dqlResponse.forEach((entity) => {
+        dqlResponse.records.forEach((entity) => {
             if (entity) {
                 resp += `- Entity '${entity['entity.name']}' of type '${entity['entity.type']} has entity id '${entity.id}'\n`;
             }