Skip to content

Commit f10abe8

Browse files
AClerboisAClerbois
committed
Add version compatibility prompts and tooling to MCP Server
Enhance SetupProjectPrompt to include explicit version info and NuGet guidance. Expose documented component and MCP Server versions in FluentUIDocumentationService. Add CheckVersionCompatibilityPrompt for semantic version checks and actionable recommendations. Introduce VersionTools for programmatic version info and compatibility checks. Register new prompt in service collection. Improves user guidance and reduces documentation mismatches.
1 parent 0c8c390 commit f10abe8

File tree

7 files changed

+427
-4
lines changed

7 files changed

+427
-4
lines changed

‎src/Tools/McpServer/Extensions/ServiceCollectionExtensions.cs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,9 @@ public static IServiceCollection AddFluentUIMcpServer(this IServiceCollection se
8080
.WithPrompts<MigrateToV5Prompt>()
8181
.WithPrompts<SetupProjectPrompt>()
8282
.WithPrompts<ConfigureThemingPrompt>()
83-
.WithPrompts<ConfigureLocalizationPrompt>();
83+
.WithPrompts<ConfigureLocalizationPrompt>()
84+
// Version & compatibility prompts
85+
.WithPrompts<CheckVersionCompatibilityPrompt>();
8486

8587
return services;
8688
}

