convez.ai
MCP ServerDevOps & InfraestruturaAvançado
pedrosakuma

Diagnósticos .NET via MCP

pedrosakuma/dotnet-diagnostics

Diagnósticos .NET em tempo real via LLM, zero instrumentation

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que oferece diagnósticos de performance para aplicações .NET sem instrumentation. Coleta contadores, amostras de CPU, exceções, eventos de GC e dumps direto de processos CoreCLR ao vivo, permitindo que LLMs conduzam investigações de performance automaticamente.

Instalação

$npx convez-ai pedrosakuma/dotnet-diagnostics

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
27
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 6 dias
Versão
v0.34.0
Issues abertas
28
Contribuidores
5

Casos de uso

  • Investigação automatizada de performance em aplicações .NET
  • Triagem rápida de problemas de CPU, memória e threadpool
  • Coleta de eventos de GC e exceções para análise de LLM
  • Integração de diagnósticos em pipelines de DevOps e observabilidade

Veredito

Ferramenta especializada e bem-arquitetada para quem precisa automatizar diagnósticos de performance .NET. O design modular (CLI + MCP) e os 15 tools unificados mostram maturidade técnica — viável para ambientes de produção com expertise C# e .NET.

README

A tradução para o português deste README ainda está na fila.

dotnet-diagnostics-mcp

CI

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.

Two ways to use it

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

PackageDriverSurfaceDocs
dotnet-diagnostics-mcpAn LLM, via an MCP clientMCP tools over HTTP (bearer) or stdiothis README + docs/
dotnet-diagnostics-cliA human / script / CISub-commands + a stateful session REPL (no HTTP, no bearer, no daemon)docs/cli-reference.md

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

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
TransportUse caseAuth
stdioLocal dev (Copilot CLI, Claude Desktop)None (OS-level trust)
HTTPSidecar, shared host, multi-clientBearer token

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.

For decompilation + call graphs:

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

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

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

ToolPurpose
inspect_process(view="triage")IoT-style diagnosis — 1 call returns verdict + severity + ranked TopIndicators + hints
inspect_process(view="list") / inspect_process(view="info")Discover .NET processes via diagnostic IPC
inspect_process(view="capabilities")Detect CoreCLR vs NativeAOT and what's usable
inspect_process(view="container")Linux cgroup v2: CPU throttling, memory pressure, OOM kills, PSI
collect_events(kind="counters")EventCounters with auto-hints (CPU, GC, starvation, contention, allocation, I/O)
collect_sample(kind="cpu") / query_snapshot(view="call-tree")Top-N CPU hotspots (inclusive/exclusive) + on-demand caller→callee tree
collect_sample(kind="off_cpu") / query_snapshotWhere threads block (futex / IO / sleep) — Linux perf backend
collect_sample(kind="native-alloc") / query_snapshot(view="call-tree")Native/unmanaged allocation hotspots (off-GC-heap malloc) attributed to call sites — Linux perf uprobe backend
collect_events(kind="exceptions")Managed exceptions thrown in a window, aggregated by type
collect_events(kind="gc")GC pauses + per-generation counts
collect_events(kind="activities") / query_snapshotActivitySource span capture (trace/span ids, parent linkage, tags, duration) + GC overlay correlation
collect_events(kind="event_source") / query_snapshotGeneric EventSource passthrough (HTTP, Kestrel, custom) + re-project artifacts
collect_thread_snapshot / query_snapshotManaged thread states + SyncBlock lock graph + deadlock / unique-stack drilldown
inspect_heap(source="live") / inspect_heap(source="dump") / query_snapshotTop retained types + retention paths + roots + async state machines, live or from a dump
collect_process_dumpWrite a Mini / Triage / WithHeap / Full dump to disk
start_investigationStructured plan (cold / warm / hypothesis) before any collector runs
export_investigation_summary / compare_to_baselinePortable JSON memory; LLM persists, diffs across deploys

Documentation

DocContents
docs/cli-reference.mdStandalone CLI — commands, flags, and the session REPL
docs/tool-reference.mdFull MCP tool schemas and return shapes
docs/investigation-playbooks.mdCommon investigation recipes
docs/aot-coverage.mdNativeAOT coverage matrix
docs/client-setup.mdMCP client configuration
docs/consumer-install.mdFull install walkthrough

Deployment guides:

PlatformGuide
Kubernetes sidecardeploy/k8s/README.md
Helm chartdeploy/helm/README.md
Azuredeploy/azure/README.md
AWSdeploy/aws/README.md
GCPdeploy/gcp/README.md

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.

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

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).

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

Roadmap

PhaseStatusDescription
1-3✅Foundation + Core diagnostics + MCP server
4✅GC, exceptions, EventSources, dumps
5✅Kubernetes sidecar (deploy/k8s/)
6✅Documentation polish
7✅Cloud integrations (Azure, AWS, GCP)
8✅Tool consolidation (24 → 15 tools)
12✅Diagnostic Journey UX — auto-hints + IoT triage
13✅GC overlay — correlate GC pauses with activity spans
Next⏳Flame graph export, NativeAOT publish

License

TBD.

Ver o original no GitHub

Bom para

Relacionados