# Longbridge MCP-UI Proxy

An MCP (Model Context Protocol) proxy server that wraps the [Longbroker OpenAPI MCP server](https://openapi.longbridge.com/mcp) and transforms its plain JSON responses into rich, interactive HTML dashboards — stock cards, candlestick charts, portfolio views, order forms, option chains, and more.

Built on the [MCP-UI](https://github.com/nicepkg/mcp-ui) specification so any MCP host that renders `ui://` resources (Goose, Claude Desktop, etc.) gets visual UIs instead of raw JSON.

## Quick start

```bash
# 1. Install dependencies
npm install

# 2. Set your Longbridge token
export LONGBRIDGE_TOKEN="your_token_here"
# Generate a token at https://open.longbridge.com/connect

# 3. Run in dev mode (auto-restart on changes)
npm run dev

# 4. Or build and run production
npm run build
npm start
```

The server starts on `http://localhost:3456` by default.

## Docker

```bash
docker build -t lb-mcp-ui-proxy .
docker run -p 3456:3456 -e LONGBRIDGE_TOKEN=your_token lb-mcp-ui-proxy
```

## Configuration

All config is via environment variables (see `.env.example`):

| Variable | Default | Description |
|---|---|---|
| `PORT` | `3456` | Server listen port |
| `LONGBRIDGE_MCP_URL` | `https://openapi.longbridge.com/mcp` | Longbridge MCP backend URL |
| `LONGBRIDGE_TOKEN` | *(required)* | Bearer token for Longbridge API |
| `LOG_LEVEL` | `info` | Logging verbosity: `debug`, `info`, `warn`, `error` |

## How it works

```
┌──────────┐    MCP (Streamable HTTP)    ┌──────────────────┐    MCP (Streamable HTTP)    ┌──────────────────┐
│  MCP Host │ ◄───────────────────────► │  lb-mcp-ui-proxy  │ ◄───────────────────────► │  Longbridge MCP  │
│ (Goose,   │   ui:// HTML resources     │  (this server)    │   JSON tool calls          │  (openapi.       │
│  Claude)  │                            │                   │                            │   longbridge.com) │
└──────────┘                            └──────────────────┘                            └──────────────────┘
```

1. An MCP host connects to this proxy at `POST /mcp` using the Streamable HTTP transport.
2. The proxy exposes 11 UI-enhanced tools (prefixed `lb_`).
3. When the host calls a tool, the proxy:
   - Opens a session to the real Longbridge MCP server.
   - Forwards the tool call (e.g. `get_quote` → Longbridge).
   - Parses the JSON response.
   - Renders an interactive HTML dashboard via `@mcp-ui/server`'s `createUIResource`.
   - Returns the HTML as a `ui://longbridge/...` resource that the host renders.

## Tools

| Proxy tool | Longbridge tool | UI |
|---|---|---|
| `lb_quote` | `get_quote` | Stock card with price, change, OHLCV, amplitude bar |
| `lb_chart` | `get_candlesticks` | Canvas-rendered candlestick chart with volume bars |
| `lb_search` | `search_security` | Search results table with symbol, name, exchange |
| `lb_portfolio` | `get_account_summary` + `get_positions` | Portfolio dashboard with P&L, positions table |
| `lb_orders` | `get_orders` | Orders table with status badges |
| `lb_place_order` | `place_order` | Interactive order form or direct order with confirmation |
| `lb_option_chain` | `get_option_chain` | Color-coded calls/puts table with Greeks |
| `lb_alerts` | `get_alerts` | Alerts list with toggle switches |
| `lb_market_overview` | `get_market_status` | Market indices and status (text) |
| `lb_dca_plans` | `get_dca_plans` | DCA plans dashboard with progress cards |

### Tool parameters

All tools accept their parameters as Zod-validated fields. Examples:

```bash
# Get a quote for Tesla
lb_quote(symbol: "TSLA.US")

# Candlestick chart
lb_chart(symbol: "TSLA.US", period: "1d", count: 100)

# Place a limit order
lb_place_order(symbol: "TSLA.US", side: "buy", type: "limit", price: 250.00, quantity: 10)

# Show the interactive order form
lb_place_order(_showForm: true)
```

## API endpoints

| Endpoint | Method | Description |
|---|---|---|
| `/mcp` | `POST` | MCP Streamable HTTP endpoint (session-based) |
| `/health` | `GET` | Health check — returns status, version, config check |

## Project structure

```
src/
├── index.ts               # Express server, MCP endpoint, session management
├── config.ts              # Environment variable config loader
├── longbridge-client.ts   # MCP client wrapper for Longbridge backend
├── tools/
│   └── register.ts        # Tool definitions — wires params → Longbridge → UI
└── ui/
    ├── styles.ts           # Shared CSS, HTML page wrapper, formatting helpers
    ├── quotes.ts           # Quote card + search results
    ├── chart.ts            # Candlestick chart (canvas)
    ├── portfolio.ts        # Portfolio dashboard + positions table
    ├── orders.ts           # Orders table + order form + confirmation
    ├── options.ts          # Option chain + price alerts
    └── dca.ts              # DCA plans dashboard
```

## Development

```bash
# Dev server with hot reload
npm run dev

# Type-check only
npx tsc --noEmit

# Build for production
npm run build
```

## Tech stack

- **Runtime:** Node.js 22, TypeScript (ESM)
- **MCP SDK:** `@modelcontextprotocol/sdk` (Streamable HTTP transport, both client and server)
- **UI rendering:** `@mcp-ui/server` (`createUIResource` with raw HTML)
- **Web server:** Express + CORS
- **Validation:** Zod (tool parameter schemas)
- **Container:** Docker (multi-stage build, Alpine)

## License

Private — not yet licensed for distribution.