@pgnio/helios-mcp 0.0.0-stage → 0.2.0

package/docs/ai-agent-mcp/03_market/02_data_contracts.txt

@@ -0,0 +1,39 @@
+================================================================================
+MARKET DATA CONTRACTS
+================================================================================
+SNAPSHOT GLOBAL RULES
+  - percent fields are already percentages
+  - null means unavailable
+  - values are compact and schema-driven
+
+SNAPSHOT TOP LEVEL
+  schema
+  view
+  scope
+  symbolCount
+  generatedAt
+  returnedSymbols
+  semantics
+  market
+  table
+  legend
+
+SEMANTICS
+  nullMeans: unavailable
+  percentScale: already_percent
+  percentFields: string[]
+  changeMapPercentKeys: string[]
+
+TABLE BLOCK
+  fieldIds: compact column ids
+  rows: row arrays aligned to fieldIds
+
+DETAIL BLOCK
+  row: keyed symbol fields
+  symbolCtx: per-symbol trading context and metadata
+  changeMap: keyed timeframe changes
+  metrics: raw metric object or null
+
+REFERENCE
+  Indicator formulas and interpretation are documented separately in:
+  ai-agent-indicators/

package/docs/ai-agent-mcp/03_market/03_decision_rules.txt

@@ -0,0 +1,22 @@
+================================================================================
+MARKET DECISION RULES
+================================================================================
+USE get_snapshot FIRST
+  - compare symbols
+  - rank opportunities
+  - detect market regime/breadth
+
+USE get_symbol_detail SECOND
+  - inspect one candidate more deeply
+  - read symbol trading context
+  - inspect detailed metrics and change map
+
+SCOPE RULES
+  default scope is usually selected symbols
+  all symbols is heavier and should be used intentionally
+  explicit symbols is best for targeted follow-up
+
+INTERPRETATION RULES
+  - do not multiply percent values by 100
+  - do not impute null to zero
+  - read generatedAt before acting on fast-changing states

package/docs/ai-agent-mcp/03_market/04_failures_and_recovery.txt

@@ -0,0 +1,18 @@
+================================================================================
+MARKET FAILURES AND RECOVERY
+================================================================================
+MISSING SESSION
+  market:read login prompt returned
+
+BACKEND 401
+  stale session
+  MCP clears session and returns fresh market:read login guidance
+
+TRUNCATION RISK
+  all-symbol snapshots may be too large for human chat display
+  this is a display/transport issue, not necessarily a backend parse issue
+  agent should prefer structured consumption, not raw inline dumping
+
+MALFORMED INTERPRETATION
+  most common error is percent scaling
+  use semantics.percentScale = already_percent

package/docs/ai-agent-mcp/04_trading/00_overview.txt

@@ -0,0 +1,25 @@
+================================================================================
+LAYER: TRADING
+================================================================================
+PURPOSE
+  Submit live trading intents and manage active orders under delegated scopes.
+
+MODEL
+  Trading is intent-first, not exchange-native-first.
+  MCP wraps Helios execution APIs rather than exposing raw Hyperliquid order
+  placement as the primary interface.
+
+PRIMARY TOOLS
+  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
+
+IMPORTANT
+  Once a user has approved delegated scopes like orders:write or orders:cancel,
+  MCP trading tools can act directly. There is no second per-trade approval
+  layer in the current implementation.

package/docs/ai-agent-mcp/04_trading/01_tools.txt

