@dynatrace-oss/dynatrace-mcp-server 0.1.4 → 0.2.0

package/README.md

@@ -102,7 +102,7 @@ A **Dynatrace OAuth Client** is needed to communicate with your Dynatrace Enviro
 [creating an Oauth Client in Dynatrace](https://docs.dynatrace.com/docs/manage/identity-access-management/access-tokens-and-oauth-clients/oauth-clients),
 and set up the following environment variables in order for this MCP to work:
 
-* `DT_ENVIRONMENT` (string, e.g., https://abcd1234.apps.dynatrace.com) - URL to your Dynatrace Platform
+* `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
 * OAuth Client Scopes:
@@ -114,7 +114,6 @@ and set up the following environment variables in order for this MCP to work:
   * `environment-api:problems:read` - get problems
   * `environment-api:metrics:read` - read metrics
   * `environment-api:slo:read` - read SLOs
-  * `settings:objects:read` - needed for reading ownership information and Guardians (SRG) from settings
   * `storage:buckets:read` - Read all system data stored on Grail
   * `storage:logs:read` - Read logs for reliability guardian validations
   * `storage:metrics:read` - Read metrics for reliability guardian validations
@@ -125,6 +124,9 @@ and set up the following environment variables in order for this MCP to work:
   * `storage:system:read` - Read System Data from Grail
   * `storage:user.events:read` - Read User events from Grail
   * `storage:user.sessions:read` - Read User sessions from Grail
+  * `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`.
 
 In addition, depending on the features you use, the following variables can be configured:
 
@@ -172,9 +174,53 @@ Can you fetch recent events from our "production-cluster"
 to help identify what might be causing these deployment issues?
 ```
 
+## Troubleshooting
+
+### 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 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.
+
+It is recommended to try access 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):
+```bash
+curl --request POST 'https://sso.dynatrace.com/sso/oauth2/token' \
+  --header 'Content-Type: application/x-www-form-urlencoded' \
+  --data-urlencode 'grant_type=client_credentials' \
+  --data-urlencode 'client_id={your-client-id}' \
+  --data-urlencode 'client_secret={your-client-secret}' \
+  --data-urlencode 'scope=app-engine:apps:run app-engine:functions:run'
+```
+
+2. Use `access_token` from the response of the above call as the bearer-token in the next call:
+```bash
+curl -X GET https://abc12345.apps.dynatrace.com/platform/management/v1/environment \
+  -H 'accept: application/json' \
+  -H 'Authorization: Bearer {your-bearer-token}'
+```
+
+3. You should retrieve a result like this:
+```json
+{
+  "environmentId": "abc12345",
+  "createTime": "2023-01-01T00:10:57.123Z",
+  "blockTime": "2025-12-07T00:00:00Z",
+  "state": "ACTIVE"
+}
+```
+
+
+### Problem accessing data on Grail
+
+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.
+
+
 ## Development
 
-For development purposes, you can use VSCode and GitHub Copilot.
+For local development purposes, you can use VSCode and GitHub Copilot.
 
 First, enable Copilot for your Workspace `.vscode/settings.json`:
 ```json

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

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findMonitoredEntityByName = void 0;
+const execute_dql_1 = require("./execute-dql");
+const findMonitoredEntityByName = async (dtClient, entityName) => {
+    const dql = `fetch dt.entity.application | search "*${entityName}*" | fieldsAdd entity.type
+                | append [fetch dt.entity.service | search "*${entityName}*" | fieldsAdd entity.type]
+                | append [fetch dt.entity.host | search "*${entityName}*" | fieldsAdd entity.type]
+                | append [fetch dt.entity.process_group | search "*${entityName}*" | fieldsAdd entity.type]
+                | append [fetch dt.entity.cloud_application | search "*${entityName}*" | fieldsAdd entity.type]`;
+    const dqlResponse = await (0, execute_dql_1.executeDql)(dtClient, dql);
+    if (dqlResponse && dqlResponse.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) => {
+            if (entity) {
+                resp += `- Entity '${entity['entity.name']}' of type '${entity['entity.type']} has entity id '${entity.id}'\n`;
+            }
+        });
+        return resp;
+    }
+    else {
+        return 'No monitored entity found with the specified name.';
+    }
+};
+exports.findMonitoredEntityByName = findMonitoredEntityByName;

