book: scaffold + ch00 (execution trail as spine) — evidence exp 8-31, round 3
This commit is contained in:
TradeAC Book Agent
@@ -0,0 +1,161 @@
|
||||
---
|
||||
name: tradeac-alpaca
|
||||
description: Guide agents to call tac-engine MCP tools for Alpaca trading and market data (news, corporate actions, screener, FX, stocks, options, realtime streams) via MCP Inspector, Cursor, or other clients.
|
||||
---
|
||||
|
||||
# tradeac-alpaca
|
||||
|
||||
Use **tac-engine** MCP tools — not raw Alpaca REST — for brokerage ops and market data. Same tool surface will back TradeAC’s Next.js UI later.
|
||||
|
||||
## MCP-first policy
|
||||
|
||||
- **Prefer the MCP tools registered in this session** (`tac-engine` server, tools listed below) over writing scripts that reimplement them. If a tool exists, call it directly — do not reinvent it with curl/bash/python (raw Alpaca REST, hand-rolled pagination, own JSON-RPC clients).
|
||||
- **NEVER script directly against the MCP server** (spawning the binary, talking stdio JSON-RPC, or driving it via bash/curl) unless the MCP tool surface genuinely can't do the job — and in that case **stop and ask the user to confirm first** before writing the script.
|
||||
- If a direct Alpaca call is needed (e.g. an endpoint with no tool), say so and let the user confirm the approach; otherwise keep everything on the MCP surface.
|
||||
|
||||
## Hosts / env
|
||||
|
||||
| Purpose | Env | Default |
|
||||
|---------|-----|---------|
|
||||
| Trading REST | `APCA_BASE_URL` | `https://paper-api.alpaca.markets` |
|
||||
| Market data REST | `APCA_DATA_BASE_URL` | `https://data.alpaca.markets` |
|
||||
| Market data WS | `APCA_STREAM_BASE_URL` | `wss://stream.data.alpaca.markets` |
|
||||
| Auth | `APCA_API_KEY_ID`, `APCA_API_SECRET_KEY` | required |
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
./target/release/tac-engine
|
||||
```
|
||||
|
||||
## Secrets policy
|
||||
|
||||
- NEVER write secrets into files: API keys (`APCA_API_KEY_ID`/`APCA_API_SECRET_KEY`), DB passwords, OAuth tokens, or credential-bearing URLs in scripts, configs, notes or committed code.
|
||||
- NEVER read `*.env` / `.env.*` directly (`cat`/`tail`/`grep`/`sed`/`head` on `.env`). That pulls secrets into this session and leaks them to any agent sharing it.
|
||||
- When a tool or command needs an env var, ASK the user to set it in the environment (shell/container env, or the user-owned `.env`) and reference it by name (`$VAR`), never by value. If it's missing, report which variable is required instead of reading it yourself.
|
||||
- If you find a committed secret, flag it, remove it, and replace it with a placeholder.
|
||||
|
||||
## MCP clients
|
||||
|
||||
### MCP Inspector
|
||||
|
||||
```bash
|
||||
npx @modelcontextprotocol/inspector /absolute/path/to/tac-engine/target/release/tac-engine
|
||||
```
|
||||
|
||||
Connect → `tools/list` → `tools/call` with JSON `arguments`.
|
||||
|
||||
### Cursor
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"tac-engine": {
|
||||
"command": "/absolute/path/to/tac-engine/target/release/tac-engine",
|
||||
"env": {
|
||||
"APCA_API_KEY_ID": "${APCA_API_KEY_ID}",
|
||||
"APCA_API_SECRET_KEY": "${APCA_API_SECRET_KEY}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
stdio is NDJSON JSON-RPC; logs on stderr.
|
||||
|
||||
## Safety
|
||||
|
||||
- Paper trading by default (`APCA_BASE_URL`).
|
||||
- Mutating trading tools: `place_order`, `close_*`, `cancel_*`, watchlist writes.
|
||||
- `subscribe_market_stream` opens a **short-lived** WebSocket (samples then disconnects). Most Alpaca plans allow **one** concurrent stream — close other clients first.
|
||||
|
||||
## Tool catalog
|
||||
|
||||
Lake tools (`get_lake_bars`, `get_lake_ta`, `get_lake_sp`, `get_lake_features`, `backfill_lake_calendar`, …) live under **`tradeac-lake`** (see `tac-engine/skills/tradeac-lake/SKILL.md`). When a lake call's purpose is **backfilling/persisting** (not reading the payload), pass `"quiet": true` so the tool returns a summary (`count`/`first_t`/`last_t`/`source`/`columns`) instead of echoing back the full bar/feature rows.
|
||||
|
||||
### Trading (brokerage account)
|
||||
|
||||
Account: `get_account`, `get_portfolio_history`, `list_account_activities`, `get_account_activities_by_type`
|
||||
Assets master: `list_assets`, `get_asset`
|
||||
Watchlists / positions / orders: `list_*`, `get_*`, `create_*`, `place_order`, `close_*`, `cancel_*`
|
||||
|
||||
### Market data — news & corporate actions
|
||||
|
||||
| Tool | Notes |
|
||||
|------|------|
|
||||
| `get_news` | optional `symbols`, `start`/`end`, `limit`, `include_content` |
|
||||
| `get_corporate_actions` | optional `symbols`, `types`, `start`/`end`, `data_quality` |
|
||||
|
||||
### Screener
|
||||
|
||||
| Tool | Notes |
|
||||
|------|------|
|
||||
| `get_most_actives` | optional `by`=`volume`\|`trades`, `top` |
|
||||
| `get_market_movers` | required `market_type`=`stocks`\|`crypto`, optional `top` |
|
||||
|
||||
### FX
|
||||
|
||||
| Tool | Notes |
|
||||
|------|------|
|
||||
| `get_forex_latest_rates` | required `currency_pairs` e.g. `USDJPY,EURUSD` |
|
||||
| `get_forex_rates` | historical; optional `timeframe`, `start`, `end` |
|
||||
|
||||
### Stocks
|
||||
|
||||
| Tool | Notes |
|
||||
|------|------|
|
||||
| `get_stock_bars` / `get_stock_bars_single` | historical; needs `timeframe` |
|
||||
| `get_stock_latest_bars` | latest minute bars |
|
||||
| `get_stock_quotes` / `get_stock_latest_quotes` | quotes |
|
||||
| `get_stock_trades` / `get_stock_latest_trades` | trades |
|
||||
| `get_stock_snapshots` / `get_stock_snapshot` | trade+quote+bars |
|
||||
| `get_stock_auctions` | auctions |
|
||||
|
||||
Multi-symbol tools take comma-separated `symbols`. Optional `feed` (`iex`/`sip`), `limit`, `page_token`, …
|
||||
|
||||
### Options
|
||||
|
||||
| Tool | Notes |
|
||||
|------|------|
|
||||
| `get_option_bars` | historical bars for contract symbols |
|
||||
| `get_option_latest_quotes` / `get_option_latest_trades` | latest |
|
||||
| `get_option_trades` | historical trades |
|
||||
| `get_option_snapshots` | contracts |
|
||||
| `get_option_chain` | underlying + filters (`type`, strikes, expiration) |
|
||||
| `get_option_meta_conditions` / `get_option_meta_exchanges` | code maps |
|
||||
|
||||
### Realtime stream sampling
|
||||
|
||||
| Tool | Notes |
|
||||
|------|------|
|
||||
| `subscribe_market_stream` | `stream`=`stocks`\|`options`\|`news`\|`test`; optional `feed`; channels `trades`/`quotes`/`bars`/`news` as CSV symbols; `duration_secs` (1–30), `max_messages` (1–200) |
|
||||
|
||||
Examples:
|
||||
|
||||
```json
|
||||
{"stream":"test","duration_secs":5,"max_messages":20}
|
||||
```
|
||||
|
||||
```json
|
||||
{"stream":"stocks","feed":"iex","quotes":"AAPL,MSFT","duration_secs":5}
|
||||
```
|
||||
|
||||
```json
|
||||
{"stream":"news","news":"*","duration_secs":8,"max_messages":30}
|
||||
```
|
||||
|
||||
```json
|
||||
{"stream":"options","feed":"indicative","quotes":"AAPL250117C00200000","duration_secs":5}
|
||||
```
|
||||
|
||||
## Example workflows
|
||||
|
||||
1. **Dashboard:** `get_account` → `list_positions` → `get_stock_snapshots` (`symbols` from positions)
|
||||
2. **Research:** `get_news` → `get_corporate_actions` → `get_stock_bars`
|
||||
3. **Screener → trade (paper):** `get_most_actives` → `get_stock_snapshot` → `place_order`
|
||||
4. **Options:** `get_option_chain` (`underlying_symbol=AAPL`) → `get_option_latest_quotes`
|
||||
5. **Live sample:** `subscribe_market_stream` with `stream=test` first, then stocks/news
|
||||
|
||||
## Protocol
|
||||
|
||||
- rmcp **3.1** / MCP **2026-07-28**, stdio
|
||||
- Prefer these MCP tool names/args over calling Alpaca hosts directly from agents/UI
|
||||
Reference in New Issue
Block a user