@aetherwealth/mcp 0.1.18-beta.4 → 0.1.21

package/README.md

@@ -1,146 +1,149 @@
-# @aetherwealth/mcp
+# Aether Wealth MCP Server
 
-A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
-a user's **Aether Wealth** trading journal to MCP clients such as Claude Desktop.
+Official Model Context Protocol (MCP) server for Aether Wealth. Connect any
+stdio-compatible MCP client to your Aether Wealth trading journal, accounts,
+alerts, market context, macro calendar, and technical indicators.
 
-Authentication is **per-user OAuth 2.1** — the user signs in through the browser
-and the MCP stores a personal access token locally. No shared secret is
-configured on the user's machine. Data calls go to `aether-backend` over a typed
-**tRPC** client.
+The package runs locally with `npx`, authenticates with browser-based OAuth, and
+uses your Aether Wealth account permissions for every data tool. It is built for
+traders who want an AI assistant to inspect their journal, summarize performance,
+create alerts, and fetch market context without copying API keys into their MCP
+client.
 
-> Destructive tools (`delete_trade`, `delete_account`) are intentionally not
-> exposed — trades are permanent records; delete them in the web app. Market-data
-> tools are public (work without sign-in); everything else needs `login`.
+## Install
 
-## Tools
-
-**Auth**
-
-| Tool | Purpose |
-|------|---------|
-| `login` | Sign in. Opens the browser; after you approve, the MCP stores a per-user token. |
-| `logout` | Sign out on this device (clears the stored token). |
-
-**Trades** (require sign-in)
-
-| Tool | Purpose |
-|------|---------|
-| `list_trades` | List trades; filter by account, status, pair, or date range. |
-| `get_trade` | Get a single trade by id. |
-| `list_accounts` | List trading accounts (for `create_trade`'s `accountId`). |
-| `trade_stats` | Performance statistics (win rate, PnL, …). |
-| `create_trade` | Record a new trade. |
-| `update_trade` | Update fields on a trade. |
-| `close_trade` | Close an open trade with an exit price + time. |
-
-**Alerts** (require sign-in)
-
-| Tool | Purpose |
-|------|---------|
-| `list_alerts` / `list_indicator_alerts` | List price+trendline / indicator alerts. |
-| `create_price_alert` | Price-level alert (above/below/crosses). |
-| `create_trendline_alert` | Trendline alert from two points. |
-| `create_indicator_alert` | Indicator-output alert (e.g. RSI crosses 70). |
-| `update_alert` / `delete_alert` | Update / delete a price/trendline alert. |
-| `update_indicator_alert` / `delete_indicator_alert` | Update / delete an indicator alert. |
+Use the package in any MCP client that can launch a local stdio server.
 
-**Market data** (public — no sign-in)
+```bash
+npx -y @aetherwealth/mcp
+```
 
-| Tool | Purpose |
-|------|---------|
-| `get_candles` | Recent OHLC candles (up to 500) for a pair + timeframe, read from Redis. |
-| `list_economic_calendar` | Economic calendar events; filter by currency, date, impact. |
-| `get_macro_series` | Macro indicator time series (e.g. USD cpi). |
-| `get_market_config` | Catalog of supported instruments + timeframes. |
+Most MCP clients use a JSON config like this:
 
-A sign-in-required tool called while signed out returns an "authentication
-required — call `login`" error, so the assistant prompts you to sign in.
+```json
+{
+  "mcpServers": {
+    "aether-wealth": {
+      "command": "npx",
+      "args": ["-y", "@aetherwealth/mcp"]
+    }
+  }
+}
+```
 
-## Authentication flow
+Restart your MCP client after adding the server. Then ask it to run the
+`login` tool once.
 
-`login` runs an OAuth 2.1 Authorization Code + PKCE flow as a public client:
+## What It Does
 
-1. Discover the provider endpoints from `${AETHER_BASE_URL}/auth/api/.well-known/openid-configuration`.
-2. Start a loopback listener on `127.0.0.1` (a fixed port from a small set).
-3. Open the browser to the authorize URL. If you're already signed in to the
-   Aether Wealth web app it completes immediately; otherwise you sign in there.
-4. The redirect lands on the loopback listener with an authorization code, which
-   is exchanged (with the PKCE verifier) for an access token.
-5. The token is stored in the **OS keychain** (macOS Keychain / Windows
-   Credential Manager / Linux libsecret), with a `0600`-file fallback, keyed by
-   backend host so prod and beta tokens coexist.
+Aether Wealth MCP gives AI assistants a safe tool layer over Aether Wealth:
 
-The token is long-lived; there is no refresh token. When it expires, run `login`
-again.
+- Read and summarize your trading journal
+- List accounts and performance stats
+- Create, update, and close trade records
+- Create and manage price, trendline, and indicator alerts
+- Fetch candles, economic calendar events, macro series, and market config
+- Compute technical indicators such as RSI, MACD, EMA, Bollinger Bands, ATR,
+  ADX, Supertrend, and more
 
-## Configuration
+Aether Wealth is trading analysis and journaling software. This MCP server does
+not place broker orders or execute trades.
 
-See [`.env.example`](./.env.example).
+## Authentication
 
-| Var | Required | Notes |
-|-----|----------|-------|
-| `AETHER_BASE_URL` | prod only | aether-backend base URL (OAuth + tRPC). Falls back to `http://localhost:9006` in dev. |
-| `AETHER_MCP_CREDENTIALS_FILE` | no | Set to force the `0600`-file credential store instead of the OS keychain. |
-| `MCP_TRANSPORT` | no | `stdio` (default) or `http`. |
-| `MCP_HTTP_PORT` / `MCP_HTTP_HOST` / `MCP_HTTP_PATH` / `MCP_HTTP_BEARER` | no | HTTP transport only. |
+The `login` tool opens the Aether Wealth OAuth flow in your browser. After you
+approve access, the MCP stores a local token in the operating-system keychain
+where available, with a protected file fallback.
 
-## Running
+No shared API key is configured in your MCP client. All data tools require
+OAuth sign-in, including market-data tools. `logout` clears the local
+credential for this device.
 
-```bash
-# From the repo root
-bun run --filter=@aetherwealth/mcp start
-# Or directly
-cd apps/aether-wealth-mcp && bun run src/index.ts
-```
+## Tools
 
-### Claude Desktop config example
+### Auth
 
-```json
-{
-  "mcpServers": {
-    "aether-wealth": {
-      "command": "bun",
-      "args": ["run", "/abs/path/to/apps/aether-wealth-mcp/src/index.ts"],
-      "env": { "AETHER_BASE_URL": "https://api.aetherwealth.ai" }
-    }
-  }
-}
-```
+| Tool | Purpose |
+| --- | --- |
+| `login` | Sign in with Aether Wealth OAuth. |
+| `logout` | Clear the local OAuth credential on this device. |
 
-Then ask the assistant to sign in (it calls `login`), complete the browser
-sign-in, and your trades become available.
+### Trades, Accounts, And Stats
 
-## Build & quality
+| Tool | Purpose |
+| --- | --- |
+| `list_trades` | List trades by account, status, pair, or date range. |
+| `get_trade` | Fetch one trade by ID. |
+| `list_accounts` | List your trading accounts. |
+| `trade_stats` | Summarize performance, win rate, PnL, and related stats. |
+| `create_trade` | Record a new trade. |
+| `update_trade` | Update fields on an existing trade. |
+| `close_trade` | Close an open trade with exit price and time. |
 
-```bash
-bun run --filter=@aetherwealth/mcp test       # vitest
-bun run --filter=@aetherwealth/mcp typecheck  # tsc --noEmit
-bun run --filter=@aetherwealth/mcp lint        # biome
-bun run --filter=@aetherwealth/mcp build       # bun bundle → dist/
-```
+### Alerts
 
-> The typecheck imports `AppRouter` from `@opusaether/aether-backend/trpc`, so
-> aether-backend's declarations must be built first (the turbo pipeline handles
-> this). A stale `node_modules` makes the vitest suite fail with
-> `[TSCONFIG_ERROR]` — fix with `bun install` and `GITHUB_TOKEN` set.
+| Tool | Purpose |
+| --- | --- |
+| `list_alerts` | List price and trendline alerts. |
+| `create_price_alert` | Create a price-level alert. |
+| `create_trendline_alert` | Create a trendline alert from two chart points. |
+| `update_alert` | Update or archive a price or trendline alert. |
+| `delete_alert` | Delete a price or trendline alert. |
+| `list_indicator_alerts` | List indicator-based alerts. |
+| `create_indicator_alert` | Create an alert on an indicator output condition. |
+| `update_indicator_alert` | Update an indicator alert. |
+| `delete_indicator_alert` | Delete an indicator alert. |
+
+### Market Context
 