‎src/Tools/McpServer/Prompts/CheckVersionCompatibilityPrompt.cs‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
// ------------------------------------------------------------------------
2+
// This file is licensed to you under the MIT License.
3+
// ------------------------------------------------------------------------
4+
5+
using System.ComponentModel;
6+
using System.Text;
7+
using Microsoft.FluentUI.AspNetCore.Components.McpServer.Services;
8+
using Microsoft.Extensions.AI;
9+
using ModelContextProtocol.Server;
10+
11+
namespace Microsoft.FluentUI.AspNetCore.Components.McpServer.Prompts;
12+
13+
/// <summary>
14+
/// MCP Prompt for checking version compatibility between NuGet package and MCP Server.
15+
/// </summary>
16+
[McpServerPromptType]
17+
public class CheckVersionCompatibilityPrompt
18+
{
19+
private readonly FluentUIDocumentationService _documentationService;
20+
21+
/// <summary>
22+
/// Initializes a new instance of the <see cref="CheckVersionCompatibilityPrompt"/> class.
23+
/// </summary>
24+
public CheckVersionCompatibilityPrompt(FluentUIDocumentationService documentationService)
25+
{
26+
_documentationService = documentationService;
27+
}
28+
29+
[McpServerPrompt(Name = "check_version_compatibility")]
30+
[Description("Check if the installed Fluent UI Blazor NuGet package version is compatible with this MCP Server.")]
31+
public ChatMessage CheckVersionCompatibility(
32+
[Description("The version of Microsoft.FluentUI.AspNetCore.Components currently installed in the project (e.g., '5.0.0', '4.10.3')")] string installedVersion)
33+
{
34+
var expectedVersion = _documentationService.ComponentsVersion;
35+
var mcpServerVersion = FluentUIDocumentationService.McpServerVersion;
36+
var generatedDate = _documentationService.DocumentationGeneratedDate;
37+
38+
var sb = new StringBuilder();
39+
sb.AppendLine("# Fluent UI Blazor Version Compatibility Check");
40+
sb.AppendLine();
41+
42+
sb.AppendLine("## Version Information");
43+
sb.AppendLine();
44+
sb.AppendLine($"| Component | Version |");
45+
sb.AppendLine($"|-----------|---------|");
46+
sb.AppendLine($"| **MCP Server** | {mcpServerVersion} |");
47+
sb.AppendLine($"| **Expected Components Version** | {expectedVersion} |");
48+
sb.AppendLine($"| **Your Installed Version** | {installedVersion} |");
49+
sb.AppendLine($"| **Documentation Generated** | {generatedDate} |");
50+
sb.AppendLine();
51+
52+
// Parse versions for comparison
53+
_ = CheckVersionCompatibilityInternal(installedVersion, expectedVersion, out var compatibilityLevel);
54+
55+
switch (compatibilityLevel)
56+
{
57+
case VersionCompatibility.Exact:
58+
sb.AppendLine("## ✅ Perfect Match");
59+
sb.AppendLine();
60+
sb.AppendLine("Your installed version matches exactly with this MCP Server's documentation.");
61+
sb.AppendLine("All component information, parameters, and examples will be accurate.");
62+
break;
63+
64+
case VersionCompatibility.MinorDifference:
65+
sb.AppendLine("## ⚠️ Minor Version Difference");
66+
sb.AppendLine();
67+
sb.AppendLine("Your installed version has a different minor or patch version.");
68+
sb.AppendLine("Most documentation should be accurate, but some new features or changes may not be reflected.");
69+
sb.AppendLine();
70+
sb.AppendLine("### Recommendations:");
71+
sb.AppendLine($"- Consider upgrading to version **{expectedVersion}** for full compatibility");
72+
sb.AppendLine("- Or update the MCP Server to match your installed version");
73+
break;
74+
75+
case VersionCompatibility.MajorDifference:
76+
sb.AppendLine("## ❌ Major Version Mismatch");
77+
sb.AppendLine();
78+
sb.AppendLine("**Warning**: Your installed version has a different major version.");
79+
sb.AppendLine("There may be significant breaking changes, removed components, or new APIs not covered by this documentation.");
80+
sb.AppendLine();
81+
sb.AppendLine("### Required Actions:");
82+
sb.AppendLine($"1. **Upgrade your NuGet package** to version **{expectedVersion}**:");
83+
sb.AppendLine(" ```shell");
84+
sb.AppendLine($" dotnet add package Microsoft.FluentUI.AspNetCore.Components --version {expectedVersion}");
85+
sb.AppendLine(" ```");
86+
sb.AppendLine();
87+
sb.AppendLine("2. **Or update the MCP Server** to match your installed version:");
88+
sb.AppendLine(" ```shell");
89+
sb.AppendLine($" dotnet tool update --global Microsoft.FluentUI.AspNetCore.Components.McpServer --version {installedVersion}");
90+
sb.AppendLine(" ```");
91+
break;
92+
93+
default:
94+
sb.AppendLine("## ⚠️ Unable to Determine Compatibility");
95+
sb.AppendLine();
96+
sb.AppendLine("Could not parse the version numbers for comparison.");
97+
sb.AppendLine($"Please verify you're using version **{expectedVersion}** of Microsoft.FluentUI.AspNetCore.Components.");
98+
break;
99+
}
100+
101+
sb.AppendLine();
102+
sb.AppendLine("## Task");
103+
sb.AppendLine();
104+
sb.AppendLine("Based on the version compatibility check above:");
105+
sb.AppendLine($"1. Explain any potential issues with using version {installedVersion} when the MCP documentation is for version {expectedVersion}");
106+
sb.AppendLine("2. If there are breaking changes between these versions, list them");
107+
sb.AppendLine("3. Provide migration guidance if an upgrade is recommended");
108+
sb.AppendLine("4. Suggest the best course of action for the user");
109+
110+
return new ChatMessage(ChatRole.User, sb.ToString());
111+
}
112+
113+
/// <summary>
114+
/// Checks version compatibility and returns the level of compatibility.
115+
/// </summary>
116+
private static bool CheckVersionCompatibilityInternal(string installedVersion, string expectedVersion, out VersionCompatibility level)
117+
{
118+
level = VersionCompatibility.Unknown;
119+
120+
// Clean versions (remove any prerelease suffixes for comparison)
121+
var installedClean = CleanVersion(installedVersion);
122+
var expectedClean = CleanVersion(expectedVersion);
123+
124+
if (!Version.TryParse(installedClean, out var installed) ||
125+
!Version.TryParse(expectedClean, out var expected))
126+
{
127+
return false;
128+
}
129+
130+
// Exact match
131+
if (installed.Major == expected.Major &&
132+
installed.Minor == expected.Minor &&
133+
installed.Build == expected.Build)
134+
{
135+
level = VersionCompatibility.Exact;
136+
return true;
137+
}
138+
139+
// Same major version
140+
if (installed.Major == expected.Major)
141+
{
142+
level = VersionCompatibility.MinorDifference;
143+
return true;
144+
}
145+
146+
// Different major version
147+
level = VersionCompatibility.MajorDifference;
148+
return false;
149+
}
150+
151+
/// <summary>
152+
/// Cleans a version string by removing prerelease suffixes.
153+
/// </summary>
154+
private static string CleanVersion(string version)
155+
{
156+
if (string.IsNullOrEmpty(version))
157+
{
158+
return "0.0.0";
159+
}
160+
161+
// Remove prerelease suffix (e.g., "-preview.1", "-rc.2", "-beta")
162+
var dashIndex = version.IndexOf('-');
163+
if (dashIndex > 0)
164+
{
165+
version = version[..dashIndex];
166+
}
167+
168+
// Ensure we have at least 3 parts
169+
var parts = version.Split('.');
170+
if (parts.Length < 3)
171+
{
172+
version = string.Join(".", parts.Concat(Enumerable.Repeat("0", 3 - parts.Length)));
173+
}
174+
175+
return version;
176+
}
177+
178+
private enum VersionCompatibility
179+
{
180+
Unknown,
181+
Exact,
182+
MinorDifference,
183+
MajorDifference
184+
}
185+
}

‎src/Tools/McpServer/Prompts/SetupProjectPrompt.cs‎

