vertical slice

Author: KSemenenko

.csharpierignore

@@ -1,6 +1,6 @@
 # These files intentionally stay on the repository's dotnet-format whitespace layout.
 Directory.Build.props
 Directory.Packages.props
-src/ManagedCode.MCPGateway/Configuration/McpGatewayOptions.cs
-src/ManagedCode.MCPGateway/Internal/Catalog/Sources/McpGatewayToolSourceRegistrations.cs
-src/ManagedCode.MCPGateway/Internal/Runtime/Catalog/McpGatewayRuntime.Indexing.cs
+src/ManagedCode.MCPGateway/Gateway/Configuration/McpGatewayOptions.cs
+src/ManagedCode.MCPGateway/Catalog/Internal/Sources/McpGatewayToolSourceRegistrations.cs
+src/ManagedCode.MCPGateway/Catalog/Internal/Runtime/McpGatewayRuntime.Indexing.cs

AGENTS.md

@@ -91,7 +91,7 @@ If no new rule is detected -> do not update the file.
 - format: `dotnet format ManagedCode.MCPGateway.slnx`
 - format-check: `dotnet format ManagedCode.MCPGateway.slnx --verify-no-changes`
 - roslynator-analyze: `dotnet tool run roslynator analyze src/ManagedCode.MCPGateway/ManagedCode.MCPGateway.csproj tests/ManagedCode.MCPGateway.Tests/ManagedCode.MCPGateway.Tests.csproj`
-- coverage: `dotnet tool run coverlet tests/ManagedCode.MCPGateway.Tests/bin/Release/net10.0/ManagedCode.MCPGateway.Tests.dll --target "dotnet" --targetargs "test --solution ManagedCode.MCPGateway.slnx -c Release --no-build" --format cobertura --output artifacts/coverage/coverage.cobertura.xml`
+- coverage: `dotnet tool run coverlet tests/ManagedCode.MCPGateway.Tests/bin/Release/net10.0/ManagedCode.MCPGateway.Tests.dll --target "./tests/ManagedCode.MCPGateway.Tests/bin/Release/net10.0/ManagedCode.MCPGateway.Tests" --targetargs "" --format cobertura --output artifacts/coverage/coverage.cobertura.xml`
 - coverage-report: `dotnet tool run reportgenerator -reports:"artifacts/coverage/coverage.cobertura.xml" -targetdir:"artifacts/coverage-report" -reporttypes:"HtmlSummary;MarkdownSummaryGithub"`
 
 ### Rule Precedence
@@ -164,17 +164,16 @@ If no new rule is detected -> do not update the file.
 
 - `src/ManagedCode.MCPGateway/` contains the package source.
 - `tests/ManagedCode.MCPGateway.Tests/` contains integration-style package tests.
-- `src/ManagedCode.MCPGateway/Abstractions/` contains public interfaces, grouped by concern when needed.
-- `src/ManagedCode.MCPGateway/Configuration/` contains public configuration types and service keys.
-- `src/ManagedCode.MCPGateway/Models/` contains public contracts grouped by behavior such as search, invocation, catalog, and embeddings.
-- `src/ManagedCode.MCPGateway/Embeddings/` contains public embedding-store implementations.
-- `src/ManagedCode.MCPGateway/Internal/` contains internal catalog, runtime, and helper implementation details.
-- `src/ManagedCode.MCPGateway/Registration/` contains DI registration extensions.
-- `src/ManagedCode.MCPGateway/McpGateway.cs` is the public gateway facade.
-- `src/ManagedCode.MCPGateway/Internal/Runtime/` contains the internal runtime orchestration implementation, grouped by core, catalog, search, invocation, and embeddings responsibilities.
-- `src/ManagedCode.MCPGateway/McpGatewayToolSet.cs` exposes the gateway as reusable `AITool` meta-tools.
+- `src/ManagedCode.MCPGateway/Gateway/` contains the public gateway facade, factory, options, DI entry points, runtime core, telemetry, and serialization.
+- `src/ManagedCode.MCPGateway/Discovery/` contains reusable `AITool` meta-tools, auto-discovery chat integration, and discovery-specific registration/configuration.
+- `src/ManagedCode.MCPGateway/Catalog/` contains catalog contracts, models, registration state, descriptors, source adapters, and index-building logic.
+- `src/ManagedCode.MCPGateway/Search/` contains search contracts, models, caching, embeddings, and internal ranking/graph/normalization/context logic.
+- `src/ManagedCode.MCPGateway/Invocation/` contains invocation models and runtime execution helpers.
+- `src/ManagedCode.MCPGateway/Prompts/` contains prompt contracts, models, and prompt catalog implementation.
+- `src/ManagedCode.MCPGateway/Hosting/` contains MCP server export and warmup integration.
 - `.codex/skills/` contains repo-local MCAF skills for Codex.
 - Keep the source tree explicitly modular: separate public API folders from `Internal/` implementation folders, and group runtime classes by responsibility in dedicated folders instead of dumping search, indexing, invocation, registry, and infrastructure files into the package root, because flat structure hides boundaries and invites god-object design.
