Prepare DecompilerServer 1.3.5

Author: pardeike

.github/copilot-instructions.md

@@ -14,7 +14,8 @@ Read these files first:
 - Reuse `TypeSurfaceComparer` for type-surface semantics instead of duplicating compare logic.
 - Use `DecompilerService.DecompileEntitySnippet(...)` for focused compare body retrieval.
 - Prefer structured JSON output over pre-rendered diff text for overview commands.
-- For unknown foreign code, start with `search_symbols`, then `list_members`/`get_members_of_type`, then source or caller/callee tools. Do not fall back to shell scans after one bad member guess unless MCP diagnostics are exhausted.
+- For unknown foreign code, start with `search_symbols` for fragments. For fully-qualified or XML-doc-like guessed symbols, start with `resolve_member_id` so structured `member_not_found` diagnostics can resolve the type and suggest candidates.
+- After a type resolves, use `list_members`/`get_members_of_type`, then source or caller/callee tools. Do not fall back to shell scans after one bad member guess unless MCP diagnostics are exhausted.
 
 ## Workspace and Compare Expectations
 

ARCHITECTURE.md

@@ -105,6 +105,8 @@ These services provide graph-style analysis:
 - implementations;
 - overrides and overloads.
 
+`find_callees` is callee-shaped, not usage-shaped. Items should identify the target through `targetMemberId` when the operand resolves to a local assembly member, and through `symbol`, `declaringType`, `opcode`, `offset`, `operandTokenHex`, and `resolution` for local, external, or unresolved metadata operands. Legacy `inMember`/`inType` aliases may remain for compatibility, but new clients should prefer the target-specific fields.
+
 ### TypeSurfaceComparer
 
 `TypeSurfaceComparer` defines the shared semantics for structural type diffs.
@@ -161,7 +163,8 @@ Operational rules:
 - `select_context` changes the default alias;
 - `unload` can unload one alias or all aliases, and removes persisted registrations by default;
 - `unload(..., preserveRegistration: true)` keeps restart-restore registrations while unloading memory;
-- `status` reports current alias plus loaded contexts when the workspace is active.
+- `status` reports current alias plus loaded contexts when the workspace is active;
+- `get_server_stats(contextAlias)` reports detailed cache, index, and performance diagnostics for one alias or the current alias.
 
 Startup behavior:
 - `WorkspaceBootstrapService` restores persisted registrations;
@@ -187,24 +190,28 @@ Search-style and overview-style endpoints should use:
 
 `compare_contexts` uses integer-offset cursors today.
 
+`get_il` supports the same `limit`/`cursor` paging pattern for instruction lists and also accepts `startOffset`/`endOffset` windows when callers need a byte-offset slice around a suspected anchor.
+
 ### Member-ID Follow-Up Flow
 
 Once a discovery tool returns a `memberId`, the caller should be able to use follow-up tools without resupplying the alias. That behavior depends on the MVID prefix and must remain reliable.
 
 ### Symbol Exploration Flow
 
 Unknown-assembly exploration should stay inside MCP tools:
-- use `search_symbols` when the caller has a partial, qualified, or guessed name;
+- use `search_symbols` when the caller has a fragment or is unsure whether a name is a type or member;
+- use `resolve_member_id` first for fully-qualified or XML-doc-like guessed symbols such as `Namespace.Type.Member` or `M:Namespace.Type.Member`;
 - use `search_types` for type-only discovery and `search_members` for member-only discovery;
 - use `list_members` or `get_members_of_type` after a type is found;
 - if a member-based tool receives a stale or human-entered symbol, return structured candidates and suggested next tool calls rather than only `Invalid member ID`.
+- if `search_symbols` receives `Type.MissingMember` and the type resolves, return a diagnostic plus the type and direct members instead of an empty success.
 
 ### MCP Server Instructions
 
 `Program.ServerInstructions` is intentionally short and workflow-oriented.
 
 It should:
-- steer clients toward `search_symbols`, `list_members`, structured errors, and common parameter names;
+- steer clients toward `search_symbols`, `resolve_member_id`, `list_members`, structured errors, and common parameter names;
 - complement the tool schemas rather than duplicate the full README or tool reference;
 - stay concise enough to be useful in the MCP handshake.
 

DecompilerServer.csproj

@@ -5,7 +5,7 @@
     <TargetFramework>net10.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <Version>1.3.4</Version>
+    <Version>1.3.5</Version>
   </PropertyGroup>
 
   <ItemGroup>

Program.cs

