PR Feedback

- Issue 1: Replace anonymous rate-limit body with typed McpRateLimitErrorEnvelope records;
  use JsonSerializer.SerializeAsync instead of WriteAsync(Serialize(...))
- Issue 2: Strip prose default values from all tool Description attributes
- Issue 3: Merge GetGuidelinesByTopic into GetCSharpGuidelines via optional 'topic' param;
  delete redundant GetGuidelinesByTopic tool
- Issue 4: Make /mcp-setup page dynamic — inject IEnumerable<McpServerTool> into
  McpSetupController; replace 330+ lines of static HTML cards with Razor @foreach loop
- Issue 5: Add listing search pattern minimum validation (>=2 alphanumeric chars or
  recognized C# operator)
- Issues 6+7: Extract duplicated FormatGuidelineType/FormatType to shared
  GuidelineTypeExtensions.ToDisplayString() extension method; delete private copies

Fix 3 subagent-found bugs: trimmedPattern in search, Razor HTML escaping, whitespace-only type guard

- BookListingTool.cs: use trimmedPattern (not pattern) in Contains() search call
- Index.cshtml: fix Razor HTML escaping of optional badge via @if block
- BookGuidelinesTool.cs: use IsNullOrWhiteSpace guard for type param
- BookGuidelinesTool.cs: fix description to say substring match not exact text

Use MCP SDK JsonRpcError/JsonRpcErrorDetail instead of custom records

Replace McpRateLimitErrorEnvelope and McpRateLimitErrorDetail private
records with the SDK's built-in ModelContextProtocol.Protocol types,
as suggested in PR review.

Author: BenjaminMichaelis

EssentialCSharp.Web/Controllers/McpSetupController.cs

@@ -1,21 +1,55 @@
 using EssentialCSharp.Web.Services;
 using Microsoft.AspNetCore.Authorization;
 using Microsoft.AspNetCore.Mvc;
+using ModelContextProtocol.Server;
+using System.Text.Json;
 
 namespace EssentialCSharp.Web.Controllers;
 
 [AllowAnonymous]
 public class McpSetupController : BaseController
 {
-    public McpSetupController(IRouteConfigurationService routeConfigurationService, IHttpContextAccessor httpContextAccessor)
+    private readonly IEnumerable<McpServerTool> _tools;
+
+    public McpSetupController(IRouteConfigurationService routeConfigurationService, IHttpContextAccessor httpContextAccessor, IEnumerable<McpServerTool> tools)
         : base(routeConfigurationService, httpContextAccessor)
     {
+        _tools = tools;
     }
 
     [Route("/mcp-setup")]
     public IActionResult Index()
     {
         ViewBag.PageTitle = "MCP Setup";
-        return View();
+        var toolInfos = _tools
+            .OrderBy(t => t.ProtocolTool.Name)
+            .Select(t =>
+            {
+                var parameters = new List<McpParamInfo>();
+                if (t.ProtocolTool.InputSchema.ValueKind == JsonValueKind.Object
+                    && t.ProtocolTool.InputSchema.TryGetProperty("properties", out JsonElement props)
+                    && props.ValueKind == JsonValueKind.Object)
+                {
+                    t.ProtocolTool.InputSchema.TryGetProperty("required", out JsonElement requiredEl);
+                    foreach (JsonProperty prop in props.EnumerateObject())
+                    {
+                        string desc = prop.Value.TryGetProperty("description", out JsonElement d) ? d.GetString() ?? "" : "";
+                        bool required = requiredEl.ValueKind == JsonValueKind.Array
+                            && requiredEl.EnumerateArray().Any(r => r.GetString() == prop.Name);
+                        parameters.Add(new McpParamInfo(prop.Name, desc, required));
+                    }
+                }
+                return new McpToolInfo(
+                    t.ProtocolTool.Name ?? "",
+                    t.ProtocolTool.Title ?? t.ProtocolTool.Name ?? "",
+                    t.ProtocolTool.Description ?? "",
+                    parameters);
+            })
+            .ToList();
+
+        return View(toolInfos);
     }
 }
+
+public sealed record McpToolInfo(string Name, string Title, string Description, IReadOnlyList<McpParamInfo> Parameters);
+public sealed record McpParamInfo(string Name, string Description, bool Required);

EssentialCSharp.Web/Extensions/GuidelineTypeExtensions.cs

@@ -0,0 +1,13 @@
+namespace EssentialCSharp.Web.Extensions;
+
+public static class GuidelineTypeExtensions
+{
+    public static string ToDisplayString(this GuidelineType type) => type switch
+    {
+        GuidelineType.Do => "DO",
+        GuidelineType.Consider => "CONSIDER",
+        GuidelineType.Avoid => "AVOID",
+        GuidelineType.DoNot => "DO NOT",
+        _ => "NOTE"
+    };
+}

EssentialCSharp.Web/Program.cs

@@ -1,4 +1,5 @@
 using System.Threading.RateLimiting;
+using ModelContextProtocol.Protocol;
 using EssentialCSharp.Chat.Common.Extensions;
 using EssentialCSharp.Web.Areas.Identity.Data;
 using EssentialCSharp.Web.Areas.Identity.Services.PasswordValidators;
@@ -324,15 +325,19 @@ private static void Main(string[] args)
                 if (context.HttpContext.Request.Path.StartsWithSegments("/mcp"))
                 {
                     context.HttpContext.Response.ContentType = "application/json";
-                    var mcpErrorResponse = new
+                    var mcpErrorResponse = new JsonRpcError
                     {
-                        jsonrpc = "2.0",
-                        error = new { code = -32000, message = "Rate limit exceeded. Please wait before sending another request." },
-                        id = (object?)null
+                        JsonRpc = "2.0",
+                        Error = new JsonRpcErrorDetail
+                        {
+                            Code = -32000,
+                            Message = "Rate limit exceeded. Please wait before sending another request."
+                        }
                     };
-                    await context.HttpContext.Response.WriteAsync(
-                        System.Text.Json.JsonSerializer.Serialize(mcpErrorResponse),
-                        cancellationToken);
+                    await System.Text.Json.JsonSerializer.SerializeAsync(
+                        context.HttpContext.Response.Body,
+                        mcpErrorResponse,
+                        cancellationToken: cancellationToken);
                     return;
                 }
 

EssentialCSharp.Web/Tools/BookContentTool.cs

@@ -37,7 +37,7 @@ public BookContentTool(
      Description("Retrieve the prose content of a specific book section identified by its slug/key (e.g., 'hello-world', 'creating-editing-compiling-and-running-c-source-code'). Returns the section text with code examples preserved. Use GetChapterSections to discover available slugs.")]
     public async Task<string> GetSectionContent(
         [Description("The section slug/key (e.g., 'hello-world'). Use GetChapterSections to get valid slugs.")] string sectionKey,
-        [Description("Maximum number of characters to return (500–8000, default 4000). Long sections are truncated.")] int maxChars = 4000,
+        [Description("Maximum number of characters to return (500–8000). Long sections are truncated.")] int maxChars = 4000,
         CancellationToken cancellationToken = default)
     {
         maxChars = Math.Clamp(maxChars, 500, 8000);
@@ -365,7 +365,7 @@ public string GetChapterSummary(
             sb.AppendLine("## Guidelines in this Chapter");
             foreach (var g in guidelines)
             {
-                sb.AppendLine(CultureInfo.InvariantCulture, $"- **[{FormatGuidelineType(g.Type)}]** {g.Guideline}");
+                sb.AppendLine(CultureInfo.InvariantCulture, $"- **[{g.Type.ToDisplayString()}]** {g.Guideline}");
             }
         }
 
@@ -431,15 +431,6 @@ private static void ExtractNodeContent(HtmlNode node, StringBuilder sb)
         }
     }
 
