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

package/README.md

@@ -18,12 +18,28 @@
   </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.
+The local _Dynatrace MCP server_ allows AI Assistants to interact with the [Dynatrace](https://www.dynatrace.com/) observability platform,
+bringing 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.
+If you need help, please contact us via [GitHub Issues](https://github.com/dynatrace-oss/dynatrace-mcp/issues) if you have feature requests, questions, or need help.
+
+## Quickstart
+
+You can add this MCP server to your MCP Client like VSCode, Claude, Cursor, Amazon Q, Windsurf, ChatGPT, or Github Copilot via the npmjs package `@dynatrace-oss/dynatrace-mcp-server`, and type `stdio`.
+You can find more details about the configuration for different AI Assistants, Agents and MCP Clients in the [Configuration section below](#configuration).
+
+Furthermore, you need your Dynatrace environment URL, e.g., `https://abc12345.apps.dynatrace.com`, as well as a [Platform Token](https://docs.dynatrace.com/docs/manage/identity-access-management/access-tokens-and-oauth-clients/platform-tokens), e.g., `dt0s16.SAMPLE.abcd1234`, with [required scopes](#scopes-for-authentication).
+
+Depending on your MCP Client, you need to configure these as environment variables or as settings in the UI:
+
+- `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`)
+- `DT_PLATFORM_TOKEN` (string, e.g., `dt0s16.SAMPLE.abcd1234`) - **Recommended**: Dynatrace Platform Token
+
+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.
+
+## Architecture
 
 ![Architecture](https://github.com/dynatrace-oss/dynatrace-mcp/blob/main/assets/dynatrace-mcp-arch.png?raw=true)
 
@@ -184,7 +200,7 @@ rules/
 
 For detailed information about the workshop rules, see the [Rules README](./dynatrace-agent-rules/rules/README.md).
 
-## Quickstart
+## Configuration
 
 You can add this MCP server (using STDIO) to your MCP Client like VS Code, Claude, Cursor, Amazon Q Developer CLI, Windsurf Github Copilot via the package `@dynatrace-oss/dynatrace-mcp-server`.
 
@@ -328,11 +344,11 @@ For fetching just error-logs, add `| filter loglevel == "ERROR"`.
 
 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`)
+- `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`)
 - `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.
+- `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.
 
@@ -384,6 +400,18 @@ and extend them as needed. They're here to help you imagine how real-time observ
 
 ### **Basic Queries & AI Assistance**
 
+**Find a monitored entity**
+
+```
+Get all details of the entity 'my-service'
+```
+
+**Find error logs**
+
+```
+Show me error logs
+```
+
 **Write a DQL query from natural language:**
 
 ```
@@ -608,51 +636,3 @@ 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.
-
-First, enable Copilot for your Workspace `.vscode/settings.json`:
-
-```json
-{
-  "github.copilot.enable": {
-    "*": true
-  }
-}
-```
-
-and make sure that you are using Agent Mode in Copilot.
-
-Second, add the MCP to `.vscode/mcp.json`:
-
-```json
-{
-  "servers": {
-    "my-dynatrace-mcp-server": {
-      "command": "node",
-      "args": ["--watch", "${workspaceFolder}/dist/index.js"],
-      "envFile": "${workspaceFolder}/.env"
-    }
-  }
-}
-```
-
-Third, create a `.env` file in this repository (you can copy from `.env.template`) and configure environment variables as [described above](#environment-variables).
-
-Finally, make changes to your code and compile it with `npm run build` or just run `npm run watch` and it auto-compiles.
-
-## Releasing
-
-When you are preparing for a release, you can use GitHub Copilot to guide you through the preparations.
-
-In Visual Studio Code, you can use `/release` in the chat with Copilot in Agent Mode, which will execute [release.prompt.md](.github/prompts/release.prompt.md).
-
-You may include additional information such as the version number. If not specified, you will be asked.
-
-This will
-
-- prepare the [changelog](CHANGELOG.md),
-- update the version number in [package.json](package.json),
-- commit the changes.

package/dist/index.js

@@ -129,7 +129,7 @@ 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 tool = (name, description, paramsSchema, annotations, cb) => {
         const wrappedCb = async (args) => {
             // track starttime for telemetry
             const startTime = Date.now();
@@ -168,10 +168,12 @@ const main = async () => {
                     .catch((e) => console.warn('Failed to track tool usage:', e));
             }
         };
-        server.tool(name, description, paramsSchema, (args) => wrappedCb(args));
+        server.tool(name, description, paramsSchema, annotations, (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 ({}) => {
+    tool('get_environment_info', 'Get information about the connected Dynatrace Environment (Tenant) and verify the connection and authentication.', {}, {
+        readOnlyHint: true,
+    }, async ({}) => {
         // create an oauth-client
         const dtClient = await (0, dynatrace_clients_1.createDtHttpClient)(dtEnvironment, scopesBase, oauthClientId, oauthClientSecret, dtPlatformToken);
         const environmentInformationClient = new client_platform_management_service_1.EnvironmentInformationClient(dtClient);
@@ -195,6 +197,8 @@ const main = async () => {
             .number()
             .default(25)
             .describe('Maximum number of vulnerabilities to display in the response.'),
+    }, {
+        readOnlyHint: true,
     }, async ({ riskScore, additionalFilter, maxVulnerabilitiesToDisplay }) => {
         const dtClient = await (0, dynatrace_clients_1.createDtHttpClient)(dtEnvironment, scopesBase.concat('storage:events:read', 'storage:buckets:read', 'storage:security.events:read'), oauthClientId, oauthClientSecret, dtPlatformToken);
         const result = await (0, list_vulnerabilities_1.listVulnerabilities)(dtClient, additionalFilter, riskScore);
@@ -236,6 +240,8 @@ const main = async () => {
             .optional()
             .describe('Additional filter for DQL statement for dt.davis.problems, e.g., \'entity_tags == array("dt.owner:team-foobar", "tag:tag")\''),
         maxProblemsToDisplay: zod_1.z.number().default(10).describe('Maximum number of problems to display in the response.'),
+    }, {
+        readOnlyHint: true,
     }, async ({ additionalFilter, maxProblemsToDisplay }) => {
         const dtClient = await (0, dynatrace_clients_1.createDtHttpClient)(dtEnvironment, scopesBase.concat('storage:events:read', 'storage:buckets:read'), oauthClientId, oauthClientSecret, dtPlatformToken);
         // get problems (uses fetch)
@@ -270,6 +276,8 @@ const main = async () => {
     });
     tool('find_entity_by_name', 'Get the entityId of a monitored entity (service, host, process-group, application, kubernetes-node, ...) within the topology based on the name of the entity on Dynatrace', {
         entityName: zod_1.z.string().describe('Name of the entity to search for, e.g., "my-service" or "my-host"'),
+    }, {
+        readOnlyHint: true,
     }, async ({ entityName }) => {
         const dtClient = await (0, dynatrace_clients_1.createDtHttpClient)(dtEnvironment, scopesBase.concat('storage:entities:read'), oauthClientId, oauthClientSecret, dtPlatformToken);
         const entityResponse = await (0, find_monitored_entity_by_name_1.findMonitoredEntityByName)(dtClient, entityName);
@@ -277,6 +285,8 @@ const main = async () => {
     });
     tool('get_entity_details', 'Get details of a monitored entity based on the entityId on Dynatrace', {
         entityId: zod_1.z.string().optional(),
+    }, {
+        readOnlyHint: true,
     }, async ({ entityId }) => {
         const dtClient = await (0, dynatrace_clients_1.createDtHttpClient)(dtEnvironment, scopesBase.concat('storage:entities:read'), oauthClientId, oauthClientSecret, dtPlatformToken);
         const entityDetails = await (0, get_monitored_entity_details_1.getMonitoredEntityDetails)(dtClient, entityId);
@@ -314,6 +324,9 @@ const main = async () => {
     tool('send_slack_message', 'Sends a Slack message to a dedicated Slack Channel via Slack Connector on Dynatrace', {
         channel: zod_1.z.string().optional(),
         message: zod_1.z.string().optional(),
+    }, {
+        // not read-only, not open-world, not destructive
+        readOnlyHint: false,
     }, async ({ channel, message }) => {
         const dtClient = await (0, dynatrace_clients_1.createDtHttpClient)(dtEnvironment, scopesBase.concat('app-settings:objects:read'), oauthClientId, oauthClientSecret, dtPlatformToken);
         const response = await (0, send_slack_message_1.sendSlackMessage)(dtClient, slackConnectionId, channel, message);
@@ -321,6 +334,9 @@ const main = async () => {
     });
     tool('verify_dql', 'Verify a Dynatrace Query Language (DQL) statement on Dynatrace GRAIL before executing it. This step is recommended for DQL statements that have been dynamically created by non-expert tools. For statements coming from the `generate_dql_from_natural_language` tool as well as from documentation, this step can be omitted.', {
         dqlStatement: zod_1.z.string(),
+    }, {
+        readOnlyHint: true,
+        idempotentHint: true, // same input always yields same output
     }, async ({ dqlStatement }) => {
         const dtClient = await (0, dynatrace_clients_1.createDtHttpClient)(dtEnvironment, scopesBase, oauthClientId, oauthClientSecret, dtPlatformToken);
         const response = await (0, execute_dql_1.verifyDqlStatement)(dtClient, dqlStatement);
@@ -345,6 +361,12 @@ const main = async () => {
         dqlStatement: zod_1.z
             .string()
             .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) }")'),
+    }, {
+        // 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 }) => {
         // 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
@@ -404,6 +426,9 @@ const main = async () => {
         text: zod_1.z
             .string()
             .describe('Natural language description of what you want to query. Be specific and include time ranges, entities, and metrics of interest.'),
+    }, {
+        readOnlyHint: true,
+        idempotentHint: true,
     }, async ({ text }) => {
         const dtClient = await (0, dynatrace_clients_1.createDtHttpClient)(dtEnvironment, scopesBase.concat('davis-copilot:nl2dql:execute'), oauthClientId, oauthClientSecret, dtPlatformToken);
         const response = await (0, davis_copilot_1.generateDqlFromNaturalLanguage)(dtClient, text);
@@ -430,6 +455,9 @@ const main = async () => {
     });
     tool('explain_dql_in_natural_language', 'Explain Dynatrace Query Language (DQL) statements in natural language using Davis CoPilot AI.', {
         dql: zod_1.z.string().describe('The DQL statement to explain'),
+    }, {
+        readOnlyHint: true,
+        idempotentHint: true,
     }, async ({ dql }) => {
         const dtClient = await (0, dynatrace_clients_1.createDtHttpClient)(dtEnvironment, scopesBase.concat('davis-copilot:dql2nl:execute'), oauthClientId, oauthClientSecret, dtPlatformToken);
         const response = await (0, davis_copilot_1.explainDqlInNaturalLanguage)(dtClient, dql);
@@ -451,6 +479,10 @@ const main = async () => {
         text: zod_1.z.string().describe('Your question or request for Davis CoPilot'),
         context: zod_1.z.string().optional().describe('Optional context to provide additional information'),
         instruction: zod_1.z.string().optional().describe('Optional instruction for how to format the response'),
+    }, {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true, // web-search like characteristics
     }, async ({ text, context, instruction }) => {
         const dtClient = await (0, dynatrace_clients_1.createDtHttpClient)(dtEnvironment, scopesBase.concat('davis-copilot:conversations:execute'), oauthClientId, oauthClientSecret, dtPlatformToken);
         const conversationContext = [];
@@ -500,6 +532,10 @@ const main = async () => {
         teamName: zod_1.z.string().optional(),
         channel: zod_1.z.string().optional(),
         isPrivate: zod_1.z.boolean().optional().default(false),
+    }, {
+        // not read only, not idempotent
+        readOnlyHint: false,
+        idempotentHint: false, // creating the same workflow multiple times is possible
     }, async ({ problemType, teamName, channel, isPrivate }) => {
         const dtClient = await (0, dynatrace_clients_1.createDtHttpClient)(dtEnvironment, scopesBase.concat('automation:workflows:write', 'automation:workflows:read', 'automation:workflows:run'), oauthClientId, oauthClientSecret, dtPlatformToken);
         const response = await (0, create_workflow_for_problem_notification_1.createWorkflowForProblemNotification)(dtClient, teamName, channel, problemType, isPrivate);
@@ -517,6 +553,10 @@ const main = async () => {
     });
     tool('make_workflow_public', 'Modify a workflow and make it publicly available to everyone on the Dynatrace Environment', {
         workflowId: zod_1.z.string().optional(),
+    }, {
+        // not read only, but idempotent
+        readOnlyHint: false,
+        idempotentHint: true, // making the same workflow public multiple times yields the same result
     }, async ({ workflowId }) => {
         const dtClient = await (0, dynatrace_clients_1.createDtHttpClient)(dtEnvironment, scopesBase.concat('automation:workflows:write', 'automation:workflows:read', 'automation:workflows:run'), oauthClientId, oauthClientSecret, dtPlatformToken);
         const response = await (0, update_workflow_1.updateWorkflow)(dtClient, workflowId, {
@@ -529,6 +569,8 @@ const main = async () => {
             .string()
             .optional()
             .describe(`The Kubernetes (K8s) Cluster Id, referred to as k8s.cluster.uid (this is NOT the Dynatrace environment)`),
+    }, {
+        readOnlyHint: true,
     }, async ({ clusterId }) => {
         const dtClient = await (0, dynatrace_clients_1.createDtHttpClient)(dtEnvironment, scopesBase.concat('storage:events:read'), oauthClientId, oauthClientSecret, dtPlatformToken);
         const events = await (0, get_events_for_cluster_1.getEventsForCluster)(dtClient, clusterId);
@@ -536,6 +578,8 @@ const main = async () => {
     });
     tool('get_ownership', 'Get detailed Ownership information for one or multiple entities on Dynatrace', {
         entityIds: zod_1.z.string().optional().describe('Comma separated list of entityIds'),
+    }, {
+        readOnlyHint: true,
     }, async ({ entityIds }) => {
         const dtClient = await (0, dynatrace_clients_1.createDtHttpClient)(dtEnvironment, scopesBase.concat('environment-api:entities:read', 'settings:objects:read'), oauthClientId, oauthClientSecret, dtPlatformToken);
         console.error(`Fetching ownership for ${entityIds}`);
@@ -545,7 +589,10 @@ const main = async () => {
         resp += JSON.stringify(ownershipInformation);
         return resp;
     });
-    tool('reset_grail_budget', 'Reset the Grail query budget after it was exhausted, allowing new queries to be executed. This clears all tracked bytes scanned in the current session.', {}, async ({}) => {
+    tool('reset_grail_budget', 'Reset the Grail query budget after it was exhausted, allowing new queries to be executed. This clears all tracked bytes scanned in the current session.', {}, {
+        readonlyHint: false, // modifies state
+        idempotentHint: true, // multiple resets yield the same result
+    }, async ({}) => {
         // Reset the global tracker
         (0, grail_budget_tracker_1.resetGrailBudgetTracker)();
         // Get a fresh tracker to show the reset state
@@ -572,6 +619,8 @@ You can now execute new Grail queries (DQL, etc.) again. If this happens more of
         bccRecipients: zod_1.z.array(zod_1.z.string().email()).optional().describe('Array of email addresses for BCC recipients'),
         subject: zod_1.z.string().describe('Subject line of the email'),
         body: zod_1.z.string().describe('Body content of the email (plain text only)'),
+    }, {
+        openWorldHint: true, // email is as close to the open-world as we can get with our system
     }, async ({ toRecipients, ccRecipients, bccRecipients, subject, body }) => {
         // Validate total recipients limit (10 max across TO, CC, and BCC)
         const totalRecipients = toRecipients.length + (ccRecipients?.length || 0) + (bccRecipients?.length || 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dynatrace-oss/dynatrace-mcp-server",
-  "version": "0.6.0-rc.2",
+  "version": "0.6.0",
   "mcpName": "io.github.dynatrace-oss/Dynatrace-mcp",
   "description": "Model Context Protocol (MCP) server for Dynatrace",
   "keywords": [