dotnet-diagnostics-cli 0.10.0

dotnet-diagnostics-mcp

An MCP server for LLM-driven performance diagnostics on .NET 10 applications — zero instrumentation required.

Status: 15 unified tools, HTTP + stdio transports, IoT-style triage (6+ steps → 2 steps). See docs/ for full reference.

Table of Contents

• Quick Start
• Install
• Tools Overview
• Documentation
• Goals
• Build & Test
• Roadmap

Quick Start

One call to understand your app's health:

# MCP call
inspect_process(view="triage")

Response:

{
  "verdict": "threadpool-starvation",
  "severity": "Critical",
  "topIndicators": [
    {"name": "threadpool-queue-length", "value": 1191, "score": 100, "level": "critical"},
    {"name": "cpu-usage", "value": 0.13, "score": 0, "level": "normal"},
    {"name": "time-in-gc", "value": 0, "score": 0, "level": "normal"}
  ],
  "hints": [{"nextTool": "collect_events", "suggestedArguments": {"kind": "threadpool"}}]
}

Verdicts: cpu-bound, gc-pressure, memory-pressure, threadpool-starvation, lock-contention, io-bound, healthy

TopIndicators are always returned (even when healthy) — enabling proactive optimization, not just reactive firefighting. The LLM simply follows the first hint.

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 (no SDK needed)
docker run -d -p 127.0.0.1:8787:8080 \
  -e MCP_BEARER_TOKEN=$(openssl rand -hex 32) \
  ghcr.io/pedrosakuma/dotnet-diagnostics-mcp:latest

# Self-contained binary — see Releases page

<details> <summary><strong>Standalone one-shot CLI (no MCP client)</strong></summary>

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

dotnet tool install -g dotnet-diagnostics-cli
dotnet-diagnostics-cli processes
dotnet-diagnostics-cli collect --kind counters --pid 1234 --duration 5

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

Self-contained per-OS binaries are attached to each Release as dotnet-diagnostics-cli-<version>-<rid>.

</details>

<details> <summary><strong>Transport options</strong></summary>

</details>

<details> <summary><strong>Linux ptrace note</strong></summary>

On Debian/Ubuntu/WSL, kernel.yama.ptrace_scope=1 blocks ClrMD tools. Fix: echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope. See docs/consumer-install.md.

</details>

<details> <summary><strong>Joint with dotnet-assembly-mcp</strong></summary>

For decompilation + call graphs:

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

</details>

Tools Overview

Documentation

Deployment guides:

<details> <summary><strong>MCP Prompts (curated playbooks)</strong></summary>

6 built-in prompts: diagnose-high-latency, diagnose-memory-growth, diagnose-5xx-errors, diagnose-slow-outbound-http, triage-nativeaot, diagnose-safely-in-prod. See Prompts section.

</details>

<details> <summary><strong>Security notes</strong></summary>

• TLS required for non-loopback binds
• Bearer token required (set MCP_BEARER_TOKEN)
• Helm chart includes optional Ingress and NetworkPolicy

</details>

Goals

• Zero changes to target app — works via diagnostic IPC
• 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).

<details> <summary><strong>Contributor setup (shared dev instance)</strong></summary>

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

Add to ~/.copilot/mcp-config.json:

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

</details>

Roadmap

License

TBD.