@@ -0,0 +1,123 @@
+================================================================================
+TRADING TOOLS
+================================================================================
+TOOL: helios_trading_open
+WHAT IT DOES
+  Opens a fresh position using the OPEN intent path.
+SCOPE
+  orders:write
+INPUT
+  provider?
+  symbol
+  direction
+  size
+  execution
+  maxSlippageBps?
+  leverageOverride?
+  marginModeOverride?
+  reduceOnly?
+  protection?
+FINALITY
+  Creates new market risk.
+
+TOOL: helios_trading_dca
+WHAT IT DOES
+  Adds to an existing position using the DCA intent path.
+SCOPE
+  orders:write
+INPUT
+  provider?
+  symbol
+  direction
+  size
+  execution
+  maxSlippageBps?
+  leverageOverride?
+  marginModeOverride?
+  reduceOnly?
+  protection?
+FINALITY
+  Increases existing exposure.
+
+TOOL: helios_trading_reverse
+WHAT IT DOES
+  Closes an existing position and flips direction using the REVERSE intent path.
+SCOPE
+  orders:write
+INPUT
+  provider?
+  symbol
+  direction
+  size
+  execution
+  maxSlippageBps?
+  leverageOverride?
+  marginModeOverride?
+  reduceOnly?
+  protection?
+FINALITY
+  Closes current directional exposure and opens opposite-direction exposure.
+
+TOOL: helios_trading_close
+WHAT IT DOES
+  Closes the full open position for a symbol.
+SCOPE
+  orders:write
+INPUT
+  provider?
+  symbol
+  maxSlippageBps?
+FINALITY
+  Removes open risk in that symbol.
+
+TOOL: helios_positions_set_tp_sl
+WHAT IT DOES
+  Creates or replaces take-profit and stop-loss protection for an open position.
+SCOPE
+  orders:write
+INPUT
+  provider?
+  symbol
+  applyTo
+  quantity?
+  parentClientOrderId
+  takeProfit?
+  stopLoss?
+FINALITY
+  Changes protection only. It does not open or close the underlying position.
+
+TOOL: helios_positions_delete_tp_sl
+WHAT IT DOES
+  Deletes one existing TP/SL order by order id.
+SCOPE
+  orders:cancel
+INPUT
+  provider?
+  symbol
+  orderId
+FINALITY
+  Removes a protective order only.
+
+TOOL: helios_orders_get_open
+WHAT IT DOES
+  Lists the account's currently open working orders.
+SCOPE
+  account:read
+FINALITY
+  Read-only open-order inspection.
+
+TOOL: helios_orders_cancel
+WHAT IT DOES
+  Cancels one working order by symbol and oid.
+SCOPE
+  orders:cancel
+INPUT
+  symbol
+  oid
+FINALITY
+  Removes a working order from the book.
+
+NOTE
+  For helios_trading_* and helios_positions_* mutation tools, provider can be
+  omitted after calling helios_provider_set_active once for the current MCP
+  session.

package/docs/ai-agent-mcp/04_trading/02_data_contracts.txt

@@ -0,0 +1,42 @@
+================================================================================
+TRADING DATA CONTRACTS
+================================================================================
+INTENT INPUT
+  symbol: string
+  direction: LONG | SHORT
+  size:
+    mode: MARGIN_USD | BASE_QUANTITY
+    value: number > 0
+  execution:
+    style: MARKET | LIMIT_TAKER | LIMIT_MAKER | LIMIT_GTC
+    timeInForce?: GTC | IOC | FOK | GTX
+    limitPrice?: number
+  maxSlippageBps?: integer
+  leverageOverride?: number
+  marginModeOverride?: ISOLATED | CROSS
+  reduceOnly?: boolean
+  protection?:
+    takeProfit? / stopLoss?
+      kind: LIMIT | MARKET
+      triggerPrice: number
+      limitPrice?: number
+
+OPEN ORDER SHAPE
+  coin
+  side: B | A
+  limitPx
+  sz
+  origSz
+  oid
+  timestamp
+  orderType
+  tif
+  reduceOnly
+  isTrigger
+  triggerPx
+  cloid
+  assetId?
+
+IMPORTANT
+  The current CLOSE intent still requires direction because the underlying
+  backend contract requires direction.

package/docs/ai-agent-mcp/04_trading/03_decision_rules.txt

@@ -0,0 +1,30 @@
+================================================================================
+TRADING OPERATIONAL NOTES
+================================================================================
+INTENT TOOLS
+  helios_trading_open
+  helios_trading_dca
+  helios_trading_reverse
+  helios_trading_close
+
+  These tools submit Helios trading intents rather than raw exchange-native order
+  syntax.
+
+ORDER IDENTIFIERS
+  helios_orders_cancel requires a live oid.
+  helios_orders_get_open is the read endpoint that returns those identifiers.
+
+PROTECTION
+  helios_positions_set_tp_sl changes protection on an existing position.
+  helios_positions_delete_tp_sl removes one existing protection order by id.
+
+DO NOT ASSUME
+  - submit result contains exchange fill confirmation
+  - submitted means fully executed
+  - orders:write implies cancel permission
+
+RELATED READ ENDPOINTS
+  account.get_wallet_state
+  positions.get_open
+  ledger.get_summary
+  market.get_snapshot

