@pgnio/helios-mcp 0.2.8 → 0.2.9

package/dist/cli.js

@@ -139,19 +139,21 @@ var protectiveOrderKindSchema = import_zod.z.enum(["STOP_LOSS", "TAKE_PROFIT"]);
 var protectiveOrderSideSchema = import_zod.z.enum(["BUY", "SELL"]);
 var protectiveOrderPositionSideSchema = import_zod.z.enum(["BOTH", "LONG", "SHORT"]);
 var protectiveOrderSchema = import_zod.z.object({
+  /** Helios's record id: what helios_positions_delete_tp_sl takes (the Hyperliquid order id works there too). */
   id: import_zod.z.string(),
-  binanceOrderId: import_zod.z.number().int().nonnegative().optional(),
-  clientOrderId: import_zod.z.string().optional(),
+  /** The Hyperliquid order id (named after the retired Binance field). */
+  binanceOrderId: import_zod.z.number().int().nonnegative().nullish(),
+  clientOrderId: import_zod.z.string().nullish(),
   symbol: import_zod.z.string(),
   side: protectiveOrderSideSchema,
-  positionSide: protectiveOrderPositionSideSchema,
+  positionSide: protectiveOrderPositionSideSchema.nullish().transform((value) => value ?? "BOTH"),
   status: import_zod.z.string(),
   kind: protectiveOrderKindSchema,
-  groupId: import_zod.z.string(),
-  stopPrice: import_zod.z.string().optional(),
-  parentClientOrderId: import_zod.z.string().optional(),
-  assetId: import_zod.z.number().int().nonnegative().optional(),
-  createdAt: import_zod.z.string().datetime()
+  groupId: import_zod.z.string().nullish(),
+  stopPrice: import_zod.z.union([import_zod.z.string(), import_zod.z.number()]).nullish().transform((value) => value == null ? value : String(value)),
+  parentClientOrderId: import_zod.z.string().nullish(),
+  assetId: import_zod.z.number().int().nonnegative().nullish(),
+  createdAt: import_zod.z.string().nullish()
 });
 var hyperliquidPortfolioSnapshotSchema = import_zod.z.object({
   provider: import_zod.z.literal("hyperliquid"),
@@ -160,6 +162,7 @@ var hyperliquidPortfolioSnapshotSchema = import_zod.z.object({
   totalMargin: import_zod.z.number(),
   unrealizedPnl: import_zod.z.number(),
   positions: import_zod.z.array(openPositionSchema),
+  /** Unreadable entries are dropped (see readProtectiveOrders) rather than failing the read. */
   protectiveOrders: import_zod.z.array(protectiveOrderSchema)
 });
 var portfolioInputSchema = import_zod.z.object({
@@ -354,6 +357,8 @@ var closePositionInputSchema = import_zod.z.object({
 });
 var closePositionResultSchema = import_zod.z.object({
   status: import_zod.z.literal("submitted"),
+  /** `no_position`: nothing was open on this coin, so no order was sent. Absent from older data-bridges. */
+  outcome: import_zod.z.enum(["closed", "no_position"]).optional(),
   provider: providerSchema.optional(),
   symbol: import_zod.z.string(),
   mode: import_zod.z.literal("FULL"),
@@ -544,7 +549,8 @@ var HeliosAgentDataBridgeClient = class {
     }
     return portfolioSnapshotSchema.parse({
       ...result,
-      provider: parsedInput.provider
+      provider: parsedInput.provider,
+      protectiveOrders: readProtectiveOrders(result.protectiveOrders)
     });
   }
   async getLedgerFills(accessToken, input = {}) {
@@ -597,7 +603,7 @@ var HeliosAgentDataBridgeClient = class {
   }
   async closePosition(accessToken, input) {
     const parsedInput = closePositionInputSchema.parse(input);
-    await this.request(
+    const payload = await this.request(
       accessToken,
       "positions.close",
       {
@@ -608,8 +614,10 @@ var HeliosAgentDataBridgeClient = class {
       },
       "POST"
     );
+    const outcome = this.tryUnwrapResult(payload)?.outcome;
     return closePositionResultSchema.parse({
       status: "submitted",
+      ...outcome === "closed" || outcome === "no_position" ? { outcome } : {},
       provider: parsedInput.provider,
       symbol: parsedInput.symbol,
       mode: "FULL",
@@ -707,6 +715,14 @@ var HeliosAgentDataBridgeClient = class {
       });
     }
   }
+  /** The result of a mutation older data-bridges answer with nothing; null when there is none. */
+  tryUnwrapResult(payload) {
+    try {
+      return this.unwrapResult(payload) ?? null;
+    } catch {
+      return null;
+    }
+  }
   unwrapResult(payload) {
     if (!payload || typeof payload !== "object") {
       throw new HeliosAgentApiError({
@@ -767,6 +783,13 @@ var HeliosAgentDataBridgeClient = class {
     return envelope;
   }
 };
+function readProtectiveOrders(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => {
+    const parsed = protectiveOrderSchema.safeParse(entry);
+    return parsed.success ? [parsed.data] : [];
+  });
+}
 var DEFAULT_AGENT_REFRESH_WINDOW_MS = 60 * 1e3;
 var agentConnectionStatusSchema = import_zod3.z.enum([
   "disconnected",
@@ -1220,6 +1243,9 @@ var HeliosAgentMcpDocsService = class {
   }
   async getDocument(input) {
     const documentPath = resolveDocumentPath(this.docsRoot, input.path);
+    if (!(0, import_node_fs.existsSync)(documentPath) || !(0, import_node_fs.statSync)(documentPath).isFile()) {
+      throw new Error(`No document "${input.path}". helios_docs_get_index lists the documents.`);
+    }
     const body = (0, import_node_fs.readFileSync)(documentPath, "utf8");
     const stats = (0, import_node_fs.statSync)(documentPath);
     const relativePath = toPosixPath(import_node_path.default.relative(this.docsRoot, documentPath));
@@ -2522,7 +2548,7 @@ function createHeliosAccountToolDefinitions(service) {
     {
       name: "helios_portfolio_get",
       title: "Get Helios Portfolio",
-      description: "Returns a provider-specific portfolio snapshot. Provider may be omitted if one is already pinned with helios_provider_set_active.",
+      description: "Returns balances, open positions and their TP/SL (protectiveOrders, each with the id helios_positions_delete_tp_sl takes). Provider may be omitted if one is already pinned with helios_provider_set_active.",
       inputSchema: providerSelectionInputSchema,
       async execute(input) {
         const result = portfolioToolOutputSchema.parse(await service.getPortfolio(input));
@@ -2759,7 +2785,7 @@ function createHeliosTradingToolDefinitions(service) {
           content: [
             {
               type: "text",
-              text: result.status === "connected" ? `Submitted Helios full close for ${result.closure.provider ?? input.provider} ${result.closure.symbol}.` : result.message
+              text: result.status !== "connected" ? result.message : result.closure.outcome === "no_position" ? `No open ${result.closure.symbol} position: nothing was closed and no order was sent.` : `Sent a market order closing the full ${result.closure.provider ?? input.provider ?? "hyperliquid"} ${result.closure.symbol} position. Check helios_positions_get_open to confirm.`
             }
           ],
           structuredContent: result.status === "connected" ? result : {
@@ -2793,7 +2819,7 @@ function createHeliosTradingToolDefinitions(service) {
     {
       name: "helios_positions_delete_tp_sl",
       title: "Delete Helios TP/SL",
-      description: "Deletes an existing Helios take-profit or stop-loss order by order id. Provider may be omitted if one is already pinned with helios_provider_set_active.",
+      description: "Deletes a take-profit or stop-loss. orderId is the id from helios_portfolio_get protectiveOrders, or the Hyperliquid order id of the TP/SL. Provider may be omitted if one is already pinned with helios_provider_set_active.",
       inputSchema: deleteTpSlInputSchema,
       async execute(input) {
         const result = deleteTpSlToolOutputSchema.parse(await service.deleteTpSl(input));
@@ -2886,7 +2912,7 @@ async function createHeliosAgentMcpServer(options) {
   const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
   const server = new McpServer({
     name: "helios",
-    version: "0.2.8"
+    version: "0.2.9"
   });
   const sessionStore = options.sessionStore ?? new FileAgentSessionStore(options.sessionPath ?? getDefaultHeliosAgentMcpSessionPath());
   const client = new HeliosAgentAuthClient({

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   createHeliosAgentMcpServer
-} from "./chunk-UHFLF3UG.mjs";
+} from "./chunk-7TMDGB6C.mjs";
 
 // src/cli.ts
 async function main() {

package/dist/index.d.mts

@@ -94,28 +94,28 @@ declare const portfolioSnapshotSchema: z.ZodObject<{
     }, z.core.$strip>>;
     protectiveOrders: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
-        binanceOrderId: z.ZodOptional<z.ZodNumber>;
-        clientOrderId: z.ZodOptional<z.ZodString>;
+        binanceOrderId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        clientOrderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         symbol: z.ZodString;
         side: z.ZodEnum<{
             BUY: "BUY";
             SELL: "SELL";
         }>;
-        positionSide: z.ZodEnum<{
+        positionSide: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             LONG: "LONG";
             SHORT: "SHORT";
             BOTH: "BOTH";
-        }>;
+        }>>>, z.ZodTransform<"LONG" | "SHORT" | "BOTH", "LONG" | "SHORT" | "BOTH" | null | undefined>>;
         status: z.ZodString;
         kind: z.ZodEnum<{
             STOP_LOSS: "STOP_LOSS";
             TAKE_PROFIT: "TAKE_PROFIT";
         }>;
-        groupId: z.ZodString;
-        stopPrice: z.ZodOptional<z.ZodString>;
-        parentClientOrderId: z.ZodOptional<z.ZodString>;
-        assetId: z.ZodOptional<z.ZodNumber>;
-        createdAt: z.ZodString;
+        groupId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        stopPrice: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>, z.ZodTransform<string | null | undefined, string | number | null | undefined>>;
+        parentClientOrderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        assetId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        createdAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 declare const ledgerFillsInputSchema: z.ZodObject<{
@@ -440,6 +440,10 @@ declare const closePositionInputSchema: z.ZodObject<{
 }, z.core.$strip>;
 declare const closePositionResultSchema: z.ZodObject<{
     status: z.ZodLiteral<"submitted">;
+    outcome: z.ZodOptional<z.ZodEnum<{
+        closed: "closed";
+        no_position: "no_position";
+    }>>;
     provider: z.ZodOptional<z.ZodEnum<{
         hyperliquid: "hyperliquid";
     }>>;
@@ -606,6 +610,8 @@ declare class HeliosAgentDataBridgeClient {
     private request;
     private buildProcedureUrl;
     private parseJson;
+    /** The result of a mutation older data-bridges answer with nothing; null when there is none. */
+    private tryUnwrapResult;
     private unwrapResult;
     private extractErrorCode;
     private extractErrorMessage;

package/dist/index.d.ts

@@ -94,28 +94,28 @@ declare const portfolioSnapshotSchema: z.ZodObject<{
     }, z.core.$strip>>;
     protectiveOrders: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
-        binanceOrderId: z.ZodOptional<z.ZodNumber>;
-        clientOrderId: z.ZodOptional<z.ZodString>;
+        binanceOrderId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        clientOrderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         symbol: z.ZodString;
         side: z.ZodEnum<{
             BUY: "BUY";
             SELL: "SELL";
         }>;
-        positionSide: z.ZodEnum<{
+        positionSide: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodEnum<{
             LONG: "LONG";
             SHORT: "SHORT";
             BOTH: "BOTH";
-        }>;
+        }>>>, z.ZodTransform<"LONG" | "SHORT" | "BOTH", "LONG" | "SHORT" | "BOTH" | null | undefined>>;
         status: z.ZodString;
         kind: z.ZodEnum<{
             STOP_LOSS: "STOP_LOSS";
             TAKE_PROFIT: "TAKE_PROFIT";
         }>;
-        groupId: z.ZodString;
-        stopPrice: z.ZodOptional<z.ZodString>;
-        parentClientOrderId: z.ZodOptional<z.ZodString>;
-        assetId: z.ZodOptional<z.ZodNumber>;
-        createdAt: z.ZodString;
+        groupId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        stopPrice: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>, z.ZodTransform<string | null | undefined, string | number | null | undefined>>;
+        parentClientOrderId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        assetId: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        createdAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 declare const ledgerFillsInputSchema: z.ZodObject<{
@@ -440,6 +440,10 @@ declare const closePositionInputSchema: z.ZodObject<{
 }, z.core.$strip>;
 declare const closePositionResultSchema: z.ZodObject<{
     status: z.ZodLiteral<"submitted">;
+    outcome: z.ZodOptional<z.ZodEnum<{
+        closed: "closed";
+        no_position: "no_position";
+    }>>;
     provider: z.ZodOptional<z.ZodEnum<{
         hyperliquid: "hyperliquid";
     }>>;
@@ -606,6 +610,8 @@ declare class HeliosAgentDataBridgeClient {
     private request;
     private buildProcedureUrl;
     private parseJson;
+    /** The result of a mutation older data-bridges answer with nothing; null when there is none. */
+    private tryUnwrapResult;
     private unwrapResult;
     private extractErrorCode;
     private extractErrorMessage;

package/dist/index.js

@@ -179,19 +179,21 @@ var protectiveOrderKindSchema = import_zod.z.enum(["STOP_LOSS", "TAKE_PROFIT"]);
 var protectiveOrderSideSchema = import_zod.z.enum(["BUY", "SELL"]);
 var protectiveOrderPositionSideSchema = import_zod.z.enum(["BOTH", "LONG", "SHORT"]);
 var protectiveOrderSchema = import_zod.z.object({
+  /** Helios's record id: what helios_positions_delete_tp_sl takes (the Hyperliquid order id works there too). */
   id: import_zod.z.string(),
-  binanceOrderId: import_zod.z.number().int().nonnegative().optional(),
-  clientOrderId: import_zod.z.string().optional(),
+  /** The Hyperliquid order id (named after the retired Binance field). */
+  binanceOrderId: import_zod.z.number().int().nonnegative().nullish(),
+  clientOrderId: import_zod.z.string().nullish(),
   symbol: import_zod.z.string(),
   side: protectiveOrderSideSchema,
-  positionSide: protectiveOrderPositionSideSchema,
+  positionSide: protectiveOrderPositionSideSchema.nullish().transform((value) => value ?? "BOTH"),
   status: import_zod.z.string(),
   kind: protectiveOrderKindSchema,
-  groupId: import_zod.z.string(),
-  stopPrice: import_zod.z.string().optional(),
-  parentClientOrderId: import_zod.z.string().optional(),
-  assetId: import_zod.z.number().int().nonnegative().optional(),
-  createdAt: import_zod.z.string().datetime()
+  groupId: import_zod.z.string().nullish(),
+  stopPrice: import_zod.z.union([import_zod.z.string(), import_zod.z.number()]).nullish().transform((value) => value == null ? value : String(value)),
+  parentClientOrderId: import_zod.z.string().nullish(),
+  assetId: import_zod.z.number().int().nonnegative().nullish(),
+  createdAt: import_zod.z.string().nullish()
 });
 var hyperliquidPortfolioSnapshotSchema = import_zod.z.object({
   provider: import_zod.z.literal("hyperliquid"),
@@ -200,6 +202,7 @@ var hyperliquidPortfolioSnapshotSchema = import_zod.z.object({
   totalMargin: import_zod.z.number(),
   unrealizedPnl: import_zod.z.number(),
   positions: import_zod.z.array(openPositionSchema),
+  /** Unreadable entries are dropped (see readProtectiveOrders) rather than failing the read. */
   protectiveOrders: import_zod.z.array(protectiveOrderSchema)
 });
 var portfolioInputSchema = import_zod.z.object({
@@ -394,6 +397,8 @@ var closePositionInputSchema = import_zod.z.object({
 });
 var closePositionResultSchema = import_zod.z.object({
   status: import_zod.z.literal("submitted"),
+  /** `no_position`: nothing was open on this coin, so no order was sent. Absent from older data-bridges. */
+  outcome: import_zod.z.enum(["closed", "no_position"]).optional(),
   provider: providerSchema.optional(),
   symbol: import_zod.z.string(),
   mode: import_zod.z.literal("FULL"),
@@ -584,7 +589,8 @@ var HeliosAgentDataBridgeClient = class {
     }
     return portfolioSnapshotSchema.parse({
       ...result,
-      provider: parsedInput.provider
+      provider: parsedInput.provider,
+      protectiveOrders: readProtectiveOrders(result.protectiveOrders)
     });
   }
   async getLedgerFills(accessToken, input = {}) {
@@ -637,7 +643,7 @@ var HeliosAgentDataBridgeClient = class {
   }
   async closePosition(accessToken, input) {
     const parsedInput = closePositionInputSchema.parse(input);
-    await this.request(
+    const payload = await this.request(
       accessToken,
       "positions.close",
       {
@@ -648,8 +654,10 @@ var HeliosAgentDataBridgeClient = class {
       },
       "POST"
     );
+    const outcome = this.tryUnwrapResult(payload)?.outcome;
     return closePositionResultSchema.parse({
       status: "submitted",
+      ...outcome === "closed" || outcome === "no_position" ? { outcome } : {},
       provider: parsedInput.provider,
       symbol: parsedInput.symbol,
       mode: "FULL",
@@ -747,6 +755,14 @@ var HeliosAgentDataBridgeClient = class {
       });
     }
   }
+  /** The result of a mutation older data-bridges answer with nothing; null when there is none. */
+  tryUnwrapResult(payload) {
+    try {
+      return this.unwrapResult(payload) ?? null;
+    } catch {
+      return null;
+    }
+  }
   unwrapResult(payload) {
     if (!payload || typeof payload !== "object") {
       throw new HeliosAgentApiError({
@@ -807,6 +823,13 @@ var HeliosAgentDataBridgeClient = class {
     return envelope;
   }
 };
+function readProtectiveOrders(value) {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry) => {
+    const parsed = protectiveOrderSchema.safeParse(entry);
+    return parsed.success ? [parsed.data] : [];
+  });
+}
 var DEFAULT_AGENT_REFRESH_WINDOW_MS = 60 * 1e3;
 var agentConnectionStatusSchema = import_zod3.z.enum([
   "disconnected",
@@ -1260,6 +1283,9 @@ var HeliosAgentMcpDocsService = class {
   }
   async getDocument(input) {
     const documentPath = resolveDocumentPath(this.docsRoot, input.path);
+    if (!(0, import_node_fs.existsSync)(documentPath) || !(0, import_node_fs.statSync)(documentPath).isFile()) {
+      throw new Error(`No document "${input.path}". helios_docs_get_index lists the documents.`);
+    }
     const body = (0, import_node_fs.readFileSync)(documentPath, "utf8");
     const stats = (0, import_node_fs.statSync)(documentPath);
     const relativePath = toPosixPath(import_node_path.default.relative(this.docsRoot, documentPath));
@@ -2596,7 +2622,7 @@ function createHeliosAccountToolDefinitions(service) {
     {
       name: "helios_portfolio_get",
       title: "Get Helios Portfolio",
-      description: "Returns a provider-specific portfolio snapshot. Provider may be omitted if one is already pinned with helios_provider_set_active.",
+      description: "Returns balances, open positions and their TP/SL (protectiveOrders, each with the id helios_positions_delete_tp_sl takes). Provider may be omitted if one is already pinned with helios_provider_set_active.",
       inputSchema: providerSelectionInputSchema,
       async execute(input) {
         const result = portfolioToolOutputSchema.parse(await service.getPortfolio(input));
@@ -2833,7 +2859,7 @@ function createHeliosTradingToolDefinitions(service) {
           content: [
             {
               type: "text",
-              text: result.status === "connected" ? `Submitted Helios full close for ${result.closure.provider ?? input.provider} ${result.closure.symbol}.` : result.message
+              text: result.status !== "connected" ? result.message : result.closure.outcome === "no_position" ? `No open ${result.closure.symbol} position: nothing was closed and no order was sent.` : `Sent a market order closing the full ${result.closure.provider ?? input.provider ?? "hyperliquid"} ${result.closure.symbol} position. Check helios_positions_get_open to confirm.`
             }
           ],
           structuredContent: result.status === "connected" ? result : {
@@ -2867,7 +2893,7 @@ function createHeliosTradingToolDefinitions(service) {
     {
       name: "helios_positions_delete_tp_sl",
       title: "Delete Helios TP/SL",
-      description: "Deletes an existing Helios take-profit or stop-loss order by order id. Provider may be omitted if one is already pinned with helios_provider_set_active.",
+      description: "Deletes a take-profit or stop-loss. orderId is the id from helios_portfolio_get protectiveOrders, or the Hyperliquid order id of the TP/SL. Provider may be omitted if one is already pinned with helios_provider_set_active.",
       inputSchema: deleteTpSlInputSchema,
       async execute(input) {
         const result = deleteTpSlToolOutputSchema.parse(await service.deleteTpSl(input));
@@ -2960,7 +2986,7 @@ async function createHeliosAgentMcpServer(options) {
   const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
   const server = new McpServer({
     name: "helios",
-    version: "0.2.8"
+    version: "0.2.9"
   });
   const sessionStore = options.sessionStore ?? new FileAgentSessionStore(options.sessionPath ?? getDefaultHeliosAgentMcpSessionPath());
   const client = new HeliosAgentAuthClient({

package/dist/index.mjs

@@ -29,7 +29,7 @@ import {
   topOfSnapshot,
   withDataText,
   withSnapshotDefaults
-} from "./chunk-UHFLF3UG.mjs";
+} from "./chunk-7TMDGB6C.mjs";
 export {
   DEFAULT_SNAPSHOT_FIELDS,
   DEFAULT_SNAPSHOT_TOP,

package/docs/ai-agent-indicators/00_columns.txt

@@ -71,4 +71,6 @@ WHAT HAS HELD UP IN BACKTESTS (out of sample, last 2 years)
 - Buying a sharp turn up (hmiv > 0, r15m and r1h turning positive) in a coin whose
   reg is BREAKDOWN or CRASH, especially when the whole market is down (os high, Mti < 0).
 - Fading stretched moves beat chasing them.
-- Shorts did not hold up. Edges are small (about +0.1% a trade): size small, always use a stop.
+- Shorts did not hold up. Edges are small: about +0.1% a trade after a 0.38% round-trip cost,
+  on holds of 1-3 days. Frequent in-and-out trading pays fees without that edge.
+  Size small, always use a stop.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgnio/helios-mcp",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "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",