# kevin1chun/robinhood-for-agents architecture

> Architecture diagram of the GitHub repository kevin1chun/robinhood-for-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kevin1chun/robinhood-for-agents
- Repository: https://github.com/kevin1chun/robinhood-for-agents

## Overview

robinhood-for-agents is an MCP server and TypeScript client for Robinhood research and trading. An agent connects over MCP; standard mode forwards calls to Robinhood’s hosted Trading MCP, while web mode registers local tools backed by the web API. Web-mode login establishes a reusable session, then tools cover portfolio, research, orders, options, and account utilities. The client owns HTTP requests and session handling; review calculations also have a pure compute layer. README capabilities are represented, though unsampled tool implementations are shown only at their documented subsystem boundaries.

Main entry points: [`src/client/client.ts`](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/client/client.ts) (Robinhood client), [`src/server/server.ts`](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/server.ts) (MCP server), [`src/server/browser-auth.ts`](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/browser-auth.ts) (Browser login), [`src/server/official/forward.ts`](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/official/forward.ts) (Official forwarding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Agent interface"]
  node_mcp["MCP server<br/>[server.ts]"]
  node_transport["Stdio transport<br/>[index.ts]"]
  node_official["Official forwarding<br/>[forward.ts]"]
end

subgraph group_auth["Authentication"]
  node_officialauth[("Official credentials<br/>[auth.ts]")]
  node_browserauth["Browser login<br/>[browser-auth.ts]"]
  node_authtools["Session tools<br/>[auth.ts]"]
end

subgraph group_webtools["Web tools"]
  node_account["Portfolio tools<br/>[portfolio.ts]"]
  node_stocks["Stock tools<br/>[stocks.ts]"]
  node_markets["Market tools<br/>[markets.ts]"]
  node_options["Options tools<br/>[options.ts]"]
  node_crypto["Crypto tools<br/>[crypto.ts]"]
  node_orders["Order tools<br/>[orders.ts]"]
  node_watchlists["Watchlist tools<br/>[watchlists.ts]"]
  node_scanners["Scanner tools<br/>[scanners.ts]"]
  node_pnl["P&amp;L tools<br/>[pnl.ts]"]
  node_taxlots["Tax lot tools<br/>[tax-lots.ts]"]
  node_review["Order review<br/>[review.ts]"]
end

subgraph group_client["Client runtime"]
  node_client["Robinhood client<br/>[client.ts]"]
  node_session["Session and auth<br/>[auth.ts]"]
  node_tokenstore[("Token stores<br/>[token-store.ts]")]
  node_http["HTTP layer<br/>[http.ts]"]
end

subgraph group_analysis["Analysis"]
  node_compute["Trading analytics"]
end

node_agent(("AI agent"))
node_robinhood["Robinhood services"]
node_chrome(("User browser"))

node_agent -->|"uses MCP"| node_transport
node_transport -->|"creates server"| node_mcp
node_mcp -->|"registers standard tools"| node_official
node_mcp -->|"registers web tools"| node_authtools
node_mcp -->|"registers web tools"| node_account
node_mcp -->|"registers web tools"| node_stocks
node_mcp -->|"registers web tools"| node_markets
node_mcp -->|"registers web tools"| node_options
node_mcp -->|"registers web tools"| node_crypto
node_mcp -->|"registers web tools"| node_orders
node_mcp -->|"registers web tools"| node_watchlists
node_mcp -->|"registers web tools"| node_scanners
node_mcp -->|"registers web tools"| node_pnl
node_mcp -->|"registers web tools"| node_taxlots
node_mcp -->|"registers web tools"| node_review
node_agent -->|"approves login"| node_chrome
node_authtools -->|"starts login"| node_browserauth
node_browserauth -->|"opens Chrome"| node_chrome
node_browserauth -->|"saves tokens"| node_tokenstore
node_browserauth -->|"restores session"| node_client
node_client -->|"manages session"| node_session
node_session -->|"loads and saves"| node_tokenstore
node_client -->|"sends requests"| node_http
node_http -->|"calls web API"| node_robinhood
node_official -->|"loads credentials"| node_officialauth
node_official -->|"relays MCP calls"| node_robinhood
node_authtools -->|"checks session"| node_client
node_account -->|"calls client"| node_client
node_stocks -->|"calls client"| node_client
node_markets -->|"calls client"| node_client
node_options -->|"calls client"| node_client
node_crypto -->|"calls client"| node_client
node_orders -->|"calls client"| node_client
node_watchlists -->|"calls client"| node_client
node_scanners -->|"calls client"| node_client
node_pnl -->|"calls client"| node_client
node_taxlots -->|"calls client"| node_client
node_review -->|"requests order data"| node_client
node_review -->|"evaluates price collar"| node_compute
node_client -->|"uses REST API"| node_robinhood

click node_mcp "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/server.ts"
click node_transport "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/index.ts"
click node_official "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/official/forward.ts"
click node_officialauth "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/official/auth.ts"
click node_browserauth "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/browser-auth.ts"
click node_authtools "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/auth.ts"
click node_account "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/portfolio.ts"
click node_stocks "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/stocks.ts"
click node_markets "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/markets.ts"
click node_options "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/options.ts"
click node_crypto "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/crypto.ts"
click node_orders "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/orders.ts"
click node_watchlists "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/watchlists.ts"
click node_scanners "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/scanners.ts"
click node_pnl "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/pnl.ts"
click node_taxlots "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/tax-lots.ts"
click node_review "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/review.ts"
click node_client "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/client/client.ts"
click node_session "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/client/auth.ts"
click node_tokenstore "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/client/token-store.ts"
click node_http "https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/client/http.ts"
click node_compute "https://github.com/kevin1chun/robinhood-for-agents/tree/main/src/compute"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_transport,node_official,node_chrome toneBlue
class node_officialauth,node_browserauth,node_authtools toneAmber
class node_account,node_stocks,node_markets,node_options,node_crypto,node_orders,node_watchlists,node_scanners,node_pnl,node_taxlots,node_review toneMint
class node_client,node_session,node_tokenstore,node_http toneRose
class node_compute,node_agent,node_robinhood toneIndigo
```

## Components

### Agent interface

- [MCP server](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/server.ts): `src/server/server.ts`
- [Stdio transport](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/index.ts): `src/server/index.ts`
- [Official forwarding](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/official/forward.ts): `src/server/official/forward.ts`

### Authentication

- [Official credentials](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/official/auth.ts): `src/server/official/auth.ts`
- [Browser login](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/browser-auth.ts): `src/server/browser-auth.ts`
- [Session tools](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/auth.ts): `src/server/tools/auth.ts`

### Web tools

- [Portfolio tools](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/portfolio.ts): `src/server/tools/portfolio.ts`
- [Stock tools](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/stocks.ts): `src/server/tools/stocks.ts`
- [Market tools](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/markets.ts): `src/server/tools/markets.ts`
- [Options tools](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/options.ts): `src/server/tools/options.ts`
- [Crypto tools](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/crypto.ts): `src/server/tools/crypto.ts`
- [Order tools](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/orders.ts): `src/server/tools/orders.ts`
- [Watchlist tools](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/watchlists.ts): `src/server/tools/watchlists.ts`
- [Scanner tools](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/scanners.ts): `src/server/tools/scanners.ts`
- [P&L tools](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/pnl.ts): `src/server/tools/pnl.ts`
- [Tax lot tools](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/tax-lots.ts): `src/server/tools/tax-lots.ts`
- [Order review](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/server/tools/review.ts): `src/server/tools/review.ts`

### Client runtime

- [Robinhood client](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/client/client.ts): `src/client/client.ts`
- [Session and auth](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/client/auth.ts): `src/client/auth.ts`
- [Token stores](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/client/token-store.ts): `src/client/token-store.ts`
- [HTTP layer](https://github.com/kevin1chun/robinhood-for-agents/blob/main/src/client/http.ts): `src/client/http.ts`

### Analysis

- [Trading analytics](https://github.com/kevin1chun/robinhood-for-agents/tree/main/src/compute): `src/compute`

### Other components

- **AI agent**
- **Robinhood services**
- **User browser**

## Connections

- AI agent → Stdio transport: uses MCP
- Stdio transport → MCP server: creates server
- MCP server → Official forwarding: registers standard tools
- MCP server → Session tools: registers web tools
- MCP server → Portfolio tools: registers web tools
- MCP server → Stock tools: registers web tools
- MCP server → Market tools: registers web tools
- MCP server → Options tools: registers web tools
- MCP server → Crypto tools: registers web tools
- MCP server → Order tools: registers web tools
- MCP server → Watchlist tools: registers web tools
- MCP server → Scanner tools: registers web tools
- MCP server → P&L tools: registers web tools
- MCP server → Tax lot tools: registers web tools
- MCP server → Order review: registers web tools
- AI agent → User browser: approves login
- Session tools → Browser login: starts login
- Browser login → User browser: opens Chrome
- Browser login → Token stores: saves tokens
- Browser login → Robinhood client: restores session
- Robinhood client → Session and auth: manages session
- Session and auth → Token stores: loads and saves
- Robinhood client → HTTP layer: sends requests
- HTTP layer → Robinhood services: calls web API
- Official forwarding → Official credentials: loads credentials
- Official forwarding → Robinhood services: relays MCP calls
- Session tools → Robinhood client: checks session
- Portfolio tools → Robinhood client: calls client
- Stock tools → Robinhood client: calls client
- Market tools → Robinhood client: calls client
- Options tools → Robinhood client: calls client
- Crypto tools → Robinhood client: calls client
- Order tools → Robinhood client: calls client
- Watchlist tools → Robinhood client: calls client
- Scanner tools → Robinhood client: calls client
- P&L tools → Robinhood client: calls client
- Tax lot tools → Robinhood client: calls client
- Order review → Robinhood client: requests order data
- Order review → Trading analytics: evaluates price collar
- Robinhood client → Robinhood services: uses REST API