TalkO11yToMe: Learning MCP Servers with Dynatrace Integration

TalkO11yToMe：通过 Dynatrace 集成学习 MCP 服务

欢迎开启 MCP（Model Context Protocol）学习之旅！本项目将帮助你了解 MCP 服务及其使用场景，特别是如何与 Dynatrace 租户集成，以构建强大的、由可观测性驱动的 AI 工作流。

🎉 项目状态：全面投入运行

全部 6 个 Dynatrace 工具现已达到生产就绪状态：

• ✅ 标准化配置：基于 dotenv 的共享配置消除了 200 多行重复代码
• ✅ DQL 查询轮询：妥善处理异步查询执行（202 → 轮询 → 结果）
• ✅ OAuth 身份验证：所有工具均可正常使用，承载令牌有效期为 5 分钟
• ✅ 真实数据检索：成功发现生产环境中的问题、日志和指标
• ✅ 整洁的架构：将 lib/ 与 tools/ 分离，便于维护

📊 代码质量改进：

• 之前：每个工具有 40 多行环境变量解析代码 × 6 个工具 = 240 多行
• 之后：每个工具使用 6 行共享配置 × 6 个工具 = 36 行
• 已消除：204 多行重复代码，并增强了验证功能

---

🚨 重要：Grail 与 Classic 环境支持

Dynatrace 环境类型决定了你需要使用哪些工具和配置：

🆕 Grail 环境（推荐 — 现代化平台）

• URL 模式：https://xxx.apps.dynatrace.com
• 身份验证：必须使用 OAuth 承载令牌
• API 端点：/platform/classic/environment-api/v2/
• 主要工具：grail-log-query.js ✅ 已可用于生产环境
• MCP 服务：✅ 已准备好构建 — 查看完整设计

🏛️ Classic 环境（旧版平台）

• URL 模式：https://xxx.live.dynatrace.com
• 身份验证：API 令牌或 OAuth
• API 端点：/api/v2/
• 主要工具：classic-log-query.js ✅ 已可用于生产环境
• MCP 服务：✅ 已准备好构建 — 查看完整设计

📖 请参阅下方的环境检测指南，了解设置详情。

---

📁 项目结构

TalkO11yToMe/
├── lib/                    # 🔧 Shared Infrastructure
│   ├── config.js          #    → Standardized dotenv configuration
│   └── demo-dotenv.js     #    → Configuration demonstration
├── tools/                  # 🚀 Production Tools (6 tools)
│   ├── grail-log-query.js        #    → Primary tool for Grail environments
│   ├── grail-business-analytics.js #  → DQL and business events (Grail)
│   ├── classic-log-query.js      #    → Primary tool for Classic environments
│   ├── classic-api-client.js     #    → Comprehensive API client (both)
│   ├── dynatrace-oauth-tool.js   #    → Authentication testing
│   └── dynatrace-monitor.js      #    → Visual monitoring dashboard
├── tests/                  # 🧪 Comprehensive Test Suite
│   ├── test-suite.js      #    → Main test runner with 8 validation tests
│   ├── test-config.js     #    → Test configuration and scenarios
│   ├── test-history.js    #    → Test history tracking and analysis
│   ├── results/           #    → Organized timestamped test results
│   └── README.md          #    → Complete testing documentation
├── docs/                   # 📚 Documentation
│   ├── FIXES_SUMMARY.md          #    → Complete technical solution summary
│   ├── TOOLS_GUIDE.md            #    → Detailed tool usage and examples
│   ├── DYNATRACE_LOGS_SOLUTION.md #  → Environment setup guide
│   └── [additional guides...]
└── env/                    # 🔐 Environment Configuration
    └── .env.dev                  #    → Your Dynatrace credentials

---

📚 文档

快速参考

• 🚀 工具指南 — 完整的工具文档和使用示例
• 🔧 技术解决方案 — 详细的环境设置与故障排除
• 📊 实现总结 — 完整的项目改造详情
• 🎯 AI 集成演示 — AI 分析示例的分步说明
• ⚡ Cursor IDE 集成 — 实用工作流和 AI 驱动的开发模式
• 🤖 MCP 服务设计 — 基于官方 TypeScript SDK 的完整架构和实现计划

主要章节

