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

package/README.md

@@ -1,8 +1,30 @@
 # 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.
 
+> 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.
+
 <img width="1046" alt="image" src="/assets/dynatrace-mcp-arch.png" />
 
 ## Use cases
@@ -27,11 +49,11 @@ 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:**
 
@@ -39,7 +61,17 @@ depend on the volume (GB scanned/billed).
 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
 
-**Note**: We will be providing a way to monitor Query Usage of the dynatrace-mcp-server in the future.
+**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 +88,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 +171,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 +204,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 +217,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 +236,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,21 +258,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
+npx -y @dynatrace-oss/dynatrace-mcp-server@latest --version
 ```
 
 **Configuration for MCP clients that support HTTP transport:**
@@ -299,16 +328,18 @@ 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)
+
+**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 +349,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_)
@@ -342,6 +375,8 @@ Depending on the features you are using, the following scopes are needed:
 
   **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,
@@ -493,12 +528,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.
 
-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 Platform Tokens:**
 
-It is recommended to try access the following API (which requires minimal scopes `app-engine:apps:run` and `app-engine:functions:run`):
+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
+
+**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 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 +575,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 +650,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/execute-dql.js

@@ -13,25 +13,48 @@ 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)")
+ * @returns DqlExecutionResult with extracted metadata
+ */
+const createResultAndLog = (queryResult, logPrefix) => {
+    const result = {
+        records: queryResult.records,
+        metadata: queryResult.metadata,
+        scannedBytes: queryResult.metadata?.grail?.scannedBytes,
+        scannedRecords: queryResult.metadata?.grail?.scannedRecords,
+        executionTimeMilliseconds: queryResult.metadata?.grail?.executionTimeMilliseconds,
+        queryId: queryResult.metadata?.grail?.queryId,
+        sampled: queryResult.metadata?.grail?.sampled,
+    };
+    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.
+ * @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) => {
+    // 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:');
     }
-    // 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 +65,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):');
             }
         } 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/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`;
             }

package/dist/capabilities/get-monitored-entity-details.js

