内容
# DiagSession MCP 服务器
用于分析来自 `.diagsession` 存档的 Windows ETL 跟踪文件的生产级模型上下文协议（MCP）服务器。遵循干净的架构原则和企业最佳实践。
## 功能
- **ETL 跟踪分析**：分析带有 CPU 采样数据的 Windows 性能记录器跟踪
- **调用树生成**：构建显示包含/排除 CPU 时间的层次调用树
- **符号解析**：与微软符号服务器集成以进行函数名称解析
- **.diagsession 支持**：自动从 `.diagsession` ZIP 存档中提取 ETL 文件
- **进程过滤**：按特定进程 ID 过滤分析
- **深度控制**：限制调用树深度以实现高效响应
- **MCP 协议**：通过标准 MCP 工具接口公开分析
## 架构
服务器遵循具有严格关注点分离的分层架构：
```
┌─────────────────────────────────────┐
│ MCP 协议层 │ 工具处理程序、模式
├─────────────────────────────────────┤
│ 应用层 │ 用例、DTO
├─────────────────────────────────────┤
│ 领域层 │ 业务逻辑、模型
├─────────────────────────────────────┤
│ 基础设施层 │ 跟踪事件适配器、ZIP 提取
└─────────────────────────────────────┘
```
### 关键组件
- **领域模型**：`CallTreeNode`、`FunctionStats`、`AnalysisResult`、`AnalysisOptions`
- **领域接口**：`IEtlAnalyzer`、`IDiagSessionExtractor`
- **应用**：`AnalyzeDiagSessionUseCase`、DTO、`RequestContext`
- **基础设施**：`TraceEventEtlAnalyzer`、`DiagSessionArchiveExtractor`
- **MCP**：`AnalyzeCallTreeTool`
## 安装
### 先决条件
- .NET 8.0 SDK 或更高版本
- Windows 操作系统（需要 TraceEvent 库）
### 构建
```bash
dotnet restore
dotnet build
```
### 运行
```bash
dotnet run --project DiagSession-Mcp.csproj
```
服务器将启动并通过 stdio 传输监听 MCP 请求。
## MCP 工具：analyze_call_tree
### 参数
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `diagsession_path` | 字符串 | 是 | `.diagsession` 或 `.etl` 文件的路径 |
| `max_depth` | 整数 | 否 | 最大调用树深度（默认值：10，最大：50） |
| `process_id` | 整数 | 否 | 按特定进程 ID 过滤 |
| `symbol_path` | 字符串 | 否 | 符号服务器路径 |
| `timeout_seconds` | 整数 | 否 | 符号加载超时（默认值：30，最大：300） |
| `max_symbol_size_mb` | 数字 | 否 | 跳过大于此大小的符号 |
| `verbose` | 布尔值 | 否 | 启用详细日志记录 |
### 响应模式
```json
{
"callTrees": {
"4036": {
"functionName": "InterruptEstimator (PID: 4036)",
"moduleName": null,
"inclusiveSamples": 246,
"exclusiveSamples": 0,
"inclusivePercent": 100.0,
"exclusivePercent": 0.0,
"inclusiveTimeMs": 246.0,
"exclusiveTimeMs": 0.0,
"children": [...]
}
},
"processNames": {
"4036": "InterruptEstimator"
},
"totalSamples": 246,
"profileIntervalMs": 1.0,
"analysisTimestamp": "2025-11-25T07:36:00Z",
"correlationId": "abc123",
"topFunctionsByExclusive": [...],
"topFunctionsByInclusive": [...]
}
```
### 错误代码
- `FILE_NOT_FOUND`：指定的文件不存在
- `INVALID_PARAMS`：提供的参数无效
- `TIMEOUT`：分析超时
- `INTERNAL_ERROR`：意外的服务器错误
## 配置
配置从 `appsettings.json` 和环境变量加载。
### appsettings.json
```json
{
"DiagSessionMcp": {
"SymbolPath": "srv*c:\\symbols*https://msdl.microsoft.com/download/symbols",
"DefaultTimeoutSeconds": 30,
"MaxConcurrentAnalyses": 2,
"MaxMemoryMB": 4096,
"AllowedDirectories": ["C:\\DiagSessions"],
"LogLevel": "Information"
}
}
```
### 环境变量
- `_NT_SYMBOL_PATH`：覆盖符号服务器路径
- `DIAGSESSION_MCP__SYMBOLPATH`：通过配置覆盖符号路径
## 开发
### 项目结构
```
DiagSession-Mcp/
├── src/
│ ├── Domain/
│ │ ├── Models/ # 领域实体
│ │ └── Interfaces/ # 领域契约
│ ├── Application/
│ │ ├── UseCases/ # 应用逻辑
│ │ ├── DTOs/ # 数据传输对象
│ │ └── Common/ # 跨领域关注点
│ ├── Infrastructure/
│ │ └── Adapters/ # 外部系统适配器
│ ├── Mcp/
│ │ └── Tools/ # MCP 工具实现
│ └── Program.cs # 入口点
├── appsettings.json
└── DiagSession-Mcp.csproj
```
### 测试
```bash
# 运行所有测试
dotnet test
# 运行特定测试类别
dotnet test --filter Category=Unit
dotnet test --filter Category=Integration
```
## 设计原则
该服务器遵循企业架构最佳实践：
- **有界上下文**：仅专注于 ETL 跟踪分析
- **端口和适配器**：外部依赖于接口
- **领域驱动设计**：具有业务逻辑的丰富领域模型
- **关注点分离**：具有明确职责的严格分层
- **依赖注入**：所有依赖项通过构造函数注入
- **不可变性**：DTO 和领域模型在可能的情况下不可变
- **显式契约**：工具模式版本控制和文档记录
- **可观察性**：具有相关 ID 的结构化日志记录
- **错误处理**：领域错误与技术故障分离
- **可测试性**：每层可独立测试
## 许可证
MIT
## 鸣谢
使用以下工具构建：
- [ModelContextProtocol C# SDK](https://github.com/modelcontextprotocol/csharp-sdk)
- [Microsoft.Diagnostics.Tracing.TraceEvent](https://github.com/microsoft/perfview)