1. 什么是 MCP？
2. 了解 MCP 架构
3. Dynatrace MCP 服务
4. 设置说明
5. 环境检测
6. 快速入门演示
7. 真实场景用例
8. 资源
9. 项目路线图

🤖 什么是 MCP？

Model Context Protocol（MCP）是一种开放标准，可让 AI 系统（如 Claude、Cursor、VS Code Copilot）安全地连接到你的业务现有工具和数据。可以把它看作 AI 的“通用适配器”。

主要优势：

• 标准化集成：无需再为每种 AI 工具定制集成
• 安全的数据访问：对系统的访问受到控制
• 实时上下文：AI 可从生产系统获取最新信息
• 可扩展性：轻松添加新功能和数据源

🏗️ 了解 MCP 架构

MCP 由三个主要组件组成：

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│    Host     │◄───┤   Client    │◄───┤   Server    │
│ (AI Agent)  │    │(Translator) │    │ (Data/Tool) │
└─────────────┘    └─────────────┘    └─────────────┘

• 宿主：你的 AI 应用（Claude Desktop、VS Code 等）
• 客户端：负责通信并转换请求
• 服务端：提供特定功能（Dynatrace 数据、文件访问、API 等）

MCP 功能：

1. 工具：AI 可以调用的函数（查询指标、创建告警等）
2. 资源：AI 可以读取的数据源（日志、仪表板、配置）
3. 提示词：常见 AI 交互的模板

🔍 Dynatrace MCP 服务

官方 Dynatrace MCP 服务可让 AI 助手与 Dynatrace 环境交互，获取实时可观测性洞察。

功能：

• 问题管理：列出并分析生产问题
• 安全问题：访问漏洞和安全问题详情
• DQL 查询：使用 Dynatrace Query Language 查询日志和事件
• Slack 集成：通过 Slack 连接器发送告警
• 工作流自动化：设置通知工作流
• 实体所有权：获取服务的所有权信息

使用场景：

• 实时调试：编码时获取生产环境上下文
• 事件响应：借助实时数据进行 AI 辅助故障排查
• 安全分析：关联代码漏洞与生产问题
• 性能优化：使用自然语言查询指标和日志

🚀 设置说明

前提条件

• Node.js 18+（我们使用 v20.19.2 LTS）
• Dynatrace 租户访问权限
• Dynatrace API 令牌或 OAuth 客户端凭据
• AI 客户端（推荐使用 Cursor IDE）

环境配置

1. 复制环境模板：

cp env/env.template env/.env.dev

2. 使用你的凭据编辑 env/.env.dev：

# Dynatrace Environment
DT_ENVIRONMENT=https://your-environment-id.live.dynatrace.com

# API Token (simpler setup)
API_TOKEN=dt0c01.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY

# OAuth (optional - for official MCP server)
OAUTH_CLIENT_ID=dt0s02.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
OAUTH_CLIENT_SECRET=dt0s02.XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.YYYYYYYYYYYYYYYYYYYYYYYYYYYY
OAUTH_RESOURCE_URN=urn:dynatrace:environment:your-environment-id

3. 测试配置：

# Test shared configuration
node lib/demo-dotenv.js

# Verify tools work
node tools/dynatrace-monitor.js

# Run comprehensive test suite
node tests/test-suite.js

🔍 环境检测

检查 Dynatrace URL，确定环境类型：

Grail 环境检测

https://xxx.apps.dynatrace.com  ← Contains ".apps."

→ 使用： grail-log-query.js（需要 OAuth）

Classic 环境检测

https://xxx.live.dynatrace.com  ← Contains ".live."

→ 使用： classic-log-query.js（支持 API 令牌）

🎯 快速入门演示

适用于 Grail 环境：

# Run primary tool for modern Dynatrace platforms
node tools/grail-log-query.js "error" now-2h

# Business analytics with DQL polling
node tools/grail-business-analytics.js query "fetch logs | limit 5"

# Visual monitoring dashboard
node tools/dynatrace-monitor.js

适用于 Classic 环境：

# Run primary tool for legacy Dynatrace platforms
node tools/classic-log-query.js search "error" now-2h

# Comprehensive API client with auto-detection
node tools/classic-api-client.js problems 10

# Visual monitoring dashboard
node tools/dynatrace-monitor.js

🎯 最近的测试结果：

