convez.ai
MCP Server
pedrosakuma

dotnet-native-mcp

pedrosakuma/dotnet-native-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server for navigating native .NET binaries (NativeAOT / R2R / single-file) — handoff target for dotnet-diagnostics-mcp native frames

Instalação

$npx convez-ai pedrosakuma/dotnet-native-mcp

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
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 2 meses
Versão
v0.6.0
Issues abertas
2
Contribuidores
5

README

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

dotnet-native-mcp

Status: V1 in progress. Eleven MCP tools are live: load_native_binary, import_native_manifest, list_native_symbols, list_native_imports, resolve_symbols, extract_strings, get_size_breakdown, explain_retention, compare_native_binaries, disassemble, find_native_callers. See the V0 tracking issue.

MCP server for navigating native .NET binaries — NativeAOT, R2R-only, single-file native — when ECMA-335 metadata is stripped or absent. Designed as the third leg of a tooling triad with dotnet-assembly-mcp (managed metadata) and dotnet-diagnostics-mcp (live process events).

Why this exists

dotnet-diagnostics-mcp already attaches to NativeAOT processes and emits hotspot frames whose symbols are mangled ILC names (S_P_____...) and whose addresses point at native code. dotnet-assembly-mcp cannot answer queries on those frames — its load_assembly rejects NativeAOT binaries with module_load_failed: not a managed PE. Today, the LLM receives a hex address and a mangled symbol and has nowhere to take them.

This server closes the gap. It accepts the NativeFrame handoff (binary + symbol + address), demangles ILC symbols back to managed-looking names, disassembles the native code with Iced, and will read the sidecar artifacts ILC emits (.mstat, .map, DGML) when they are available.

Where it does not belong

  • Managed metadata, IL, decompile-to-C#. That's dotnet-assembly-mcp.
  • Live process attach, EventPipe / ETW collection. That's dotnet-diagnostics-mcp.
  • Generic reverse engineering (full Ghidra-class decompilation, full dynamic instrumentation, kernel-mode debuggers). Out of scope by design.

Tool surface (13 tools, V1)