+- Prefer vertical-slice package structure for non-trivial areas: group code by feature and subfeature with isolated supporting types nearby instead of accumulating broad cross-cutting buckets that mix unrelated behaviors in one folder, because feature-local structure keeps boundaries auditable.
 
 ### Skills (ALL TASKS)
 
@@ -211,14 +210,16 @@ If no new rule is detected -> do not update the file.
 - Test framework in this repository is TUnit. Never add or keep xUnit here.
 - This repository uses `TUnit` on `Microsoft.Testing.Platform`; never use VSTest-only flags such as `--filter` or `--logger`, because they are not supported here.
 - For TUnit solution runs, always invoke `dotnet test --solution ...`; do not pass the solution path positionally.
-- Coverage in this repository uses the local `coverlet.console` tool against the built test assembly, then renders human-readable output with the local `reportgenerator` tool.
+- Coverage in this repository uses the local `coverlet.console` tool against the built test assembly and must target the built `ManagedCode.MCPGateway.Tests` TUnit application directly; routing coverage through `dotnet test --solution ...` under `Microsoft.Testing.Platform` reports zero hits in this repo.
 - Every behavior change must include or update tests in `tests/ManagedCode.MCPGateway.Tests/`.
 - Add tests only when they close a meaningful behavior or regression gap; avoid low-signal tests that only increase count without improving confidence.
 - Keep tests focused on real gateway behavior:
   - local tool indexing and invocation
   - MCP tool indexing and invocation
   - vector search behavior
   - Markdown-LD graph search and vector-to-graph fallback behavior
+- For MCP protocol coverage, prefer end-to-end integration tests that use the official `ModelContextProtocol` C# SDK on both client and server paths instead of test doubles when the behavior depends on real protocol contracts, because MCP regressions often hide outside mocked flows.
+- When changing MCP discovery, routing, search, or invocation behavior, add multi-step integration cases with realistic tool metadata, side-effect boundaries, and client-driven execution so retrieval and invocation are verified under production-like conditions.
 - Keep embedding-based search covered with deterministic local tests by using a fake or test-only embedding generator.
 - Keep request context behavior covered when search or invocation consumes contextual inputs.
 - Do not remove tests to get green builds.
@@ -307,6 +308,7 @@ If no new rule is detected -> do not update the file.
 ### Likes
 
 - Explicit package structure
+- Vertical-slice structure with feature and subfeature isolation
 - Reusable library design over app-specific glue
 - Search + execute flows covered by automated tests
 - Clean root packaging and CI setup

Directory.Packages.props

@@ -4,7 +4,7 @@
   </PropertyGroup>
   <ItemGroup>
     <PackageVersion Include="DotNet.ReproducibleBuilds" Version="2.0.2" />