-    private static string FormatGuidelineType(GuidelineType type) => type switch
-    {
-        GuidelineType.Do => "DO",
-        GuidelineType.Consider => "CONSIDER",
-        GuidelineType.Avoid => "AVOID",
-        GuidelineType.DoNot => "DO NOT",
-        _ => "NOTE"
-    };
-
     [GeneratedRegex(@"^[A-Za-z0-9_-]{1,128}$")]
     private static partial Regex AnchorIdRegex();
 }

EssentialCSharp.Web/Tools/BookGuidelinesTool.cs

@@ -1,6 +1,7 @@
 using System.ComponentModel;
 using System.Globalization;
 using System.Text;
+using EssentialCSharp.Web.Extensions;
 using EssentialCSharp.Web.Services;
 using ModelContextProtocol.Server;
 
@@ -17,17 +18,18 @@ public BookGuidelinesTool(IGuidelinesService guidelinesService)
     }
 
     [McpServerTool(Title = "Get C# Guidelines", ReadOnly = true, Destructive = false, Idempotent = true, OpenWorld = false),
-     Description("Retrieve C# coding guidelines from the Essential C# book. Optionally filter by keyword, chapter number, or guideline type (do/consider/avoid/donot). The book contains guidelines covering naming conventions, error handling, LINQ, async/await, generics, and many other topics. Each guideline includes its chapter and subsection context.")]
+     Description("Retrieve C# coding guidelines from the Essential C# book. Filter by keyword (case-insensitive substring match), chapter number, or guideline type. Use the 'topic' parameter for relevance-ranked discovery by concept (e.g., 'exception handling', 'naming', 'async'). Each guideline includes its chapter and subsection context. Tip: use 'topic' for broad discovery; use 'keyword' for precise substring matching.")]
     public string GetCSharpGuidelines(
-        [Description("Optional keyword to filter guidelines by (searched in guideline text and subsection name).")] string? keyword = null,
+        [Description("Optional keyword for case-insensitive substring search in guideline text and subsection name.")] string? keyword = null,
         [Description("Optional chapter number to restrict results to a specific chapter.")] int? chapter = null,
         [Description("Optional guideline type: 'do', 'consider', 'avoid', or 'donot' (also accepts 'do not', 'dont').")] string? type = null,
-        [Description("Maximum number of guidelines to return (1–50, default 20).")] int maxResults = 20)
+        [Description("Optional topic or concept for relevance-ranked search (e.g., 'exception handling', 'naming', 'async'). Results are ordered by relevance. Use for broad discovery; use 'keyword' for substring text matching.")] string? topic = null,
+        [Description("Maximum number of guidelines to return (1–50).")] int maxResults = 20)
     {
         maxResults = Math.Clamp(maxResults, 1, 50);
         GuidelineType? typeFilter = ParseGuidelineType(type);
 
-        if (type is not null && typeFilter is null)
+        if (!string.IsNullOrWhiteSpace(type) && typeFilter is null)
         {
             return "Invalid guideline type. Valid values: 'do', 'consider', 'avoid', 'donot' (also accepts 'do not', 'dont').";
         }
@@ -46,66 +48,54 @@ public string GetCSharpGuidelines(
                 g.SanitizedSubsection.Contains(keyword, StringComparison.OrdinalIgnoreCase) ||
                 (g.ActualSubsection?.Contains(keyword, StringComparison.OrdinalIgnoreCase) == true));
 
-        var results = filtered.Take(maxResults).ToList();
-
-        if (results.Count == 0)
+        if (!string.IsNullOrWhiteSpace(topic))
         {
-            return "No guidelines found matching the specified filters.";
-        }
-
-        var sb = new StringBuilder();
-        sb.AppendLine(CultureInfo.InvariantCulture, $"# Essential C# Guidelines ({results.Count} result{(results.Count == 1 ? "" : "s")})");
-        sb.AppendLine();
+            var words = topic.Split(' ', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+            var scored = filtered
+                .Select(g =>
+                {
+                    string combined = $"{g.Guideline} {g.SanitizedSubsection} {g.ActualSubsection} {g.ChapterTitle}";
+                    int score = words.Count(w => combined.Contains(w, StringComparison.OrdinalIgnoreCase));
+                    return (guideline: g, score);
+                })
+                .Where(x => x.score > 0)
+                .OrderByDescending(x => x.score)
+                .Take(maxResults)
+                .ToList();
+
+            if (scored.Count == 0)
+            {
+                return $"No guidelines found related to '{topic}'.";
+            }
 
-        foreach (var g in results)
-        {
-            sb.AppendLine(CultureInfo.InvariantCulture, $"**[{FormatType(g.Type)}]** {g.Guideline}");
-            sb.AppendLine(CultureInfo.InvariantCulture, $"  — Chapter {g.ChapterNumber}: {g.ChapterTitle} / {g.SanitizedSubsection}");
-            sb.AppendLine();
-        }
+            var topicSb = new StringBuilder();
+            topicSb.AppendLine(CultureInfo.InvariantCulture, $"# Essential C# Guidelines — Topic: {topic} ({scored.Count} result{(scored.Count == 1 ? "" : "s")})");
+            topicSb.AppendLine();
 
-        return sb.ToString();
-    }
+            foreach (var (g, _) in scored)
+            {
+                topicSb.AppendLine(CultureInfo.InvariantCulture, $"**[{g.Type.ToDisplayString()}]** {g.Guideline}");
+                topicSb.AppendLine(CultureInfo.InvariantCulture, $"  — Chapter {g.ChapterNumber}: {g.ChapterTitle} / {g.SanitizedSubsection}");
+                topicSb.AppendLine();
+            }
 
-    [McpServerTool(Title = "Get Guidelines By Topic", ReadOnly = true, Destructive = false, Idempotent = true, OpenWorld = false),
-     Description("Search C# coding guidelines from the Essential C# book by topic or concept. More discoverable than filtering by chapter — finds all guidelines related to exceptions, naming, async, LINQ, generics, interfaces, and more. Results are ordered by relevance to the topic.")]
-    public string GetGuidelinesByTopic(
-        [Description("The topic or concept to search guidelines for (e.g., 'exception handling', 'naming', 'async', 'LINQ', 'generics', 'interface').")] string topic,
-        [Description("Maximum number of guidelines to return (1–30, default 15).")] int maxResults = 15)
-    {
-        if (string.IsNullOrWhiteSpace(topic))
-        {
-            return "Topic must not be empty.";
+            return topicSb.ToString();
         }
 
-        maxResults = Math.Clamp(maxResults, 1, 30);
-
-        var words = topic.Split(' ', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        var results = filtered.Take(maxResults).ToList();
 
-        var scored = _guidelinesService.Guidelines
-            .Select(g =>
-            {
-                string combined = $"{g.Guideline} {g.SanitizedSubsection} {g.ActualSubsection} {g.ChapterTitle}";
-                int score = words.Count(w => combined.Contains(w, StringComparison.OrdinalIgnoreCase));
-                return (guideline: g, score);
-            })
-            .Where(x => x.score > 0)
-            .OrderByDescending(x => x.score)
-            .Take(maxResults)
-            .ToList();
-
-        if (scored.Count == 0)
+        if (results.Count == 0)
         {
-            return $"No guidelines found related to '{topic}'.";
+            return "No guidelines found matching the specified filters.";
         }
 
         var sb = new StringBuilder();
-        sb.AppendLine(CultureInfo.InvariantCulture, $"# Essential C# Guidelines — Topic: {topic} ({scored.Count} result{(scored.Count == 1 ? "" : "s")})");
+        sb.AppendLine(CultureInfo.InvariantCulture, $"# Essential C# Guidelines ({results.Count} result{(results.Count == 1 ? "" : "s")})");
         sb.AppendLine();
 
-        foreach (var (g, _) in scored)
+        foreach (var g in results)
         {
-            sb.AppendLine(CultureInfo.InvariantCulture, $"**[{FormatType(g.Type)}]** {g.Guideline}");
+            sb.AppendLine(CultureInfo.InvariantCulture, $"**[{g.Type.ToDisplayString()}]** {g.Guideline}");
             sb.AppendLine(CultureInfo.InvariantCulture, $"  — Chapter {g.ChapterNumber}: {g.ChapterTitle} / {g.SanitizedSubsection}");
             sb.AppendLine();
         }
@@ -126,13 +116,4 @@ public string GetGuidelinesByTopic(
             _ => null
         };
     }
-
-    private static string FormatType(GuidelineType type) => type switch
-    {
-        GuidelineType.Do => "DO",
-        GuidelineType.Consider => "CONSIDER",
-        GuidelineType.Avoid => "AVOID",
-        GuidelineType.DoNot => "DO NOT",
-        _ => "NOTE"
-    };
 }

EssentialCSharp.Web/Tools/BookListingTool.cs

@@ -39,14 +39,21 @@ public async Task<string> GetListingSourceCode(
      Description("Search all code listings in the Essential C# book for a specific code pattern, keyword, or identifier. Searches actual C# source code (not prose). Useful for finding examples of Task.WhenAll, yield return, IDisposable, pattern matching, and similar code constructs.")]
     public async Task<string> SearchListingsByCode(
         [Description("The code pattern or keyword to search for in listing source code (case-insensitive substring match).")] string pattern,
-        [Description("Maximum number of matching listings to return (1–20, default 10).")] int maxResults = 10,
+        [Description("Maximum number of matching listings to return (1–20).")] int maxResults = 10,
         CancellationToken cancellationToken = default)
     {
         if (string.IsNullOrWhiteSpace(pattern))
         {
             return "Pattern must not be empty.";
         }
 
+        string trimmedPattern = pattern.Trim();
+        bool isKnownOperator = trimmedPattern is "=>" or "??" or "?." or "::" or "??=" or "==" or "!=" or "<=" or ">=" or "&&" or "||";
+        if (!isKnownOperator && trimmedPattern.Count(char.IsLetterOrDigit) < 2)
+        {
+            return "Pattern must contain at least two letters or digits, or be a recognized C# operator (=>, ??, ?., ::, ??=, ==, !=, <=, >=, &&, ||).";
+        }
+
         maxResults = Math.Clamp(maxResults, 1, 20);
 
         var distinctChapters = _siteMappingService.SiteMappings
@@ -66,7 +73,7 @@ public async Task<string> SearchListingsByCode(
             foreach (var listing in listings)
             {
                 if (found >= maxResults) break;
-                if (listing.Content.Contains(pattern, StringComparison.OrdinalIgnoreCase))
+                if (listing.Content.Contains(trimmedPattern, StringComparison.OrdinalIgnoreCase))
                 {
                     string langHint = listing.FileExtension == "cs" ? "csharp" : listing.FileExtension;
                     sb.AppendLine(CultureInfo.InvariantCulture, $"### Listing {listing.ChapterNumber}.{listing.ListingNumber}");