package/dist/getDynatraceEnv.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDynatraceEnv = getDynatraceEnv;
+/**
+ * Reads and validates required environment variables for Dynatrace MCP.
+ * Throws an Error if validation fails.
+ */
+function getDynatraceEnv(env = process.env) {
+    const oauthClient = env.OAUTH_CLIENT_ID;
+    const oauthClientSecret = env.OAUTH_CLIENT_SECRET;
+    const dtEnvironment = env.DT_ENVIRONMENT;
+    const slackConnectionId = env.SLACK_CONNECTION_ID || "fake-slack-connection-id";
+    if (!oauthClient || !oauthClientSecret || !dtEnvironment) {
+        throw new Error("Please set OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET and DT_ENVIRONMENT environment variables");
+    }
+    if (!dtEnvironment.startsWith("https://")) {
+        throw new Error("Please set DT_ENVIRONMENT to a valid Dynatrace Environment URL (e.g., https://<environment-id>.apps.dynatrace.com)");
+    }
+    if (!dtEnvironment.includes("apps.dynatrace.com") && !dtEnvironment.includes("apps.dynatracelabs.com")) {
+        throw new Error("Please set DT_ENVIRONMENT to a valid Dynatrace Platform Environment URL (e.g., https://<environment-id>.apps.dynatrace.com)");
+    }
+    return { oauthClient, oauthClientSecret, dtEnvironment, slackConnectionId };
+}

