Prepare 0.1.1 release

KSemenenko · KSemenenko · commit 8d748087b111 · 2026-03-06T16:41:01.000+01:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -190,6 +190,7 @@ If no new rule is detected -> do not update the file.
 - Reusable library design over app-specific glue
 - Search + execute flows covered by automated tests
 - Clean root packaging and CI setup
+- Direct fixes over preserving legacy compatibility paths when cleanup or review-driven corrections are requested
 
 ### Dislikes
 
diff --git a/Directory.Build.props b/Directory.Build.props
@@ -11,7 +11,7 @@
     <AnalysisLevel>latest-recommended</AnalysisLevel>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     <NoWarn>$(NoWarn);CS1591;CA1707;CA1848;CA1859;CA1873</NoWarn>
-    <Version>0.1.0</Version>
+    <Version>0.1.1</Version>
     <PackageVersion>$(Version)</PackageVersion>
   </PropertyGroup>
 
diff --git a/README.md b/README.md
@@ -238,7 +238,7 @@ During `BuildIndexAsync()` the gateway:
 - generates embeddings only for tools that are missing in the store
 - upserts the newly generated vectors back into the store
 
-This avoids recalculating tool embeddings on every rebuild while still refreshing them automatically when the descriptor document changes. Query embeddings are still generated at search time from the registered `IEmbeddingGenerator<string, Embedding<float>>`.
+This avoids recalculating tool embeddings on every rebuild while still refreshing them automatically when the descriptor document changes. Stored vectors are scoped to both the descriptor hash and the resolved embedding-generator fingerprint, so changing the provider or model automatically forces regeneration. Query embeddings are still generated at search time from the registered `IEmbeddingGenerator<string, Embedding<float>>`.
 
 ## Supported Sources
 
