Dotnet Diagnostics

CI

An MCP server for LLM-driven performance diagnostics on .NET 10 applications. Normal EventPipe and ClrMD diagnostics require no target code changes or prior instrumentation. The explicit exception is collect_sample(kind="method-params"), an opt-in, privileged, security-gated dynamic profiler attach that temporarily instruments an allowlist of methods.

Status: 17 unified tools in the full surface (13 default plus 4 configuration-gated), HTTP + stdio transports, IoT-style triage (6+ steps → 2 steps). See docs/ for full reference.

Two ways to use it

This repo ships two NuGet tools built on the same Core diagnostics engine — pick by who is driving:

Most of this README is about the MCP server. If you want to run diagnostics yourself, jump to the Standalone CLI section or the CLI reference.

Table of Contents

• Quick Start
• Install
• Standalone CLI
• Tools Overview
• Documentation
• Goals
• Build & Test

Quick Start

One call to understand your app's health:

# MCP call
inspect_process(view="triage")

Response excerpt (rationales shortened):

{
  "modelVersion": 2,
  "assessment": "critical",
  "severity": "Critical",
  "observedSignals": [
    {
      "name": "threadpool.queue",
      "level": "critical",
      "summary": "The ThreadPool queue contained 1191 work items.",
      "evidence": [
        {"name": "threadpool-queue-length", "value": 1191, "comparison": ">=", "threshold": 200, "unit": "items", "rationale": "Queue crossed the critical threshold."}
      ]
    }
  ],
  "hypotheses": [
    {
      "name": "threadpool.backlog",
      "confidence": "moderate",
      "summary": "Work was queued faster than the ThreadPool completed it; counters do not prove starvation.",
      "supportingEvidence": [{"name": "threadpool-queue-length", "value": 1191, "comparison": ">=", "threshold": 50, "rationale": "Large queue supports a backlog hypothesis."}],
      "contradictingEvidence": [],
      "nextStep": "Collect ThreadPool events and blocking stacks to distinguish sustained starvation, blocking, and transient demand."
    }
  ],
  "topIndicators": [
    {"name": "threadpool-queue-length", "value": 1191, "score": 100, "level": "critical"}
  ],
  // deprecated — kept for compatibility, scheduled for removal in v1.0; prefer topIndicators
  "verdict": "threadpool-starvation",
  "secondaryVerdicts": null
}

observedSignals report threshold crossings; hypotheses explain bounded interpretations and the evidence needed to confirm them. A low-CPU snapshot with a small queue is inconclusive, not categorically io-bound. verdict / secondaryVerdicts remain for compatibility and are deprecated for removal in v1.0. TopIndicators remain available on every result.

Install

Three distributions — pick by environment. Full walkthrough: docs/consumer-install.md

# .NET global tool (requires .NET 10 SDK)
dotnet tool install -g dotnet-diagnostics-mcp
dotnet-diagnostics-mcp --urls http://127.0.0.1:8787

# Container — host-loopback only, local dev (container binds 0.0.0.0:8080 internally)
# MCP_ALLOW_INSECURE_HTTP=true is required for cleartext on the container-internal non-loopback bind;
# -p 127.0.0.1:8787:8080 restricts host access to loopback. Use TLS for production.
docker run -d -p 127.0.0.1:8787:8080 \
  -e MCP_BEARER_TOKEN=$(openssl rand -hex 32) \
  -e MCP_ALLOW_INSECURE_HTTP=true \
  ghcr.io/pedrosakuma/dotnet-diagnostics:latest

# Self-contained binary — see Releases page

export ASSEMBLIES_DIR=/path/to/binaries
docker compose -f deploy/docker-compose.yml up -d

Standalone CLI

dotnet-diagnostics-cli is a separate NuGet tool that runs the same Core diagnostics engine as a command you drive yourself — no HTTP server, bearer token, MCP client, or daemon. Useful for scripts, CI, and kubectl exec into the sidecar (the container image ships it on PATH).

dotnet tool install -g dotnet-diagnostics-cli

# One-shot
dotnet-diagnostics-cli processes
dotnet-diagnostics-cli collect --kind counters --pid 1234 --duration 5
dotnet-diagnostics-cli inspect-heap --pid 1234 --top-types 30 --acknowledge-risk high

# Inside the sidecar container (image bundles the CLI):
kubectl exec -it <pod> -c diagnostics-mcp -- \
  dotnet-diagnostics-cli inspect-heap --pid 1 --acknowledge-risk high

A stateful session REPL keeps collected handles queryable across commands so you can drill in (query --handle <id> --view <view>) without re-collecting, and bind a target pid once with target <pid>:

dotnet-diagnostics-cli session
diag> target 1234
diag(pid 1234)> collect --kind gc --duration 10
diag(pid 1234)> query --handle <id> --view pauseHistogram
diag(pid 1234)> exit

Self-contained per-OS binaries are attached to each Release as dotnet-diagnostics-cli-<version>-<rid>. Full reference: docs/cli-reference.md.

Tools Overview

17 unified tools. Full schemas and return shapes: docs/tool-reference.md.

Documentation

📖 docs/ is the documentation hub — start there. It indexes the tool reference, CLI reference, investigation playbooks, output examples, authorization/scopes, client setup, and all deployment guides (Kubernetes, Helm, Azure, AWS, GCP).

Before any production rollout, complete the production-readiness go/no-go checklist.

Goals

• No prior instrumentation for standard diagnostics — EventPipe and ClrMD work through diagnostic IPC without target code changes
• Explicit sensitive attach boundary — method-parameter capture is opt-in dynamic profiler instrumentation, not a passive collector
• Cross-platform — Linux + Windows, containers first-class
• Graceful NativeAOT — unsupported tools return not_supported, not crashes
• LLM-friendly — summarized JSON, not raw .nettrace

Build & Test

dotnet build
dotnet test

Requires .NET 10 SDK (pinned in global.json).

scripts/local-mcp.sh start     # builds + starts in background
scripts/local-mcp.sh status
scripts/local-mcp.sh logs -f
scripts/local-mcp.sh stop

{
  "mcpServers": {
    "dotnet-diagnostics": {
      "type": "http",
      "url": "http://127.0.0.1:8787/mcp",
      "headers": { "Authorization": "Bearer demo-local-token-2026" }
    }
  }
}

Roadmap

License

MIT — see LICENSE.