# wealthy/wealthy-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/wealthy/wealthy-mcp
- Repository: https://github.com/wealthy/wealthy-mcp

## Overview

##### Project Type and Purpose
- This is an open-source CLI-driven server application (written in Go) that implements a “Model Context Protocol” (MCP) server.
- It integrates with trading clients (Claude, Cursor), authenticates users against the Wealthy trading platform, routes natural-language queries through an embedded LLM (Falcon), and fetches market data or executes trading actions via Wealthy’s APIs.

##### File Structure
- cmd/wealthy-mcp
- Entry point (“mcp_server.go”) and prompt handling (“prompt.go”).
- internal/
- auth.go – user authentication & session management.
- falcon/ – LLM integration module (model loading, request/response).
- websocket/ – real-time price streaming support.
- utils/ – shared context, error handling, config utilities.
- tools/ – developer/helper scripts for Falcon model.
- Configuration & CI: go.mod, Makefile, GitHub Actions workflow for releases.

##### README for Additional Insights
- Describes MCP client configuration, supported query types (get_price, get_holdings, etc.), and future roadmap (WebSocket, alerts).
- Emphasizes OAuth‐like login flow & natural-language interface via Falcon LLM.

##### Main Components
a. Wealthy-MCP CLI/Server
– Launches a local server on a configurable port.
– Reads command-line args (addr=…).
b. MCP Client (Claude / Cursor)
– Connects to Wealthy-MCP server via child-process protocol; exchanges JSON messages.
c. Authentication Module
– Presents login UI (browser redirect to Wealthy login page).
– Receives credentials/cookies, issues session context.
d. Falcon LLM Module
– Loads local/remote Falcon model.
– Receives text prompt (natural-language query), returns parsed intent & parameters.
e. Wealthy Trading Platform REST/WebSocket APIs
– Query endpoints: price, holdings, positions, orders, trade ideas, etc.
– Real-time WebSocket feed for updates (future roadmap).
f. WebSocket Service (internal/websocket/price.go)
– Manages live subscriptions, pushes updates to client via MCP channel.
g. Utilities & Context
– Shared config, logging, timeouts.

##### Relationships and Data Flow
1. MCP Client spawns Wealthy-MCP process → establishes IPC channel (stdin/stdout).
2. Client sends JSON query (e.g., “get_price RELIANCE”).
3. Server → Auth module ensures valid session (or triggers login).
4. Server forwards query text to Falcon module → receives structured intent.
5. Intent handler invokes Wealthy REST API (HTTP) or WebSocket feed.
6. Response data is formatted into MCP response JSON.
7. Server writes JSON back to MCP client → client displays to user.

##### Architectural Patterns & Principles
- Modular “hexagonal” design: clear separation between transport (MCP IPC), business logic (intent handling), external services (Wealthy APIs), and LLM integration.
- Single binary, configurable via flags & JSON config files.
- Dependency injection via Go interfaces in internal packages.

##### Final Checklist
- [ ] Components: MCP Client, Wealthy-MCP server, Auth, Falcon, Web API, WebSocket, Utils
- [ ] Data flows and protocols labeled
- [ ] Configuration files & entry point noted

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    MCP["MCP Client (Claude/Cursor)"]:::external

    %% Server process
    subgraph "Wealthy-MCP CLI/Server"
        Entry["mcp_server.go\n(Entry Point)"]:::cli
        Prompt["prompt.go\n(Prompt Handling)"]:::cli
    end

    %% Internal Modules
    Auth["Authentication Module\n(internal/auth.go)"]:::internal
    subgraph "Falcon LLM Module"
        FalconCore["falcon.go"]:::internal
        FalconModels["models.go"]:::internal
    end
    WSModule["WebSocket Service\n(internal/websocket/price.go)"]:::internal
    Utils["Shared Utilities & Context\n(internal/utils/context.go)"]:::internal

    %% External Trading Services
    RestAPI["Wealthy Trading Platform REST API"]:::external
    WSTrading["Wealthy WebSocket Feed"]:::external,future

    %% Developer Tools
    subgraph "Developer Tools"
        FalconTool["falcon.go\n(tools)"]:::internal
        FalconDocs["falcon.md"]:::internal
        FalconTests["falcon_test.go"]:::internal
    end

    %% Connections
    MCP -->|"stdin/stdout JSON RPC"| Entry
    Entry --> Prompt
    Entry -->|"validate session"| Auth
    Entry -->|"natural-language query"| FalconCore
    FalconCore --> FalconModels
    Entry --> Utils
    Entry -->|"HTTP/HTTPS REST"| RestAPI
    Entry -->|"invoke WS service"| WSModule
    WSModule -->|"WebSocket"| WSTrading
    RestAPI -->|"HTTP response"| Entry
    Entry -->|"JSON RPC response"| MCP

    %% Click Events
    click Entry "https://github.com/wealthy/wealthy-mcp/blob/master/cmd/wealthy-mcp/mcp_server.go"
    click Prompt "https://github.com/wealthy/wealthy-mcp/blob/master/cmd/wealthy-mcp/prompt.go"
    click Auth "https://github.com/wealthy/wealthy-mcp/blob/master/internal/auth.go"
    click FalconCore "https://github.com/wealthy/wealthy-mcp/blob/master/internal/falcon/falcon.go"
    click FalconModels "https://github.com/wealthy/wealthy-mcp/blob/master/internal/falcon/models.go"
    click WSModule "https://github.com/wealthy/wealthy-mcp/blob/master/internal/websocket/price.go"
    click Utils "https://github.com/wealthy/wealthy-mcp/blob/master/internal/utils/context.go"
    click FalconTool "https://github.com/wealthy/wealthy-mcp/blob/master/tools/falcon.go"
    click FalconDocs "https://github.com/wealthy/wealthy-mcp/blob/master/tools/falcon.md"
    click FalconTests "https://github.com/wealthy/wealthy-mcp/blob/master/tools/falcon_test.go"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef internal fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef external fill:#FFD580,stroke:#000,stroke-width:1px;
    classDef future stroke-dasharray: 5 5;
```
