# DiagSession Mcp

> A production-grade Model Context Protocol (MCP) server for analyzing Windows ETL trace files from .diagsession archives. Built with clean architecture principles and enterprise best practices.

- **Type:** MCP server
- **Install:** `agentstack add mcp-bivex-diagsession-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [bivex](https://agentstack.voostack.com/s/bivex)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [bivex](https://github.com/bivex)
- **Source:** https://github.com/bivex/DiagSession-Mcp

## Install

```sh
agentstack add mcp-bivex-diagsession-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# DiagSession MCP Server

A production-grade Model Context Protocol (MCP) server for analyzing Windows ETL trace files from .diagsession archives. Built with clean architecture principles and enterprise best practices.

## Features

- **ETL Trace Analysis**: Analyzes Windows Performance Recorder traces with CPU sampling data
- **Call Tree Generation**: Builds hierarchical call trees showing inclusive/exclusive CPU time
- **Symbol Resolution**: Integrates with Microsoft symbol servers for function name resolution
- **.diagsession Support**: Automatically extracts ETL files from .diagsession ZIP archives
- **Process Filtering**: Filter analysis by specific process ID
- **Depth Control**: Limit call tree depth for efficient responses
- **MCP Protocol**: Exposes analysis via standard MCP tool interface

## Architecture

The server follows a layered architecture with strict separation of concerns:

```
┌─────────────────────────────────────┐
│      MCP Protocol Layer             │  Tool handlers, schemas
├─────────────────────────────────────┤
│      Application Layer              │  Use cases, DTOs
├─────────────────────────────────────┤
│      Domain Layer                   │  Business logic, models
├─────────────────────────────────────┤
│      Infrastructure Layer           │  TraceEvent adapter, ZIP extraction
└─────────────────────────────────────┘
```

### Key Components

- **Domain Models**: `CallTreeNode`, `FunctionStats`, `AnalysisResult`, `AnalysisOptions`
- **Domain Interfaces**: `IEtlAnalyzer`, `IDiagSessionExtractor`
- **Application**: `AnalyzeDiagSessionUseCase`, DTOs, `RequestContext`
- **Infrastructure**: `TraceEventEtlAnalyzer`, `DiagSessionArchiveExtractor`
- **MCP**: `AnalyzeCallTreeTool`

## Installation

### Prerequisites

- .NET 8.0 SDK or later
- Windows OS (required for TraceEvent library)

### Build

```bash
dotnet restore
dotnet build
```

### Run

```bash
dotnet run --project DiagSession-Mcp.csproj
```

The server will start and listen for MCP requests via stdio transport.

## MCP Tool: analyze_call_tree

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `diagsession_path` | string | Yes | Path to .diagsession or .etl file |
| `max_depth` | integer | No | Maximum call tree depth (default: 10, max: 50) |
| `process_id` | integer | No | Filter by specific process ID |
| `symbol_path` | string | No | Symbol server path |
| `timeout_seconds` | integer | No | Symbol loading timeout (default: 30, max: 300) |
| `max_symbol_size_mb` | number | No | Skip symbols larger than this size |
| `verbose` | boolean | No | Enable verbose logging |

### Response Schema

```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": [...]
}
```

### Error Codes

- `FILE_NOT_FOUND`: Specified file does not exist
- `INVALID_PARAMS`: Invalid parameters provided
- `TIMEOUT`: Analysis timeout exceeded
- `INTERNAL_ERROR`: Unexpected server error

## Configuration

Configuration is loaded from `appsettings.json` and environment variables.

### 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"
  }
}
```

### Environment Variables

- `_NT_SYMBOL_PATH`: Override symbol server path
- `DIAGSESSION_MCP__SYMBOLPATH`: Override symbol path via configuration

## Development

### Project Structure

```
DiagSession-Mcp/
├── src/
│   ├── Domain/
│   │   ├── Models/          # Domain entities
│   │   └── Interfaces/      # Domain contracts
│   ├── Application/
│   │   ├── UseCases/        # Application logic
│   │   ├── DTOs/            # Data transfer objects
│   │   └── Common/          # Cross-cutting concerns
│   ├── Infrastructure/
│   │   └── Adapters/        # External system adapters
│   ├── Mcp/
│   │   └── Tools/           # MCP tool implementations
│   └── Program.cs           # Entry point
├── appsettings.json
└── DiagSession-Mcp.csproj
```

### Testing

```bash
# Run all tests
dotnet test

# Run specific test category
dotnet test --filter Category=Unit
dotnet test --filter Category=Integration
```

## Design Principles

This server follows enterprise architecture best practices:

- **Bounded Context**: Focused solely on ETL trace analysis
- **Ports & Adapters**: External dependencies behind interfaces
- **Domain-Driven Design**: Rich domain models with business logic
- **Separation of Concerns**: Strict layering with clear responsibilities
- **Dependency Injection**: All dependencies injected via constructors
- **Immutability**: DTOs and domain models are immutable where possible
- **Explicit Contracts**: Tool schemas versioned and documented
- **Observability**: Structured logging with correlation IDs
- **Error Handling**: Domain errors separated from technical failures
- **Testability**: Each layer independently testable

## License

MIT

## Credits

Built with:
- [ModelContextProtocol C# SDK](https://github.com/modelcontextprotocol/csharp-sdk)
- [Microsoft.Diagnostics.Tracing.TraceEvent](https://github.com/microsoft/perfview)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [bivex](https://github.com/bivex)
- **Source:** [bivex/DiagSession-Mcp](https://github.com/bivex/DiagSession-Mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-bivex-diagsession-mcp
- Seller: https://agentstack.voostack.com/s/bivex
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.