dotnet-dump-mcp: Instructions file for Codex

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Summary

dotnet-dump-mcp-server is a Model Context Protocol (MCP) server that wraps Microsoft.Diagnostics.Runtime (ClrMD) to enable AI agents to analyze .NET memory dumps. It provides tools for heap analysis, thread inspection, exception tracing, and module/metadata investigation. The server runs in Docker (recommended for architecture mismatches) or natively with .NET SDK 8+.

Build, Test, and Development Commands

Core Development

# Build the solution
dotnet build

# Run the MCP server locally (requires DUMP_PATH to be set)
export DUMP_PATH="/path/to/dump.core"
dotnet run --project src/DotNetDump.Server/DotNetDump.Server.csproj --framework net9.0

# Run all tests (xUnit)
dotnet test

# Run a single test by name
dotnet test --filter "MethodName"

# Code formatting (applies formatting in-place)
dotnet format

# Code formatting with verify (checks without modifying)
dotnet format --verify-no-changes

# Run coverage analysis
./run-coverage.sh

Docker

# Build Docker image
docker build -t dotnet-dump-mcp-server .

# Run with a dump mounted
docker run --rm -i \
  -v "/path/to/dumps:/dumps" \
  -e DUMP_PATH=/dumps/target.core \
  dotnet-dump-mcp-server

MCP Inspector (Interactive Testing)

# Launch the MCP Inspector web UI to test tools directly
export DUMP_PATH="/path/to/sample.core"
npx @modelcontextprotocol/inspector \
  dotnet run --project src/DotNetDump.Server/DotNetDump.Server.csproj --framework net9.0

High-Level Architecture

The solution follows a clean three-layer architecture:

1. DotNetDump.Core (Class Library)

Reusable analysis engine with no MCP dependencies:

• DumpContext (IDumpContext): Lazy-loading wrapper around ClrMD's DataTarget and ClrRuntime. Manages lifecycle and symbol resolution via environment variables (DOTNETDUMP_SYMBOL_PATHS, DOTNETDUMP_SYMBOL_CACHE).
• Analyzers (Analyzers/):
  • HeapAnalyzer: Heap stats, object listing, GC roots, heap segments, object inspection, GC handles, heap verification.
  • ThreadAnalyzer: Managed thread enumeration, stack traces (grouped or per-thread), thread pool stats, exception printing.
  • ModuleAnalyzer: Loaded assemblies, module details, MethodTable/MethodDesc lookup.
  • MetadataAnalyzer: EEClass, MethodDesc, and MethodTable information display.
• Models (Models/): Strongly-typed result objects (e.g., HeapStatItem, ThreadInfo, ObjectDetails). No formatting logic; data only.
• Formatting (Formatting/): Markdown table generation for LLM-friendly output. Handles pagination (Skip/Take) and sorting.