@dynatrace-oss/dynatrace-mcp-server 1.4.0 → 1.5.0-beta.2

package/README.md

@@ -43,8 +43,26 @@ Furthermore, you need to configure the URL to a Dynatrace environment:
 
 - `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`)
 
+Authentication will be handled via Authorization Code Flow in your browser, you don't need to define a Platform Token nor an OAuth Client to get started.
+
 Once you are done, we recommend looking into [example prompts](#-example-prompts-), like `Get all details of the entity 'my-service'` or `Show me error logs`. Please mind that these prompts lead to executing DQL statements which may incur [costs](#costs) in accordance to your licence.
 
+**VSCode**
+
+```json
+{
+  "servers": {
+    "npx-dynatrace-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "@dynatrace-oss/dynatrace-mcp-server@latest"],
+      "env": {
+        "DT_ENVIRONMENT": "https://abc12345.apps.dynatrace.com"
+      }
+    }
+  }
+}
+```
+
 ## Architecture
 
 ![Architecture](https://github.com/dynatrace-oss/dynatrace-mcp/blob/main/assets/dynatrace-mcp-arch.png?raw=true)
@@ -124,22 +142,6 @@ We recommend to always set it up for your current workspace instead of using it
 
 **VS Code**
 
-```json
-{
-  "servers": {
-    "npx-dynatrace-mcp-server": {
-      "command": "npx",
-      "cwd": "${workspaceFolder}",
-      "args": ["-y", "@dynatrace-oss/dynatrace-mcp-server@latest"],
-      "envFile": "${workspaceFolder}/.env"
-    }
-  }
-}
-```
-
-Please note: In this config, [the `${workspaceFolder}` variable](https://code.visualstudio.com/docs/reference/variables-reference#_predefined-variables) is used.
-This only works if the config is stored in the current workspaces, e.g., `<your-repo>/.vscode/mcp.json`. Alternatively, this can also be stored in user-settings, and you can define `env` as follows:
-
 ```json
 {
   "servers": {
@@ -147,7 +149,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": {
-        "DT_ENVIRONMENT": ""
+        "DT_ENVIRONMENT": "https://abc12345.apps.dynatrace.com"
       }
     }
   }
@@ -163,7 +165,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": {
-        "DT_ENVIRONMENT": ""
+        "DT_ENVIRONMENT": "https://abc12345.apps.dynatrace.com"
       }
     }
   }
@@ -181,7 +183,7 @@ The [Amazon Q Developer CLI](https://docs.aws.amazon.com/amazonq/latest/qdevelop
       "command": "npx",
       "args": ["-y", "@dynatrace-oss/dynatrace-mcp-server@latest"],
       "env": {
-        "DT_ENVIRONMENT": ""
+        "DT_ENVIRONMENT": "https://abc12345.apps.dynatrace.com"
       }
     }
   }
@@ -201,7 +203,7 @@ The [Amazon Kiro](https://kiro.dev/) is an agentic IDE that helps you do your be
       "command": "npx",
       "args": ["-y", "@dynatrace-oss/dynatrace-mcp-server@latest"],
       "env": {
-        "DT_ENVIRONMENT": ""
+        "DT_ENVIRONMENT": "https://abc12345.apps.dynatrace.com"
       }
     }
   }
@@ -219,10 +221,11 @@ Using `gemini` CLI directly (recommended):
 ```bash
 gemini extensions install https://github.com/dynatrace-oss/dynatrace-mcp
 export DT_PLATFORM_TOKEN=... # optional
-export DT_ENVIRONMENT=https://...
 ```
 
-and verify that the server is running via
+The command will ask for the value Dynatrace Environment.
+
+Verify that the server is running via
 
 ```bash
 gemini mcp list
@@ -237,7 +240,7 @@ Or manually in your `~/.gemini/settings.json` or `.gemini/settings.json`:
       "command": "npx",
       "args": ["@dynatrace-oss/dynatrace-mcp-server@latest"],
       "env": {
-        "DT_ENVIRONMENT": ""
+        "DT_ENVIRONMENT": "https://abc12345.apps.dynatrace.com"
       },
       "timeout": 30000,
       "trust": false
@@ -325,7 +328,7 @@ When just providing `DT_ENVIRONMENT`, the local MCP server will try to open a br
 
 For more information about the other authentication methods, please have a look at the documentation about
 [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.
+[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 (service-users, backend-to-backend communication).
 
 In addition, depending on the features you use, the following variables can be configured:
 
@@ -338,6 +341,7 @@ The MCP server honors system proxy settings for corporate environments:
 - `https_proxy` or `HTTPS_PROXY` (optional, string, e.g., `http://proxy.example.com:8080`) - Proxy server URL for HTTPS requests
 - `http_proxy` or `HTTP_PROXY` (optional, string, e.g., `http://proxy.example.com:8080`) - Proxy server URL for HTTP requests
 - `no_proxy` or `NO_PROXY` (optional, string, e.g., `localhost,127.0.0.1,.local`) - Comma-separated list of hostnames or domains that should bypass the proxy
+- `NODE_EXTRA_CA_CERTS` (optional, string, e.g., `C:\some-path\certificate.pem`) - When set, the well known "root" CAs (like VeriSign) will be extended with the extra certificates
 
 **Note:** The `no_proxy` environment variable is currently logged for informational purposes but not fully enforced by the underlying HTTP client. If you need to bypass the proxy for specific hosts, consider configuring your proxy server to handle these exclusions.
 

package/dist/capabilities/execute-dql.js

@@ -34,6 +34,7 @@ const createResultAndLog = (queryResult, logPrefix, budgetLimitGB) => {
     const result = {
         records: queryResult.records,
         metadata: queryResult.metadata,
+        types: queryResult.types ?? [],
         scannedBytes,
         scannedRecords: queryResult.metadata?.grail?.scannedRecords,
         executionTimeMilliseconds: queryResult.metadata?.grail?.executionTimeMilliseconds,

package/dist/index.js

@@ -3,10 +3,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const client_platform_management_service_1 = require("@dynatrace-sdk/client-platform-management-service");
 const shared_errors_1 = require("@dynatrace-sdk/shared-errors");
+// Dynamically imported below (ESM-only package)
+// import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/server';
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const node_http_1 = require("node:http");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
 const commander_1 = require("commander");
 const zod_1 = require("zod");
 const version_1 = require("./utils/version");
@@ -76,6 +80,9 @@ const allRequiredScopes = scopesBase.concat([
     'document:documents:write', // Create and update documents
 ]);
 const main = async () => {
+    // Dynamic import: @modelcontextprotocol/ext-apps is ESM-only and can't be require()'d.
+    const dynamicImport = new Function('specifier', 'return import(specifier)');
+    const { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE } = await dynamicImport('@modelcontextprotocol/ext-apps/server');
     console.error(`Initializing Dynatrace MCP Server v${(0, version_1.getPackageJsonVersion)()}...`);
     // Configure proxy from environment variables early in the startup process
     (0, proxy_config_1.configureProxyFromEnvironment)();
@@ -181,9 +188,9 @@ const main = async () => {
     }
     // Ready to start the server
     console.error(`Starting Dynatrace MCP Server v${(0, version_1.getPackageJsonVersion)()}...`);
-    // quick abstraction/wrapper to make it easier for tools to reply text instead of JSON
-    const tool = (name, title, description, paramsSchema, annotations, cb) => {
-        const wrappedCb = async (args) => {
+    // Wraps a string-returning tool callback with rate limiting, telemetry, and error handling
+    const wrapToolCallback = (name, cb) => {
+        return async (args, _extra) => {
             // Capture starttime for telemetry and rate limiting
             const startTime = Date.now();
             /**
@@ -210,9 +217,16 @@ const main = async () => {
                 // call the tool
                 const response = await cb(args);
                 toolCallSuccessful = true;
-                return {
-                    content: [{ type: 'text', text: response }],
+                // Support callbacks that return either a plain string or { text, _meta }
+                const text = typeof response === 'string' ? response : response.text;
+                const _meta = typeof response === 'string' ? undefined : response._meta;
+                const result = {
+                    content: [{ type: 'text', text }],
                 };
+                if (_meta) {
+                    result._meta = _meta;
+                }
+                return result;
             }
             catch (error) {
                 // Track error
@@ -239,12 +253,15 @@ const main = async () => {
                     .catch((e) => console.warn('Failed to track tool usage:', e));
             }
         };
+    };
+    // quick abstraction/wrapper to make it easier for tools to reply text instead of JSON
+    const tool = (name, title, description, paramsSchema, annotations, cb) => {
         server.registerTool(name, {
             title: title,
             description: description,
             inputSchema: zod_1.z.object(paramsSchema),
             annotations: annotations,
-        }, (args) => wrappedCb(args));
+        }, (args) => wrapToolCallback(name, cb)(args));
     };
     /**
      * Helper function to request human approval for potentially sensitive operations
@@ -498,26 +515,39 @@ const main = async () => {
         }
         return resp;
     });
-    tool('execute_dql', 'Execute DQL', 'Get data like Logs, Metrics, Spans, Events, or Entity Data from Dynatrace GRAIL by executing a Dynatrace Query Language (DQL) statement. ' +
-        'Use the "generate_dql_from_natural_language" tool upfront to generate or refine a DQL statement based on your request. ' +
-        'To learn about possible fields available for filtering, 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, metric.series, ...], from: now()-4h, to: now() [| filter <some-filter>] [| summarize count(), by:{some-fields}]", or for metrics: "timeseries { avg(<metric-name>), value.A = avg(<metric-name>, scalar: true) }", or for entities via smartscape: "smartscapeNodes \"[*, HOST, PROCESS, ...]\" [| filter id == "<ENTITY-ID>"]"). ' +
-            'When querying data for a specific entity, call the `find_entity_by_name` tool first to get an appropriate filter like `dt.entity.service == "SERVICE-1234"` or `dt.entity.host == "HOST-1234"` to be used in the DQL statement. '),
-        recordLimit: zod_1.z.number().optional().default(100).describe('Maximum number of records to return (default: 100)'),
-        recordSizeLimitMB: zod_1.z
-            .number()
-            .optional()
-            .default(1)
-            .describe('Maximum size of the returned records in MB (default: 1MB)'),
-    }, {
-        // not readonly (DQL statements may modify things), not idempotent (may change over time)
-        readOnlyHint: false,
-        idempotentHint: false,
-        // while we are not strictly talking to the open world here, the response from execute DQL could interpreted as a web-search, which often is referred to open-world
-        openWorldHint: true,
-    }, async ({ dqlStatement, recordLimit = 100, recordSizeLimitMB = 1 }) => {
+    // MCP App: Define the resource URI for the execute_dql interactive UI
+    // The ui:// scheme tells hosts this is an MCP App resource.
+    const executeDqlResourceUri = 'ui://execute-dql/execute-dql.html';
+    // Register the execute_dql tool with MCP App UI support.
+    registerAppTool(server, 'execute_dql', {
+        title: 'Execute DQL',
+        description: 'Get data like Logs, Metrics, Spans, Events, or Entity Data from Dynatrace Grail by executing a Dynatrace Query Language (DQL) statement. ' +
+            'Use the "generate_dql_from_natural_language" tool upfront to generate or refine a DQL statement based on your request. ' +
+            'To learn about possible fields available for filtering, use the query "fetch dt.semantic_dictionary.models | filter data_object == \\"logs\\""',
+        inputSchema: {
+            dqlStatement: zod_1.z
+                .string()
+                .describe('DQL Statement (Ex: "fetch [logs, spans, events, metric.series, ...], from: now()-4h, to: now() [| filter <some-filter>] [| summarize count(), by:{some-fields}]", or for metrics: "timeseries { avg(<metric-name>), value.A = avg(<metric-name>, scalar: true) }", or for entities via smartscape: "smartscapeNodes \\"[*, HOST, PROCESS, ...]\\" [| filter id == \\"<ENTITY-ID>\\"]"). ' +
+                'When querying data for a specific entity, call the `find_entity_by_name` tool first to get an appropriate filter like `dt.entity.service == "SERVICE-1234"` or `dt.entity.host == "HOST-1234"` to be used in the DQL statement. '),
+            recordLimit: zod_1.z.number().optional().default(100).describe('Maximum number of records to return (default: 100)'),
+            recordSizeLimitMB: zod_1.z
+                .number()
+                .optional()
+                .default(1)
+                .describe('Maximum size of the returned records in MB (default: 1MB)'),
+        },
+        annotations: {
+            // not readonly (DQL statements may modify things), not idempotent (may change over time)
+            readOnlyHint: false,
+            idempotentHint: false,
+            // while we are not strictly talking to the open world here, the response from execute DQL could interpreted as a web-search, which often is referred to open-world
+            openWorldHint: true,
+        },
+        _meta: {
+            // MCP App
+            ui: { resourceUri: executeDqlResourceUri },
+        },
+    }, wrapToolCallback('execute_dql', async ({ dqlStatement, recordLimit = 100, recordSizeLimitMB = 1 }) => {
         // Create a HTTP Client that has all storage:*:read scopes
         const dtClient = await createAuthenticatedHttpClient(scopesBase.concat('storage:buckets:read', // Read all system data stored on Grail
         'storage:logs:read', // Read logs for reliability guardian validations
@@ -535,17 +565,20 @@ const main = async () => {
         if (!response) {
             return 'DQL execution failed or returned no result.';
         }
-        let result = `📊 **DQL Query Results**\n\n`;
-        // Budget warning comes first if present
+        // Build warnings array for structured metadata
+        const warnings = [];
         if (response.budgetWarning) {
-            result += `${response.budgetWarning}\n\n`;
+            warnings.push(response.budgetWarning);
         }
+        // Build human-readable text 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);
+            // calculate scanned gigabytes for better readability in warnings and result text
+            const scannedGB = response.scannedBytes !== undefined ? response.scannedBytes / (1000 * 1000 * 1000) : 0;
             result += `- **Scanned Bytes:** ${scannedGB.toFixed(2)} GB`;
             // Show budget status if available
             if (response.budgetState) {
@@ -561,27 +594,58 @@ const main = async () => {
             }
             result += '\n';
             if (scannedGB > 500) {
-                result += `    ⚠️ **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`;
+                warnings.push(`Very High Data Usage: 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.`);
             }
             else if (scannedGB > 50) {
-                result += `    ⚠️ **High Data Usage Warning:** This query scanned ${scannedGB.toFixed(2)} GB of data, which may impact your Dynatrace consumption.\n`;
+                warnings.push(`High Data Usage: This query scanned ${scannedGB.toFixed(2)} GB of data, which may impact your Dynatrace consumption.`);
             }
-            else if (scannedGB > 5) {
+            // Add informational messages (not warnings) about data usage
+            else if (scannedGB > 5 && scannedGB <= 50) {
                 result += `    💡 **Moderate Data Usage:** This query scanned ${scannedGB.toFixed(2)} GB of data.\n`;
             }
             else if (response.scannedBytes === 0) {
                 result += `    💡 **No Data consumed:** This query did not consume any data.\n`;
             }
+            if (response.sampled) {
+                warnings.push('Sampling Used: Results may be approximate');
+            }
+            if (response.records.length === recordLimit) {
+                warnings.push(`Record Limit Reached: The result set was limited to ${recordLimit} records. Consider changing your query with a smaller timeframe, an aggregation or a more concise filter. Alternatively, increase the recordLimit if you expect more results.`);
+            }
         }
-        if (response.sampled !== undefined && response.sampled) {
-            result += `- **⚠️ Sampling Used:** Yes (results may be approximate)\n`;
-        }
-        if (response.records.length === recordLimit) {
-            result += `- **⚠️ Record Limit Reached:** The result set was limited to ${recordLimit} records. Consider changing your query with a smaller timeframe, an aggregation or a more concise filter. Alternatively, increase the recordLimit if you expect more results.\n`;
+        // Add all warnings to result
+        if (warnings.length > 0) {
+            result += '\n';
+            warnings.forEach((warning) => {
+                result += `- **⚠️ ${warning}**\n`;
+            });
         }
         result += `\n📋 **Query Results**: (${response.records?.length || 0} records):\n\n`;
         result += `\`\`\`json\n${JSON.stringify(response.records, null, 2)}\n\`\`\``;
-        return result;
+        // Return structured data in _meta for MCP App UI instead of embedding in text
+        return {
+            text: result,
+            _meta: {
+                records: response.records,
+                types: response.types,
+                analysisTimeframe: response.metadata?.grail?.analysisTimeframe,
+                scannedRecords: response.scannedRecords,
+                scannedBytes: response.scannedBytes,
+                sampled: response.sampled,
+                environmentUrl: dtEnvironment,
+                budgetState: response.budgetState,
+                warnings,
+                recordLimit,
+                recordLimitReached: response.records.length === recordLimit,
+            },
+        };
+    }));
+    // MCP App: Register the HTML resource for the execute_dql interactive UI (MCP App)
+    registerAppResource(server, 'DQL Results Viewer', executeDqlResourceUri, {}, async () => {
+        const html = (0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, 'ui', 'execute-dql', 'index.html'), 'utf-8');
+        return {
+            contents: [{ uri: executeDqlResourceUri, mimeType: RESOURCE_MIME_TYPE, text: html }],
+        };
     });
     tool('generate_dql_from_natural_language', '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