Implement XML Documentation Generator for Tool Methods

[jongalloway]

Overview

The MCP C# SDK v0.4.1-preview.1 includes a production-ready source generator that automatically creates [Description] attributes from XML documentation comments. This feature would reduce maintenance burden and improve IDE experience by using a single source of truth for documentation.

Current State

Our codebase has:

• 100+ manual [Description] attributes across all tool methods and parameters
• ~1400 lines of documentation spread across DotNetCliTools.cs
• Duplicate information (XML comments would appear in IDE IntelliSense AND generate MCP descriptions)

Benefits

1. Reduced Maintenance: Single source of truth for documentation
2. Better IDE Experience: XML comments provide IntelliSense support
3. Automatic Sync: Descriptions automatically update with XML comments
4. .NET Best Practices: Follows standard .NET documentation conventions
5. Built-in Feature: Source generator is included in SDK, no additional dependencies

How It Works

The source generator (introduced in #899) automatically generates [Description] attributes from XML comments for partial methods tagged with MCP attributes.

Pattern

Before (Current):

[McpServerTool, Description("Build a .NET project")]
public async Task<string> DotnetProjectBuild(
    [Description("The project file")] string? project = null)
{
    // implementation
}

After (With XML Generator):

/// <summary>
/// Build a .NET project
/// </summary>
/// <param name="project">The project file</param>
[McpServerTool]
public partial Task<string> DotnetProjectBuild(string? project = null);

// Implementation in same file
public async partial Task<string> DotnetProjectBuild(string? project)
{
    // implementation
}

The source generator automatically creates:

[Description("Build a .NET project")]
public partial Task<string> DotnetProjectBuild([Description("The project file")] string? project = null);

Requirements

1. Class must be partial: public sealed partial class DotNetCliTools
2. Methods must be partial: Declaration + implementation pattern
3. XML documentation: Use /// <summary>, /// <param>, /// <returns>
4. Enable XML generation: Add <GenerateDocumentationFile>true</GenerateDocumentationFile> to project

Implementation Approach

Phase 1: Setup

• Update to MCP SDK v0.4.1-preview.1 (completed in #XXX)
• Mark DotNetCliTools class as partial
• Enable XML documentation file generation in project

Phase 2: Incremental Conversion

Convert methods incrementally by category to minimize risk:

1. Template tools (5 methods) - Test the pattern
2. Project tools (10 methods) - Validate approach
3. Package tools (8 methods)
4. Solution tools (8 methods)
5. SDK/Runtime tools (10 methods)
6. Remaining tools (60+ methods)

Phase 3: Verification

• Verify all tool descriptions are preserved
• Check IntelliSense works correctly
• Run full test suite
• Test with MCP Inspector
• Verify generated code in obj/ directory

Risks & Considerations

Risks

• Large refactor (~1400 lines changed)
• Potential for regressions if descriptions don't match exactly
• Partial method pattern is less familiar to contributors
• Requires careful testing of all tools

Mitigations

• Incremental approach (convert category by category)
• Comprehensive testing after each phase
• Keep PR focused and reviewable
• Document the pattern clearly for future contributors

Example Conversion

Current Code:

[McpServerTool, Description("List all installed .NET templates with their metadata using the Template Engine. Provides structured information about available project templates.")]
[McpMeta("category", "template")]
[McpMeta("commonlyUsed", true)]
public async Task<string> DotnetTemplateList(
    [Description("If true, bypasses cache and reloads templates from disk")] bool forceReload = false)
    => await TemplateEngineHelper.GetInstalledTemplatesAsync(forceReload, _logger);

Converted Code:

/// <summary>
/// List all installed .NET templates with their metadata using the Template Engine. 
/// Provides structured information about available project templates.
/// </summary>
/// <param name="forceReload">If true, bypasses cache and reloads templates from disk</param>
[McpServerTool]
[McpMeta("category", "template")]
[McpMeta("commonlyUsed", true)]
public partial Task<string> DotnetTemplateList(bool forceReload = false);

public async partial Task<string> DotnetTemplateList(bool forceReload)
    => await TemplateEngineHelper.GetInstalledTemplatesAsync(forceReload, _logger);

Success Criteria

• All tool methods use XML documentation
• All manual [Description] attributes removed
• Source generator creates correct descriptions
• All 279+ tests pass
• IntelliSense shows documentation correctly
• MCP Inspector shows same tool descriptions as before
• No performance degradation

References

• SDK PR #899: XML Documentation Generator
• SDK Release v0.4.1-preview.1
• C# Partial Methods Documentation

Timeline Estimate

• Phase 1 (Setup): 1-2 hours
• Phase 2 (Conversion): 8-12 hours (incremental over multiple sessions)
• Phase 3 (Verification): 2-3 hours
• Total: 11-17 hours

Decision

This feature should be implemented as a separate, dedicated PR to:

• Minimize risk to the SDK update PR
• Allow focused review of the refactor
• Enable incremental rollback if issues arise
• Keep PR sizes manageable

---

Related to: SDK update PR (to be linked when created)