diff --git a/src/ManagedCode.MCPGateway/McpGateway.cs b/src/ManagedCode.MCPGateway/McpGateway.cs
@@ -44,7 +44,7 @@ public sealed class McpGateway(
     private const string SourceLoadFailedMessageTemplate = "Failed to load tools from source '{0}': {1}";
     private const string DuplicateToolIdMessageTemplate = "Skipped duplicate tool id '{0}'.";
     private const string EmbeddingCountMismatchMessageTemplate = "Embedding generation returned {0} vectors for {1} tools.";
-    private const string EmbeddingGeneratorMissingMessage = "No keyed or unkeyed IEmbeddingGenerator<string, Embedding<float>> is registered. Lexical fallback only.";
+    private const string EmbeddingGeneratorMissingMessage = "No keyed or unkeyed IEmbeddingGenerator<string, Embedding<float>> is registered. Stored tool embeddings may be reused, but search falls back lexically without a query embedding generator.";
     private const string EmbeddingFailedMessageTemplate = "Embedding generation failed: {0}";
     private const string EmbeddingStoreLoadFailedMessageTemplate = "Loading stored tool embeddings failed: {0}";
     private const string EmbeddingStoreSaveFailedMessageTemplate = "Persisting generated tool embeddings failed: {0}";
@@ -80,6 +80,8 @@ public sealed class McpGateway(
     private const string ContextPrefix = "context: ";
     private const string PluralSuffixIes = "ies";
     private const string PluralSuffixEs = "es";
+    private const string EmbeddingGeneratorFingerprintUnknownComponent = "unknown";
+    private const string EmbeddingGeneratorFingerprintComponentSeparator = "\n";
 
     private static readonly char[] TokenSeparators =
     [
@@ -285,16 +287,21 @@ public async Task<McpGatewayIndexBuildResult> BuildIndexAsync(CancellationToken
             }
 
             var vectorizedToolCount = 0;
+            var isVectorSearchEnabled = false;
             if (entries.Count > 0)
             {
                 await using var embeddingGeneratorLease = ResolveEmbeddingGenerator();
                 await using var embeddingStoreLease = ResolveToolEmbeddingStore();
                 var embeddingGenerator = embeddingGeneratorLease.Generator;
+                var embeddingGeneratorFingerprint = ResolveEmbeddingGeneratorFingerprint(embeddingGenerator);
                 var embeddingStore = embeddingStoreLease.Store;
                 var storeCandidates = entries
                     .Select((entry, index) => new ToolEmbeddingCandidate(
                         index,
-                        new McpGatewayToolEmbeddingLookup(entry.Descriptor.ToolId, ComputeDocumentHash(entry.Document)),
+                        new McpGatewayToolEmbeddingLookup(
+                            entry.Descriptor.ToolId,
+                            ComputeDocumentHash(entry.Document),
+                            embeddingGeneratorFingerprint),
                         entry.Descriptor.SourceId,
                         entry.Descriptor.ToolName))
                     .ToList();
@@ -306,13 +313,12 @@ public async Task<McpGatewayIndexBuildResult> BuildIndexAsync(CancellationToken
                         var storedEmbeddings = await embeddingStore.GetAsync(
                             storeCandidates.Select(static candidate => candidate.Lookup).ToList(),
                             cancellationToken);
-                        var storedEmbeddingsByLookup = storedEmbeddings
-                            .GroupBy(static embedding => new McpGatewayToolEmbeddingLookup(embedding.ToolId, embedding.DocumentHash))
-                            .ToDictionary(static group => group.Key, static group => group.Last());
 
                         foreach (var candidate in storeCandidates)
                         {
-                            if (storedEmbeddingsByLookup.TryGetValue(candidate.Lookup, out var storedEmbedding))
+                            var storedEmbedding = storedEmbeddings.LastOrDefault(embedding =>
+                                MatchesStoredEmbedding(candidate.Lookup, embedding));
+                            if (storedEmbedding is not null)
                             {
                                 ApplyEmbedding(entries, candidate.Index, storedEmbedding.Vector, ref vectorizedToolCount);
                             }
@@ -331,6 +337,13 @@ public async Task<McpGatewayIndexBuildResult> BuildIndexAsync(CancellationToken
                     .Where(candidate => entries[candidate.Index].Magnitude <= double.Epsilon)
                     .ToList();
 
+                if (embeddingGenerator is null && vectorizedToolCount > 0)
+                {
+                    diagnostics.Add(new McpGatewayDiagnostic(
+                        EmbeddingGeneratorMissingDiagnosticCode,
+                        EmbeddingGeneratorMissingMessage));
+                }
+
                 if (missingCandidates.Count > 0)
                 {
                     try
@@ -355,6 +368,7 @@ public async Task<McpGatewayIndexBuildResult> BuildIndexAsync(CancellationToken
                                             candidate.SourceId,
                                             candidate.ToolName,
                                             candidate.Lookup.DocumentHash,
+                                            candidate.Lookup.EmbeddingGeneratorFingerprint,
                                             vector));
                                     }
                                 }
@@ -400,14 +414,16 @@ public async Task<McpGatewayIndexBuildResult> BuildIndexAsync(CancellationToken
                         _logger.LogWarning(ex, EmbeddingGenerationFailedLogMessage);
                     }
                 }
+
+                isVectorSearchEnabled = vectorizedToolCount > 0 && embeddingGenerator is not null;
             }
 
             var snapshot = new ToolCatalogSnapshot(
                 entries
                     .OrderBy(static item => item.Descriptor.ToolName, StringComparer.OrdinalIgnoreCase)
                     .ThenBy(static item => item.Descriptor.SourceId, StringComparer.OrdinalIgnoreCase)
                     .ToList(),
-                vectorizedToolCount > 0);
+                isVectorSearchEnabled);
 
             lock (_gate)
             {
@@ -1002,6 +1018,37 @@ private static bool ApplyEmbedding(
     private static string ComputeDocumentHash(string value)
         => Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(value)));
 
+    private static bool MatchesStoredEmbedding(
+        McpGatewayToolEmbeddingLookup lookup,
+        McpGatewayToolEmbedding embedding)
+        => string.Equals(embedding.ToolId, lookup.ToolId, StringComparison.OrdinalIgnoreCase)
+            && string.Equals(embedding.DocumentHash, lookup.DocumentHash, StringComparison.Ordinal)
+            && (lookup.EmbeddingGeneratorFingerprint is null
+                || string.Equals(
+                    embedding.EmbeddingGeneratorFingerprint,
+                    lookup.EmbeddingGeneratorFingerprint,
+                    StringComparison.Ordinal));
+
+    private static string? ResolveEmbeddingGeneratorFingerprint(
+        IEmbeddingGenerator<string, Embedding<float>>? embeddingGenerator)
+    {
+        if (embeddingGenerator is null)
+        {
+            return null;
+        }
+
+        var metadata = embeddingGenerator.GetService(typeof(EmbeddingGeneratorMetadata)) as EmbeddingGeneratorMetadata;
+        var generatorTypeName = embeddingGenerator.GetType().FullName ?? embeddingGenerator.GetType().Name;
+
+        return ComputeDocumentHash(string.Join(
+            EmbeddingGeneratorFingerprintComponentSeparator,
+            metadata?.ProviderName ?? EmbeddingGeneratorFingerprintUnknownComponent,
+            metadata?.ProviderUri?.AbsoluteUri ?? EmbeddingGeneratorFingerprintUnknownComponent,
+            metadata?.DefaultModelId ?? EmbeddingGeneratorFingerprintUnknownComponent,
+            metadata?.DefaultModelDimensions?.ToString(CultureInfo.InvariantCulture) ?? EmbeddingGeneratorFingerprintUnknownComponent,
+            generatorTypeName ?? EmbeddingGeneratorFingerprintUnknownComponent));
+    }
+
     private static string BuildEffectiveSearchQuery(McpGatewaySearchRequest request)
     {
         List<string> parts = [];
diff --git a/src/ManagedCode.MCPGateway/McpGatewayInMemoryToolEmbeddingStore.cs b/src/ManagedCode.MCPGateway/McpGatewayInMemoryToolEmbeddingStore.cs
@@ -5,18 +5,22 @@ namespace ManagedCode.MCPGateway;
 
 public sealed class McpGatewayInMemoryToolEmbeddingStore : IMcpGatewayToolEmbeddingStore
 {
-    private readonly ConcurrentDictionary<McpGatewayToolEmbeddingLookup, McpGatewayToolEmbedding> _embeddings = new();
+    private readonly ConcurrentDictionary<StoreKey, McpGatewayToolEmbedding> _embeddings = new();
 
     public Task<IReadOnlyList<McpGatewayToolEmbedding>> GetAsync(
         IReadOnlyList<McpGatewayToolEmbeddingLookup> lookups,
         CancellationToken cancellationToken = default)
     {
         cancellationToken.ThrowIfCancellationRequested();
 
-        var results = lookups
-            .Where(_embeddings.ContainsKey)
-            .Select(lookup => Clone(_embeddings[lookup]))
-            .ToList();
+        var results = new List<McpGatewayToolEmbedding>(lookups.Count);
+        foreach (var lookup in lookups)
+        {
+            if (TryGetEmbedding(lookup, out var embedding))
+            {
+                results.Add(Clone(embedding));
+            }
+        }
 
         return Task.FromResult<IReadOnlyList<McpGatewayToolEmbedding>>(results);
     }
@@ -30,15 +34,67 @@ public Task UpsertAsync(
         foreach (var embedding in embeddings)
         {
             var clone = Clone(embedding);
-            _embeddings[new McpGatewayToolEmbeddingLookup(clone.ToolId, clone.DocumentHash)] = clone;
+            _embeddings[StoreKey.FromEmbedding(clone)] = clone;
         }
 
         return Task.CompletedTask;
     }
 
+    private bool TryGetEmbedding(
+        McpGatewayToolEmbeddingLookup lookup,
+        out McpGatewayToolEmbedding embedding)
+    {
+        var storeKey = StoreKey.FromLookup(lookup);
+        if (lookup.EmbeddingGeneratorFingerprint is not null)
+        {
+            return _embeddings.TryGetValue(storeKey, out embedding!);
+        }
+
+        foreach (var pair in _embeddings)
+        {
+            if (pair.Key.Matches(storeKey))
+            {
+                embedding = pair.Value;
+                return true;
+            }
+        }
+
+        embedding = default!;
+        return false;
+    }
+
     private static McpGatewayToolEmbedding Clone(McpGatewayToolEmbedding embedding)
         => embedding with
         {
             Vector = [.. embedding.Vector]
         };
+
+    private static string NormalizeToolId(string toolId) => toolId.ToUpperInvariant();
+
+    private readonly record struct StoreKey(
+        string NormalizedToolId,
+        string DocumentHash,
+        string? EmbeddingGeneratorFingerprint)
+    {
+        public static StoreKey FromLookup(McpGatewayToolEmbeddingLookup lookup)
+            => new(
+                NormalizeToolId(lookup.ToolId),
+                lookup.DocumentHash,
+                lookup.EmbeddingGeneratorFingerprint);
+
+        public static StoreKey FromEmbedding(McpGatewayToolEmbedding embedding)
+            => new(
+                NormalizeToolId(embedding.ToolId),
+                embedding.DocumentHash,
+                embedding.EmbeddingGeneratorFingerprint);
+
+        public bool Matches(StoreKey other)
+            => string.Equals(NormalizedToolId, other.NormalizedToolId, StringComparison.Ordinal)
+                && string.Equals(DocumentHash, other.DocumentHash, StringComparison.Ordinal)
+                && (other.EmbeddingGeneratorFingerprint is null
+                    || string.Equals(
+                        EmbeddingGeneratorFingerprint,
+                        other.EmbeddingGeneratorFingerprint,
+                        StringComparison.Ordinal));
+    }
 }
diff --git a/src/ManagedCode.MCPGateway/Models/McpGatewayToolEmbedding.cs b/src/ManagedCode.MCPGateway/Models/McpGatewayToolEmbedding.cs
@@ -5,4 +5,5 @@ public sealed record McpGatewayToolEmbedding(
     string SourceId,
     string ToolName,
     string DocumentHash,
+    string? EmbeddingGeneratorFingerprint,
     float[] Vector);
diff --git a/src/ManagedCode.MCPGateway/Models/McpGatewayToolEmbeddingLookup.cs b/src/ManagedCode.MCPGateway/Models/McpGatewayToolEmbeddingLookup.cs
@@ -2,4 +2,5 @@ namespace ManagedCode.MCPGateway;
 
 public sealed record McpGatewayToolEmbeddingLookup(
     string ToolId,
-    string DocumentHash);
+    string DocumentHash,
+    string? EmbeddingGeneratorFingerprint = null);
diff --git a/tests/ManagedCode.MCPGateway.Tests/Search/McpGatewayInMemoryToolEmbeddingStoreTests.cs b/tests/ManagedCode.MCPGateway.Tests/Search/McpGatewayInMemoryToolEmbeddingStoreTests.cs
@@ -13,20 +13,22 @@ await store.UpsertAsync(
                 "local",
                 "github_search_issues",
                 "hash-1",
+                "fingerprint-a",
                 [1f, 2f, 3f]),
             new McpGatewayToolEmbedding(
                 "local:weather_search_forecast",
                 "local",
                 "weather_search_forecast",
                 "hash-2",
+                "fingerprint-a",
                 [4f, 5f, 6f])
         ]);
 
         var result = await store.GetAsync(
         [
-            new McpGatewayToolEmbeddingLookup("local:weather_search_forecast", "hash-2"),
-            new McpGatewayToolEmbeddingLookup("local:missing", "hash-3"),
-            new McpGatewayToolEmbeddingLookup("local:github_search_issues", "hash-1")
+            new McpGatewayToolEmbeddingLookup("local:weather_search_forecast", "hash-2", "fingerprint-a"),
+            new McpGatewayToolEmbeddingLookup("local:missing", "hash-3", "fingerprint-a"),
+            new McpGatewayToolEmbeddingLookup("local:github_search_issues", "hash-1", "fingerprint-a")
         ]);
 
         await Assert.That(result.Count).IsEqualTo(2);
