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

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`.
 
@@ -261,6 +277,43 @@ The [Amazon Q Developer CLI](https://docs.aws.amazon.com/amazonq/latest/qdevelop
 
 This configuration should be stored in `<your-repo>/.amazonq/mcp.json`.
 
+**Google Gemini CLI**
+
+The [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) is Google's official command-line AI assistant that supports MCP server integration. You can add the Dynatrace MCP server using either the built-in management commands or manual configuration.
+
+Using `gemini` CLI directly (recommended):
+
+```bash
+gemini extensions install https://github.com/dynatrace-oss/dynatrace-mcp
+export DT_PLATFORM_TOKEN=...
+export DT_ENVIRONMENT=https://...
+```
+
+and verify that the server is running via
+
+```bash
+gemini mcp list
+```
+
+Or manually in your `~/.gemini/settings.json` or `.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "dynatrace": {
+      "command": "npx",
+      "args": ["@dynatrace-oss/dynatrace-mcp-server@latest"],
+      "env": {
+        "DT_PLATFORM_TOKEN": "",
+        "DT_ENVIRONMENT": ""
+      },
+      "timeout": 30000,
+      "trust": false
+    }
+  }
+}
+```
+
 ### HTTP Server Mode (Alternative)
 
 For scenarios where you need to run the MCP server as an HTTP service instead of using stdio (e.g., for stateful sessions, load balancing, or integration with web clients), you can use the HTTP server mode:
@@ -328,11 +381,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 +437,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 +673,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

@@ -27,7 +27,20 @@ const davis_copilot_1 = require("./capabilities/davis-copilot");
 const getDynatraceEnv_1 = require("./getDynatraceEnv");
 const telemetry_openkit_1 = require("./utils/telemetry-openkit");
 const grail_budget_tracker_1 = require("./utils/grail-budget-tracker");
-(0, dotenv_1.config)();
+// Load environment variables from .env file if available, and suppress warnings/logging to stdio
+// as it breaks MCP communication when using stdio transport
+const dotEnvOutput = (0, dotenv_1.config)({ quiet: true });
+if (dotEnvOutput.error) {
+    // Only log error if it's not about missing .env file
+    if (dotEnvOutput.error.code !== 'ENOENT') {
+        console.error('Error loading .env file:', dotEnvOutput.error);
+        process.exit(1);
+    }
+}
+else {
+    // Successfully loaded .env file
+    console.error(`.env file loaded successfully - loaded ${dotEnvOutput.parsed ? Object.keys(dotEnvOutput.parsed).length : 0} environment variables: ${Object.keys(dotEnvOutput.parsed || {}).join(', ')}`);
+}
 let scopesBase = [
     'app-engine:apps:run', // needed for environmentInformationClient
     'app-engine:functions:run', // needed for environmentInformationClient
@@ -129,7 +142,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 +181,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 +210,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 +253,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 +289,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 +298,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 +337,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 +347,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 +374,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 +439,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 +468,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 +492,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 +545,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 +566,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 +582,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 +591,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 +602,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 +632,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.1",
   "mcpName": "io.github.dynatrace-oss/Dynatrace-mcp",
   "description": "Model Context Protocol (MCP) server for Dynatrace",
   "keywords": [