ToolPurpose
load_native_binaryOpen a PE/ELF/Mach-O, verify it's a managed-flavored native build, return a handle. Accepts path + optional buildId.
import_native_manifestBulk handshake from a producer (typically dotnet-diagnostics-mcp): register a list of native binaries in one call. Accepts entries: [{path, name?, buildId?}] + mode (lazy|eager). Per-entry failures reported inline without failing the batch.
list_native_symbolsPaginated symbol table. Source priority: .map sidecar → ELF .symtab/.dynsym → PE export table. Includes raw + demangled names.
list_native_importsPaginated import/dependency walk. kind="functions" lists ELF undefined .dynsym imports or PE Import Directory entries; kind="libraries" lists ELF DT_NEEDED or PE imported DLL names.
resolve_symbolsBatch address ↔ symbol lookup with ILC demangling. Accepts up to 200 hex (0x-prefixed or bare) or decimal address strings against a single image. Per-address failures are reported inline without failing the whole batch. Replaces the former single-address resolve_symbol and multi-frame symbolicate_stack tools.
extract_stringsPaginated printable ASCII / UTF-16LE scan over .rodata / .rdata / .data.rel.ro / __const (with .data fallback). Returns section + offset for forensics.
get_size_breakdownRead the .mstat sidecar emitted by NativeAOT and aggregate native bytes by assembly, namespace, type, or method.
explain_retentionRead the DGML reachability sidecar emitted by NativeAOT and return the shortest root → target path that kept a type or method reachable.
compare_native_binariesDiff two loaded images: build-id, format, arch, file/section size deltas, added/removed/size-changed symbols.
disassembleIced x86/x64 and AsmArm64 ARM64 disassembly with CALL/JMP/BL cross-ref hints. Default 64 instructions, capped at 2048. resolveSource=false (default) skips per-instruction DWARF lookup; set true to annotate each instruction with file:line. Two modes: registered-handle mode (imageHandle + address/symbolName) for images loaded via load_native_binary; or raw-bytes mode (imagePath + rva + size) for any PE/ELF/Mach-O — including managed PEs with R2R bodies — without a prior load_native_binary call.
find_native_callersLazily-built xref index: scan all executable sections of a loaded x86-64 or ARM64 image and return every CALL/JMP/BL instruction that targets a given symbol name or hex address. The index is cached in-process (L1) and persisted to disk under ~/.cache/dotnet-native-mcp/<build-id>.xref (L2) so large NativeAOT binaries pay the scan cost only once across sessions. crossImage=true resolves call sites that branch into PLT/import/stub thunks of other loaded images (ELF PLT entries account for the architecture-specific PLT0 header — 16 bytes on x86-64, 32 on AArch64). resolveSource=true (default) annotates each call site with file:line; set false to skip PDB I/O for large binaries.
get_r2r_headerRead the ReadyToRun header of a managed PE: version, decoded READYTORUN_FLAG_* names, full sections table, and the CompilerIdentifier (type 100) / OwnerCompositeExecutable (type 116) strings. includeImportSections=true decodes the ImportSections (type 101) fixup-region metadata; includeCompositeInfo=true decodes the composite-image ComponentAssemblies (type 115) entries and ManifestAssemblyMvids (type 118) GUIDs; includeMethodEntryPoints=true decodes the MethodDefEntryPoints (type 103) NativeFormat array into a MethodDef RID → RUNTIME_FUNCTION index mapping (with a has-fixups flag), capped by methodEntryPointsLimit; includeAvailableTypes=true decodes the AvailableTypes (type 108) NativeFormat hashtable into TypeDef (0x02) / ExportedType (0x27) metadata tokens for handoff to dotnet-assembly-mcp, capped by availableTypesLimit; includeInfoMaps=true decodes the V9 RID-indexed info maps — EnclosingTypeMap (type 122, nested→enclosing type tokens), MethodIsGenericMap (type 121, generic-method tokens) and TypeGenericInfoMap (type 123, per-type generic arity/variance/constraints) — capped by infoMapsLimit; includeManifestMetadata=true surfaces the ManifestMetadata (type 112) embedded ECMA-335 blob as a handoff descriptor (file offset, RVA, size, version string and stream directory) without decoding the managed metadata itself; includeHotColdMap=true decodes the HotColdMap (type 120) section into (cold, hot) RUNTIME_FUNCTION index pairs (capped by infoMapsLimit). Returns r2r_not_present for pure-managed or NativeAOT binaries.
list_r2r_runtime_functionsPaginated RUNTIME_FUNCTION entries from the RuntimeFunctions section (type 102), or — with rva — a binary-search lookup of the single covering entry. x64 + ARM64; other arches return r2r_arch_unsupported.

For crash logs or sampled stacks where dotnet-diagnostics-mcp is not in the loop, use load_native_binary once and then call resolve_symbols with a list of raw hex addresses. When you already have NativeFrame handoffs with mangled addresses, pass those address strings directly to resolve_symbols.

ReadyToRun coverage

get_r2r_header + list_r2r_runtime_functions cover every R2R section whose layout is structurally tractable — decodable from raw PE bytes alone — plus the MethodDefEntryPoints array, which a safe span-based port of the runtime's NativeFormat reader now decodes:

Section (type)Surface
Header, version, decoded flagsget_r2r_header
Sections tableget_r2r_header
RuntimeFunctions (102), x64 + ARM64list_r2r_runtime_functions (list + RVA lookup)
ImportSections (101)get_r2r_header includeImportSections=true
CompilerIdentifier (100)get_r2r_header (eager)
OwnerCompositeExecutable (116)get_r2r_header (eager)
ComponentAssemblies (115)get_r2r_header includeCompositeInfo=true
ManifestAssemblyMvids (118)get_r2r_header includeCompositeInfo=true
MethodDefEntryPoints (103)get_r2r_header includeMethodEntryPoints=true
AvailableTypes (108)get_r2r_header includeAvailableTypes=true (metadata tokens)
MethodIsGenericMap (121)get_r2r_header includeInfoMaps=true (generic-method tokens)
EnclosingTypeMap (122)get_r2r_header includeInfoMaps=true (nested→enclosing type tokens)
TypeGenericInfoMap (123)get_r2r_header includeInfoMaps=true (per-type generic info)
ManifestMetadata (112)get_r2r_header includeManifestMetadata=true (ECMA blob handoff descriptor)
HotColdMap (120)get_r2r_header includeHotColdMap=true ((cold, hot) RUNTIME_FUNCTION index pairs)