• 检索到 5 条日志记录，包含丰富的元数据（16ms 内扫描了 418,085 条记录）
• 检测到 17 个 Lambda 问题，包括高错误率和超时
• OAuth 令牌正常工作，持有令牌生命周期为 5 分钟
• DQL 轮询正常——202 → 轮询 → 结果的工作流运行正常

📖 有关工具的详细用法，请参阅 工具指南。

🎯 实际使用场景

1. AI 驱动的事件响应

使用 AI 集成演示来：

• 自动分析 Lambda 函数错误
• 生成事件响应优先级
• 创建安全评估
• 设计监控仪表板

2. 生产环境调试上下文

# Get context for coding session
node tools/dynatrace-monitor.js

# Search for specific errors with polling
node tools/grail-log-query.js "timeout" now-1h

3. 每日运行状况监控

# Morning standup dashboard
node tools/dynatrace-monitor.js

# Lambda function health check
node tools/classic-api-client.js lambda-problems now-24h

📊 架构改进

共享配置（lib/config.js）

之前：每个工具都有 40 多行重复的环境解析代码 之后：采用 dotenv 标准化的单一共享配置

// All tools now use this simple pattern:
const config = require('../lib/config');
const dt = await config.getDynatraceConfig();
// 6 lines replace 40+ lines of custom parsing

实现的收益：

• ✅ 减少 204 行以上代码——大幅精简代码
• ✅ 错误处理标准化——所有工具保持一致
• ✅ 环境验证——自动检测 Grail 或 Classic 环境
• ✅ 增强安全性——在日志中妥善屏蔽凭据
• ✅ 提升可维护性——配置的唯一事实来源

📚 资源

官方 MCP 资源：

• MCP 规范
• Anthropic MCP 文档
• MCP Python SDK
• MCP TypeScript SDK

Dynatrace MCP 集成：

• Dynatrace 官方 MCP 服务（仅限 Classic 环境）
• Dynatrace API 文档
• Dynatrace DQL 文档

项目文档：

• 完整工具指南 - 所有工具的示例和最佳实践
• 技术实现 - 环境设置、故障排除和架构详情
• AI 集成示例 - 分步式 AI 分析工作流
• Cursor IDE 集成 - 开发工作流和实用 AI 模式

---

🎉 准备开始了吗？ 查看工具指南，了解全面的用法示例和最佳实践！

🧪 测试套件

我们提供了全面的测试套件，用于验证所有工具和基础设施：

快速运行测试

# Run all tests (takes ~8 seconds)
node tests/test-suite.js

测试内容

• ✅ 文件结构：所有 9 个预期文件均已就位
• ✅ 共享配置：Dotenv 集成正常工作
• ✅ 身份验证：OAuth 令牌生成（生命周期为 5 分钟）
• ✅ 全部 6 个工具：Grail、Classic 和 Universal 工具
• ✅ 真实数据访问：生产环境的问题和日志
• ✅ DQL 轮询：异步查询执行（202 → 轮询 → 结果）

预期结果

📊 TEST RESULTS SUMMARY
Total Tests: 8
✅ Passed: 8
❌ Failed: 0
📈 Success Rate: 100.0%

📋 详细用法和故障排除信息，请参阅测试套件文档。

---

🚀 项目路线图

🎯 当前状态：已可用于生产环境

所有工具均可正常运行，测试全面，结构清晰。已准备好进入下一阶段的增强工作。

📋 后续优先事项

1. 🌐 HTTP 改进：从 fetch 迁移到 axios，以获得更好的错误处理和请求拦截器
2. 🤖 MCP 服务开发：构建自定义 MCP 服务，将工具作为 AI 可访问的能力提供
3. ⚡ 性能优化：并行测试、性能基准测试、负载测试

📚 规划文档

• 完整项目路线图 - 全面的功能路线图和实施时间表
• Axios 迁移计划 - HTTP 改进的详细计划
• MCP 服务设计 - 基于官方 TypeScript SDK 的完整架构和实现方案

💡 想法与贡献

路线图包含以下高级功能：

• 自然语言查询（“显示过去一小时的 Lambda 错误”）
• 多环境支持和比较
• 预测分析和异常检测
• 与其他可观测性平台集成

📝 贡献：查看 TODO.md，了解如何为未来开发做贡献

🎯 重点方向：HTTP 改进和 MCP 服务开发是当前的优先事项**