@pgnio/helios-mcp 0.0.0-stage → 0.2.1

package/docs/ai-agent-mcp/00_index.txt

@@ -0,0 +1,110 @@
+================================================================================
+HELIOS MCP INDEX — AI AGENT REFERENCE
+================================================================================
+PURPOSE
+  One-shot technical reference for the Helios MCP server.
+  Audience: agents and engineers.
+  Goal: understand tool inventory, scopes, data semantics, and failure rules
+  without reading source code.
+
+READ ORDER
+  1  01_auth/00_overview.txt
+  2  02_account/00_overview.txt
+  3  03_market/00_overview.txt
+  4  04_trading/00_overview.txt
+  5  05_ledger/00_overview.txt
+  6  ai-agent-indicators/00_index.txt
+
+GLOBAL RULES
+  - Transport is MCP over stdio.
+  - Auth is delegated device/browser approval, not browser-session reuse.
+  - Missing session => MCP returns manual login guidance, not silent auth.
+  - Backend 401 => local session is stale; clear session and re-login.
+  - Do not assume "connected" means every backend call will succeed forever.
+  - For market returns:
+      percent fields are already percentages
+      null means unavailable, not zero
+  - For ledger history:
+      default history is bounded
+      recent fills default to 7d window and limit 100
+      full history is NOT returned by default
+
+SCOPES
+  account:read
+    Read wallet state, open positions, open orders, fills, and ledger summary.
+
+  market:read
+    Read market snapshots and symbol detail.
+
+  orders:write
+    Submit trading intents and create TP/SL protection.
+
+  orders:cancel
+    Cancel open orders and delete TP/SL orders.
+
+TOOL INVENTORY
+  DOCS
+    helios_docs_get_index
+    helios_docs_get_document
+
+  AUTH
+    helios_auth_start_login
+    helios_auth_ensure_login
+    helios_auth_poll_login
+    helios_auth_whoami
+
+  PROVIDER
+    helios_provider_get_active
+    helios_provider_set_active
+
+  ACCOUNT
+    helios_account_get_wallet_state
+    helios_portfolio_get
+
+  MARKET
+    helios_market_get_snapshot
+    helios_market_get_snapshot_chunk
+    helios_market_get_symbol_detail
+
+  TRADING
+    helios_trading_open
+    helios_trading_dca
+    helios_trading_reverse
+    helios_trading_close
+    helios_positions_set_tp_sl
+    helios_positions_delete_tp_sl
+    helios_orders_get_open
+    helios_orders_cancel
+
+  LEDGER
+    helios_positions_get_open
+    helios_ledger_get_fills
+    helios_ledger_get_summary
+
+LAYER MAP
+  01_auth
+    Delegated login, refresh, stale-session recovery.
+
+  02_account
+    Current wallet/equity state only.
+
+  03_market
+    Market snapshot and symbol detail. Indicator formulas live in:
+    ai-agent-indicators/
+
+  04_trading
+    Intent execution, TP/SL management, working-order management.
+
+  05_ledger
+    Open positions, fills, realized/unrealized PnL context, summary metrics.
+
+COMMON MISTAKES
+  - Do not skip helios_docs_get_index / helios_docs_get_document when tool or
+    indicator semantics are unclear.
+  - Do not multiply market percent fields by 100.
+  - Do not treat null as zero.
+  - Do not treat wallet state as ledger history.
+  - Do not treat open orders as positions.
+  - Do not assume orders:write implies orders:cancel.
+  - Do not assume a connected local session survives backend grant replacement.
+  - Do not assume provider defaults; use helios_provider_set_active or pass provider explicitly.

package/docs/ai-agent-mcp/01_auth/00_overview.txt