Out of scope — sections encoded with the runtime's NativeFormat native hashtables / nibble-compressed signature streams, or that embed an ECMA metadata blob we do not parse into managed metadata. Decoding them requires the NativeFormat hashtable reader plus Internal.TypeSystem type resolution — partly redundant with dotnet-assembly-mcp (which owns managed metadata):

InstanceMethodEntryPoints, InliningInfo*, ProfileDataInfo, PgoInstrumentationData, AttributePresence, CrossModuleInlineInfo, the remaining *Map sections, DelayLoadMethodCallThunks, ExceptionInfo, and DebugInfo. The ManifestMetadata (112) blob is located (offset/size/version/streams) for handoff but its managed metadata is decoded by dotnet-assembly-mcp.

Sidecar tier (V1+)

ILC emits structured sidecars on request:

ArtifactSwitchWhat it gives us
.mstatIlcGenerateMstatFile=trueper-type / per-method native size
.mapIlcMapFileType=Normalsymbol → address map
DGMLIlcGenerateDgmlFile=truereachability graph from the trimmer

.mstat parsing answers "what blew up my AOT binary"; DGML reachability answers "why was this type or method kept?".

Install

# stdio (local MCP client)
dotnet tool install -g dotnet-native-mcp
dotnet-native-mcp --stdio

# HTTP (sidecar / multi-client)
docker run --rm -p 8789:8080 \
  -v /path/to/binaries:/binaries:ro \
  ghcr.io/pedrosakuma/dotnet-native-mcp:latest

Default port: 8789. Slot picked to continue the convention started by dotnet-diagnostics-mcp (8787) and dotnet-assembly-mcp (8788).

Running the triad with Docker Compose

To bring up all three servers together (diagnostics on 8787, assembly on 8788, native on 8789):

export BINARIES_DIR=/path/to/your/nativeaot/binaries
export ASSEMBLIES_DIR=/path/to/your/managed/assemblies
docker compose -f deploy/docker-compose.yml up -d

See docs/compose.md for the full guide: env vars, bearer-token setup, MCP client configuration, and how to attach to live processes.

Verifying releases

Every release artifact (NuGet package and self-contained binary archive) is published with a SLSA build provenance attestation generated by actions/attest-build-provenance and signed by Sigstore via GitHub's OIDC issuer. The attestation proves the artifact was built by this repository on a specific commit by GitHub-hosted runners — no separate cert to install, no key to rotate.

Verify with the GitHub CLI. The --signer-workflow and --source-ref flags bind verification to the exact release workflow file and tag, so an attestation produced by a different workflow in the same repository (e.g. a hypothetical CI workflow added in a PR) cannot pass these checks:

# NuGet package
gh attestation verify dotnet-native-mcp.0.5.4.nupkg \
  --repo pedrosakuma/dotnet-native-mcp \
  --signer-workflow pedrosakuma/dotnet-native-mcp/.github/workflows/release.yml \
  --source-ref refs/tags/v0.5.4

# Self-contained binary tarball / zip
gh attestation verify dotnet-native-mcp-0.5.4-linux-x64.tar.gz \
  --repo pedrosakuma/dotnet-native-mcp \
  --signer-workflow pedrosakuma/dotnet-native-mcp/.github/workflows/release.yml \
  --source-ref refs/tags/v0.5.4

For maximum strictness, also pin to the exact release commit with --source-digest <commit-sha> (look it up on the release page).

A passing verification confirms the build came from pedrosakuma/dotnet-native-mcp, on the expected tag, produced by .github/workflows/release.yml.

Disk cache

find_native_callers maintains a persistent on-disk xref index so large NativeAOT binaries are scanned only once across server restarts.

DetailValue
Location~/.cache/dotnet-native-mcp/<build-id>.xref (Linux: $XDG_CACHE_HOME/dotnet-native-mcp/ if set)
Cache keyELF build-id / PE CodeView GUID+Age / Mach-O LC_UUID, falling back to a SHA-256 prefix of the file bytes
Format4-byte magic NXR1 + 4-byte version + JSON body
InvalidationAutomatic on binary rebuild (new build-id → new file). On format upgrade the old file is silently ignored and rebuilt.
EvictionNone (files accumulate by build-id). Run rm -rf ~/.cache/dotnet-native-mcp/ to clear manually.
DisableSet DOTNET_NATIVE_MCP_XREF_CACHE=0 to bypass all disk I/O (useful in CI or read-only environments).

Authentication

