@@ -265,119 +265,6 @@ graph TB
265265
266266The platform includes an intelligent AI assistant powered by RAG (Retrieval Augmented Generation) technology through a dedicated ** Model Context Protocol (MCP)** server.
267267
268- ### Architecture
269-
270- ```
271- UI (React) → Backend (Elysia/Node.js) → MCP Server (Python/FastAPI) → OpenAI GPT-5
272- ↓
273- RAG Knowledge Base
274- (Platform Documentation)
275- ```
276-
277- The AI assistant is built on a ** three-tier architecture** :
278-
279- 1 . ** Frontend Layer** (` ui/src/components/AIChatOverlay.tsx ` ): Streaming chat interface with SSE
280- 2 . ** Proxy Layer** (` backend/src/routes/ai.ts ` ): Authentication & request forwarding
281- 3 . ** MCP Server** (` mcp-server/ ` ): Python-based FastAPI server with RAG capabilities
282-
283- ### 🔌 MCP (Model Context Protocol) Server
284-
285- The ** MCP server** is a standalone Python service that handles AI interactions:
286-
287- - ** RAG Implementation** : Vector-based semantic search over platform documentation
288- - ** OpenAI Integration** : Uses GPT-5 with function calling for intelligent responses
289- - ** Knowledge Base** : Pre-loaded chunks of SMART on FHIR platform documentation
290- - ** Streaming Support** : Server-Sent Events (SSE) for real-time response streaming
291- - ** Keycloak Authentication** : Uses SMART Backend Services (JWT) to call backend APIs
292-
293- ** Why MCP?** Separating the AI logic into a dedicated Python server enables:
294- - Better AI/ML library ecosystem (OpenAI, LangChain, vector databases)
295- - Independent scaling and deployment
296- - Easier integration with Claude Desktop and other MCP clients
297- - Clear separation between Node.js business logic and Python AI capabilities
298-
299- ### 🧠 Capabilities
300-
301- - ** Navigation Guidance** : Help finding the right administrative sections
302- - ** Configuration Assistance** : Step-by-step setup guidance with function calling
303- - ** SMART on FHIR Expertise** : Deep knowledge of specifications and best practices
304- - ** Troubleshooting Support** : Context-aware solutions with source citations
305- - ** Real-time Documentation** : RAG ensures responses reflect current platform state
306- - ** Function Execution** : Can call backend APIs to fetch live data (users, apps, servers)
307- - ** Streaming Responses** : Real-time generation with reasoning transparency
308-
309- ### 💬 Example Queries
310-
311- ```
312- "How do I register a new SMART app?"
313- "What scopes do I need for patient data access?"
314- "Show me the OAuth monitoring dashboard"
315- "List all healthcare users in the system" (calls backend API)
316- "How do I configure launch contexts for my app?"
317- "What are the security best practices?"
318- "Explain the OAuth flow for EHR launch"
319- ```
320-
321- ### 🔧 MCP Server Setup
322-
323- See [ ` mcp-server/README.md ` ] ( mcp-server/README.md ) for detailed setup instructions.
324-
325- ** Quick Start:**
326- ``` bash
327- cd mcp-server
328- uv venv && uv sync
329- uv run python src/main.py
330- ```
331-
332- ** Requirements:**
333- - Python 3.11+
334- - OpenAI API key
335- - Keycloak credentials (for backend API access)
336-
337- The MCP server runs on ` localhost:8081 ` and is proxied by the backend at ` /api/ai/* ` endpoints.
338-
339- ## 🛠️ Development
340-
341- ### Project Structure
342-
343- ```
344- proxy-smart/
345- ├── backend/ # Node.js backend API
346- ├── ui/ # React admin interface
347- ├── test/ # Comprehensive test suites
348- ├── keycloak/ # Identity provider configuration
349- ├── docs/ # Complete documentation
350- ├── .github/ # CI/CD workflows
351- └── scripts/ # Development and deployment scripts
352- ```
353-
354- ### Development Commands
355-
356- ``` bash
357- # Development
358- bun run dev # Start all development servers
359- bun run dev:backend # Backend only
360- bun run dev:ui # Frontend only
361-
362- # Building
363- bun run build # Build all projects
364- bun run build:backend # Build backend
365- bun run build:ui # Build frontend
366-
367- # Testing
368- bun run test # Run all tests
369- bun run test:smart-flows # SMART App Launch tests
370- bun run test:backend-services # Backend API tests
371-
372- # API Generation
373- bun run generate # Generate client APIs
374- bun run validate-api # Validate OpenAPI specs
375-
376- # Version Management
377- bun run version:sync # Sync all package.json versions
378- bun run version:bump patch # Bump patch version
379- ```
380-
381268### Docker Commands
382269
383270Proxy Smart provides multiple Docker deployment strategies for different use cases:
0 commit comments