@@ -0,0 +1,51 @@
+================================================================================
+LAYER: AUTH
+================================================================================
+PURPOSE
+  Establish and maintain a delegated Helios session for an external agent.
+
+MODEL
+  User creates Helios account manually first.
+  Agent does NOT create users.
+  Agent starts device login.
+  User opens approval URL in browser.
+  User authenticates to Helios and approves requested scopes.
+  Agent polls for approval and stores delegated tokens locally.
+
+WHAT AUTH ENABLES
+  account:read  -> read wallet, positions, open orders, fills, summary
+  market:read   -> read market snapshots
+  orders:write  -> submit intents, set TP/SL
+  orders:cancel -> cancel orders, delete TP/SL
+
+HOSTED SERVER (helios.pgn.io/mcp, wagmi.pgn.io/mcp)
+  Sign-in is done by the AI app itself (OAuth): the user approves Helios once
+  when adding the connector, and the app holds and refreshes the tokens.
+  The login tools below are not offered there; helios_auth_whoami is.
+  If a call fails because the connection expired or was revoked, ask the
+  user to reconnect Helios in their AI app.
+
+SESSION MODEL
+  - access token is short-lived
+  - refresh token is stored locally by the MCP server
+  - MCP refreshes automatically near expiry
+  - backend 401 invalidates local session and forces re-login
+
+IMPORTANT
+  "connected" means:
+    MCP currently has a valid local delegated session
+
+  "connected" does NOT guarantee:
+    every backend request will succeed
+    grant still exists forever
+    requested scope upgrades have already been approved
+
+PRIMARY TOOLS
+  helios_auth_start_login
+  helios_auth_ensure_login
+  helios_auth_poll_login
+  helios_auth_whoami
+
+READ NEXT
+  01_tools.txt
+  04_failures_and_recovery.txt

package/docs/ai-agent-mcp/01_auth/01_tools.txt

@@ -0,0 +1,94 @@
+================================================================================
+AUTH TOOLS
+================================================================================
+TOOL: helios_auth_start_login
+WHAT IT DOES
+  Starts a brand-new delegated Helios device flow and returns the approval URL
+  and device codes needed for browser consent.
+WHEN TO USE IT
+  Use when you explicitly want to force a fresh login instead of reusing any
+  cached session state.
+INPUT
+  clientName: string
+  scope: AgentScope[]
+  constraints?: record
+OUTPUT
+  status: pending
+  deviceCode
+  userCode
+  verificationUri
+  verificationUriComplete
+  expiresInSeconds
+  pollIntervalSeconds
+  requestedScope
+  startedAt
+  actionRequired: true
+  loginUrl
+  nextStep
+FINALITY
+  Starts approval only. It does NOT create a usable session until the request is
+  approved and later exchanged via helios_auth_poll_login.
+COMMON PATTERN
+  start_login -> browser approval -> poll_login
+
+TOOL: helios_auth_ensure_login
+WHAT IT DOES
+  Reuses a valid delegated session if one already exists. If not, it starts a
+  login flow and returns pending approval instructions.
+WHEN TO USE IT
+  Use at the start of an agent loop or before any account/market/trading call
+  when you want the MCP server to handle the "reuse vs login" decision.
+INPUT
+  clientName?: string
+  scope?: AgentScope[]
+  constraints?: record
+OUTPUT
+  connected state OR pending login state
+DEFAULT_SCOPE
+  account:read + market:read when no explicit scope is supplied
+FINALITY
+  This is the normal "gatekeeper" auth tool. If it returns connected, the next
+  MCP call can proceed. If it returns pending, the agent must complete approval
+  before continuing.
+COMMON PATTERN
+  ensure_login -> if pending: browser approval -> poll_login -> continue work
+
+TOOL: helios_auth_poll_login
+WHAT IT DOES
+  Checks whether a pending device request has been approved, rejected, expired,
+  or successfully exchanged into an active delegated session.
+WHEN TO USE IT
+  Use after start_login or ensure_login returned a pending device flow.
+INPUT
+  deviceCode: string
+OUTPUT
+  status: connected | pending | rejected | expired | failed
+  connected: boolean
+  message when not connected
+FINALITY
+  This is the step that turns browser approval into a usable delegated session.
+  A connected result means account/market/trading tools can now be called.
+COMMON PATTERN
+  poll until status becomes connected, rejected, or expired
+
+TOOL: helios_auth_whoami
+WHAT IT DOES
+  Returns the delegated session currently stored in the MCP server, if any.
+WHEN TO USE IT
+  Use for inspection, debugging, status reporting, or to confirm which scopes
+  are already active before planning work.
+INPUT
+  none
+OUTPUT
+  connected
+  status
+  ownerUserId?
+  agentGrantId?
+  scope?
+  accessTokenExpiresAt?
+  lastRefreshedAt?
+FINALITY
+  Read-only status check. It does not start login and does not refresh scope.
+DECISION IT ENABLES
+  Decide whether to continue normally, call ensure_login, or start a fresh
+  delegated login flow.

