# kartha-ai/agentcare-mcp architecture

> Architecture diagram of the GitHub repository kartha-ai/agentcare-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kartha-ai/agentcare-mcp
- Repository: https://github.com/kartha-ai/agentcare-mcp

## Overview

The Agent Care project is an MCP (Model Context Protocol) server built to integrate with EMR systems like Cerner and Epic. It exposes a variety of healthcare tools for FHIR data access and medical research (including PubMed, Clinical Trials, and FDA data) and is designed to work with client applications like Claude Desktop and Goose Desktop.

##### Main Components
- FHIR Connector: Represent the modules in both the build and src trees under “server/connectors/fhir”. This includes components such as the FhirClient, Formatters, Helper, and Prompter. These components encapsulate FHIR-related functionality used to interface with EMRs.
- Medical Research Connector: Similarly, show the “server/connectors/medical” components (ClinicalTrials, FDA, and PubMed) that allow integrations with external medical research data providers.
- Handlers: Include the PromptHandler and ToolHandler components that manage incoming commands and tool invocations.
- Utilities & Authentication: Illustrate the utility functions and authentication modules (Auth, AuthConfig, Cache). Note that these manage OAuth2 authentication with EMRs, token exchange, and caching of responses.
- Configuration: Mark external configuration files (in the config folder and environment variables) that tailor connectivity for different EMRs (Cerner and Epic).
- External Services:
- Medical Research APIs: Include PubMed, Clinical Trials, and FDA APIs.
- OAuth2 Provider: For handling user authentication and authorization.
- Claude & Goose Desktop: Represent the client/agent interfaces used to interact with the server.

##### Relationships and Data Flows
- Authentication flow: start with the incoming OAuth login request, handled by the Auth modules, then flowing to the EMRs’ OAuth endpoints.

##### Architectural Patterns and Principles
- Separation of Concerns: The clear division between connectors (FHIR and Medical), handlers, and utility modules suggests a modular architecture. Each component should be shown as an isolated block working as part of a layered system.
- Client-Server Interaction: Emphasize the separation between external client interfaces (Claude/Goose) and the back-end service logic.
- External Configuration: Note the role of configuration files (.env, JSON configs, etc.) that support different environments (Cerner vs. Epic) by providing unique API endpoints and creds.

##### Relevant Technologies and Libraries
- Programming Languages: Highlight the use of TypeScript (see src/ folder) which compiles down to JavaScript (build/ folder).
- Node.js Runtime: Indicate that the server runs on Node, as seen through scripts like build/index.js.
- OAuth2: Mark its central role in authentication flows.
- FHIR API integration: Emphasize that this is used extensively to interact with the EMRs.
- Caching Mechanism: Represent the caching logic from "Cache.js" to improve response times.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Client Applications"
        cd("Claude Desktop"):::client
        gd("Goose Desktop"):::client
    end

    %% Core Server
    cs["Core MCP Server"]:::internal

    cd --> cs
    gd --> cs

    %% Configuration
    configNode["Configurations"]:::config
    configNode --> cs

    %% Connectors
    subgraph "Connectors"
        subgraph "FHIR Connector"
            fclient["FhirClient"]:::internal
            formatters["Formatters"]:::internal
            helper["Helper"]:::internal
            prompter["Prompter"]:::internal
        end
        subgraph "Medical Research Connector"
            clinical["ClinicalTrials"]:::internal
            fda["FDA"]:::internal
            pubmed["PubMed"]:::internal
        end
    end

    %% Handlers
    subgraph "Handlers"
        promptHandler["PromptHandler"]:::internal
        toolHandler["ToolHandler"]:::internal
    end

    %% Utilities & Authentication
    subgraph "Utilities & Authentication"
        auth["Auth"]:::internal
        authConfig["AuthConfig"]:::internal
        cache["Cache"]:::internal
        authSuccess["AuthSuccess"]:::internal
    end

    %% External Systems
    cerner["Cerner EMR"]:::external
    epic["Epic EMR"]:::external
    pubmedAPI["PubMed API"]:::external
    clinicalAPI["ClinicalTrials API"]:::external
    fdaAPI["FDA API"]:::external
    oauthProvider["OAuth2 Provider"]:::external

    %% Data flows from Core Server to internal modules
    cs -->|"routes to"| fclient
    cs -->|"routes to"| clinical
    cs -->|"routes to"| promptHandler
    cs -->|"initiates auth"| auth
    cs -->|"triggers tools"| toolHandler

    %% FHIR Connector interactions with EMRs
    fclient -->|"FHIR calls"| cerner
    fclient -->|"FHIR calls"| epic
    formatters --- cerner
    formatters --- epic
    helper --- cerner
    helper --- epic
    prompter --- cerner
    prompter --- epic

    %% Medical Research Connector interactions with external APIs
    clinical -->|"queries"| clinicalAPI
    fda -->|"queries"| fdaAPI
    pubmed -->|"queries"| pubmedAPI

    %% Authentication flow
    auth -->|"OAuth request"| oauthProvider
    oauthProvider -->|"auth response"| cerner
    oauthProvider -->|"auth response"| epic

    %% Caching responses from external systems
    cerner --> cache
    epic --> cache
    pubmedAPI --> cache
    clinicalAPI --> cache
    fdaAPI --> cache
    cache --> cs

    %% Click Events
    click cs "https://github.com/kartha-ai/agentcare-mcp/blob/main/build/server/AgentCareServer.js"
    click fclient "https://github.com/kartha-ai/agentcare-mcp/blob/main/build/server/connectors/fhir/FhirClient.js"
    click formatters "https://github.com/kartha-ai/agentcare-mcp/blob/main/build/server/connectors/fhir/Formatters.js"
    click helper "https://github.com/kartha-ai/agentcare-mcp/blob/main/build/server/connectors/fhir/Helper.js"
    click prompter "https://github.com/kartha-ai/agentcare-mcp/blob/main/build/server/connectors/fhir/Prompter.js"
    click clinical "https://github.com/kartha-ai/agentcare-mcp/blob/main/build/server/connectors/medical/ClinicalTrials.js"
    click fda "https://github.com/kartha-ai/agentcare-mcp/blob/main/build/server/connectors/medical/FDA.js"
    click pubmed "https://github.com/kartha-ai/agentcare-mcp/blob/main/build/server/connectors/medical/PubMed.js"
    click promptHandler "https://github.com/kartha-ai/agentcare-mcp/blob/main/build/server/handlers/PromptHandler.js"
    click toolHandler "https://github.com/kartha-ai/agentcare-mcp/blob/main/build/server/handlers/ToolHandler.js"
    click auth "https://github.com/kartha-ai/agentcare-mcp/blob/main/build/server/utils/Auth.js"
    click authConfig "https://github.com/kartha-ai/agentcare-mcp/blob/main/build/server/utils/AuthConfig.js"
    click cache "https://github.com/kartha-ai/agentcare-mcp/blob/main/build/server/utils/Cache.js"
    click authSuccess "https://github.com/kartha-ai/agentcare-mcp/blob/main/build/server/utils/auth-success.html"
    click configNode "https://github.com/kartha-ai/agentcare-mcp/tree/main/config/"

    %% Styles
    classDef internal fill:#cde,stroke:#333,stroke-width:2px;
    classDef external fill:#fee,stroke:#900,stroke-width:2px;
    classDef config fill:#dfd,stroke:#060,stroke-width:2px;
    classDef client fill:#ffd,stroke:#bb0,stroke-width:2px;
```
