more fixes for names

Author: KSemenenko

Directory.Build.props

@@ -11,7 +11,7 @@
     <AnalysisLevel>latest-recommended</AnalysisLevel>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     <NoWarn>$(NoWarn);CS1591;CA1707;CA1848;CA1859;CA1873</NoWarn>
-    <Version>0.4.3</Version>
+    <Version>0.4.4</Version>
     <PackageVersion>$(Version)</PackageVersion>
   </PropertyGroup>
 

Directory.Packages.props

@@ -6,7 +6,7 @@
     <PackageVersion Include="BenchmarkDotNet" Version="0.15.8" />
     <PackageVersion Include="DotNet.ReproducibleBuilds" Version="2.0.2" />
     <PackageVersion Include="ManagedCode.MarkdownLd.Kb" Version="0.2.5" />
-    <PackageVersion Include="Microsoft.Agents.AI" Version="1.7.0" />
+    <PackageVersion Include="Microsoft.Agents.AI" Version="1.8.0" />
     <PackageVersion Include="Microsoft.Extensions.AI" Version="10.6.0" />
     <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.8" />
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.8" />
@@ -20,6 +20,6 @@
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="10.0.300" />
     <PackageVersion Include="ModelContextProtocol" Version="1.3.0" />
     <PackageVersion Include="ModelContextProtocol.AspNetCore" Version="1.3.0" />
-    <PackageVersion Include="TUnit" Version="1.45.29" />
+    <PackageVersion Include="TUnit" Version="1.48.6" />
   </ItemGroup>
 </Project>

README.md

@@ -330,7 +330,7 @@ services.AddMcpServer()
 - task-backed tool execution through MCP `tools/call` with `task` metadata plus MCP `tasks/list`, `tasks/get`, `tasks/result`, and `tasks/cancel`
 - forwarded `notifications/tasks/status` for exported gateway tasks
 
-Exported MCP tool names are canonical lowercase MCP-safe gateway ids. A unique upstream tool such as `notion-fetch` is exported as `notion-fetch`; when multiple sources expose the same normalized tool name, the gateway uses a source-qualified safe id such as `docs_search_repository` or `ops_search_repository`. `McpGatewayToolDescriptor.ToolId`, downstream MCP `Tool.Name`, and downstream `tools/call` names are the same value, and gateway-owned name resolution is case-insensitive so callers can vary casing without creating a different tool identity. Prompt names and exported resource names use the same lowercase MCP-safe source qualification, for example `ops_deployment_review_system_prompt` or `local_release_review_bundle`, while raw upstream `SourceId`, prompt name, tool name, and resource URI remain available as routing metadata and `_meta` values. Exported MCP resource URIs and URI templates are rewritten into gateway-owned opaque URIs so downstream `resources/read` calls route back to the correct upstream source even when multiple servers expose overlapping URI spaces. The same source-aware rewrite is also used for `completion/complete`, forwarded prompt list changes, and forwarded resource update notifications, so downstream clients always talk in terms of gateway-owned prompt names and resource URIs while the gateway proxies the corresponding upstream MCP operations. When an upstream MCP tool already advertises task support, the gateway preserves that contract on the exported tool and proxies the corresponding upstream task flow. Local gateway tools are exported as optional task-capable tools and are executed through the gateway-owned task store.
+Exported MCP tool names are canonical lowercase MCP-safe gateway ids. A unique upstream tool such as `notion-fetch` is exported as `notion-fetch`; when multiple sources expose the same normalized tool name, the gateway uses a source-qualified safe id such as `docs_search_repository` or `ops_search_repository`. Hash suffixes are added only when length or collision handling requires them. Names that would exceed 64 characters keep a readable normalized prefix and receive a deterministic hash suffix instead of being blindly truncated. `McpGatewayToolDescriptor.ToolId`, downstream MCP `Tool.Name`, and downstream `tools/call` names are the same value, and gateway-owned name resolution is case-insensitive so callers can vary casing without creating a different tool identity. Prompt names and exported resource names use the same lowercase MCP-safe source qualification, for example `ops_deployment_review_system_prompt` or `local_release_review_bundle`, while raw upstream `SourceId`, prompt name, tool name, and resource URI remain available as routing metadata and `_meta` values. Exported MCP resource URIs and URI templates are rewritten into gateway-owned opaque URIs so downstream `resources/read` calls route back to the correct upstream source even when multiple servers expose overlapping URI spaces. The same source-aware rewrite is also used for `completion/complete`, forwarded prompt list changes, and forwarded resource update notifications, so downstream clients always talk in terms of gateway-owned prompt names and resource URIs while the gateway proxies the corresponding upstream MCP operations. When an upstream MCP tool already advertises task support, the gateway preserves that contract on the exported tool and proxies the corresponding upstream task flow. Local gateway tools are exported as optional task-capable tools and are executed through the gateway-owned task store.
 
 The exported task store uses the official SDK `InMemoryMcpTaskStore` with MCPGateway-owned bounded defaults: task TTL 30 minutes, maximum task TTL 2 hours, cleanup every minute, maximum 10,000 tasks globally, and maximum 1,000 tasks per downstream session. Hosts can override those limits through `McpGatewayOptions.McpTaskStore`, or replace `McpServerOptions.TaskStore` with a durable production store when tasks must survive process restarts:
 