@@ -47,24 +49,54 @@ await store.UpsertAsync(
                 "local",
                 "github_search_issues",
                 "hash-1",
+                "fingerprint-a",
                 inputVector)
         ]);
 
         inputVector[0] = 99f;
 
         var firstRead = await store.GetAsync(
         [
-            new McpGatewayToolEmbeddingLookup("local:github_search_issues", "hash-1")
+            new McpGatewayToolEmbeddingLookup("local:github_search_issues", "hash-1", "fingerprint-a")
         ]);
         firstRead[0].Vector[1] = 77f;
 
         var secondRead = await store.GetAsync(
         [
-            new McpGatewayToolEmbeddingLookup("local:github_search_issues", "hash-1")
+            new McpGatewayToolEmbeddingLookup("local:github_search_issues", "hash-1", "fingerprint-a")
         ]);
 
         await Assert.That(secondRead[0].Vector[0]).IsEqualTo(1f);
         await Assert.That(secondRead[0].Vector[1]).IsEqualTo(2f);
         await Assert.That(secondRead[0].Vector[2]).IsEqualTo(3f);
     }
+
+    [TUnit.Core.Test]
+    public async Task GetAsync_TreatsToolIdsCaseInsensitivelyAndSupportsFingerprintFallback()
+    {
+        var store = new McpGatewayInMemoryToolEmbeddingStore();
+        await store.UpsertAsync(
+        [
+            new McpGatewayToolEmbedding(
+                "local:github_search_issues",
+                "local",
+                "github_search_issues",
+                "hash-1",
+                "fingerprint-a",
+                [1f, 2f, 3f])
+        ]);
+
+        var fingerprintMatch = await store.GetAsync(
+        [
+            new McpGatewayToolEmbeddingLookup("LOCAL:GITHUB_SEARCH_ISSUES", "hash-1", "fingerprint-a")
+        ]);
+        var fingerprintAgnosticMatch = await store.GetAsync(
+        [
+            new McpGatewayToolEmbeddingLookup("LOCAL:GITHUB_SEARCH_ISSUES", "hash-1")
+        ]);
+
+        await Assert.That(fingerprintMatch.Count).IsEqualTo(1);
+        await Assert.That(fingerprintAgnosticMatch.Count).IsEqualTo(1);
+        await Assert.That(fingerprintAgnosticMatch[0].ToolId).IsEqualTo("local:github_search_issues");
+    }
 }
diff --git a/tests/ManagedCode.MCPGateway.Tests/Search/McpGatewaySearchTests.cs b/tests/ManagedCode.MCPGateway.Tests/Search/McpGatewaySearchTests.cs
diff --git a/tests/ManagedCode.MCPGateway.Tests/TestSupport/TestEmbeddingGenerator.cs b/tests/ManagedCode.MCPGateway.Tests/TestSupport/TestEmbeddingGenerator.cs
diff --git a/tests/ManagedCode.MCPGateway.Tests/TestSupport/TestToolEmbeddingStore.cs b/tests/ManagedCode.MCPGateway.Tests/TestSupport/TestToolEmbeddingStore.cs
