Add production-ready incremental source generator for automatic Description attributes from XML comments (#899)

Co-authored-by: Stephen Toub <stoub@microsoft.com>

Author: Copilot

Directory.Packages.props

@@ -46,11 +46,19 @@
     <PackageVersion Include="Microsoft.IdentityModel.Tokens" Version="8.14.0" />
   </ItemGroup>
 
+  <!-- Source Generator & Analyzer dependencies -->
+  <ItemGroup>
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.8.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.4" />
+  </ItemGroup>
+
+  <!-- Build Infra & Packaging dependencies-->
   <ItemGroup>
-    <!-- Build Infra & Packaging -->
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
+  </ItemGroup>
 
-    <!-- Testing dependencies -->
+  <!-- Testing dependencies -->
+  <ItemGroup>
     <PackageVersion Include="Anthropic.SDK" Version="5.8.0" />
     <PackageVersion Include="coverlet.collector" Version="6.0.4">
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>

ModelContextProtocol.slnx

@@ -62,11 +62,13 @@
   </Folder>
   <Folder Name="/src/">
     <File Path="src/Directory.Build.props" />
+    <Project Path="src/ModelContextProtocol.Analyzers/ModelContextProtocol.Analyzers.csproj" />
     <Project Path="src/ModelContextProtocol.AspNetCore/ModelContextProtocol.AspNetCore.csproj" />
     <Project Path="src/ModelContextProtocol.Core/ModelContextProtocol.Core.csproj" />
     <Project Path="src/ModelContextProtocol/ModelContextProtocol.csproj" />
   </Folder>
   <Folder Name="/tests/">
+    <Project Path="tests/ModelContextProtocol.Analyzers.Tests/ModelContextProtocol.Analyzers.Tests.csproj" />
     <Project Path="tests/ModelContextProtocol.AspNetCore.Tests/ModelContextProtocol.AspNetCore.Tests.csproj" />
     <Project Path="tests/ModelContextProtocol.TestOAuthServer/ModelContextProtocol.TestOAuthServer.csproj" />
     <Project Path="tests/ModelContextProtocol.Tests/ModelContextProtocol.Tests.csproj" />

README.md

@@ -228,6 +228,11 @@ await using McpServer server = McpServer.Create(new StdioServerTransport("MyServ
 await server.RunAsync();
 ```
 
+Descriptions can be added to tools, prompts, and resources in a variety of ways, including via the `[Description]` attribute from `System.ComponentModel`.
+This attribute may be placed on a method to provide for the tool, prompt, or resource, or on individual parameters to describe each's purpose.
+XML comments may also be used; if an `[McpServerTool]`, `[McpServerPrompt]`, or `[McpServerResource]`-attributed method is marked as `partial`,
+XML comments placed on the method will be used automatically to generate `[Description]` attributes for the method and its parameters.
+
 ## Acknowledgements
 
 The starting point for this library was a project called [mcpdotnet](https://github.com/PederHP/mcpdotnet), initiated by [Peder Holdgaard Pedersen](https://github.com/PederHP). We are grateful for the work done by Peder and other contributors to that repository, which created a solid foundation for this library.

src/ModelContextProtocol.Analyzers/Diagnostics.cs

@@ -0,0 +1,31 @@
+using Microsoft.CodeAnalysis;
+using Microsoft.CodeAnalysis.CSharp;
+using Microsoft.CodeAnalysis.CSharp.Syntax;
+using Microsoft.CodeAnalysis.Text;
+using System.Collections.Immutable;
+using System.Text;
+using System.Xml.Linq;
+
+namespace ModelContextProtocol.Analyzers;
+
+/// <summary>Provides the diagnostic descriptors used by the assembly.</summary>
+internal static class Diagnostics
+{
+    public static DiagnosticDescriptor InvalidXmlDocumentation { get; } = new(
+        id: "MCP001",
+        title: "Invalid XML documentation for MCP method",
+        messageFormat: "XML comment for method '{0}' is invalid and cannot be processed to generate [Description] attributes.",
+        category: "mcp",
+        defaultSeverity: DiagnosticSeverity.Warning,
+        isEnabledByDefault: true,
+        description: "The XML documentation comment contains invalid XML and cannot be processed to generate Description attributes.");
+
+    public static DiagnosticDescriptor McpMethodMustBePartial { get; } = new(
+        id: "MCP002",
+        title: "MCP method must be partial to generate [Description] attributes",
+        messageFormat: "Method '{0}' has XML documentation that could be used to generate [Description] attributes, but the method is not declared as partial.",
+        category: "mcp",
+        defaultSeverity: DiagnosticSeverity.Warning,
+        isEnabledByDefault: true,
+        description: "Methods with MCP attributes should be declared as partial to allow the source generator to emit Description attributes from XML documentation comments.");
+}

src/ModelContextProtocol.Analyzers/ModelContextProtocol.Analyzers.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>netstandard2.0</TargetFramework>
+    <IsRoslynComponent>true</IsRoslynComponent>
+    <IncludeBuildOutput>false</IncludeBuildOutput>
+    <EnforceExtendedAnalyzerRules>true</EnforceExtendedAnalyzerRules>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <Compile Remove="..\Common\Polyfills\**\*.cs" />
+    <Compile Include="..\Common\Polyfills\System\Runtime\CompilerServices\IsExternalInit.cs" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.CodeAnalysis.CSharp" PrivateAssets="all" />
+    <PackageReference Include="Microsoft.CodeAnalysis.Analyzers" PrivateAssets="all" />
+  </ItemGroup>
+
+</Project>