@oobe-protocol-labs/sap-mcp-server 0.9.36 → 0.9.38

package/dist/tools/perp-tools.d.ts

@@ -2,10 +2,10 @@
  * @name tools/perp-tools
  * @description MCP tools for perpetual futures trading and chart analysis on Solana.
  *
- * Provides 8 tools across two categories:
+ * Provides perp analytics plus explicit execution-readiness tooling:
  *
  *   Read-only tools (7):
- *     - sap_perp_markets          — List Adrena perp markets with mark price, funding, OI.
+ *     - sap_perp_markets          — List Adrena markets with funding/accounting, OI, and oracle ids.
  *     - sap_perp_position_info    — Read on-chain perp positions for a wallet.
  *     - sap_perp_funding_history  — Compute funding rate from on-chain custody account.
  *     - sap_chart_ohlc            — OHLC candlestick data for any Solana token.
@@ -13,20 +13,162 @@
  *     - sap_chart_volume_profile  — Volume profile analysis (POC, VAH, VAL).
  *     - sap_perp_liquidation_zones — Compute liquidation zones for open positions.
  *
- *   Professional planning tools (1):
+ *   Professional planning tools:
  *     - sap_perp_trade_plan       — Build a trader-grade risk, route, and execution checklist.
+ *     - sap_perp_builder_status   — Report whether a hosted unsigned perps builder is configured.
  *
- * All read-only tools use free APIs (DexScreener, DeFiLlama) and Solana RPC
- * (Triton). Execution builders are intentionally not exposed unless the
- * account graph is IDL-backed and safe for local finalization.
+ * Adrena reads decode Pool, Custody, and Position accounts directly from the
+ * official release/39 ABI layout through Solana RPC. Optional provider hooks
+ * can enrich reads or build unsigned execution transactions, but SAP MCP never
+ * pretends a perps execution route exists until the builder can return a real
+ * locally finalizable Solana transaction.
  *
  * @module tools/perp-tools
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { PublicKey } from '@solana/web3.js';
 import type { SapMcpContext } from '../core/types.js';