package/docs/ai-agent-mcp/04_trading/04_failures_and_recovery.txt

@@ -0,0 +1,25 @@
+================================================================================
+TRADING FAILURES AND RECOVERY
+================================================================================
+MISSING SESSION
+  exact-scope login prompt returned:
+    orders:write for intent / set_tp_sl
+    orders:cancel for cancel / delete_tp_sl
+
+BACKEND 401
+  stale session
+  MCP clears local session
+  fresh login guidance returned
+
+VALIDATION FAILURE
+  malformed symbol, size, protection, or execution fields
+  fix input before retrying
+
+AUTHORIZATION FAILURE
+  missing delegated scope
+  user must approve a new login with the required scope
+
+EXECUTION FAILURE
+  backend may reject due to market state, symbol resolution, leverage, margin,
+  or exchange-specific conditions
+  submitted != guaranteed fill

package/docs/ai-agent-mcp/05_ledger/00_overview.txt

@@ -0,0 +1,31 @@
+================================================================================
+LAYER: LEDGER
+================================================================================
+PURPOSE
+  Give the agent current position state plus recent trading history and compact
+  performance metrics for real-time decisions.
+
+THIS LAYER COVERS
+  helios_positions_get_open
+  helios_ledger_get_fills
+  helios_ledger_get_summary
+
+DISTINCTIONS
+  wallet state
+    current account-level balances and margin
+
+  open positions
+    current directional exposures with unrealized PnL
+
+  open orders
+    working orders not yet fully resolved
+
+  fills
+    recent execution history
+
+  summary
+    derived realized-PnL and fee metrics over recent history
+
+DEFAULT HISTORY
+  window: 7d
+  limit: 100

package/docs/ai-agent-mcp/05_ledger/01_tools.txt

@@ -0,0 +1,80 @@
+================================================================================
+LEDGER TOOLS
+================================================================================
+TOOL: helios_positions_get_open
+WHAT IT DOES
+  Returns the current open positions with unrealized PnL, size, leverage, and
+  mark-price context.
+WHEN TO USE IT
+  Use near the start of every cycle before evaluating fresh entries.
+SCOPE
+  account:read
+OUTPUT
+  provider: hyperliquid
+  fetchedAt
+  totalUnrealizedPnl
+  positions[]
+FINALITY
+  Read-only live position state. This is not fill history and not realized PnL.
+DECISION IT ENABLES
+  - whether risk is already on
+  - which symbols require management first
+  - whether adding new trades would overextend the account
+
+TOOL: helios_ledger_get_fills
+WHAT IT DOES
+  Returns recent fills and trade history in a bounded time window.
+WHEN TO USE IT
+  Use when evaluating recent execution quality, recent behavior, or whether the
+  account is overtrading one symbol or regime.
+SCOPE
+  account:read
+INPUT
+  window?: 24h | 7d | 30d
+  limit?: 1..200
+  before?: timestamp_ms
+OUTPUT
+  window
+  limit
+  before?
+  hasMore
+  nextBefore?
+  fetchedAt
+  fills[]
+FINALITY
+  Bounded historical trade events only. It is not a live position endpoint.
+DECISION IT ENABLES
+  - inspect recent execution cadence
+  - detect repeated losses or churn
+  - reconstruct recent trade intent and behavior
+
+TOOL: helios_ledger_get_summary
+WHAT IT DOES
+  Returns compact realized performance metrics aggregated over recent fills.
+WHEN TO USE IT
+  Use once per cycle to understand recent PnL, fee drag, and win/loss quality
+  before deciding whether risk should be expanded or reduced.
+SCOPE
+  account:read
+INPUT
+  window?: 24h | 7d | 30d
+OUTPUT
+  window
+  generatedAt
+  realizedPnl
+  totalFees
+  fillCount
+  closeCount
+  winCount
+  lossCount
+  averageWin
+  averageLoss
+  periods.24h
+  periods.7d
+FINALITY
+  Aggregated realized-performance context. It does not replace fills when exact
+  trade reconstruction is needed.
+DECISION IT ENABLES
+  - whether recent performance supports normal risk-taking
+  - whether fee drag is too high
+  - whether the current regime is hurting execution quality