package/dist/getDynatraceEnv.test.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const getDynatraceEnv_1 = require("./getDynatraceEnv");
+describe("getDynatraceEnv", () => {
+    const baseEnv = {
+        OAUTH_CLIENT_ID: "dt0s02.SAMPLE",
+        OAUTH_CLIENT_SECRET: "dt0s02.SAMPLE.abcd1234",
+        DT_ENVIRONMENT: "https://abc123.apps.dynatrace.com",
+        SLACK_CONNECTION_ID: "slack-conn-id"
+    };
+    it("returns all required values when environment is valid", () => {
+        const env = { ...baseEnv };
+        const result = (0, getDynatraceEnv_1.getDynatraceEnv)(env);
+        expect(result).toEqual({
+            oauthClient: env.OAUTH_CLIENT_ID,
+            oauthClientSecret: env.OAUTH_CLIENT_SECRET,
+            dtEnvironment: env.DT_ENVIRONMENT,
+            slackConnectionId: env.SLACK_CONNECTION_ID
+        });
+    });
+    it("uses default slackConnectionId if not set", () => {
+        const env = { ...baseEnv, SLACK_CONNECTION_ID: undefined };
+        const result = (0, getDynatraceEnv_1.getDynatraceEnv)(env);
+        expect(result.slackConnectionId).toBe("fake-slack-connection-id");
+    });
+    it("throws if OAUTH_CLIENT_ID is missing", () => {
+        const env = { ...baseEnv, OAUTH_CLIENT_ID: undefined };
+        expect(() => (0, getDynatraceEnv_1.getDynatraceEnv)(env)).toThrow(/OAUTH_CLIENT_ID/);
+    });
+    it("throws if OAUTH_CLIENT_SECRET is missing", () => {
+        const env = { ...baseEnv, OAUTH_CLIENT_SECRET: undefined };
+        expect(() => (0, getDynatraceEnv_1.getDynatraceEnv)(env)).toThrow(/OAUTH_CLIENT_SECRET/);
+    });
+    it("throws if DT_ENVIRONMENT is missing", () => {
+        const env = { ...baseEnv, DT_ENVIRONMENT: undefined };
+        expect(() => (0, getDynatraceEnv_1.getDynatraceEnv)(env)).toThrow(/DT_ENVIRONMENT/);
+    });
+    it("throws if DT_ENVIRONMENT does not start with https://", () => {
+        const env = { ...baseEnv, DT_ENVIRONMENT: "http://abc123.apps.dynatrace.com" };
+        expect(() => (0, getDynatraceEnv_1.getDynatraceEnv)(env)).toThrow(/https:\/\//);
+    });
+    it("throws if DT_ENVIRONMENT is not a Dynatrace Platform URL (any URL)", () => {
+        const env = { ...baseEnv, DT_ENVIRONMENT: "https://abc123.example.com" };
+        expect(() => (0, getDynatraceEnv_1.getDynatraceEnv)(env)).toThrow(/Dynatrace Platform Environment URL/);
+    });
+    it("throws if DT_ENVIRONMENT is not a Dynatrace Platform URL (contains live)", () => {
+        const env = { ...baseEnv, DT_ENVIRONMENT: "https://abc123.live.dynatrace.com" };
+        expect(() => (0, getDynatraceEnv_1.getDynatraceEnv)(env)).toThrow(/Dynatrace Platform Environment URL/);
+    });
+    it("accepts DT_ENVIRONMENT with apps.dynatracelabs.com", () => {
+        const env = { ...baseEnv, DT_ENVIRONMENT: "https://xyz789.apps.dynatracelabs.com" };
+        expect(() => (0, getDynatraceEnv_1.getDynatraceEnv)(env)).not.toThrow();
+    });
+    it("accepts DT_ENVIRONMENT with apps.dynatrace.com", () => {
+        const env = { ...baseEnv, DT_ENVIRONMENT: "https://env123.apps.dynatrace.com" };
+        expect(() => (0, getDynatraceEnv_1.getDynatraceEnv)(env)).not.toThrow();
+    });
+});

package/dist/index.js

@@ -20,6 +20,8 @@ const update_workflow_1 = require("./capabilities/update-workflow");
 const get_vulnerability_details_1 = require("./capabilities/get-vulnerability-details");
 const execute_dql_1 = require("./capabilities/execute-dql");
 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 getDynatraceEnv_1 = require("./getDynatraceEnv");
 (0, dotenv_1.config)();
 let scopes = [
     'app-engine:apps:run', // needed for environmentInformationClient
@@ -55,15 +57,15 @@ if (process.env.USE_WORKFLOWS) {
 }
 const main = async () => {
     // read Environment variables
-    const oauthClient = process.env.OAUTH_CLIENT_ID;
-    const oauthClientSecret = process.env.OAUTH_CLIENT_SECRET;
-    const dtEnvironment = process.env.DT_ENVIRONMENT;
-    const slackConnectionId = process.env.SLACK_CONNECTION_ID || "fake-slack-connection-id";
-    // ensure oauthClient and dtEnvironment are set
-    if (!oauthClient || !oauthClientSecret || !dtEnvironment) {
-        console.error("Please set OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET and DT_ENVIRONMENT environment variables");
+    let dynatraceEnv;
+    try {
+        dynatraceEnv = (0, getDynatraceEnv_1.getDynatraceEnv)();
+    }
+    catch (err) {
+        console.error(err.message);
         process.exit(1);
     }
+    const { oauthClient, oauthClientSecret, dtEnvironment, slackConnectionId } = dynatraceEnv;
     // create an oauth-client
     const dtClient = await (0, dynatrace_clients_1.createOAuthClient)(oauthClient, oauthClientSecret, dtEnvironment, scopes);
     console.error("Starting Dynatrace MCP Server...");
@@ -208,6 +210,12 @@ const main = async () => {
         resp += `Tell the user to access the link ${dtEnvironment}/ui/apps/dynatrace.davis.problems/problem/${result.problemId} to get more insights into the problem.\n`;
         return resp;
     });
+    tool("find_entity_by_name", "Get the entityId of a monitored entity based on the name of the entity on Dynatrace", {
+        entityName: zod_1.z.string()
+    }, async ({ entityName }) => {
+        const entityResponse = await (0, find_monitored_entity_by_name_1.findMonitoredEntityByName)(dtClient, entityName);
+        return entityResponse;
+    });
     tool("get_entity_details", "Get details of a monitored entity based on the entityId on Dynatrace", {
         entityId: zod_1.z.string().optional()
     }, async ({ entityId }) => {
@@ -241,13 +249,26 @@ const main = async () => {
         const logs = await (0, get_logs_for_entity_1.getLogsForEntity)(dtClient, entityName);
         return `Logs:\n${JSON.stringify(logs?.map(logLine => logLine ? logLine.content : 'Empty log'))}`;
     });
-    tool("verify_dql", "Verify a DQL statement on Dynatrace", {
+    tool("verify_dql", "Verify a Dynatrace Query Language (DQL) statement on Dynatrace GRAIL before executing it. This is useful to ensure that the DQL statement is valid and can be executed without errors.", {
         dqlStatement: zod_1.z.string()
     }, async ({ dqlStatement }) => {
         const response = await (0, execute_dql_1.verifyDqlStatement)(dtClient, dqlStatement);
-        return `Parsing DQL Statement resulted in: ${JSON.stringify(response)}`;
+        let resp = 'DQL Statement Verification:\n';
+        if (response.notifications && response.notifications.length > 0) {
+            resp += `Please consider the following notifications for adapting the your DQL statement:\n`;
+            response.notifications.forEach((notification) => {
+                resp += `* ${notification.severity}: ${notification.message}\n`;
+            });
+        }
+        if (response.valid) {
+            resp += `The DQL statement is valid - you can use the "execute_dql" tool.\n`;
+        }
+        else {
+            resp += `The DQL statement is invalid. Please adapt your statement.\n`;
+        }
+        return resp;
     });
-    tool("execute_dql", "Get Logs, Metrics, Spans, Events from Dynatrace by executing a DQL statement. Please use verify_dql tool before you execute a DQL statement.", {
+    tool("execute_dql", 'Get Logs, Metrics, Spans or Events from Dynatrace GRAIL by executing a Dynatrace Query Language (DQL) statement. Always use "verify_dql" tool before you execute a DQL statement. A valid statement looks like this: "fetch [logs, metrics, spans, events] | filter <some-filter> | summarize count(), by:{some-fields}. Adapt filters for certain attributes: `traceId` could be `trace_id` or `trace.id`.', {
         dqlStatement: zod_1.z.string()
     }, async ({ dqlStatement }) => {
         const response = await (0, execute_dql_1.executeDql)(dtClient, dqlStatement);

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/dynatrace-clients.ts","../src/index.ts","../src/capabilities/create-workflow-for-problem-notification.ts","../src/capabilities/execute-dql.ts","../src/capabilities/get-events-for-cluster.ts","../src/capabilities/get-logs-for-entity.ts","../src/capabilities/get-monitored-entity-details.ts","../src/capabilities/get-ownership-information.ts","../src/capabilities/get-problem-details.ts","../src/capabilities/get-vulnerability-details.ts","../src/capabilities/list-problems.ts","../src/capabilities/list-vulnerabilities.ts","../src/capabilities/send-slack-message.ts","../src/capabilities/update-workflow.ts"],"version":"5.8.2"}
+{"root":["../src/dynatrace-clients.ts","../src/getDynatraceEnv.test.ts","../src/getDynatraceEnv.ts","../src/index.ts","../src/capabilities/create-workflow-for-problem-notification.ts","../src/capabilities/execute-dql.ts","../src/capabilities/find-monitored-entity-by-name.ts","../src/capabilities/get-events-for-cluster.ts","../src/capabilities/get-logs-for-entity.ts","../src/capabilities/get-monitored-entity-details.ts","../src/capabilities/get-ownership-information.ts","../src/capabilities/get-problem-details.ts","../src/capabilities/get-vulnerability-details.ts","../src/capabilities/list-problems.ts","../src/capabilities/list-vulnerabilities.ts","../src/capabilities/send-slack-message.ts","../src/capabilities/update-workflow.ts"],"version":"5.8.2"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dynatrace-oss/dynatrace-mcp-server",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Model Context Protocol (MCP) server for Dynatrace",
   "keywords": [
     "Dynatrace",
@@ -36,7 +36,8 @@
   "scripts": {
     "build": "tsc --build",
     "prepare": "npm run build",
-    "watch": "tsc --watch"
+    "watch": "tsc --watch",
+    "test": "jest"
   },
   "author": "Dynatrace",
   "license": "MIT",
@@ -52,7 +53,10 @@
     "zod-to-json-schema": "^3.24.5"
   },
   "devDependencies": {
+    "@types/jest": "^30.0.0",
     "@types/node": "^22",
+    "jest": "^30.0.0",
+    "ts-jest": "^29.4.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.6.2"
   }