@@ -21,15 +21,15 @@ const getMonitoredEntityDetails = async (dtClient, entityId) => {
     // Get response from API
     const dqlResponse = await (0, execute_dql_1.executeDql)(dtClient, { query: dql });
     // verify response and length
-    if (!dqlResponse || dqlResponse.length === 0) {
+    if (!dqlResponse || !dqlResponse.records || dqlResponse.records.length === 0) {
         console.error(`No entity found for ID: ${entityId}`);
         return;
     }
     // in case we have more than one entity -> log it
-    if (dqlResponse.length > 1) {
-        console.error(`Multiple entities (${dqlResponse.length}) found for entity ID: ${entityId}. Returning the first one.`);
+    if (dqlResponse.records.length > 1) {
+        console.error(`Multiple entities (${dqlResponse.records.length}) found for entity ID: ${entityId}. Returning the first one.`);
     }
-    const entity = dqlResponse[0];
+    const entity = dqlResponse.records[0];
     // make typescript happy; entity should never be null though
     if (!entity) {
         console.error(`No entity found for ID: ${entityId}`);
@@ -38,6 +38,7 @@ const getMonitoredEntityDetails = async (dtClient, entityId) => {
     // return entity details
     return {
         entityId: String(entity.id),
+        entityTypeTable: entityType,
         displayName: String(entity['entity.name']),
         type: String(entity['entity.type']),
         allProperties: entity || undefined,

package/dist/capabilities/list-vulnerabilities.js

@@ -22,10 +22,10 @@ const listVulnerabilities = async (dtClient, additionalFilter, riskScore) => {
         maxResultRecords: 5000,
         maxResultBytes: 5_000_000, // 5 MB
     });
-    if (!response || response.length === 0) {
+    if (!response || !response.records || response.records.length === 0) {
         return [];
     }
-    const vulnerabilities = response.map((vuln) => {
+    const vulnerabilities = response.records.map((vuln) => {
         const vulnerabilityId = vuln['vulnerability.id'] || 'N/A';
         const vulnerabilityDisplayId = vuln['vulnerability.display_id'] || 'N/A';
         const riskScore = vuln['vulnerability.risk.score'] || 'N/A';

package/dist/index.js

@@ -11,7 +11,7 @@ const node_http_1 = require("node:http");
 const node_crypto_1 = require("node:crypto");
 const commander_1 = require("commander");
 const zod_1 = require("zod");
-const package_json_1 = require("../package.json");
+const version_1 = require("./utils/version");
 const dynatrace_clients_1 = require("./authentication/dynatrace-clients");
 const list_vulnerabilities_1 = require("./capabilities/list-vulnerabilities");
 const list_problems_1 = require("./capabilities/list-problems");
@@ -25,6 +25,7 @@ const send_slack_message_1 = require("./capabilities/send-slack-message");
 const find_monitored_entity_by_name_1 = require("./capabilities/find-monitored-entity-by-name");
 const davis_copilot_1 = require("./capabilities/davis-copilot");
 const getDynatraceEnv_1 = require("./getDynatraceEnv");
+const telemetry_openkit_1 = require("./utils/telemetry-openkit");
 (0, dotenv_1.config)();
 let scopesBase = [
     'app-engine:apps:run', // needed for environmentInformationClient
@@ -58,7 +59,7 @@ const main = async () => {
         console.error(err.message);
         process.exit(1);
     }
-    console.error(`Initializing Dynatrace MCP Server v${package_json_1.version}...`);
+    console.error(`Initializing Dynatrace MCP Server v${(0, version_1.getPackageJsonVersion)()}...`);
     const { oauthClientId, oauthClientSecret, dtEnvironment, dtPlatformToken, slackConnectionId } = dynatraceEnv;
     // Test connection on startup
     let retryCount = 0;
@@ -88,10 +89,24 @@ const main = async () => {
             await new Promise((resolve) => setTimeout(resolve, delay));
         }
     }
-    console.error(`Starting Dynatrace MCP Server v${package_json_1.version}...`);
+    console.error(`Starting Dynatrace MCP Server v${(0, version_1.getPackageJsonVersion)()}...`);
+    // Initialize usage tracking
+    const telemetry = (0, telemetry_openkit_1.createTelemetry)();
+    await telemetry.trackMcpServerStart();
+    // Create a shutdown handler that takes shutdown operations as parameters
+    const shutdownHandler = (...shutdownOps) => {
+        return async () => {
+            console.error('Shutting down MCP server...');
+            for (const op of shutdownOps) {
+                await op();
+            }
+            process.exit(0);
+        };
+    };
+    // Initialize Metadata for MCP Server
     const server = new mcp_js_1.McpServer({
         name: 'Dynatrace MCP Server',
-        version: package_json_1.version,
+        version: (0, version_1.getPackageJsonVersion)(),
     }, {
         capabilities: {
             tools: {},
@@ -100,13 +115,21 @@ const main = async () => {
     // quick abstraction/wrapper to make it easier for tools to reply text instead of JSON
     const tool = (name, description, paramsSchema, cb) => {
         const wrappedCb = async (args) => {
+            // track starttime for telemetry
+            const startTime = Date.now();
+            // track toolcall for telemetry
+            let toolCallSuccessful = false;
             try {
+                // call the tool
                 const response = await cb(args);
+                toolCallSuccessful = true;
                 return {
                     content: [{ type: 'text', text: response }],
                 };
             }
             catch (error) {
+                // Track error
+                telemetry.trackError(error, `tool_${name}`).catch((e) => console.warn('Failed to track error:', e));
                 // check if it's an error originating from the Dynatrace SDK / API Gateway and provide an appropriate message to the user
                 if ((0, shared_errors_1.isClientRequestError)(error)) {
                     return {
@@ -121,9 +144,17 @@ const main = async () => {
                     isError: true,
                 };
             }
+            finally {
+                // Track tool usage
+                const duration = Date.now() - startTime;
+                telemetry
+                    .trackMcpToolUsage(name, toolCallSuccessful, duration)
+                    .catch((e) => console.warn('Failed to track tool usage:', e));
+            }
         };
         server.tool(name, description, paramsSchema, (args) => wrappedCb(args));
     };
+    /** Tool Definitions below */
     tool('get_environment_info', 'Get information about the connected Dynatrace Environment (Tenant) and verify the connection and authentication.', {}, async ({}) => {
         // create an oauth-client
         const dtClient = await (0, dynatrace_clients_1.createDtHttpClient)(dtEnvironment, scopesBase, oauthClientId, oauthClientSecret, dtPlatformToken);
@@ -193,10 +224,10 @@ const main = async () => {
         const dtClient = await (0, dynatrace_clients_1.createDtHttpClient)(dtEnvironment, scopesBase.concat('storage:events:read', 'storage:buckets:read'), oauthClientId, oauthClientSecret, dtPlatformToken);
         // get problems (uses fetch)
         const result = await (0, list_problems_1.listProblems)(dtClient, additionalFilter);
-        if (result && result.length > 0) {
-            let resp = `Found ${result.length} problems! Displaying the top ${maxProblemsToDisplay} problems:\n`;
+        if (result && result.records && result.records.length > 0) {
+            let resp = `Found ${result.records.length} problems! Displaying the top ${maxProblemsToDisplay} problems:\n`;
             // iterate over dqlResponse and create a string with the problem details, but only show the top maxProblemsToDisplay problems
-            result.slice(0, maxProblemsToDisplay).forEach((problem) => {
+            result.records.slice(0, maxProblemsToDisplay).forEach((problem) => {
                 if (problem) {
                     resp += `Problem ${problem['display_id']} (please refer to this problem with \`problemId\` or \`event.id\` ${problem['problem_id']}))
                   with event.status ${problem['event.status']}, event.category ${problem['event.category']}: ${problem['event.name']} -
@@ -250,6 +281,18 @@ const main = async () => {
         else if (entityDetails.type == 'CLOUD_APPLICATION') {
             resp += `You can find more details about the application at ${dtEnvironment}/ui/apps/dynatrace.kubernetes/explorer/workload?detailsId=${entityDetails.entityId}`;
         }
+        resp += `\n\n**Filter**:`;
+        // Use entityTypeTable as the filter (e.g., fetch logs | filter dt.entity.service == "SERVICE-1234")
+        if (entityDetails.entityTypeTable) {
+            resp += ` You can use the following filter to get relevant information from other tools: \`| filter ${entityDetails.entityTypeTable} == "${entityDetails.entityId}"\`. `;
+        }
+        else {
+            resp += ` Try to use search command as follows: \`| search "${entityDetails.entityId}"\`. `;
+        }
+        resp += `\n\n**Next Steps**\n\n`;
+        resp += `1. Find available metrics for this entity, by using execute_dql tool with the following DQL statement: "fetch metric.series" and the filter defined above\n`;
+        resp += `2. Find out whether any problems exist for this entity using the list_problems tool\n`;
+        resp += `3. Explore logs for this entity by using execute_dql with "fetch logs" and applying the filter mentioned above'\n`;
         return resp;
     });
     tool('send_slack_message', 'Sends a Slack message to a dedicated Slack Channel via Slack Connector on Dynatrace', {
@@ -281,11 +324,11 @@ const main = async () => {
         return resp;
     });
     tool('execute_dql', 'Get Logs, Metrics, Spans or Events from Dynatrace GRAIL by executing a Dynatrace Query Language (DQL) statement. ' +
-        'You can also use "generate_dql_from_natural_language" to generate a DQL statement based on your request. ' +
+        'You can also use the "generate_dql_from_natural_language" tool upfront to generate or refine a DQL statement based on your request. ' +
         'Note: For more information about available fields for filters and aggregation, use the query "fetch dt.semantic_dictionary.models | filter data_object == \"logs\""', {
         dqlStatement: zod_1.z
             .string()
-            .describe('DQL Statement (Ex: "fetch [logs, spans, events] | filter <some-filter> | summarize count(), by:{some-fields}.", "timeseries { avg(<metric-name>), value.A = avg(<metric-name>, scalar: true) }")'),
+            .describe('DQL Statement (Ex: "fetch [logs, spans, events] | filter <some-filter> | summarize count(), by:{some-fields}.", or for metrics: "timeseries { avg(<metric-name>), value.A = avg(<metric-name>, scalar: true) }")'),
     }, async ({ dqlStatement }) => {
         // Create a HTTP Client that has all storage:*:read scopes
         const dtClient = await (0, dynatrace_clients_1.createDtHttpClient)(dtEnvironment, scopesBase.concat('storage:buckets:read', // Read all system data stored on Grail
@@ -300,7 +343,37 @@ const main = async () => {
         'storage:user.sessions:read', // Read User sessions from Grail
         'storage:security.events:read'), oauthClientId, oauthClientSecret, dtPlatformToken);
         const response = await (0, execute_dql_1.executeDql)(dtClient, { query: dqlStatement });
-        return `DQL Response: ${JSON.stringify(response)}`;
+        if (!response) {
+            return 'DQL execution failed or returned no result.';
+        }
+        let result = `📊 **DQL Query Results**\n\n`;
+        // Cost and Performance Information
+        if (response.scannedRecords !== undefined) {
+            result += `- **Scanned Records:** ${response.scannedRecords.toLocaleString()}\n`;
+        }
+        if (response.scannedBytes !== undefined) {
+            const scannedGB = response.scannedBytes / (1000 * 1000 * 1000);
+            result += `- **Scanned Bytes:** ${scannedGB.toFixed(2)} GB`;
+            // Cost warning based on scanned bytes
+            if (scannedGB > 500) {
+                result += `\n    ⚠️ **Very High Data Usage Warning:** This query scanned ${scannedGB.toFixed(1)} GB of data, which may impact your Dynatrace consumption. Please take measures to optimize your query, like limiting the timeframe or selecting a bucket.\n`;
+            }
+            else if (scannedGB > 50) {
+                result += `\n    ⚠️ **High Data Usage Warning:** This query scanned ${scannedGB.toFixed(2)} GB of data, which may impact your Dynatrace consumption.\n`;
+            }
+            else if (scannedGB > 5) {
+                result += `\n    💡 **Moderate Data Usage:** This query scanned ${scannedGB.toFixed(2)} GB of data.\n`;
+            }
+            else if (response.scannedBytes === 0) {
+                result += `\n    💡 **No Data consumed:** This query did not consume any data.\n`;
+            }
+        }
+        if (response.sampled !== undefined && response.sampled) {
+            result += `- **⚠️ Sampling Used:** Yes (results may be approximate)\n`;
+        }
+        result += `\n📋 **Query Results**: (${response.records?.length || 0} records):\n\n`;
+        result += `\`\`\`json\n${JSON.stringify(response.records, null, 2)}\n\`\`\``;
+        return result;
     });
     tool('generate_dql_from_natural_language', 'Convert natural language queries to Dynatrace Query Language (DQL) using Davis CoPilot AI. You can ask for problem events, security issues, logs, metrics, spans, and custom data.', {
         text: zod_1.z
@@ -311,7 +384,10 @@ const main = async () => {
         const response = await (0, davis_copilot_1.generateDqlFromNaturalLanguage)(dtClient, text);
         let resp = `🔤 Natural Language to DQL:\n\n`;
         resp += `**Query:** "${text}"\n\n`;
-        resp += `**Generated DQL:**\n\`\`\`\n${response.dql}\n\`\`\`\n\n`;
+        if (response.dql) {
+            // Typically, the DQL response is empty if status == FAILED
+            resp += `**Generated DQL:**\n\`\`\`\n${response.dql}\n\`\`\`\n\n`;
+        }
         resp += `**Status:** ${response.status}\n`;
         resp += `**Message Token:** ${response.messageToken}\n`;
         if (response.metadata?.notifications && response.metadata.notifications.length > 0) {
@@ -320,9 +396,11 @@ const main = async () => {
                 resp += `- ${notification.severity}: ${notification.message}\n`;
             });
         }
-        resp += `\n💡 **Next Steps:**\n`;
-        resp += `1. Use "execute_dql" tool to run the query (you can omit running the "verify_dql" tool)\n`;
-        resp += `2. If results don't match expectations, refine your natural language description and try again\n`;
+        if (response.status != 'FAILED') {
+            resp += `\n💡 **Next Steps:**\n`;
+            resp += `1. Use "execute_dql" tool to run the query (you can omit running the "verify_dql" tool)\n`;
+            resp += `2. If results don't match expectations, refine your natural language description and try again\n`;
+        }
         return resp;
     });
     tool('explain_dql_in_natural_language', 'Explain Dynatrace Query Language (DQL) statements in natural language using Davis CoPilot AI.', {
@@ -366,7 +444,10 @@ const main = async () => {
         const response = await (0, davis_copilot_1.chatWithDavisCopilot)(dtClient, text, conversationContext);
         let resp = `🤖 Davis CoPilot Response:\n\n`;
         resp += `**Your Question:** "${text}"\n\n`;
-        resp += `**Answer:**\n${response.text}\n\n`;
+        if (response.text) {
+            // Typically, text is empty if status is FAILED
+            resp += `**Answer:**\n${response.text}\n\n`;
+        }
         resp += `**Status:** ${response.status}\n`;
         resp += `**Message Token:** ${response.messageToken}\n`;
         if (response.metadata?.sources && response.metadata.sources.length > 0) {
@@ -384,6 +465,9 @@ const main = async () => {
         if (response.state?.conversationId) {
             resp += `\n**Conversation ID:** ${response.state.conversationId}`;
         }
+        if (response.status == 'FAILED') {
+            resp += `\n❌ **Your request was not successful**\n`;
+        }
         return resp;
     });
     tool('create_workflow_for_notification', 'Create a notification for a team based on a problem type within Workflows in Dynatrace', {
@@ -441,7 +525,7 @@ const main = async () => {
     program
         .name('dynatrace-mcp-server')
         .description('Dynatrace Model Context Protocol (MCP) Server')
-        .version(package_json_1.version)
+        .version((0, version_1.getPackageJsonVersion)())
         .option('--http', 'enable HTTP server mode instead of stdio')
         .option('--server', 'enable HTTP server mode (alias for --http)')
         .option('-p, --port <number>', 'port for HTTP server', '3000')
@@ -482,13 +566,8 @@ const main = async () => {
         httpServer.listen(httpPort, host, () => {
             console.error(`Dynatrace MCP Server running on HTTP at http://${host}:${httpPort}`);
         });
-        // Handle graceful shutdown
-        process.on('SIGINT', () => {
-            console.error('Shutting down HTTP server...');
-            httpServer.close(() => {
-                process.exit(0);
-            });
-        });
+        // Handle graceful shutdown for http server mode
+        process.on('SIGINT', shutdownHandler(async () => await telemetry.shutdown(), () => new Promise((resolve) => httpServer.close(() => resolve()))));
     }
     else {
         // Default stdio mode
@@ -496,9 +575,21 @@ const main = async () => {
         console.error('Connecting server to transport...');
         await server.connect(transport);
         console.error('Dynatrace MCP Server running on stdio');
+        // Handle graceful shutdown for stdio mode
+        process.on('SIGINT', shutdownHandler(async () => await telemetry.shutdown()));
+        process.on('SIGTERM', shutdownHandler(async () => await telemetry.shutdown()));
     }
 };
-main().catch((error) => {
+main().catch(async (error) => {
     console.error('Fatal error in main():', error);
+    try {
+        // report error in main
+        const telemetry = (0, telemetry_openkit_1.createTelemetry)();
+        await telemetry.trackError(error, 'main_error');
+        await telemetry.shutdown();
+    }
+    catch (e) {
+        console.warn('Failed to track fatal error:', e);
+    }
     process.exit(1);
 });

package/dist/utils/telemetry-openkit.js

@@ -0,0 +1,223 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTelemetry = createTelemetry;
+const openkit_js_1 = require("@dynatrace/openkit-js");
+const os = __importStar(require("os"));
+const crypto = __importStar(require("crypto"));
+const version_1 = require("./version");
+/**
+ * Based on https://docs.dynatrace.com/docs/ingest-from/extend-dynatrace/openkit/instrument-your-application-using-dynatrace-openkit#openkit-basic-sample--javascript
+ */
+class DynatraceMcpTelemetry {
+    openKit = null;
+    session = null;
+    isEnabled;
+    initPromise;
+    constructor() {
+        this.isEnabled = process.env.DT_MCP_DISABLE_TELEMETRY !== 'true';
+        if (!this.isEnabled) {
+            throw new Error('Dynatrace Telemetry is disabled via DT_MCP_DISABLE_TELEMETRY=true');
+        }
+        // Default configuration for Dynatrace MCP Server Telemetry endpoints (DT Prod Self Mon)
+        const applicationId = process.env.DT_MCP_TELEMETRY_APPLICATION_ID || '5e2dbb56-076b-412e-8ffc-7babb7ae7c5d';
+        const endpointUrl = process.env.DT_MCP_TELEMETRY_ENDPOINT_URL || 'https://bf96767wvv.bf.dynatrace.com/mbeacon';
+        // get anonymized device id
+        const deviceId = process.env.DT_MCP_TELEMETRY_DEVICE_ID || this.generateDeviceId();
+        this.initPromise = this.initializeOpenKit(endpointUrl, applicationId, deviceId);
+    }
+    /**
+     *
+     * @param endpointUrl Dynatrace Endpoint for OpenKit Ingest
+     * @param applicationId Application Id for OpenKit Ingest
+     * @param deviceId Device or Session ID (should be anonymized)
+     * @returns true if initialization was successful, false otherwise
+     */
+    async initializeOpenKit(endpointUrl, applicationId, deviceId) {
+        try {
+            console.error(`Connecting Dynatrace Telemetry via ${endpointUrl}. You can disable this by setting DT_MCP_DISABLE_TELEMETRY=true.`);
+            this.openKit = new openkit_js_1.OpenKitBuilder(endpointUrl, applicationId, parseInt(deviceId, 10))
+                .withApplicationVersion((0, version_1.getPackageJsonVersion)())
+                .withOperatingSystem(`${os.platform()} ${os.release()}`)
+                .withManufacturer('Dynatrace-OSS')
+                .withModelId('Dynatrace-MCP-Server')
+                .build();
+            return new Promise((resolve) => {
+                const timeoutInMilliseconds = 10 * 1000; // 10 seconds timeout
+                this.openKit.waitForInit((success) => {
+                    if (success) {
+                        this.session = this.openKit.createSession();
+                    }
+                    else {
+                        console.error('Failed to initialize Dynatrace Telemetry: timeout or connection failed');
+                        this.isEnabled = false;
+                    }
+                    resolve(success);
+                }, timeoutInMilliseconds);
+            });
+        }
+        catch (error) {
+            console.error('Failed to initialize Dynatrace Telemetry:', error);
+            console.error('If the error persists, please consider disabling telemetry by setting DT_MCP_DISABLE_TELEMETRY=true.');
+            this.isEnabled = false;
+            return false;
+        }
+    }
+    /**
+     * Generates a random device identifier
+     * @returns deviceId - a string containing number for OpenKit
+     */
+    generateDeviceId() {
+        // Generate a simple device ID based on hostname and some randomness
+        const hostname = os.hostname();
+        const random = crypto.randomBytes(8).toString('hex');
+        const hash = crypto.createHash('md5').update(`${hostname}-${random}`).digest('hex');
+        // Convert to a number (device ID must be a number for OpenKit)
+        return parseInt(hash.substring(0, 15), 16).toString();
+    }
+    /**
+     * Track Server Start
+     * @returns nothing
+     */
+    async trackMcpServerStart() {
+        if (!this.isEnabled)
+            return;
+        await this.initPromise;
+        if (!this.session)
+            return;
+        try {
+            const action = this.session.enterAction('mcp_server_start');
+            action.reportEvent('server_started');
+            action.reportValue('version', (0, version_1.getPackageJsonVersion)());
+            action.reportValue('node_version', process.version);
+            action.reportValue('platform', process.platform);
+            action.leaveAction();
+        }
+        catch (error) {
+            console.warn('Failed to track server start:', error);
+        }
+    }
+    /**
+     * Track Tool Usage
+     * @param toolName name of the tool
+     * @param success whether or not the tool call was successful
+     * @param duration duration of the tool call
+     * @returns nothing
+     */
+    async trackMcpToolUsage(toolName, success, duration) {
+        if (!this.isEnabled)
+            return;
+        await this.initPromise;
+        if (!this.session)
+            return;
+        try {
+            const action = this.session.enterAction(`tool_${toolName}`);
+            action.reportEvent(success ? 'tool_success' : 'tool_error');
+            action.reportValue('tool_name', toolName);
+            action.reportValue('success', success ? 'true' : 'false');
+            if (duration !== undefined) {
+                action.reportValue('duration_ms', duration);
+            }
+            action.leaveAction();
+        }
+        catch (error) {
+            console.warn('Failed to track tool usage:', error);
+        }
+    }
+    /**
+     * Track Errors
+     * @param error error message to be tracked
+     * @param context
+     * @returns nothing
+     */
+    async trackError(error, context) {
+        if (!this.isEnabled)
+            return;
+        await this.initPromise;
+        if (!this.session)
+            return;
+        try {
+            const action = this.session.enterAction('error_occurred');
+            // reportError expects name and code, so we'll use error name and a generic error code
+            action.reportError(error.name || 'Error', 500);
+            if (context) {
+                action.reportValue('error_context', context);
+            }
+            action.reportValue('error_message', error.message);
+            if (error.stack) {
+                action.reportValue('error_stack', error.stack.substring(0, 1000)); // Limit stack trace length
+            }
+            action.leaveAction();
+        }
+        catch (trackingError) {
+            console.warn('Failed to track error:', trackingError);
+        }
+    }
+    async shutdown() {
+        if (!this.isEnabled)
+            return;
+        await this.initPromise;
+        try {
+            if (this.session) {
+                this.session.end();
+            }
+            if (this.openKit) {
+                await new Promise((resolve) => {
+                    this.openKit.shutdown(() => resolve());
+                });
+            }
+        }
+        catch (error) {
+            console.warn('Failed to shutdown usage tracking:', error);
+        }
+    }
+}
+class NoOpTelemetry {
+    async trackMcpServerStart() { }
+    async trackMcpToolUsage() { }
+    async trackError() { }
+    async shutdown() { }
+}
+function createTelemetry() {
+    try {
+        return new DynatraceMcpTelemetry();
+    }
+    catch (e) {
+        // Failed to initialize
+        console.error(e);
+        // fallback to NoOp Telemetry
+        return new NoOpTelemetry();
+    }
+}

package/dist/utils/user-agent.js

@@ -1,12 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getUserAgent = void 0;
-const package_json_1 = require("../../package.json");
+const version_1 = require("./version");
 /**
  * Generate a user agent string for Dynatrace MCP Server
  * @returns User agent string in format: dynatrace-mcp-server/vX.X.X (platform-arch)
  */
 const getUserAgent = () => {
-    return `dynatrace-mcp-server/v${package_json_1.version} (${process.platform}-${process.arch})`;
+    return `dynatrace-mcp-server/v${(0, version_1.getPackageJsonVersion)()} (${process.platform}-${process.arch})`;
 };
 exports.getUserAgent = getUserAgent;

package/dist/utils/version.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPackageJsonVersion = getPackageJsonVersion;
+const package_json_1 = require("../../package.json");
+/**
+ * Gets the current version of the Dynatrace MCP Server from package.json
+ * Note: we have package.json listed in exports, such that we can ensure it's always part of the bundle
+ * @returns The version string from package.json
+ */
+function getPackageJsonVersion() {
+    return package_json_1.version;
+}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@dynatrace-oss/dynatrace-mcp-server",
-  "version": "0.5.0",
+  "version": "0.6.0-rc.1",
+  "mcpName": "io.github.dynatrace-oss/Dynatrace-mcp",
   "description": "Model Context Protocol (MCP) server for Dynatrace",
   "keywords": [
     "Dynatrace",
@@ -50,6 +51,7 @@
     "@dynatrace-sdk/client-platform-management-service": "^1.6.3",
     "@dynatrace-sdk/client-query": "^1.18.1",
     "@dynatrace-sdk/shared-errors": "^1.0.0",
+    "@dynatrace/openkit-js": "^4.1.0",
     "@modelcontextprotocol/sdk": "^1.8.0",
     "commander": "^14.0.0",
     "dotenv": "^17.2.1",