package/docs/ai-agent-mcp/01_auth/02_data_contracts.txt

@@ -0,0 +1,38 @@
+================================================================================
+AUTH DATA CONTRACTS
+================================================================================
+START LOGIN RESULT
+  status: pending
+  deviceCode: string
+  userCode: string
+  verificationUri: URL
+  verificationUriComplete: URL
+  expiresInSeconds: integer
+  pollIntervalSeconds: integer
+  requestedScope: AgentScope[]
+  startedAt: ISO-8601
+
+SESSION VIEW
+  connected: boolean
+  status: disconnected | pending | connected | rejected | expired | failed
+  ownerUserId?: string
+  agentGrantId?: string
+  scope?: AgentScope[]
+  accessTokenExpiresAt?: ISO-8601
+  lastRefreshedAt?: ISO-8601
+
+MANUAL LOGIN FIELDS
+  actionRequired: true
+  loginUrl: string
+  nextStep: string
+
+TOKEN HANDLING
+  - raw accessToken is never returned by MCP tools
+  - raw refreshToken is never returned by MCP tools
+  - tokens are stored only in local MCP session storage
+
+AGENT SCOPES
+  account:read
+  market:read
+  orders:write
+  orders:cancel

package/docs/ai-agent-mcp/01_auth/03_decision_rules.txt

@@ -0,0 +1,25 @@
+================================================================================
+AUTH DECISION RULES
+================================================================================
+USE ensure_login WHEN
+  - you want the session if present
+  - you are about to call another Helios tool
+  - you want a manual approval URL only if needed
+
+USE start_login WHEN
+  - you explicitly want to force a fresh login flow now
+  - you want the approval URL without first checking for an existing session
+
+USE poll_login WHEN
+  - you already have a deviceCode
+  - user has had time to approve in browser
+
+USE whoami WHEN
+  - you only need local session state
+  - you do not want to start a new login flow
+
+LOGIN UX RULE
+  Approval is manual.
+  MCP returns the approval URL.
+  User opens it in browser.
+  Agent should not assume browser automation is required.

package/docs/ai-agent-mcp/01_auth/04_failures_and_recovery.txt

@@ -0,0 +1,46 @@
+================================================================================
+AUTH FAILURES AND RECOVERY
+================================================================================
+MISSING SESSION
+  Symptom:
+    connected = false
+    pending login result returned
+  Recovery:
+    open loginUrl
+    approve access
+    poll login
+
+AUTHORIZATION_PENDING
+  Symptom:
+    poll_login returns pending
+  Recovery:
+    wait and poll again
+
+ACCESS_DENIED
+  Symptom:
+    poll_login returns rejected
+  Recovery:
+    start a new login flow if still needed
+
+EXPIRED DEVICE FLOW
+  Symptom:
+    poll_login returns expired
+  Recovery:
+    start a new login flow
+
+BACKEND 401
+  Meaning:
+    local session is stale relative to backend
+  Recovery:
+    MCP clears local session
+    new login guidance is returned
+
+INVALID JSON FROM BACKEND
+  Meaning:
+    wrong base URL, proxy error, or undeployed backend path
+  Recovery:
+    verify HELIOS_IDENTITY_SERVICE_URL / HELIOS_DATA_BRIDGE_URL
+
+ENVIRONMENT MATCH RULE
+  HELIOS_IDENTITY_SERVICE_URL and HELIOS_DATA_BRIDGE_URL must point to the
+  same environment. Mixed environments cause false "connected" states and 401s.

package/docs/ai-agent-mcp/02_account/00_overview.txt

@@ -0,0 +1,29 @@
+================================================================================
+LAYER: ACCOUNT
+================================================================================
+PURPOSE
+  Return current wallet/equity state for the connected Helios account.
+
+THIS LAYER ANSWERS
+  - how much capital is available now
+  - current account value
+  - current margin usage
+  - whether Hyperliquid is activated
+  - Hyperliquid portfolio state
+
+THIS LAYER DOES NOT ANSWER
+  - trade history
+  - realized PnL history
+  - open positions detail by symbol
+  - open orders
+
+PRIMARY TOOLS
+  helios_account_get_wallet_state
+  helios_portfolio_get
+
+SCOPE
+  account:read
+
+PROVIDER
+  helios_account_get_wallet_state -> hyperliquid only
+  helios_portfolio_get           -> hyperliquid only