-    <PackageVersion Include="ManagedCode.MarkdownLd.Kb" Version="0.1.3" />
+    <PackageVersion Include="ManagedCode.MarkdownLd.Kb" Version="0.1.5" />
     <PackageVersion Include="Microsoft.Agents.AI" Version="1.1.0" />
     <PackageVersion Include="Microsoft.Extensions.AI" Version="10.5.0" />
     <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.6" />
@@ -17,6 +17,6 @@
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.4.0" />
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="10.0.202" />
     <PackageVersion Include="ModelContextProtocol" Version="1.2.0" />
-    <PackageVersion Include="TUnit" Version="1.37.0" />
+    <PackageVersion Include="TUnit" Version="1.37.10" />
   </ItemGroup>
 </Project>

README.md

@@ -25,6 +25,7 @@ dotnet add package ManagedCode.MCPGateway
 - one prompt catalog for MCP prompts aggregated across registered MCP sources
 - one downstream MCP server export path over the aggregated tool and prompt catalog
 - one search API with default Markdown-LD graph ranking, opt-in vector ranking, and vector-first `Auto`
+- one category-first routing API for advanced tool discovery flows
 - one invocation API for both local tools and MCP tools
 - additive catalog registration through `IMcpGatewayRegistry`
 - full in-memory catalog control through `IMcpGatewayCatalogRuntime`
@@ -74,6 +75,10 @@ await using var serviceProvider = services.BuildServiceProvider();
 var gateway = serviceProvider.GetRequiredService<IMcpGateway>();
 
 var search = await gateway.SearchAsync("find github repositories");
+var route = await gateway.RouteToolsAsync(new McpGatewayToolRouteRequest(
+    Query: "find github repositories",
+    MaxCategories: 3,
+    MaxToolsPerCategory: 2));
 var invoke = await gateway.InvokeAsync(new McpGatewayInvokeRequest(
     ToolId: search.Matches[0].ToolId,
     Query: "managedcode"));
@@ -244,7 +249,7 @@ var prompts = await gatewayHost.PromptCatalog.ListPromptsAsync();
 
 Use the package surfaces like this:
 
-- `IMcpGateway`: build, list, search, invoke
+- `IMcpGateway`: build, list, search, route, invoke
 - `IMcpGatewayRegistry`: additive tool and source registration
 - `IMcpGatewayCatalogRuntime`: full in-memory catalog clear or reconfiguration
 - `IMcpGatewayPromptCatalog`: list and render aggregated MCP prompts