-## Architecture
+| Tool | Purpose |
+| --- | --- |
+| `get_candles` | Fetch recent OHLC candles for a pair and timeframe. |
+| `list_economic_calendar` | List economic calendar events by currency, release, date, or impact. |
+| `get_macro_series` | Fetch macro indicator time series such as CPI or interest-rate data. |
+| `get_market_config` | Fetch supported instruments and timeframes. |
 
-```
-index.ts             entry: config → credential store → OAuth session → tRPC client → transport
-config.ts            env → { baseUrl, trpcUrl, host } (OAuth-only)
-trpc-client.ts       typed tRPC client (AppRouter); attaches Bearer token per request
-tool-registry.ts     login / logout / list_trades; McpToolContext = { session, trpc }
-server.ts            registry → @modelcontextprotocol/sdk request-handler bridge
-oauth/
-  contract.ts        client id / redirect ports / scopes (mirrors aether-backend constants)
-  pkce.ts            PKCE verifier + S256 challenge, state
-  discovery.ts       fetch the AS openid-configuration
-  loopback.ts        loopback redirect listener (captures code/state)
-  browser.ts         open the system browser
-  login.ts           runLogin: PKCE → loopback → browser → token exchange
-  credential-store.ts  OS keychain + 0600-file fallback, keyed by host
-  session.ts         OAuthSession: getAccessToken / login / logout
-```
+### Technical Indicators
 