package/docs/ai-agent-mcp/02_account/01_tools.txt

@@ -0,0 +1,67 @@
+================================================================================
+ACCOUNT TOOLS
+================================================================================
+TOOL: helios_account_get_wallet_state
+WHAT IT DOES
+  Returns the current Hyperliquid wallet snapshot for the connected account.
+WHEN TO USE IT
+  Use near the start of every trading cycle before proposing or submitting any
+  new risk.
+SCOPE
+  account:read
+INPUT
+  none
+OUTPUT
+  provider: hyperliquid
+  accountValue: number
+  availableBalance: number
+  withdrawable: number
+  totalMarginUsed: number
+  totalNotionalPosition: number
+  crossMarginAccountValue: number
+  isActivated: boolean
+  fetchedAt: ISO-8601
+FINALITY
+  Read-only account state. It does not include fill history, trade quality, or
+  position-level structure.
+DECISION IT ENABLES
+  - whether the account is activated and tradable
+  - how much dry powder exists
+  - whether current margin usage is already high
+  - whether new trades should be reduced, skipped, or allowed
+DO NOT USE IT FOR
+  - determining realized performance
+  - reconstructing past trades
+  - replacing positions.get_open or ledger.get_summary
+
+TOOL: helios_portfolio_get
+WHAT IT DOES
+  Returns the Hyperliquid portfolio snapshot (Hyperliquid is the only provider).
+WHEN TO USE IT
+  Use when the agent needs explicit provider separation instead of assuming a
+  single unified account model.
+SCOPE
+  account:read
+INPUT
+  provider?: hyperliquid
+  If omitted, helios_portfolio_get uses the provider pinned by
+  helios_provider_set_active.
+OUTPUT
+  provider-specific portfolio payload
+  - hyperliquid:
+    totalBalance
+    availableBalance
+    totalMargin
+    unrealizedPnl
+    positions[]
+    protectiveOrders[]
+FINALITY
+  Read-only portfolio state. It does not submit trades or mutate exchange
+  state.
+DECISION IT ENABLES
+  - whether Hyperliquid equity and margin support a new trade
+  - whether provider-specific exposure is already present
+DO NOT USE IT FOR
+  - fill history
+  - cancelling orders
+  - assuming parity between provider payload shapes

package/docs/ai-agent-mcp/02_account/02_data_contracts.txt

@@ -0,0 +1,34 @@
+================================================================================
+ACCOUNT DATA CONTRACTS
+================================================================================
+WALLET SNAPSHOT
+  provider
+    literal: hyperliquid
+
+  accountValue
+    numeric total account value
+
+  availableBalance
+    numeric currently available balance
+
+  withdrawable
+    numeric withdrawable/free balance
+
+  totalMarginUsed
+    numeric margin currently in use
+
+  totalNotionalPosition
+    numeric current notional exposure
+
+  crossMarginAccountValue
+    numeric cross-margin account value
+
+  isActivated
+    boolean account activation flag from backend state
+
+  fetchedAt
+    ISO-8601 snapshot time
+
+UNITS
+  All numeric fields are plain numbers, not strings.
+  Currency is backend account currency context, typically USDT-equivalent.

package/docs/ai-agent-mcp/02_account/03_decision_rules.txt

@@ -0,0 +1,17 @@
+================================================================================
+ACCOUNT DECISION RULES
+================================================================================
+USE wallet_state WHEN
+  - deciding whether any trade is possible now
+  - sizing a trade based on available capital
+  - checking whether the account is activated/funded
+
+DO NOT USE wallet_state FOR
+  - realized PnL history
+  - whether a symbol position is already open
+  - determining which existing order to cancel
+
+PAIR WITH
+  ledger.get_summary   -> realized performance
+  positions.get_open   -> current open positions
+  orders.get_open      -> working orders

package/docs/ai-agent-mcp/02_account/04_failures_and_recovery.txt

@@ -0,0 +1,17 @@
+================================================================================
+ACCOUNT FAILURES AND RECOVERY
+================================================================================
+MISSING SESSION
+  account:read login prompt returned
+
+BACKEND 401
+  stale session
+  MCP clears session and starts fresh account:read login flow
+
+PRECONDITION_FAILED
+  account state unavailable or user not ready on backend
+  usually means missing Hyperliquid context or failed account fetch
+
+ZERO VALUES
+  accountValue = 0 and availableBalance = 0 can be a real state
+  do not assume this is an error

