How jmandel/health-record-mcp works
──────────────────────────────
Project Type & Core Purpose
• This is a specialized backend server and toolkit that sits between Electronic Health Records (EHR) and external AI/LLM agents.
• It implements the SMART on FHIR client to fetch detailed patient data and then exposes that data via empowered MCP tools (grep_record, query_record, eval_record).
• It supports multiple modes: a standalone web client mode (using HTML/JS), a CLI/standard IO mode that builds a local SQLite database, and an SSE (Server-Sent Events) mode for persistent networked connections with OAuth 2.1.
──────────────────────────────
Out the Main Components
A. Client-Side Components
1. SMART on FHIR Web Client
• Represented by “opener.html” (and possibly other static files in the “static” directory, e.g. db-picker.html).
• Function: Initiate the SMART App Launch flow, authenticate with the EHR provider, and fetch a comprehensive set of FHIR resources.
2. External AI / LLM Interface (Consumer)
• Function: Sends queries/requests to the MCP endpoint (e.g., for performing a grep, SQL, or eval function).
B. Server-Side Components
1. MCP Server components (core engine)
• Two modes/capabilities:
a. Local MCP Server via Stdio/CLI (referencing “src/cli.ts”)
• Two-step: First, fetch data and create a local SQLite database; second, load the database and start the MCP server communicating via standard input/output.
b. Persistent MCP Server via SSE (referencing “src/sse.ts”)
• Provides a network endpoint using SSE, handles OAuth 2.1 endpoints (/authorize, /token, etc.), and has an experimental authentication flow.
• MCP Server component with sub-nodes or annotations explaining its dual mode of operation.
2. Authentication & OAuth Endpoints
• Dedicated endpoints for OAuth endpoints (illustrate: /authorize, /token, /register).
• These are part of the MCP SSE mode and are critical for secure client (and AI agent) approval.
C. Data Management Components
1. Database Storage (SQLite Database)
• Use a node for the local SQLite database that gets created when running the CLI with "--create-db" flag.
• That absolute paths are recommended for configuration (as observed in the README).
2. FHIR Data Extraction & Transformation
• This node interfaces between the fetched data and the MCP tools (grep_record, query_record, eval_record).
D. Configuration & Deployment
1. Configuration Files
• Role of various configuration files (e.g., “config.epicprod.json”, “sample-config.json”) which tailor the system’s behavior to different EHR providers (Epic, SMART sandbox, etc.).
2. Docker and CI/CD
• That the project includes a Dockerfile and GitHub workflows (”.github/workflows/build-and-package.yml”), indicating that containerization and automated builds/deployments are part of the overall ecosystem.
──────────────────────────────
Relationships and Data Flow
• “SMART on FHIR Web Client” → (data extraction using the SMART App Launch flow) → “FHIR Data Extraction & Transformation Module”
• “FHIR Data Extraction” → “MCP Server”
• That once extracted, data enters the MCP process and is either stored in an SQLite database (CLI mode) or retained in memory for SSE sessions.
• “MCP Server” ←→ “Authentication & OAuth Endpoints”
• “MCP Server” ↔ “External AI / LLM Interface”
• “MCP Server” → “SQLite Database” (when in CLI mode)
• Optionally, include CI/CD/Deployment pipelines (Docker / GitHub Actions) as peripheral nodes that trigger builds and packaging.
──────────────────────────────
Technology & Architectural Patterns
A. Architectural Patterns
• Separation of concerns: clearly differentiate between the UI (SMART client), business logic (MCP server, FHIR extraction), and persistence (SQLite database).
• Use of asynchronous communication (postMessage for the standing web client, and SSE for persistent server mode).
B. Technologies and Frameworks
• Use a note to mention that the project uses TypeScript (files in “src”, “clientTypes.ts”, etc.).
• Mention the use of Docker (via Dockerfile) and continuous integration (via GitHub workflows).
• The OAuth 2.1 implementation and the Server-Sent Events model is essential to the design.
──────────────────────────────