-See [ADR 0001](../../docs/adr/0001-mcp-oauth.md) for the auth design + trade-offs.
+| Tool | Purpose |
+| --- | --- |
+| `get_indicators` | Compute up to 8 technical indicators for a pair and interval. |
+
+## Example Prompts
+
+- "List my open trades and group them by pair. Flag anything without a stop
+  loss."
+- "Summarize my last 20 closed trades. What setup is leaking the most R?"
+- "What high-impact USD events are left this week, and which open trades overlap
+  them?"
+- "Fetch EUR/USD 1h RSI and MACD, then create an alert if RSI crosses below 40."
+- "Create a price alert if XAU/USD crosses yesterday's high before New York
+  open."
+
+## Safety And Limits
+
+- OAuth is per user. Your MCP client does not store a shared service secret.
+- Tokens are stored locally and can be cleared with `logout`.
+- Backend rate limits protect market-data reads, MCP Bearer traffic, and
+  cost-sensitive indicator calls.
+- Technical indicators include request, active-pair, cache, and upstream credit
+  gates.
+- Destructive trade and account deletion tools are intentionally not exposed.
+- The MCP does not execute trades or route broker orders.
+
+## Updating
+
+If your MCP client launches the server with `npx -y @aetherwealth/mcp`, restart
+the client to pick up the current published package.
+
+The backend can also advertise a minimum supported MCP version. If your local
+server is too old, tool calls return an update-required message instead of
+failing silently.
+
+## Links
+
+- Aether Wealth: https://aetherwealth.ai
+- Trading app: https://app.aetherwealth.ai
+- MCP page: https://aetherwealth.ai/mcp
+- Tool reference: https://aetherwealth.ai/mcp-tools.json
+- npm package: https://www.npmjs.com/package/@aetherwealth/mcp