Skip to content

Commit c35b472

Browse files
elbrunoelbruno
committed
Add Hugging Face MCP Server integration to Blazor web app with AI capabilities
1 parent 5f1f9f3 commit c35b472

File tree

1 file changed

+274
-0
lines changed

1 file changed

+274
-0
lines changed

‎05-AppCreatedWithGenAI/HFMCP.GenImage/genai-prompt.md

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
# GitHub Copilot Agent Prompt: Add Hugging Face MCP Server Integration to Blazor Web App
2+
3+
## Overview
4+
Transform the existing .NET Aspire Blazor web application to integrate with the Hugging Face MCP (Model Context Protocol) Server for AI image generation and text responses.
5+
6+
## Context
7+
8+
- Starting with a .NET Aspire solution containing 4 projects: ApiService, AppHost, ServiceDefaults, and Web (Blazor)
9+
- Web project currently has basic Weather and Counter pages (to be removed)
10+
- Need to add AI capabilities using Hugging Face MCP Server
11+
- Reference implementation: https://elbruno.com/2025/07/21/%f0%9f%a4%96-using-c-to-call-hugging-face-mcp-server-and-generate-ai-images/
12+
- Sample code: https://github.com/microsoft/Generative-AI-for-beginners-dotnet/blob/main/03-CoreGenerativeAITechniques/src/MCP-01-HuggingFace/Program.cs
13+
14+
## Requirements
15+
16+
### 1. Home Page Enhancement (Main AI Interface)
17+
- **Replace current Home.razor** with an AI interaction interface
18+
- **User Input**: Text box for prompts (e.g., "create a pixelated image of a beaver")
19+
- **Predefined Suggestions**: Include quick-start suggestion buttons:
20+
- `who am I`
21+
- `create a pixelated image of a beaver`
22+
- **AI Response Display**:
23+
- Show generated images when AI responds with images
24+
- Show text responses when AI responds with text
25+
- **Chat History**: Display conversation history between user and AI
26+
- **Loading States**: Show loading indicators during AI processing
27+
- **Error Handling**: Display user-friendly error messages
28+
29+
### 2. Settings Page Implementation
30+
Create a new Settings.razor page with secure configuration management:
31+
32+
#### Required Settings Fields
33+
34+
- **Hugging Face Access Token** (masked input, required)
35+
- **Model Name** (text input, default: "gpt-4.1-mini") - allows user to type any model name
36+
37+
#### AI Provider Settings (Choose One)
38+
39+
Either configure **GitHub Models** OR **Azure OpenAI** (at least one required):
40+
41+
**GitHub Models (Optional)**:
42+
- **GitHub Model Access Token** (masked input)
43+
44+
**Azure OpenAI (Optional)**:
45+
- **Azure OpenAI service endpoint** (text input, not masked)
46+
- **Azure OpenAI service ApiKey** (masked input)
47+
48+
#### Field Order
49+
50+
1. Hugging Face Access Token
51+
2. Model Name
52+
3. GitHub Models Access Token
53+
4. Azure OpenAI (optional)
54+
55+
#### Settings Page UX Requirements
56+
57+
- **Save Confirmation**: Display success message when settings are saved
58+
- **Visual Indicators**: Show configuration status badges for each service:
59+
- Green "Configured" badge when tokens are provided
60+
- Yellow "Required" badge for missing Hugging Face token
61+
- Clear indication of which services are ready to use
62+
- **User Feedback**: Clear messaging about what was saved and current configuration state
63+
64+
#### Security Requirements
65+
66+
- Use ASP.NET Core's User Secrets for development
67+
- Use secure configuration providers for production
68+
- All sensitive data must be encrypted at rest
69+
- Settings should persist between application restarts
70+
- Implement validation for all inputs
71+
72+
### 3. Navigation Updates
73+
- Remove Counter and Weather pages from the navigation and delete the page files
74+
- Add Settings page to NavMenu.razor
75+
- Update navigation to include AI-focused branding
76+
- Ensure responsive design for both desktop and mobile
77+
78+
### 4. Technical Implementation
79+
80+
#### Required NuGet Packages:
81+
```xml
82+
<PackageReference Include="Microsoft.Extensions.AI" />
83+
<PackageReference Include="Azure.AI.Inference" />
84+
<PackageReference Include="Azure.AI.OpenAI" />
85+
<PackageReference Include="ModelContextProtocol.Client" />
86+
<PackageReference Include="System.ClientModel" />
87+
```
88+
89+
#### Core Components to Implement:
90+
91+
1. **AI Service Layer**:
92+
- Create `IAIService` interface
93+
- Implement `AIService` with MCP client integration AND Azure OpenAI support
94+
- Support multiple AI providers (Azure OpenAI, GitHub Models, with fallback options)
95+
- Handle image generation and text responses
96+
- Prioritize Azure OpenAI when configured, fallback to GitHub Models
97+
98+
2. **Configuration Service**:
99+
- Create `IConfigurationService` interface
100+
- Implement secure settings storage and retrieval
101+
- Support environment-specific configurations
102+
- Validate that at least one AI provider (Azure OpenAI OR GitHub Models) is configured along with Hugging Face
103+
104+
3. **Azure OpenAI Integration**:
105+
- Support standard Azure OpenAI REST API endpoints
106+
- Handle proper authentication with API keys
107+
- Support deployment-based model calls
108+
- Implement error handling for Azure OpenAI specific errors
109+
110+
4. **MCP Integration**:
111+
- Initialize Hugging Face MCP client with proper authentication
112+
- Connect to MCP server: https://huggingface.co/mcp
113+
- Handle tool discovery and invocation
114+
- Implement proper error handling and retry logic
115+
116+
#### Key Implementation Patterns:
117+
```csharp
118+
// MCP Client Setup
119+
var hfHeaders = new Dictionary<string, string>
120+
{
121+
{ "Authorization", $"Bearer {hfApiKey}" }
122+
};
123+
var clientTransport = new SseClientTransport(new()
124+
{
125+
Name = "HF Server",
126+
Endpoint = new Uri("https://huggingface.co/mcp"),
127+
AdditionalHeaders = hfHeaders
128+
});
129+
await using var mcpClient = await McpClientFactory.CreateAsync(clientTransport);
130+
131+
// Chat Client with MCP Tools
132+
var tools = await mcpClient.ListToolsAsync();
133+
IChatClient client = GetChatClient(); // GitHub Models or Azure OpenAI
134+
var chatOptions = new ChatOptions
135+
{
136+
Tools = [.. tools],
137+
ModelId = deploymentName
138+
};
139+
```
140+
141+
#### Response Handling:
142+
- Check response content type
143+
- Display images with proper formatting and download options
144+
- Format text responses with markdown support
145+
- Handle streaming responses for better UX
146+
147+
### 5. User Experience Requirements
148+
149+
#### Home Page UX:
150+
- Clean, modern chat interface
151+
- Clear prompt input with placeholder text
152+
- Responsive image display with zoom capabilities
153+
- Copy/share functionality for generated content
154+
- Clear visual distinction between user messages and AI responses
155+
156+
#### Settings Page UX:
157+
- Intuitive form layout with proper labeling
158+
- Password visibility toggles for sensitive fields
159+
- Save confirmation messages
160+
- Input validation with helpful error messages
161+
- Quick setup buttons for common configurations (GitHub Models, Azure OpenAI, Ollama)
162+
163+
### 6. Error Handling & Validation
164+
- Network connectivity issues
165+
- Invalid API tokens
166+
- Rate limiting from AI services
167+
- Malformed responses
168+
- Image loading failures
169+
- Configuration validation
170+
171+
### 7. Security Considerations
172+
- Never log sensitive tokens
173+
- Implement proper CORS policies
174+
- Use HTTPS for all external communications
175+
- Validate all user inputs
176+
- Implement rate limiting on AI requests
177+
- Secure token storage using ASP.NET Core Data Protection
178+
179+
### 8. Testing Requirements
180+
- Unit tests for AI service integration
181+
- Integration tests for MCP client
182+
- UI tests for critical user flows
183+
- Configuration validation tests
184+
- Error scenario testing
185+
186+
## Acceptance Criteria
187+
188+
1. ✅ User can enter prompts and receive AI responses
189+
2. ✅ Generated images display properly in the interface
190+
3. ✅ Text responses render with appropriate formatting
191+
4. ✅ Settings page allows secure configuration of all required tokens
192+
5. ✅ Settings persist between application restarts
193+
6. ✅ Navigation includes new Settings page
194+
7. ✅ Error states provide helpful feedback to users
195+
8. ✅ Application handles both successful and failed AI requests gracefully
196+
9. ✅ Security best practices are implemented for sensitive data
197+
10. ✅ Responsive design works on desktop and mobile devices
198+
11. ✅ **Azure OpenAI Integration**: Users can configure and use Azure OpenAI instead of GitHub Models
199+
12. ✅ **Provider Prioritization**: Azure OpenAI is prioritized when both providers are configured
200+
13. ✅ **Flexible Configuration**: Users can choose either GitHub Models OR Azure OpenAI (with Hugging Face required)
201+
14. ✅ **Error Resolution**: Fixed "No configured AI provider available for chat" error when Azure OpenAI is configured
202+
15. ✅ **MCP Tools Panel**: Collapsible panel showing Hugging Face MCP server tools when configured
203+
16. ✅ **Proper MCP Integration**: Following Microsoft sample pattern from GitHub repository
204+
205+
## Implementation Status: COMPLETED ✅
206+
207+
### Final Session Completion:
208+
- ✅ **Package Version Alignment**: Successfully updated to Microsoft.Extensions.AI 9.7.1 to match GitHub sample
209+
- ✅ **Extension Method Resolution**: Resolved AsIChatClient() extension method availability issues
210+
- ✅ **Microsoft.Extensions.AI.OpenAI**: Added preview package (9.7.1-preview.1.25365.4)
211+
- ✅ **Microsoft.Extensions.AI.AzureAIInference**: Added preview package (9.7.1-preview.1.25365.4)
212+
- ✅ **System.ClientModel**: Updated to version 1.4.2 to resolve package conflicts
213+
- ✅ **Builder Pattern Implementation**: Using proper AsIChatClient().AsBuilder().UseFunctionInvocation().Build()
214+
- ✅ **Runtime Testing**: Application builds clean and runs successfully
215+
- ✅ **No Casting Errors**: Resolved InvalidCastException by using proper extension methods
216+
217+
### Key Technical Resolution:
218+
- **Issue**: System.InvalidCastException when casting Azure OpenAI clients to IChatClient
219+
- **Root Cause**: Direct casting instead of using Microsoft.Extensions.AI extension methods
220+
- **Solution**: Used proper AsIChatClient() extension methods following the Microsoft GitHub sample pattern
221+
- **Pattern**: chatClient.AsIChatClient().AsBuilder().UseFunctionInvocation().Build()
222+
- **Verification**: Clean build with no warnings, application running successfully
223+
224+
### Previous Session Achievements:
225+
- ✅ **Fixed MCP Package Issues**: Updated to use correct ModelContextProtocol packages (v0.3.0-preview.3)
226+
- ✅ **MCP Service Implementation**: Created proper MCP service following GitHub sample pattern
227+
- ✅ **AI Service Refactoring**: Complete rewrite to use MCP integration with Microsoft.Extensions.AI
228+
- ✅ **Home Page Enhancement**: Added collapsible MCP tools panel
229+
- ✅ **Application Architecture**: Complete implementation following Microsoft patterns
230+
231+
### Key Features Implemented:
232+
1. **Proper MCP Integration**: Following exact pattern from Microsoft GitHub sample
233+
2. **SseClientTransport**: Server-Sent Events transport for MCP communication
234+
3. **McpClientFactory**: Proper MCP client initialization
235+
4. **Function Invocation**: Microsoft.Extensions.AI pattern with MCP tools
236+
5. **Dual Provider Support**: Azure OpenAI and GitHub Models with MCP tools
237+
6. **Tools Panel**: Collapsible UI showing available Hugging Face MCP tools
238+
7. **Error Handling**: Comprehensive error handling for MCP operations
239+
8. **Image Display**: Automatic detection and display of images from AI responses
240+
9. **Configurable MCP Server**: Settings allow customization of Hugging Face MCP server endpoint
241+
242+
### Latest Enhancements (Current Session):
243+
- ✅ **Smart Image Detection**: Automatically extracts image URLs from AI responses using multiple patterns:
244+
- Markdown image syntax: `![alt text](url)`
245+
- Direct HTTP/HTTPS URLs with image extensions
246+
- Hugging Face specific URLs (e.g., evalstate-flux1-schnell.hf.space)
247+
- ✅ **Enhanced Image Display**:
248+
- Proper image sizing and responsive design
249+
- View full size and copy URL functionality
250+
- Error handling for failed image loads
251+
- Removes markdown syntax from text when images are displayed separately
252+
- ✅ **Configurable MCP Server**: Added setting for Hugging Face MCP Server with default value `https://huggingface.co/mcp`
253+
- ✅ **Settings Page Enhancement**: Added Hugging Face MCP Server field to configuration
254+
- ✅ **Code Consistency**: Updated all services to use the configurable MCP server endpoint
255+
256+
## Implementation Priority: COMPLETED ✅
257+
1. ✅ **Phase 1**: Basic MCP integration and Home page AI interface
258+
2. ✅ **Phase 2**: Settings page with secure configuration
259+
3. ✅ **Phase 3**: Enhanced UX, error handling, and responsive design
260+
4. ✅ **Phase 4**: Image detection, display, and MCP server configuration
261+
262+
## Additional Notes
263+
- Follow .NET Aspire patterns and conventions ✅
264+
- Ensure compatibility with existing ServiceDefaults ✅
265+
- Maintain clean separation of concerns ✅
266+
- Use dependency injection throughout ✅
267+
- Implement proper logging for debugging and monitoring ✅
268+
- Consider performance implications of image generation and display ✅
269+
- **MCP Integration**: Follows Microsoft's recommended patterns for Model Context Protocol ✅
270+
- **Package Versions**: Uses stable and preview packages as specified in Microsoft samples ✅
271+
- **Image Processing**: Smart extraction and display of images from AI responses ✅
272+
- **User Experience**: Clean image gallery with actions for viewing and copying ✅
273+
274+
This implementation successfully transforms the basic Aspire starter into a fully functional AI-powered image generation and chat application with proper MCP integration, smart image detection and display, while maintaining security and user experience best practices.

0 commit comments

Comments
 (0)