package/docs/ai-agent-mcp/03_market/00_overview.txt

@@ -0,0 +1,27 @@
+================================================================================
+LAYER: MARKET
+================================================================================
+PURPOSE
+  Deliver a compact, agent-readable market state without screenshots.
+
+PRIMARY TOOLS
+  helios_market_get_snapshot
+  helios_market_get_symbol_detail
+
+MODEL
+  get_snapshot
+    first-pass global market view
+    compact matrix for selected, all, or explicit symbols
+
+  get_symbol_detail
+    second-pass deep read for one symbol
+
+INDICATOR SOURCE OF TRUTH
+  ai-agent-indicators/
+
+SCOPE
+  market:read
+
+FRESHNESS
+  Market snapshots are hydrated in Redis and refreshed on a short cadence.
+  Read `generatedAt` instead of assuming real-time-by-default.

package/docs/ai-agent-mcp/03_market/01_tools.txt

@@ -0,0 +1,102 @@
+================================================================================
+MARKET TOOLS
+================================================================================
+TOOL: helios_market_get_snapshot
+WHAT IT DOES
+  Returns one compact market overview payload for selected, all, or explicitly
+  requested symbols.
+WHEN TO USE IT
+  Use only when the requested market universe is small enough to fit in runtime
+  context comfortably.
+SCOPE
+  market:read
+INPUT
+  scope?: selected | all
+  symbols?: string[]
+OUTPUT
+  schema: helios.market_snapshot.v1
+  view: market_overview
+  scope: selected | all | explicit
+  symbolCount
+  generatedAt
+  returnedSymbols
+  semantics
+  market
+  table
+  legend
+FINALITY
+  Produces one-shot market context. It is best for small selected universes or
+  explicit symbol lists, not full-market batch scanning.
+DECISION IT ENABLES
+  Build a first-pass shortlist of symbols that deserve deeper drilldown.
+DO NOT USE IT FOR
+  Very large full-market scans when runtime token limits are likely to truncate
+  the result. Use helios_market_get_snapshot_chunk instead.
+
+TOOL: helios_market_get_snapshot_chunk
+WHAT IT DOES
+  Returns one bounded chunk of the market overview with pagination metadata.
+WHEN TO USE IT
+  Use as the default full-market scan method when the agent needs to analyze the
+  whole market universe without overflowing context limits.
+SCOPE
+  market:read
+INPUT
+  scope?: selected | all
+  symbols?: string[]
+  offset?: number
+  limit?: number (recommended 25; max 100)
+OUTPUT
+  schema: helios.market_snapshot_chunk.v1
+  view: market_overview_chunk
+  scope: selected | all | explicit
+  totalSymbolCount
+  generatedAt
+  offset
+  limit
+  chunkSymbolCount
+  hasMore
+  nextOffset?
+  returnedSymbols
+  semantics
+  market
+  table
+  legend
+FINALITY
+  This is the preferred market-scanning tool for large universes. One call is
+  not sufficient unless hasMore is false.
+DECISION IT ENABLES
+  Scan the full market in stable batches, score or shortlist symbols, then move
+  to symbol detail only after the scan is complete.
+COMMON PATTERN
+  offset 0 -> analyze chunk -> if hasMore use nextOffset -> repeat until done
+
+TOOL: helios_market_get_symbol_detail
+WHAT IT DOES
+  Returns expanded detail for a single symbol from the current market dataset.
+WHEN TO USE IT
+  Use after a snapshot or chunked snapshot pass has identified a symbol as
+  relevant for existing-position management or new-entry evaluation.
+SCOPE
+  market:read
+INPUT
+  symbol: string
+OUTPUT
+  schema: helios.market_symbol_detail.v1
+  generatedAt
+  symbol
+  semantics
+  market
+  row
+  symbolCtx
+  changeMap
+  metrics
+  legend
+FINALITY
+  This is the final market-read step before making a concrete trade decision on
+  one symbol.
+DECISION IT ENABLES
+  - entry timing
+  - stop placement quality
+  - take-profit context
+  - whether to hold, close, or avoid a symbol