@@ -9,9 +9,10 @@ namespace DecompilerServer;
 public partial class Program
 {
     internal const string ServerInstructions = """
-        DecompilerServer inspects loaded .NET assemblies. Use search_symbols first when you have a partial, qualified, or guessed name.
+        DecompilerServer inspects loaded .NET assemblies. Use search_symbols first for fragments; use resolve_member_id first for fully-qualified or XML-doc-like guessed symbols.
         Common parameter names: search_types/search_members use query, not pattern; resolve_member_id/get_decompiled_source/find_usages use memberId; find_callers/find_callees/get_overrides use methodId; get_types_in_namespace uses ns.
         After resolving a type, use list_members or get_members_of_type before guessing method names. If a lookup fails, inspect structured error.details, candidates, and hints before retrying.
+        Use status/list_contexts to confirm loaded aliases; use get_server_stats for detailed cache/index diagnostics.
         """;
 
     internal static void ConfigureMcpServerOptions(McpServerOptions options)

README.md

@@ -237,6 +237,7 @@ load_assembly({
 ```text
 list_contexts({})
 status({})
+get_server_stats({ "contextAlias": "rw16" })
 ```
 
 **Search and decompile:**
@@ -269,12 +270,13 @@ Once you have a `memberId`, follow-up tools normally route to the correct loaded
 For foreign-code exploration, prefer this path before falling back to shell tools:
 
 1. Load the assembly with `load_assembly` and verify the active alias with `list_contexts` or `status`.
-2. Start broad with `search_symbols` when you have a partial or guessed name; use `search_types` only when you specifically want types.
+2. Start broad with `search_symbols` when you have a fragment; use `resolve_member_id` first when you have a fully-qualified or XML-doc-like guess such as `Namespace.Type.Member` or `M:Namespace.Type.Member`.
 3. Use `list_members` or `get_members_of_type` on the resolved type before guessing method IDs.
 4. Fetch code with `get_decompiled_source`, `get_source_slice`, or `plan_chunking`.
-5. Move outward with `find_callers`, `find_usages`, `find_callees`, `get_il`, or compare tools.
+5. Move outward with `find_callers`, `find_usages`, `find_callees`, `get_il`, or compare tools. `find_callees` returns callee-focused `targetMemberId`, `symbol`, `opcode`, `offset`, and `resolution` fields; external calls are explicit instead of pretending to be canonical local IDs.
+6. Use `get_server_stats` when you need cache/index/performance diagnostics for one alias; `status` is the cheaper current-alias overview.
 
-If a guessed member does not exist, member-based tools return structured error hints with likely candidates and concrete next tool calls. For example, a stale method guess can still resolve the type and point you at nearby overrides instead of forcing a `grep` or `monodis` fallback.
+If a guessed member does not exist, member-based tools return structured error hints with likely candidates and concrete next tool calls. `search_symbols` also degrades gracefully for `Type.MissingMember`: if the type resolves but the member does not, it returns the type, its direct members, and a diagnostic instead of an empty success.
 
 **Compare aliases:**
 
@@ -319,11 +321,11 @@ The repo includes a portable skill at [skills/decompiler-mcp/SKILL.md](skills/de
 
 The GitHub `Release` workflow is triggered by pushing a tag that starts with `v` and matches the project version in `DecompilerServer.csproj`.
 
-For example, if the project version is `1.3.4`:
+For example, if the project version is `1.3.5`:
 
 ```bash
-git tag -a v1.3.4 -m "Release v1.3.4"
-git push origin v1.3.4
+git tag -a v1.3.5 -m "Release v1.3.5"
+git push origin v1.3.5
 ```
 
 ### Documentation

Services/AssemblyContextManager.cs

@@ -21,6 +21,7 @@ public class AssemblyContextManager : IDisposable
     private PEFile? _peFile;
     private ICompilation? _compilation;
     private CSharpDecompiler? _decompiler;
+    private DecompilerSettings? _settings;
     private UniversalAssemblyResolver? _resolver;
     private bool _disposed;
     private long _contextVersion;
@@ -99,12 +100,8 @@ public void LoadAssemblyDirect(string assemblyPath, string[]? additionalSearchDi
             _compilation = new DecompilerTypeSystem(_peFile, _resolver);
 
             // Create decompiler with enhanced settings
-            var settings = new DecompilerSettings
-            {
-                UsingDeclarations = true,
-                ShowXmlDocumentation = true,
-                NamedArguments = true
-            };
+            var settings = CreateDefaultDecompilerSettings();
+            _settings = CloneSettings(settings);
             _decompiler = new CSharpDecompiler(_peFile, _resolver, settings);
 
             // Extract MVID
@@ -162,12 +159,8 @@ public void LoadAssembly(string gameDir, string assemblyFile = "Assembly-CSharp.
             _compilation = new DecompilerTypeSystem(_peFile, _resolver);
 
             // Create decompiler with enhanced settings
-            var settings = new DecompilerSettings
-            {
-                UsingDeclarations = true,
-                ShowXmlDocumentation = true,
-                NamedArguments = true
-            };
+            var settings = CreateDefaultDecompilerSettings();
+            _settings = CloneSettings(settings);
             _decompiler = new CSharpDecompiler(_peFile, _resolver, settings);
 
             // Extract MVID
@@ -200,6 +193,23 @@ public CSharpDecompiler GetDecompiler()
         }
     }
 
+    /// <summary>
+    /// Get a snapshot of the current decompiler settings.
+    /// </summary>
+    public DecompilerSettings GetSettings()
+    {
+        _lock.EnterReadLock();
+        try
+        {
+            EnsureLoaded();
+            return CloneSettings(_settings!);
+        }
+        finally
+        {
+            _lock.ExitReadLock();
+        }
+    }
+
     /// <summary>
     /// Get the current compilation/type system
     /// </summary>
@@ -316,7 +326,9 @@ public void UpdateSettings(DecompilerSettings settings)
         try
         {
             if (!IsLoaded) return;
-            _decompiler = new CSharpDecompiler(_peFile!, _resolver!, settings);
+            var settingsSnapshot = CloneSettings(settings);
+            _settings = CloneSettings(settingsSnapshot);
+            _decompiler = new CSharpDecompiler(_peFile!, _resolver!, settingsSnapshot);
             Interlocked.Increment(ref _contextVersion);
         }
         finally
@@ -512,10 +524,39 @@ private static PEFile CreatePEFile(string assemblyPath)
         return new PEFile(assemblyPath, AssemblyLoadOptions, MetadataReaderOptions.Default);
     }
 
+    private static DecompilerSettings CreateDefaultDecompilerSettings()
+    {
+        return new DecompilerSettings
+        {
+            UsingDeclarations = true,
+            ShowXmlDocumentation = true,
+            NamedArguments = true,
+            MakeAssignmentExpressions = true,
+            AlwaysUseBraces = true,
+            RemoveDeadCode = true,
+            IntroduceIncrementAndDecrement = true
+        };
+    }
+
+    private static DecompilerSettings CloneSettings(DecompilerSettings settings)
+    {
+        return new DecompilerSettings
+        {
+            UsingDeclarations = settings.UsingDeclarations,
+            ShowXmlDocumentation = settings.ShowXmlDocumentation,
+            NamedArguments = settings.NamedArguments,
+            MakeAssignmentExpressions = settings.MakeAssignmentExpressions,
+            AlwaysUseBraces = settings.AlwaysUseBraces,
+            RemoveDeadCode = settings.RemoveDeadCode,
+            IntroduceIncrementAndDecrement = settings.IntroduceIncrementAndDecrement
+        };
+    }
+
     private void DisposeContext()
     {
         Interlocked.Increment(ref _contextVersion);
         _decompiler = null;
+        _settings = null;
         _compilation = null;
         _peFile?.Dispose();
         _peFile = null;

Services/DecompilerWorkspace.cs

@@ -46,7 +46,7 @@ public WorkspaceContextInfo LoadAssembly(WorkspaceLoadRequest request)
             }
 
             _sessionsByAlias[contextAlias] = session;
-            _aliasByMvid[session.ContextManager.Mvid!] = contextAlias;
+            AddSessionMappings(session);
 
             if (request.MakeCurrent || CurrentContextAlias == null)
             {
@@ -419,12 +419,44 @@ private static string GetDefaultRegistryPath()
     private void RemoveSessionMappings(DecompilerSession session)
     {
         _sessionsByAlias.Remove(session.ContextAlias);
-        if (session.ContextManager.Mvid != null)
-            _aliasByMvid.Remove(session.ContextManager.Mvid);
+
+        var mvid = session.ContextManager.Mvid;
+        if (mvid != null &&
+            _aliasByMvid.TryGetValue(mvid, out var mappedAlias) &&
+            string.Equals(mappedAlias, session.ContextAlias, StringComparison.OrdinalIgnoreCase))
+        {
+            _aliasByMvid.Remove(mvid);
+
+            var replacement = FindReplacementSessionForMvid(mvid);
+            if (replacement != null)
+                _aliasByMvid[mvid] = replacement.ContextAlias;
+        }
 
         if (string.Equals(CurrentContextAlias, session.ContextAlias, StringComparison.OrdinalIgnoreCase))
             CurrentContextAlias = null;
     }
+
+    private void AddSessionMappings(DecompilerSession session)
+    {
+        var mvid = session.ContextManager.Mvid;
+        if (mvid != null && !_aliasByMvid.ContainsKey(mvid))
+            _aliasByMvid[mvid] = session.ContextAlias;
+    }
+
+    private DecompilerSession? FindReplacementSessionForMvid(string mvid)
+    {
+        if (CurrentContextAlias != null &&
+            _sessionsByAlias.TryGetValue(CurrentContextAlias, out var currentSession) &&
+            string.Equals(currentSession.ContextManager.Mvid, mvid, StringComparison.OrdinalIgnoreCase))
+        {
+            return currentSession;
+        }
+
+        return _sessionsByAlias.Values
+            .Where(candidate => string.Equals(candidate.ContextManager.Mvid, mvid, StringComparison.OrdinalIgnoreCase))
+            .OrderBy(candidate => candidate.ContextAlias, StringComparer.OrdinalIgnoreCase)
+            .FirstOrDefault();
+    }
 }
 
 public sealed class DecompilerSession : IDisposable
@@ -481,14 +513,23 @@ public WorkspaceContextInfo ToContextInfo(bool isCurrent)
             ContextAlias = ContextAlias,
             Mvid = ContextManager.Mvid!,
             AssemblyPath = ContextManager.AssemblyPath!,
-            LoadedAtUnix = ContextManager.LoadedAtUtc?.Ticks,
+            LoadedAtUnix = ToUnixTimeSeconds(ContextManager.LoadedAtUtc),
             TypeCount = ContextManager.TypeCount,
             MethodCount = ContextManager.GetAllTypes().Sum(type => type.Methods.Count()),
             NamespaceCount = ContextManager.NamespaceCount,
             IsCurrent = isCurrent
         };
     }
 
+    private static long? ToUnixTimeSeconds(DateTime? utc)
+    {
+        if (!utc.HasValue)
+            return null;
+
+        var value = DateTime.SpecifyKind(utc.Value, DateTimeKind.Utc);
+        return new DateTimeOffset(value).ToUnixTimeSeconds();
+    }
+
     public void Dispose()
     {
         if (_disposed)

Services/IlAnalysisService.cs

@@ -74,6 +74,7 @@ public static IEnumerable<IlInstructionInfo> ReadInstructions(byte[] il, Metadat
 
             object? operand = null;
             int? operandToken = null;
+            string? operandTokenHex = null;
             string? operandKind = null;
             string? operandSummary = null;
 
@@ -101,11 +102,13 @@ public static IEnumerable<IlInstructionInfo> ReadInstructions(byte[] il, Metadat
                     position += 4;
                     operand = token;
                     operandToken = token;
+                    operandTokenHex = $"0x{token:X8}";
                     operandKind = opCode.OperandType.ToString();
                     operandSummary = FormatMetadataToken(metadata, token);
                     break;
                 case OperandType.InlineSig:
                     operandToken = BitConverter.ToInt32(il, position);
+                    operandTokenHex = $"0x{operandToken.Value:X8}";
                     position += 4;
                     operand = operandToken;
                     operandKind = "signature";
@@ -116,6 +119,7 @@ public static IEnumerable<IlInstructionInfo> ReadInstructions(byte[] il, Metadat
                     position += 4;
                     operand = stringToken;
                     operandToken = stringToken;
+                    operandTokenHex = $"0x{stringToken:X8}";
                     operandKind = "string";
                     operandSummary = Quote(metadata.GetUserString(MetadataTokens.UserStringHandle(stringToken)));
                     break;
@@ -185,6 +189,7 @@ public static IEnumerable<IlInstructionInfo> ReadInstructions(byte[] il, Metadat
                 OpCode: opCode.Name ?? opCode.ToString() ?? "unknown",
                 Operand: operand,
                 OperandToken: operandToken,
+                OperandTokenHex: operandTokenHex,
                 OperandKind: operandKind,
                 OperandSummary: operandSummary);
         }
@@ -300,5 +305,6 @@ public sealed record IlInstructionInfo(
     string OpCode,
     object? Operand,
     int? OperandToken,
+    string? OperandTokenHex,
     string? OperandKind,
     string? OperandSummary);