+export declare const ADRENA_POSITION_OWNER_MEMCMP_OFFSET = 16;
+interface PerpMarketProviderRecord {
+    symbol?: string;
+    market?: string;
+    custodyAddress?: string;
+    poolAddress?: string;
+    custodyMint?: string;
+    markPrice?: number;
+    fundingRate?: number;
+    openInterestLong?: number;
+    openInterestShort?: number;
+    volume24h?: number;
+    provider?: string;
+    [key: string]: unknown;
+}
+interface DecodedAdrenaPool {
+    poolAddress: string;
+    name: string;
+    type?: string;
+    allowTrade: boolean;
+    allowSwap: boolean;
+    registeredCustodyCount: number;
+    custodies: string[];
+    lpTokenPriceUsd: number;
+    aumUsd: number;
+}
+interface DecodedAdrenaCustody {
+    symbol: string;
+    market: string;
+    custodyAddress: string;
+    poolAddress: string;
+    poolName?: string;
+    poolType?: string;
+    custodyMint: string;
+    tokenAccount: string;
+    oracle: string;
+    tradeOracle: string;
+    oracleFeedId: number;
+    tradeOracleFeedId: number;
+    decimals: number;
+    allowTrade: boolean;
+    allowSwap: boolean;
+    isStable: boolean;
+    isSynthetic: boolean;
+    version: number;
+    kind: 'collateral' | 'perp' | 'synthetic-perp' | 'unknown';
+    markPrice: number | null;
+    markPriceSource: 'not_in_custody_account';
+    maxInitialLeverage: number;
+    maxLeverage: number;
+    maxPositionLockedUsd: number;
+    openInterestLong: number;
+    openInterestShort: number;
+    openPositionsLong: number;
+    openPositionsShort: number;
+    borrowSizeLongUsd: number;
+    borrowSizeShortUsd: number;
+    collateralLongUsd: number;
+    collateralShortUsd: number;
+    lockedAmountLongRaw: string;
+    lockedAmountShortRaw: string;
+    tradeOiLongUsd: number;
+    tradeOiShortUsd: number;
+    cumulativeOpenPositionUsd: number;
+    assetsRaw: {
+        collateral: string;
+        owned: string;
+        locked: string;
+    };
+    borrowRate: {
+        currentRateRaw: string;
+        lastUpdate: number;
+    };
+    funding: {
+        currentRateLongToShortRaw: string;
+        lastUpdate: number;
+        cumulativeLongToShortRaw: string;
+        cumulativeShortToLongRaw: string;
+        maxHourlyFundingRateRaw: string;
+        minTotalOiUsd: number;
+        imbalanceSensitivityBps: number;
+    };
+}
+interface DecodedAdrenaPosition {
+    positionKey: string;
+    market: string;
+    side: 'long' | 'short';
+    sideRaw: number;
+    owner: string;
+    poolAddress: string;
+    custodyAddress: string;
+    collateralCustodyAddress: string;
+    openTime: number;
+    updateTime: number;
+    entryPrice: number;
+    entryPriceRaw: string;
+    size: number;
+    collateral: number;
+    borrowSizeUsd: number;
+    leverage: number;
+    unrealizedPnl: number;
+    unrealizedInterestUsd: number;
+    unrealizedFundingPaidUsd: number;
+    unrealizedFundingReceivedUsd: number;
+    lockedAmountRaw: string;
+    collateralAmountRaw: string;
+    liquidationPrice: number;
+    takeProfitLimitPrice: number | null;
+    stopLossLimitPrice: number | null;
+    stopLossClosePositionPrice: number | null;
+    id: string;
+}
+export declare function normalizePerpProviderMarkets(payload: unknown, marketFilter?: string): PerpMarketProviderRecord[];
+/**
+ * @name discToBase58
+ * @description Convert an 8-byte discriminator Buffer to a base58 string for
+ *              use in `getProgramAccounts` memcmp filters.
+ *
+ * @param disc — 8-byte discriminator Buffer.
+ * @returns Base58-encoded string.
+ *
+ * @internal
+ */
+export declare function discToBase58(disc: Buffer): string;
+/**
+ * @name readAdrenaLimitedString
+ * @description Read Adrena `LimitedString` (31-byte value + 1-byte length)
+ *              from an account data buffer.
+ *
+ * @param buf    — Source buffer.
+ * @param offset — Offset to the LimitedString field.
+ * @returns Decoded symbol string, or empty string on failure.
+ *
+ * @internal
+ */
+export declare function readAdrenaLimitedString(buf: Buffer, offset: number): string;
+export declare function decodeAdrenaCustodyAccount(pubkey: PublicKey, data: Buffer, pool?: DecodedAdrenaPool): DecodedAdrenaCustody | null;
+export declare function decodeAdrenaPositionAccount(pubkey: PublicKey, data: Buffer, marketsByCustody?: Map<string, DecodedAdrenaCustody>): DecodedAdrenaPosition | null;
 /**
  * @name registerPerpTools
- * @description Register all 8 perp trading analytics and planning MCP tools.
+ * @description Register perp trading analytics, planning, and optional execution-builder tools.
  *
  * @param server  — MCP server instance.
  * @param context — Shared runtime context with SAP client, connection, and config.
@@ -34,4 +176,5 @@ import type { SapMcpContext } from '../core/types.js';
  * @usedBy `register-tools.ts`
  */
 export declare function registerPerpTools(server: Server, context: SapMcpContext): void;
+export {};
 //# sourceMappingURL=perp-tools.d.ts.map

package/dist/tools/perp-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"perp-tools.d.ts","sourceRoot":"","sources":["../../src/tools/perp-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAEnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAkyCtD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,IAAI,CAa9E"}
+{"version":3,"file":"perp-tools.d.ts","sourceRoot":"","sources":["../../src/tools/perp-tools.ts"],"names":[],"mappings":"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"}