HTTP transport supports optional bearer-token auth. Leave it unset for local/dev back-compat; set either NATIVE_MCP_BEARER_TOKEN or NativeMcp:BearerToken to require Authorization: Bearer <token> on every /mcp request. /health remains open. STDIO transport stays unauthenticated.

export NATIVE_MCP_BEARER_TOKEN="replace-me"
dotnet-native-mcp

Loopback-or-token invariant

The HTTP transport enforces a startup-time safety check: if any configured URL binds to a non-loopback address (anything other than 127.0.0.1, ::1, or localhost) and no bearer token is configured, the server refuses to start. This prevents accidentally exposing the MCP tool surface — which can open arbitrary files on the host — to anyone on the network.

To bind to a non-loopback address you must either:

  1. Set a bearer token (NATIVE_MCP_BEARER_TOKEN / NativeMcp:BearerToken / MCP_BEARER_TOKEN), or
  2. Explicitly opt out with NativeMcp:AllowUnauthenticatedNonLoopback=true — only safe when a trusted reverse proxy in front of the server enforces authentication.

The check inspects Urls, ASPNETCORE_URLS, HTTP_PORTS / HTTPS_PORTS (and the ASPNETCORE_* aliases), and Kestrel:Endpoints:*:Url configuration sources.

Trusted-path allowlist (untrusted path hints)

Filesystem paths arrive off the wire from an LLM and are treated as untrusted display hints, per the handoff contract. Every path passed to load_native_binary, import_native_manifest, disassemble (imagePath / ilMapPath) and the sidecar overrides (mstatPath / dgmlPath) is canonicalised — .. flattened and symlinks / junctions resolved to their true target — before any file is opened.

Enforcement is opt-in. Configure at least one trusted root to restrict opens to that subtree (anything outside is refused with path_not_allowed):

# any of these turns enforcement on
export NATIVE_MCP_ALLOWED_ROOTS="/binaries:/app/assemblies"   # PATH-separator list
export BINARIES_DIR=/binaries                                  # single root (Compose tier)
# or NativeMcp:AllowedBinaryRoots in appsettings.json / config

When enforcing, the NuGet global packages cache, the .NET shared framework, and the system temp directory are always allowed in addition to your roots so handed-off binaries and staged sidecars keep resolving. Until a root is configured the server stays permissive (paths are still canonicalised) and logs a one-time startup warning.

Resource limits

To bound memory use and adversarial inputs, the server applies the following caps:

LimitValueApplies to
MaxImageBytes512 MiBWhole-image reads (load_native_binary, raw disassembly paths)
MaxDgmlBytes64 MiBDGML sidecar file size
MaxIlMapBytes16 MiB.ilmap file size
MaxManifestEntries1024import_native_manifest entries per call
MaxStringMatches500,000Total matches collected by extract_strings
MaxExtractedStringChars16,384Characters materialized for any single extracted string value
MaxCallerSites100,000find_native_callers rows returned
MaxDgmlNodes1,000,000DGML nodes parsed from a sidecar
MaxDgmlEdges2,000,000DGML edges parsed from a sidecar
MaxIlMapEntries1,048,576.ilmap entries parsed from a sidecar
MaxPdbBytes64 MiBPDB files read for SourceLink resolution
MaxMapFileBytes256 MiB.map sidecar file size
MaxMapFileEntries5,000,000.map sidecar entries parsed
MaxMstatBytes256 MiB.mstat sidecar file size
MaxMstatAttributions5,000,000.mstat attributions parsed
MaxXrefCacheBytes256 MiBxref disk cache size accepted on read
MaxEmbeddedPdbCacheBytes32 MiBextracted-PDB disk cache size accepted on read

Error responses

Errors returned to MCP clients are sanitised: NativeError.Detail never carries Exception.ToString() stack traces, and absolute filesystem paths supplied by the caller are reduced to their file name. Full exception detail (including the original path and stack trace) is logged server-side via the SanitisedError.Sink hook (defaulting to System.Diagnostics.Trace) so operators can still investigate parse failures.

Building blocks

  • Iced — MIT, .NET-native x86/x64 disassembler.
  • System.Reflection.PortableExecutable — for PE headers and section reads.
  • System.IO.Pipelines — for streaming reads of large native binaries.
  • A small ELF reader (Linux NativeAOT binaries are ELF).
  • (V1) Capstone P/Invoke for ARM64 disassembly.

License

MIT.

Ver o original no GitHub

Relacionados