Lines changed: 37 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,27 +17,40 @@ namespace Microsoft.FluentUI.AspNetCore.Components.McpServer.Prompts;
1717
public class SetupProjectPrompt
1818
{
1919
private readonly DocumentationGuideService _guideService;
20+
private readonly FluentUIDocumentationService _documentationService;
2021

2122
/// <summary>
2223
/// Initializes a new instance of the <see cref="SetupProjectPrompt"/> class.
2324
/// </summary>
24-
public SetupProjectPrompt(DocumentationGuideService guideService)
25+
public SetupProjectPrompt(DocumentationGuideService guideService, FluentUIDocumentationService documentationService)
2526
{
2627
_guideService = guideService;
28+
_documentationService = documentationService;
2729
}
2830

2931
[McpServerPrompt(Name = "setup_project")]
30-
[Description("Get step-by-step guidance for setting up a new Fluent UI Blazor project.")]
32+
[Description("Get step-by-step guidance for setting up a new Fluent UI Blazor project with the correct package version.")]
3133
public ChatMessage SetupProject(
3234
[Description("The type of Blazor project: 'server', 'wasm', 'hybrid', or 'maui'")] string projectType,
3335
[Description("Optional: specific features to include (e.g., 'icons', 'datagrid', 'charts')")] string? features = null)
3436
{
3537
var installGuide = _guideService.GetGuideContent("installation");
38+
var componentsVersion = _documentationService.ComponentsVersion;
39+
var mcpServerVersion = FluentUIDocumentationService.McpServerVersion;
3640

3741
var sb = new StringBuilder();
3842
sb.AppendLine($"# Set Up a Fluent UI Blazor {projectType.ToUpperInvariant()} Project");
3943
sb.AppendLine();
4044

45+
// Version compatibility information
46+
sb.AppendLine("## Version Information");
47+
sb.AppendLine();
48+
sb.AppendLine($"- **MCP Server Version**: {mcpServerVersion}");
49+
sb.AppendLine($"- **Compatible Components Version**: {componentsVersion}");
50+
sb.AppendLine();
51+
sb.AppendLine("> ⚠️ **Important**: For optimal compatibility with this MCP Server, install the matching version of the NuGet package.");
52+
sb.AppendLine();
53+
4154
if (!string.IsNullOrEmpty(installGuide) && installGuide.Length > 100)
4255
{
4356
sb.AppendLine("## Installation Guide Reference");
@@ -66,11 +79,32 @@ public ChatMessage SetupProject(
6679
}
6780

6881
sb.AppendLine();
82+
sb.AppendLine("## Required NuGet Packages");
83+
sb.AppendLine();
84+
sb.AppendLine("```shell");
85+
sb.AppendLine($"dotnet add package Microsoft.FluentUI.AspNetCore.Components --version {componentsVersion}");
86+
87+
if (!string.IsNullOrEmpty(features))
88+
{
89+
if (features.Contains("icon", StringComparison.OrdinalIgnoreCase))
90+
{
91+
sb.AppendLine($"dotnet add package Microsoft.FluentUI.AspNetCore.Components.Icons --version {componentsVersion}");
92+
}
93+
94+
if (features.Contains("emoji", StringComparison.OrdinalIgnoreCase))
95+
{
96+
sb.AppendLine($"dotnet add package Microsoft.FluentUI.AspNetCore.Components.Emoji --version {componentsVersion}");
97+
}
98+
}
99+
100+
sb.AppendLine("```");
101+
sb.AppendLine();
102+
69103
sb.AppendLine("## Task");
70104
sb.AppendLine();
71105
sb.AppendLine($"Provide complete step-by-step instructions for setting up a Blazor {projectType} project with Fluent UI Blazor:");
72106
sb.AppendLine("1. Project creation commands");
73-
sb.AppendLine("2. NuGet package installation");
107+
sb.AppendLine($"2. NuGet package installation (use version **{componentsVersion}**)");
74108
sb.AppendLine("3. Program.cs configuration");
75109
sb.AppendLine("4. _Imports.razor setup");
76110
sb.AppendLine("5. Layout configuration");

‎src/Tools/McpServer/Services/FluentUIDocumentationService.cs‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
// This file is licensed to you under the MIT License.
33
// ------------------------------------------------------------------------
44

5+
using System.Reflection;
56
using Microsoft.FluentUI.AspNetCore.Components.McpServer.Models;
67

78
namespace Microsoft.FluentUI.AspNetCore.Components.McpServer.Services;
@@ -31,6 +32,29 @@ public FluentUIDocumentationService(string? jsonDocumentationPath = null)
3132
/// </summary>
3233
public bool IsAvailable => _reader.IsAvailable;
3334

35+
/// <summary>
36+
/// Gets the version of the Fluent UI Components library that this documentation was generated from.
37+
/// </summary>
38+
public string ComponentsVersion => _reader.Metadata?.AssemblyVersion ?? "Unknown";
39+
40+
/// <summary>
41+
/// Gets the version of the MCP Server.
42+
/// </summary>
43+
public static string McpServerVersion
44+
{
45+
get
46+
{
47+
var assembly = Assembly.GetExecutingAssembly();
48+
var version = assembly.GetName().Version;
49+
return version?.ToString(3) ?? "Unknown";
50+
}
51+
}
52+
53+
/// <summary>
54+
/// Gets the date when the documentation was generated.
55+
/// </summary>
56+
public string DocumentationGeneratedDate => _reader.Metadata?.GeneratedDateUtc ?? "Unknown";
57+
3458
/// <summary>
3559
/// Initializes the component and enum caches from JSON data.
3660
/// </summary>

‎src/Tools/McpServer/Services/JsonBasedDocumentationService.cs‎

Whitespace-only changes.

0 commit comments

Comments
 (0)