package/docs/ai-agent-mcp/05_ledger/02_data_contracts.txt

@@ -0,0 +1,46 @@
+================================================================================
+LEDGER DATA CONTRACTS
+================================================================================
+OPEN POSITION
+  symbol
+  side: LONG | SHORT
+  size: number
+  entryPrice: number
+  markPrice: number
+  unrealizedPnl: number
+  margin: number
+  leverage: number
+  liquidationPrice?: number
+
+LEDGER FILL
+  coin
+  px: number
+  sz: number
+  side: B | A
+  time: timestamp_ms
+  dir: string
+  closedPnl: number
+  fee: number
+  crossed: boolean
+  oid: number
+  tid: number
+
+LEDGER SUMMARY
+  realizedPnl
+  totalFees
+  fillCount
+  closeCount
+  winCount
+  lossCount
+  averageWin
+  averageLoss
+  periods:
+    24h
+    7d
+
+PAGINATION
+  before
+    timestamp_ms upper bound, exclusive
+
+  nextBefore
+    use this value to fetch older fills

package/docs/ai-agent-mcp/05_ledger/03_decision_rules.txt

@@ -0,0 +1,44 @@
+================================================================================
+LEDGER DECISION RULES
+================================================================================
+USE positions.get_open FOR
+  - current directional exposure
+  - unrealized PnL
+  - leverage and liquidation context
+
+USE ledger.get_fills FOR
+  - recent execution context
+  - fill-by-fill review
+  - what actually traded recently
+
+USE ledger.get_summary FOR
+  - fast realized performance read
+  - recent fees
+  - win/loss tendency
+
+SUMMARY MATH RULES
+  closing fills
+    dir contains "close" OR closedPnl != 0
+
+  totalFees
+    absolute fee sum
+
+  winCount
+    closing fills with closedPnl > 0
+
+  lossCount
+    closing fills with closedPnl < 0
+
+  zero-PnL closes
+    count as closes
+    do not count as wins or losses
+
+BEST PAIRINGS
+  wallet_state + positions.get_open
+    current account risk state
+
+  market.get_snapshot + ledger.get_summary
+    recent performance + current opportunity set
+
+  orders.get_open + positions.get_open
+    distinguish resting intent from active exposure

package/docs/ai-agent-mcp/05_ledger/04_failures_and_recovery.txt

@@ -0,0 +1,24 @@
+================================================================================
+LEDGER FAILURES AND RECOVERY
+================================================================================
+MISSING SESSION
+  account:read login prompt returned
+
+BACKEND 401
+  stale session
+  MCP clears session and returns fresh account:read login guidance
+
+EMPTY HISTORY
+  empty fills array can be a valid state
+  do not treat as backend failure
+
+HASMORE FALSE
+  means the bounded query exhausted the available results inside the current
+  window / before boundary
+
+COMMON MISTAKES
+  - do not confuse realizedPnl with unrealizedPnl
+  - do not infer position state from fills alone
+  - do not infer open orders from fills
+  - do not assume fee sign should be preserved in summary totals; summary uses
+    absolute fee totals

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@pgnio/helios-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Helios MCP server: connect an AI agent to your Helios account to read markets and your portfolio and to trade on Hyperliquid. Most apps can use the hosted URL https://helios.pgn.io/mcp instead.",
+  "license": "UNLICENSED",
+  "homepage": "https://helios.pgn.io/?connect=ai",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.mjs",
+  "bin": {
+    "helios-mcp": "./dist/cli.js",
+    "helios-agent-mcp": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "helios",
+    "mcp",
+    "agent",
+    "cli",
+    "trading"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "4.1.12"
+  },
+  "devDependencies": {
+    "@trivago/prettier-plugin-sort-imports": "6.0.0",
+    "@types/node": "24.10.1",
+    "@typescript-eslint/eslint-plugin": "8.46.4",
+    "@typescript-eslint/parser": "8.46.4",
+    "@vitest/coverage-v8": "4.0.9",
+    "eslint": "9.39.1",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-prettier": "5.5.4",
+    "prettier": "3.6.2",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.46.4",
+    "vitest": "4.0.9",
+    "@supercodebros/helios-agent": "0.1.0"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit --project tsconfig.json",
+    "format": "prettier . --write",
+    "format:check": "prettier . --check"
+  }
 }