@@ -315,7 +320,7 @@ var invoke = await gateway.InvokeAsync(new McpGatewayInvokeRequest(
 
 ## Search Hints
 
-If a tool should be easier to find through multilingual aliases or stable domain keywords, register explicit search hints:
+If a tool should be easier to find through multilingual aliases, stable domain keywords, category-first routing, or execution-aware discovery, register explicit search hints:
 
 ```csharp
 services.AddMcpGateway(options =>
@@ -340,11 +345,35 @@ services.AddMcpGateway(options =>
                 "alerts",
                 "inbox",
                 "mentions"
-            ]));
+            ],
+            Categories: ["communications"],
+            Tags: ["notifications", "activity-feed"],
+            DataSources: ["inbox-api"],
+            UsageExamples:
+            [
+                new McpGatewayToolExample(
+                    "show unread alerts",
+                    "{\"count\":3}",
+                    "Check whether the user has pending notifications."),
+                new McpGatewayToolExample(
+                    "summarize mentions from the last release thread",
+                    "{\"mentions\":[\"alice\",\"bob\"]}",
+                    "Triage release-thread mentions before replying."),
+                new McpGatewayToolExample(
+                    "list urgent notifications for the mobile workspace",
+                    "{\"alerts\":[{\"severity\":\"high\"}]}",
+                    "Filter alerts for a specific workspace and urgency level.")
+            ],
+            ReadOnly: true,
+            Idempotent: true,
+            CostTier: McpGatewayToolCostTier.Low,
+            LatencyTier: McpGatewayToolLatencyTier.Low));
 });
 ```
 
-Hints are included in descriptors, Markdown-LD graph documents, vector documents, and lexical boosts. They are the preferred way to improve multilingual discovery without hardcoded ranking exceptions.
+Hints are included in descriptors, Markdown-LD graph documents, vector documents, exported MCP metadata, and lexical boosts. They are the preferred way to improve multilingual discovery and category-aware routing without hardcoded ranking exceptions.
+
+If a tool should stay out of default discovery until a host explicitly opts into it, set `EnabledByDefault: false`. Standard `SearchAsync(...)` and `RouteToolsAsync(...)` hide those tools unless the request sets `IncludeDisabledTools = true`.
 
 ## Search Strategies
 
@@ -525,11 +554,33 @@ services.AddMcpGateway(options =>
 });
 ```
 
-## Meta-Tools And Chat Integration
+## Routing, Meta-Tools, And Chat Integration
+
+For category-first discovery:
+
+```csharp
+var route = await gateway.RouteToolsAsync(new McpGatewayToolRouteRequest(
+    Query: "open a bridge and prepare a failover plan for incident 42",
+    MaxCategories: 2,
+    MaxToolsPerCategory: 2,
+    ContextSummary: "incident already confirmed; the next step is an action tool",
+    PreferReadOnly: false,
+    IncludeDisabledTools: true));
+```
+
+`McpGatewayToolRouteResult` returns:
+
+- `Categories` with grouped tool candidates
+- `SuggestedMatches` with the flattened recommended tools
+- `Diagnostics` from the underlying search path
+- `RankingMode` from the underlying graph/vector/hybrid search
+
+The router prefers safe read-only tools for discovery/inspection-style requests and uses cost and latency tiers as tie-breakers when tool quality is otherwise similar.
 
-The gateway can expose itself as two reusable tools:
+The gateway can expose itself as three reusable tools:
 
 - `gateway_tools_search`
+- `gateway_tools_route`
 - `gateway_tool_invoke`
 
 From the gateway:
@@ -575,7 +626,7 @@ var response = await chatClient.GetResponseAsync(
     });
 ```
 
-This flow starts with the two gateway meta-tools and only projects the latest matching tools as direct proxy tools after search.
+This flow starts with the three gateway meta-tools and only projects the latest matching tools as direct proxy tools after search.
 
 If the host already has search results and only wants the discovered proxy tools:
 
@@ -655,6 +706,7 @@ Search telemetry includes configured strategy, ranking mode, graph/vector usage,
 - [ADR-0004: Process-local embedding store uses IMemoryCache](docs/ADR/ADR-0004-process-local-embedding-store-uses-imemorycache.md)
 - [ADR-0005: Markdown-LD graph search for tool retrieval](docs/ADR/ADR-0005-markdown-ld-graph-search-for-tool-retrieval.md)
 - [ADR-0006: Vector-first auto search and runtime telemetry](docs/ADR/ADR-0006-vector-first-auto-search-and-runtime-telemetry.md)
+- [ADR-0007: Vertical-slice package organization](docs/ADR/ADR-0007-vertical-slice-package-organization.md)
 - [Feature spec: Search query normalization and ranking](docs/Features/SearchQueryNormalizationAndRanking.md)
 - [Feature spec: Auto vector-first search and performance](docs/Features/AutoVectorFirstSearchAndPerformance.md)
 
@@ -684,6 +736,6 @@ dotnet csharpier check .
 Coverage:
 
 ```bash
-dotnet tool run coverlet tests/ManagedCode.MCPGateway.Tests/bin/Release/net10.0/ManagedCode.MCPGateway.Tests.dll --target "dotnet" --targetargs "test --solution ManagedCode.MCPGateway.slnx -c Release --no-build" --format cobertura --output artifacts/coverage/coverage.cobertura.xml
+dotnet tool run coverlet tests/ManagedCode.MCPGateway.Tests/bin/Release/net10.0/ManagedCode.MCPGateway.Tests.dll --target "./tests/ManagedCode.MCPGateway.Tests/bin/Release/net10.0/ManagedCode.MCPGateway.Tests" --targetargs "" --format cobertura --output artifacts/coverage/coverage.cobertura.xml
 dotnet tool run reportgenerator -reports:"artifacts/coverage/coverage.cobertura.xml" -targetdir:"artifacts/coverage-report" -reporttypes:"HtmlSummary;MarkdownSummaryGithub"
 ```

docs/ADR/ADR-0003-reusable-chat-client-and-agent-tool-modules.md

@@ -2,7 +2,7 @@
 
 ## Context
 
-`ManagedCode.MCPGateway` already exposes the gateway as two reusable meta-tools through `McpGatewayToolSet` and `IMcpGateway.CreateMetaTools(...)`.
+`ManagedCode.MCPGateway` already exposes the gateway as reusable meta-tools through `McpGatewayToolSet` and `IMcpGateway.CreateMetaTools(...)`.
 
 The package now also needs to prove that these tools integrate cleanly with two host-side consumption patterns:
 
@@ -14,7 +14,7 @@ The user explicitly asked for:
 - very lightweight host integration
 - deterministic scenario-driven tests
 - coverage both without embeddings and with embeddings
-- a staged auto-discovery flow where the model starts with only two gateway tools, then receives only the currently needed direct tools, and then sees those discovered tools replaced when a new search result arrives
+- a staged auto-discovery flow where the model starts with the gateway search, route, and invoke tools, then receives only the currently needed direct tools, and then sees those discovered tools replaced when a new search result arrives
 
 At the same time, the repository still wants to keep the core package generic, library-first, and free from unnecessary host-framework dependencies.
 
@@ -30,8 +30,8 @@ At the same time, the repository still wants to keep the core package generic, l
 
 The recommended host flow is:
 
-1. expose only `gateway_tools_search` and `gateway_tool_invoke`
-2. let the model search the gateway
+1. expose only `gateway_tools_search`, `gateway_tools_route`, and `gateway_tool_invoke`
+2. let the model search or route the gateway first
 3. project only the latest search matches as direct proxy tools
 4. replace that discovered proxy set when a new search result arrives
 
@@ -42,7 +42,7 @@ The core package will not take a hard runtime dependency on Microsoft Agent Fram
 ```mermaid
 flowchart LR
     Gateway["IMcpGateway / McpGateway"] --> ToolSet["McpGatewayToolSet"]
-    ToolSet --> MetaTools["gateway_tools_search + gateway_tool_invoke"]
+    ToolSet --> MetaTools["gateway_tools_search + gateway_tools_route + gateway_tool_invoke"]
     ToolSet --> Discovered["CreateDiscoveredTools(...)"]
     MetaTools --> ChatOptions["ChatOptions.AddMcpGatewayTools(...)"]
     MetaTools --> AutoDiscovery["McpGatewayAutoDiscoveryChatClient"]
@@ -117,7 +117,7 @@ Mitigations:
 - `McpGatewayToolSet.CreateTools(...)` MUST remain the canonical source of gateway meta-tools.
 - `McpGatewayToolSet.AddTools(...)` MUST preserve existing tool entries and MUST avoid duplicate names.
 - `ChatOptions.AddMcpGatewayTools(...)` MUST preserve existing `ChatOptions.Tools` entries and MUST avoid duplicate names.
-- `McpGatewayAutoDiscoveryChatClient` MUST start each host loop with only the two gateway meta-tools visible unless the host already supplied other non-gateway tools.
+- `McpGatewayAutoDiscoveryChatClient` MUST start each host loop with only the gateway search, route, and invoke meta-tools visible unless the host already supplied other non-gateway tools.
 - `McpGatewayAutoDiscoveryChatClient` MUST replace the discovered proxy-tool set when a newer gateway search result is present instead of accumulating old discovered tools forever.
 - The core package MUST stay generic around `AITool` composition and MUST NOT require Microsoft Agent Framework for normal package use.
 - Chat-client and agent integration tests MUST prove the staged auto-discovery lifecycle against a realistic multi-tool catalog in both default graph mode and opt-in vector mode.