docs/ADR/ADR-0013-mcp-safe-canonical-protocol-names.md

@@ -18,6 +18,8 @@ Gateway-owned protocol names use one canonical lowercase MCP-safe identity.
 - Unique tools use the normalized upstream tool name, for example `notion-fetch`.
 - Colliding normalized tool names receive deterministic source-qualified safe ids, for example `docs_search_repository`.
 - Exact duplicate source/tool pairs receive a deterministic suffix instead of being skipped.
+- Hash suffixes are added only when length or collision handling requires them; normal short names such as `notion-fetch` remain unchanged.
+- Names that exceed the bounded host limit keep a readable normalized prefix and receive a deterministic hash suffix within 64 characters instead of being blindly truncated.
 - Prompt ids and exported resource names are lowercase MCP-safe source-qualified names.
 - Gateway-owned name resolution is case-insensitive for tools, prompts, task support maps, and embedding-store lookups.
 - Raw upstream `SourceId`, tool name, prompt name, resource name, and URI remain separate routing metadata and `_meta` values.

docs/Architecture/Overview.md

@@ -36,7 +36,7 @@ Graph-specific search and indexing operations deliberately sit on `IMcpGatewayGr
 
 The package also keeps chat-client and agent integration generic: `McpGatewayToolSet` is the source of reusable `AITool` search, route, invoke, graph schema-describe, tool index-build, graph schema-search, graph federated-search, and graph export meta-tools plus discovered proxy tools, `ChatOptions.AddMcpGatewayTools(...)` and `ChatOptions.AddMcpGatewayGraphTools(...)` remain the low-level bridges, and `McpGatewayAutoDiscoveryChatClient` plus `UseMcpGatewayAutoDiscovery(...)` provide the recommended staged host wrapper that starts with the gateway search/route/invoke tools and replaces the discovered proxy set on each new search result without introducing a hard Agent Framework dependency into the core package.
 
-For MCP interoperability in the other direction, the package also exposes `WithMcpGatewayCatalog()` as a server-builder extension. Hosts can take one aggregated gateway catalog and re-export it as a downstream MCP server that exposes the combined tools, prompts, and resources from multiple upstream MCP sources plus gateway-owned prompts. That export also proxies MCP completions, forwarded prompt list-change notifications, resource subscriptions, forwarded resource-updated notifications, logging level changes, and task-backed tool execution through the MCP tasks surface. Tool ids, downstream MCP tool names, prompt ids, and exported resource names are normalized to lowercase MCP-safe names; unique tools keep their normalized upstream tool name, collisions get deterministic source-qualified ids, and gateway-owned name resolution is case-insensitive while raw `SourceId` and upstream protocol names stay in routing metadata. Resource URIs are rewritten into gateway-owned source-qualified URIs during export so downstream reads, completions, and forwarded update notifications stay unambiguous even when upstream servers reuse the same URI spaces. Exported task storage uses the official SDK in-memory task store with MCPGateway-owned bounded TTL, cleanup, and task-count limits by default. Gateway-owned per-session prompt notification, resource subscription, and active task binding state is removed both on protocol cleanup paths and, for Streamable HTTP hosting, through the official SDK `HttpServerTransportOptions.RunSessionHandler` lifecycle when the SDK-owned HTTP session ends. By default the export binds to the singleton gateway services in DI, but hosts can override that binding per request or per downstream MCP session through `IMcpGatewayServerBindingResolver`, which allows route-specific or tenant-specific gateway instances without forking the exported MCP handler stack.
+For MCP interoperability in the other direction, the package also exposes `WithMcpGatewayCatalog()` as a server-builder extension. Hosts can take one aggregated gateway catalog and re-export it as a downstream MCP server that exposes the combined tools, prompts, and resources from multiple upstream MCP sources plus gateway-owned prompts. That export also proxies MCP completions, forwarded prompt list-change notifications, resource subscriptions, forwarded resource-updated notifications, logging level changes, and task-backed tool execution through the MCP tasks surface. Tool ids, downstream MCP tool names, prompt ids, and exported resource names are normalized to lowercase MCP-safe names; unique tools keep their normalized upstream tool name, collisions get deterministic source-qualified ids, hash suffixes appear only when length or collision handling requires them, and gateway-owned name resolution is case-insensitive while raw `SourceId` and upstream protocol names stay in routing metadata. Resource URIs are rewritten into gateway-owned source-qualified URIs during export so downstream reads, completions, and forwarded update notifications stay unambiguous even when upstream servers reuse the same URI spaces. Exported task storage uses the official SDK in-memory task store with MCPGateway-owned bounded TTL, cleanup, and task-count limits by default. Gateway-owned per-session prompt notification, resource subscription, and active task binding state is removed both on protocol cleanup paths and, for Streamable HTTP hosting, through the official SDK `HttpServerTransportOptions.RunSessionHandler` lifecycle when the SDK-owned HTTP session ends. By default the export binds to the singleton gateway services in DI, but hosts can override that binding per request or per downstream MCP session through `IMcpGatewayServerBindingResolver`, which allows route-specific or tenant-specific gateway instances without forking the exported MCP handler stack.
 
 The repository now uses feature-first package slices for `Gateway`, `Discovery`, `Catalog`, `Search`, `Invocation`, `Prompts`, `Resources`, and `Hosting`. The durable policy decision behind that structure is captured in [`docs/ADR/ADR-0007-vertical-slice-package-organization.md`](../ADR/ADR-0007-vertical-slice-package-organization.md).
 

src/ManagedCode.MCPGateway/AGENTS.md

@@ -72,6 +72,7 @@ For this .NET project:
 - Keep `McpGateway` focused on search and invoke orchestration; registry mutation belongs in catalog and registration collaborators.
 - Keep transport-specific logic inside registration and source abstractions, not scattered through runtime code.
 - When production behavior changes here, update the integration-style tests under `tests/ManagedCode.MCPGateway.Tests/` in the same task.
+- Keep package-owned production string values such as source ids, fallback names, protocol metadata keys, tool kinds, and default runtime identifiers behind named constants instead of inline literals, because gateway naming contracts must stay auditable and reusable.
 - Do not hide shared runtime services such as `ILoggerFactory` inside options bags for public factory APIs; when custom gateway instances need host-owned shared dependencies, expose a DI-registered factory service that resolves those dependencies from the container and accepts only gateway-specific configuration at creation time.
 - For public runtime-mutation APIs in this package, use precise lifecycle verbs such as `Reconfigure` or `Reset`; avoid ambiguous or alarming names like `Replace` when the operation only rebuilds in-memory registry configuration.
 - For public factory APIs in this package, prefer explicit overloads over nullable optional delegate parameters; use `Create()` plus `Create(Action<T>)` when both cases are supported.

src/ManagedCode.MCPGateway/Catalog/Internal/Runtime/McpGatewayRuntime.Indexing.cs

@@ -213,7 +213,10 @@ IList<McpGatewayDiagnostic> diagnostics
             }
 
             var toolName = loadedTool.Tool.Name.Trim();
-            var normalizedToolName = McpGatewayProtocolName.Normalize(toolName, "gateway_tool");
+            var normalizedToolName = McpGatewayProtocolName.Normalize(
+                toolName,
+                McpGatewayProtocolName.DefaultToolName
+            );
             var requiresSourcePrefix =
                 normalizedToolNameCounts.TryGetValue(normalizedToolName, out var count)
                 && count > 1;
@@ -269,7 +272,7 @@ private static IReadOnlyDictionary<string, int> CountNormalizedToolNames(
 
                 var normalizedToolName = McpGatewayProtocolName.Normalize(
                     loadedTool.Tool.Name,
-                    "gateway_tool"
+                    McpGatewayProtocolName.DefaultToolName
                 );
                 counts[normalizedToolName] = counts.GetValueOrDefault(normalizedToolName) + 1;
             }

src/ManagedCode.MCPGateway/Discovery/Internal/McpGatewayDiscoveredToolNaming.cs

@@ -1,8 +1,9 @@
+using System.Globalization;
+
 namespace ManagedCode.MCPGateway;
 
 internal static class McpGatewayDiscoveredToolNaming
 {
-    private const string DefaultToolName = "gateway_tool";
     private const string NameSeparator = "_";
     private const string DescriptionPrefix = "Direct proxy for gateway tool ";
     private const string ToolIdLabel = " (";
@@ -65,7 +66,10 @@ public static string CreateName(McpGatewaySearchMatch match, ISet<string> reserv
         ArgumentNullException.ThrowIfNull(match);
         ArgumentNullException.ThrowIfNull(reservedNames);
 
-        var sanitizedToolName = McpGatewayProtocolName.Normalize(match.ToolName, DefaultToolName);
+        var sanitizedToolName = McpGatewayProtocolName.Normalize(
+            match.ToolName,
+            McpGatewayProtocolName.DefaultToolName
+        );
         if (reservedNames.Add(sanitizedToolName))
         {
             return sanitizedToolName;
@@ -74,7 +78,7 @@ public static string CreateName(McpGatewaySearchMatch match, ISet<string> reserv
         var compositeName = McpGatewayProtocolName.CreateSourceQualifiedName(
             match.SourceId,
             sanitizedToolName,
-            DefaultToolName
+            McpGatewayProtocolName.DefaultToolName
         );
         if (reservedNames.Add(compositeName))
         {
@@ -83,7 +87,10 @@ public static string CreateName(McpGatewaySearchMatch match, ISet<string> reserv
 
         for (var suffix = 2; ; suffix++)
         {
-            var uniqueName = $"{compositeName}{NameSeparator}{suffix}";
+            var uniqueName = McpGatewayProtocolName.AppendSuffix(
+                compositeName,
+                string.Concat(NameSeparator, suffix.ToString(CultureInfo.InvariantCulture))
+            );
             if (reservedNames.Add(uniqueName))
             {
                 return uniqueName;

src/ManagedCode.MCPGateway/Discovery/Internal/McpGatewayGraphToolFactory.cs

@@ -28,12 +28,38 @@ string toolIndexBuildToolName
     )
     {
         _ = RequireGraphSearch();
+        var reservedNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        var graphSchemaName = McpGatewayToolSet.CreateToolName(
+            graphSchemaToolName,
+            McpGatewayToolSet.DefaultGraphSchemaToolName,
+            reservedNames
+        );
+        var toolIndexBuildName = McpGatewayToolSet.CreateToolName(
+            toolIndexBuildToolName,
+            McpGatewayToolSet.DefaultToolIndexBuildToolName,
+            reservedNames
+        );
+        var graphSearchName = McpGatewayToolSet.CreateToolName(
+            graphSearchToolName,
+            McpGatewayToolSet.DefaultGraphSearchToolName,
+            reservedNames
+        );
+        var graphFederatedSearchName = McpGatewayToolSet.CreateToolName(
+            graphFederatedSearchToolName,
+            McpGatewayToolSet.DefaultGraphFederatedSearchToolName,
+            reservedNames
+        );
+        var graphExportName = McpGatewayToolSet.CreateToolName(
+            graphExportToolName,
+            McpGatewayToolSet.DefaultGraphExportToolName,
+            reservedNames
+        );
 
         var graphSchemaTool = AIFunctionFactory.Create(
             DescribeGraphSchemaAsync,
             new AIFunctionFactoryOptions
             {
-                Name = graphSchemaToolName,
+                Name = graphSchemaName,
                 Description = McpGatewayToolSet.GraphSchemaToolDescription,
             }
         );
@@ -42,7 +68,7 @@ string toolIndexBuildToolName
             BuildToolIndexAsync,
             new AIFunctionFactoryOptions
             {
-                Name = toolIndexBuildToolName,
+                Name = toolIndexBuildName,
                 Description = McpGatewayToolSet.ToolIndexBuildToolDescription,
             }
         );
@@ -51,7 +77,7 @@ string toolIndexBuildToolName
             SchemaGraphSearchAsync,
             new AIFunctionFactoryOptions
             {
-                Name = graphSearchToolName,
+                Name = graphSearchName,
                 Description = McpGatewayToolSet.GraphSearchToolDescription,
             }
         );
@@ -60,7 +86,7 @@ string toolIndexBuildToolName
             FederatedGraphSearchAsync,
             new AIFunctionFactoryOptions
             {
-                Name = graphFederatedSearchToolName,
+                Name = graphFederatedSearchName,
                 Description = McpGatewayToolSet.GraphFederatedSearchToolDescription,
             }
         );
@@ -69,7 +95,7 @@ string toolIndexBuildToolName
             ExportGraphAsync,
             new AIFunctionFactoryOptions
             {
-                Name = graphExportToolName,
+                Name = graphExportName,
                 Description = McpGatewayToolSet.GraphExportToolDescription,
             }
         );
@@ -100,6 +126,12 @@ string toolIndexBuildToolName
         foreach (var tool in targetTools)
         {
             toolNames.Add(tool.Name);
+            toolNames.Add(
+                McpGatewayToolSet.NormalizeToolName(
+                    tool.Name,
+                    McpGatewayToolSet.DefaultGraphSearchToolName
+                )
+            );
         }
 
         foreach (

src/ManagedCode.MCPGateway/Discovery/McpGatewayAutoDiscoveryChatClient.cs

@@ -274,6 +274,10 @@ IReadOnlyList<AITool> gatewayTools
                 StringComparer.OrdinalIgnoreCase
             );
             McpGatewaySearchResult? latestSearchResult = null;
+            var searchToolName = McpGatewayToolSet.NormalizeToolName(
+                _options.SearchToolName,
+                McpGatewayToolSet.DefaultSearchToolName
+            );
 
             foreach (var message in messages)
             {
@@ -291,7 +295,7 @@ out var functionName
                             )
                                 && string.Equals(
                                     functionName,
-                                    _options.SearchToolName,
+                                    searchToolName,
                                     StringComparison.OrdinalIgnoreCase
                                 ):
                             latestSearchResult = ReadSearchResult(functionResult.Result);