From 3dc6e9ee6e2c6749f6d8f2074c96f84f4e1423ea Mon Sep 17 00:00:00 2001 From: Roberto Montero Date: Mon, 2 Mar 2026 17:38:34 +0100 Subject: [PATCH 1/4] Add AI tools integration documentation and configuration This change introduces comprehensive AI-assisted development support: - Add AI Tools Integration Guide documenting available tools and setup - Configure MCP servers for Datadog CI Visibility integration - Add Claude CLI configuration files - Update AGENTS.md with developer tools guidance (MCP, GitHub CLI, GitLab CLI) - Update CONTRIBUTING.md with link to AI tools documentation Made-with: Cursor --- .claude/settings.json | 7 ++ .mcp.json | 8 ++ AGENTS.md | 23 +++++ CONTRIBUTING.md | 9 ++ docs/ai-tools-integration-guide.md | 146 +++++++++++++++++++++++++++++ 5 files changed, 193 insertions(+) create mode 100644 .claude/settings.json create mode 100644 .mcp.json create mode 100644 docs/ai-tools-integration-guide.md diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000000..994ca3b9c20 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,7 @@ +{ + "defaultMode": "acceptEdits", + "enabledMcpjsonServers": [ + "datadog" + ], + "enableAllProjectMcpServers": true +} diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 00000000000..fd053873f24 --- /dev/null +++ b/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "datadog": { + "type": "http", + "url": "https://mcp.datadoghq.com/api/unstable/mcp-server/mcp?toolsets=software-delivery" + } + } +} diff --git a/AGENTS.md b/AGENTS.md index ef91103f717..37c0c13f9b3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -78,3 +78,26 @@ Code running in the agent's `premain` phase must **not** use: - `javax.management.*` — causes class loading issues See [docs/bootstrap_design_guidelines.md](docs/bootstrap_design_guidelines.md) for details and alternatives. + +## Developer Tools + +### MCP Tools + +* Datadog MCP defaults: When using Datadog MCP tools (CI pipelines, tests, flaky tests, coverage, PR insights), default to the repository `github.com/DataDog/dd-trace-java` (or `https://github.com/DataDog/dd-trace-java` for PR-related tools) unless the user specifies a different repository. Use the current git branch and latest commit SHA as context when relevant. + +### GitHub Tools + +- When interacting with GitHub (github.com), ALWAYS use `gh` on the command line. +- If `gh` CLI is not installed or there are authentication or configuration problems, check the document: [AI Tools Integration Guide - GitHub CLI](docs/ai-tools-integration-guide.md#github-cli-gh) + +### GitLab Tools + +- When interacting with GitLab (gitlab.ddbuild.io), ALWAYS use `glab` on the command line. +- If `glab` CLI is not installed or there are authentication or configuration problems, check the document: [AI Tools Integration Guide - GitLab CLI](docs/ai-tools-integration-guide.md#gitlab-cli-glab) + +### Handling the Pull Request and CI + +- To create and monitor PR data, use the gh client (GitHub Tools). +- If the request relates to CI status for a branch or PR, MUST ALWAYS try the Datadog MCP first. +- Use local GitLab/GitHub tools as a fallback/support for the Datadog MCP when interacting with GitLab/GitHub CI. + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1399caf947a..10b44c9771e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -81,6 +81,15 @@ For IntelliJ IDEA, we suggest the following settings and plugin. * Switch to `IntelliJ IDEA CE 2021.2.3`. +## AI-assisted development + +This project includes documentation and configurations to help you use AI coding assistants effectively. + +Check [AI Tools Integration Guide](docs/ai-tools-integration-guide.md) for information about: +* Project-specific AI context and conventions +* How to use AI tools with dd-trace-java +* Best practices for AI-assisted contributions + ## Pull request guidelines ### Draft first diff --git a/docs/ai-tools-integration-guide.md b/docs/ai-tools-integration-guide.md new file mode 100644 index 00000000000..74b4315fe21 --- /dev/null +++ b/docs/ai-tools-integration-guide.md @@ -0,0 +1,146 @@ +# AI Tools Integration Guide + +> **Note**: This document is currently under development and will be populated with guidance on using AI coding assistants effectively with dd-trace-java. + +## The AI tools + +This section describes the AI tools and integrations available for dd-trace-java development. + +**Index:** +- [MCP Servers Integration (Beta)](#mcp-servers-integration-beta) + - [Datadog MCP Server Setup](#datadog-mcp-server-setup-for-dd-trace-java) +- [Claude CLI](#claude-cli) +- [GitHub CLI (gh)](#github-cli-gh) +- [GitLab CLI (glab)](#gitlab-cli-glab) + + +### MCP Servers Integration (Beta) + +Model Context Protocol (MCP) servers extend AI capabilities with specialized tools and integrations. The dd-trace-java repository provides several MCP server configurations to enhance your development workflow. MCP servers can be used with any compatible AI tool, including Cursor and Claude CLI. + +**Available MCP Servers:** + +- **Datadog MCP Server**: Provides CI Visibility integration including pipeline event search and aggregation, test event analysis, flaky test detection, code coverage summaries, and PR insights. Pre-configured in the repository via `.cursor/mcp.json` (for Cursor) and `.mcp.json` (for Claude CLI and other compatible tools). See [Datadog MCP Server Setup](datadog-mcp-server.md) for detailed setup and usage instructions. + +To set up MCP servers, follow the specific setup guides for each server. All MCP servers integrate seamlessly with compatible AI tools, providing enhanced context and capabilities for working with the dd-trace-java repository. + +#### Datadog MCP Server Setup for dd-trace-java + +The Datadog MCP server connects Cursor's AI assistant to Datadog's CI Visibility platform, letting you query pipeline events, test results, flaky tests, code coverage, and PR insights directly from the chat. + +##### Setup + +**1. Repository Configuration (Pre-configured)** + +The repository already includes the MCP server configuration in `.cursor/mcp.json`: + +```json +{ + "mcpServers": { + "datadog": { + "url": "https://mcp.datadoghq.com/api/unstable/mcp-server/mcp?toolsets=software-delivery", + "headers": {} + } + } +} +``` + +**2. Authentication via SSO** + +The Datadog MCP server uses SSO for authentication. No API or App keys are required. + +1. Open Cursor IDE in the dd-trace-java repository +2. Go to the MCP settings panel and trigger the **login** command on the `datadog` server + For the in terminal agent use `/mcp login`. +3. A browser tab opens automatically for Datadog SSO login +4. Complete the login in your browser — Cursor picks up the session automatically + +After logging in, the MCP tools are immediately available in the AI chat. + +##### Available Tools + +The repository configuration enables the **software-delivery** toolset. See the [official Datadog MCP toolsets documentation](https://docs.datadoghq.com/bits_ai/mcp_server/#toolsets:~:text=MCP%20Server.-,Toolsets,-The%20Datadog%20MCP) for the full list of available tools. + +##### Example Prompts + +``` +Show me the latest failed CI jobs on the main branch of DataDog/dd-trace-java +``` + +``` +Find the top 10 flaky tests in dd-trace-java sorted by failure rate +``` + +``` +What issues are blocking PR #1234 in DataDog/dd-trace-java? +``` + +``` +What's the P95 pipeline duration for dd-trace-java over the last 30 days? +``` + +### Claude CLI + +The dd-trace-java repository provides native support for **Claude CLI** (Anthropic's command-line interface for Claude) through a dedicated configuration in the `.claude/` directory. + +#### Configuration Files + +``` +.claude/ +├── CLAUDE.md # Claude-specific instructions and rules pointer +├── settings.json # Claude CLI settings (permissions, environment, MCP enablement) + +.mcp.json # MCP server configuration (shared across AI tools) +``` + +* **`.claude/CLAUDE.md`**: Contains Claude-specific instructions and points to the shared rules in `AGENTS.md` +* **`.claude/settings.json`**: Configures Claude CLI behavior, including default permission mode, environment variables, and MCP server enablement (e.g., the Datadog MCP server) +* **`.mcp.json`**: Defines MCP server connections at the repository root. Claude CLI automatically discovers this file and makes the configured servers available. Currently includes the Datadog MCP server for CI Visibility integration + +### GitHub CLI (gh) + +The AI tools are configured to use the **GitHub CLI** (`gh`) for all interactions with GitHub (github.com), including repository management, pull requests, issues, and CI/CD operations. The AI assistant will automatically use `gh` commands when performing GitHub-related tasks. + +#### Installation + +```bash +brew install gh +``` + +#### Authentication + +```bash +gh auth login +``` + +To verify your authentication status: + +```bash +gh auth status +``` + +### GitLab CLI (glab) + +The AI tools are configured to use the **GitLab CLI** (`glab`) for all interactions with GitLab (gitlab.ddbuild.io), including pipeline management, merge requests, and CI/CD operations. The AI assistant will automatically use `glab` commands when performing GitLab-related tasks. + +#### Installation + +```bash +brew install glab +``` + +#### Authentication + +You will need a **personal access token** to authenticate with GitLab. You can create one from your GitLab profile at **Settings > Access Tokens** on `gitlab.ddbuild.io`. + +Once you have your token, authenticate: + +```bash +glab auth login --hostname gitlab.ddbuild.io +``` + +To set the default host: + +```bash +glab config set host gitlab.ddbuild.io +``` \ No newline at end of file From cae7a1914795f7acb61fc964f67d93819b0aab91 Mon Sep 17 00:00:00 2001 From: Roberto Montero Date: Mon, 2 Mar 2026 17:48:40 +0100 Subject: [PATCH 2/4] fix docs --- docs/ai-tools-integration-guide.md | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/docs/ai-tools-integration-guide.md b/docs/ai-tools-integration-guide.md index 74b4315fe21..bddb69c51b9 100644 --- a/docs/ai-tools-integration-guide.md +++ b/docs/ai-tools-integration-guide.md @@ -20,19 +20,32 @@ Model Context Protocol (MCP) servers extend AI capabilities with specialized too **Available MCP Servers:** -- **Datadog MCP Server**: Provides CI Visibility integration including pipeline event search and aggregation, test event analysis, flaky test detection, code coverage summaries, and PR insights. Pre-configured in the repository via `.cursor/mcp.json` (for Cursor) and `.mcp.json` (for Claude CLI and other compatible tools). See [Datadog MCP Server Setup](datadog-mcp-server.md) for detailed setup and usage instructions. +- **Datadog MCP Server**: Provides CI Visibility integration including pipeline event search and aggregation, test event analysis, flaky test detection, code coverage summaries, and PR insights. Pre-configured in the repository via `.mcp.json` (for Claude CLI and other compatible tools). Cursor users need to set up `.cursor/mcp.json` manually (see setup instructions below). To set up MCP servers, follow the specific setup guides for each server. All MCP servers integrate seamlessly with compatible AI tools, providing enhanced context and capabilities for working with the dd-trace-java repository. #### Datadog MCP Server Setup for dd-trace-java -The Datadog MCP server connects Cursor's AI assistant to Datadog's CI Visibility platform, letting you query pipeline events, test results, flaky tests, code coverage, and PR insights directly from the chat. +The Datadog MCP server connects Cursor's/Claude AI assistant to Datadog's CI Visibility platform, letting you query pipeline events, test results, flaky tests, code coverage, and PR insights directly from the chat. ##### Setup -**1. Repository Configuration (Pre-configured)** +**1. Repository Configuration** -The repository already includes the MCP server configuration in `.cursor/mcp.json`: +The repository includes the MCP server configuration for Claude CLI and other compatible tools in `.mcp.json`: + +```json +{ + "mcpServers": { + "datadog": { + "type": "http", + "url": "https://mcp.datadoghq.com/api/unstable/mcp-server/mcp?toolsets=software-delivery" + } + } +} +``` + +For **Cursor** users, the `.cursor/` directory is not tracked in git. Create the file `.cursor/mcp.json` manually with the following content: ```json { @@ -49,11 +62,12 @@ The repository already includes the MCP server configuration in `.cursor/mcp.jso The Datadog MCP server uses SSO for authentication. No API or App keys are required. -1. Open Cursor IDE in the dd-trace-java repository -2. Go to the MCP settings panel and trigger the **login** command on the `datadog` server - For the in terminal agent use `/mcp login`. +1. Open your AI tool in the dd-trace-java repository +2. Trigger the **login** command on the `datadog` MCP server: + - **Cursor**: Go to the MCP settings panel and trigger the login command. For the in-terminal agent use `/mcp login`. + - **Claude CLI**: Run `/mcp` to see server status, then follow the login prompt. 3. A browser tab opens automatically for Datadog SSO login -4. Complete the login in your browser — Cursor picks up the session automatically +4. Complete the login in your browser — the tool picks up the session automatically After logging in, the MCP tools are immediately available in the AI chat. From 3a89f9139df194994d66044b36628ff5ccf11453 Mon Sep 17 00:00:00 2001 From: Roberto Montero Date: Mon, 2 Mar 2026 17:56:42 +0100 Subject: [PATCH 3/4] Fix format issues --- AGENTS.md | 1 - 1 file changed, 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 37c0c13f9b3..c419216bed5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -100,4 +100,3 @@ See [docs/bootstrap_design_guidelines.md](docs/bootstrap_design_guidelines.md) f - To create and monitor PR data, use the gh client (GitHub Tools). - If the request relates to CI status for a branch or PR, MUST ALWAYS try the Datadog MCP first. - Use local GitLab/GitHub tools as a fallback/support for the Datadog MCP when interacting with GitLab/GitHub CI. - From 5e26682fbcf2fcb42b662c7e69e98b505abb7953 Mon Sep 17 00:00:00 2001 From: Roberto Montero Date: Tue, 3 Mar 2026 08:13:54 +0100 Subject: [PATCH 4/4] address review coments --- .claude/settings.json | 1 - AGENTS.md | 1 - 2 files changed, 2 deletions(-) diff --git a/.claude/settings.json b/.claude/settings.json index 994ca3b9c20..7766b465b39 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,5 +1,4 @@ { - "defaultMode": "acceptEdits", "enabledMcpjsonServers": [ "datadog" ], diff --git a/AGENTS.md b/AGENTS.md index c419216bed5..bdfe4f63acb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -97,6 +97,5 @@ See [docs/bootstrap_design_guidelines.md](docs/bootstrap_design_guidelines.md) f ### Handling the Pull Request and CI -- To create and monitor PR data, use the gh client (GitHub Tools). - If the request relates to CI status for a branch or PR, MUST ALWAYS try the Datadog MCP first. - Use local GitLab/GitHub tools as a fallback/support for the Datadog MCP when interacting with GitLab/GitHub CI.