@oobe-protocol-labs/sap-mcp-server 0.9.21 → 0.9.35

package/skills/sap-mcp/SKILL.md

@@ -9,6 +9,7 @@ safe signing behavior.
 If the user says "Start SAP MCP", "Initialize SAP MCP", "Load SAP", or "SAP
 mode", treat it as the activation command. Call `sap_agent_start` when it is
 available, then call `sap_agent_runtime_status` with the closest intent and
+`sap_prepare_action` when the request is more than a status check. Then call
 `sap_skills_bundle` with `includeContents: true`. Load the returned SAP MCP
 skill contents into context before selecting advanced tools.
 
@@ -22,18 +23,19 @@ Always inspect runtime context through MCP tools, not by reading config files:
 
 1. `sap_agent_start`
 2. `sap_agent_runtime_status` with `intent: "connection"`, `"paid-call"`, `"registry-write"`, `"transaction-finalize"`, `"escrow"`, `"identity"`, or `"general"`
-3. `sap_agent_context` for free compact agent/directory orientation before paid discovery
-4. `sap_skills_bundle` with `includeContents: true`
-5. `sap_pricing_catalog` before estimating hosted paid call tiers
-6. `sap_agent_next_action` before retrying after any SAP MCP error or partial write result
-7. `sap_skills_upgrade_plan` when local skills are missing or stale
-8. `sap_runtime_repair_plan` when hosted tools are connected but `sap_payments` is missing
-9. `sap_protocol_invariants` before SAP registry writes or when treasury, protocol fee, hosted write routing, or local signer routing is unclear
-10. `sap_agent_identity_plan` before agent registration, profile-image updates, Metaplex identity, SNS linking, or full identity setup
-11. `sap_profile_current`
-12. `sap_profile_list`
-13. `sap_profile_public_key`
-14. `sap_network_stats`
+3. `sap_prepare_action` with the closest intent before paid calls, swaps, registry writes, identity updates, Escrow V2, external x402 agents, premium streams, or transaction finalization
+4. `sap_agent_context` for free compact agent/directory orientation before paid discovery
+5. `sap_skills_bundle` with `includeContents: true`
+6. `sap_pricing_catalog` before estimating hosted paid call tiers
+7. `sap_agent_next_action` before retrying after any SAP MCP error or partial write result
+8. `sap_skills_upgrade_plan` when local skills are missing or stale
+9. `sap_runtime_repair_plan` when hosted tools are connected but `sap_payments` is missing
+10. `sap_protocol_invariants` before SAP registry writes or when treasury, protocol fee, hosted write routing, or local signer routing is unclear
+11. `sap_agent_identity_plan` before agent registration, profile-image updates, Metaplex identity, SNS linking, or full identity setup
+12. `sap_profile_current`
+13. `sap_profile_list`
+14. `sap_profile_public_key`
+15. `sap_network_stats`
 
 For simple "are you connected?" checks, do not dump tool counts or inspect
 local files. Use `sap_agent_runtime_status` first and answer with the hosted
@@ -57,6 +59,12 @@ and error strings unchanged.
   agent profile reads as fresh data. Do not rely on old chat memory when the
   user asks for current state; use exact lightweight reads first, then paid
   discovery only when enrichment or broad search is needed.
+- Treat session memory as operational context and proof tape, not cached market
+  or on-chain truth. It may store active profile names, public wallet keys,
+  runtime namespace availability, receipts, signatures, and error
+  classifications. It must not be used as truth for token prices, Jupiter
+  quotes/orders, balances, blockhashes, simulations, liquidity, routes, or SAP
+  account state.
 - Use free exact/base reads first when the wallet, PDA, or a small orientation
   page is enough: `sap_agent_context`, `sap_get_agent`, `sap_get_agent_profile`,
   `sap_get_agent_stats`, `sap_is_agent_active`, `sap_get_global_state`, and
@@ -100,7 +108,7 @@ Use the bundled routing map for local MCP tool selection:
 
 SAP MCP startup and skill bootstrap tools are free context/setup tools. Call
 `sap_agent_start`, `sap_agent_runtime_status`, `sap_agent_context`,
-`sap_agent_next_action`, `sap_pricing_catalog`,
+`sap_prepare_action`, `sap_agent_next_action`, `sap_pricing_catalog`,
 `sap_skills_list`, `sap_skills_bundle`, `sap_skills_upgrade_plan`,
 `sap_runtime_repair_plan`, and local `sap_skills_install` directly. Do not
 route startup, runtime status, pricing catalog, skill listing, bundling,
@@ -198,6 +206,9 @@ This prevents silent cap aborts and failed x402 attempts on local-signer-only
 tools. For local-signer-only tools (e.g. `sap_register_agent`), the estimate
 will say `tier: "local-signer-only"` and tell you to use the local
 `sap_payments_*` equivalent instead of `sap_payments_call_paid_tool`.
+For any intent-level workflow, call `sap_prepare_action` before execution. It
+returns the correct hosted/local route, fresh-data requirements, confirmation
+policy, retry rules, and proof-tape shape without charging x402.
 
 If a hosted paid tool returns `BlockhashNotFound`,
 `transaction_simulation_failed`, `smart_wallet_simulation_failed`, `node is

package/skills/sap-mcp/TOOL_REFERENCE.md

@@ -178,9 +178,7 @@ Jupiter protocol toolkit:
 `adrena_openPosition`, `adrena_removeCollateral`,
 `bridging_bridgeDeBridge`, `bridging_bridgeDeBridgeStatus`,
 `bridging_bridgeWormhole`, `bridging_bridgeWormholeStatus`,
-`drift_borrow`, `drift_closePerpPosition`, `drift_deposit`,
-`drift_getPositions`, `drift_lend`, `drift_openPerpPosition`,
-`drift_withdraw`, `jito_getBundleStatus`, `jito_getTipEstimate`,
+`jito_getBundleStatus`, `jito_getTipEstimate`,
 `jito_sendBundle`, `lulo_deposit`, `lulo_getBestRates`,
 `lulo_getPositions`, `lulo_withdraw`, `manifest_cancelOrder`,
 `manifest_createMarket`, `manifest_getOrderbook`,
@@ -209,7 +207,7 @@ Protocol routing shortcuts:
 | Token launch/mint/burn | `spl-token_deployToken`, `spl-token_mintTo`, `spl-token_burn` |
 | Jupiter quote/swap | `jupiter_getQuote`, `jupiter_smartSwap`, `jupiter_swap`, `jupiter_swapInstructions` |
 | Jupiter limit/DCA | `jupiter_createLimitOrder`, `jupiter_getLimitOrders`, `jupiter_createDCA`, `jupiter_getDCAOrders` |
-| Perps/lending | `drift_*`, `adrena_*`, `lulo_*` |
+| Perps/lending | `sap_perp_trade_plan`, `sap_perp_*`, `adrena_*`, `lulo_*` |
 | Liquidity pools | `raydium-pools_*`, `orca_*`, `meteora_*` |
 | Orderbooks | `openbook_*`, `manifest_*` |
 | Price data | `pyth_*`, `coingecko_*` |

package/skills/sap-payments-x402/SKILL.md

@@ -16,6 +16,7 @@ workflows, and hosted SAP MCP x402/pay.sh monetization.
 - `sap_payments_prepare_challenge`
 - `sap_payments_sign_challenge`
 - `sap_payments_verify_receipt`
+- `sap_prepare_action`
 - `sap_x402_paid_call`
 - `sap_create_subscription`
 - `sap_fund_subscription`
@@ -70,6 +71,15 @@ Before retrying `payment_required`, `hosted_local_signer_required`,
 signature, call `sap_agent_next_action`. Use its `safeToRetryNow`, `nextTool`,
 and `paymentCharged` fields as the retry guard.
 
+Before starting a paid or value-moving workflow, call the free hosted
+`sap_prepare_action` planner with the closest intent. It returns:
+
+- fresh data that must be fetched again before payment/signing;
+- whether to use hosted `sap`, local `sap_payments`, or a hosted unsigned
+  builder plus `sap_payments_finalize_transaction`;
+- max-price and confirmation guidance;
+- retry rules and the proof-tape fields to report back to the user.
+
 For fast x402 execution:
 
 1. Reuse the MCP session returned by `initialize`.
@@ -78,9 +88,11 @@ For fast x402 execution:
 3. Use `PAYMENT-SIGNATURE` first; use `X-PAYMENT` only for clients that require
    the alternate header.
 4. Cache only static MCP surface metadata such as `tools/list`, `prompts/list`,
-   and `resources/list` inside the runtime when useful. Do not cache on-chain
-   balances, SAP agent rows, pricing, SNS ownership, quotes, or settlement
-   state when the user expects fresh data.
+   and `resources/list` inside the runtime when useful. Session memory can
+   store operational context, receipts, signatures, and error classifications.
+   Do not cache on-chain balances, SAP agent rows, pricing, SNS ownership,
+   quotes, blockhashes, simulations, liquidity, routes, or settlement state
+   when the user expects fresh data.
 5. Treat `PAYMENT-RESPONSE` as the receipt bound to the tool output.
 6. If the client runtime cannot sign or attach x402 payment headers itself, use
    the local SAP MCP `sap_payments_call_paid_tool` bridge configured by the SAP

package/assets/logos/drift.svg

@@ -1,12 +0,0 @@
-<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
-<path d="M0 64C0 28.6538 28.6538 0 64 0H192C227.346 0 256 28.6538 256 64V192C256 227.346 227.346 256 192 256H64C28.6538 256 0 227.346 0 192V64Z" fill="#08AA18"/>
-<g clip-path="url(#clip0_354_3823)">
-<path d="M32 62.9677C32 45.8647 45.8647 32 62.9677 32H193.032C210.135 32 224 45.8647 224 62.9677V193.032C224 210.135 210.135 224 193.032 224H62.9677C45.8647 224 32 210.135 32 193.032V62.9677Z" fill="#08AA18"/>
-<path d="M105.764 71.4325C105.367 72.4792 106.14 73.599 107.259 73.5993H129.162C130.199 73.5993 130.962 74.5712 130.717 75.5786L116.825 132.535C116.424 134.18 118.518 135.239 119.606 133.941L169.692 74.1724C169.996 73.8097 170.446 73.5993 170.919 73.5993H203.043C204.411 73.5993 205.148 75.2066 204.256 76.2439L77.1854 224H65.261L92.329 110.773C92.5694 109.767 91.8069 108.8 90.7731 108.799H52.9722C51.6232 108.799 50.8805 107.233 51.7338 106.188L112.32 32H120.719L105.764 71.4325Z" fill="white"/>
-</g>
-<defs>
-<clipPath id="clip0_354_3823">
-<rect width="192" height="192" fill="white" transform="translate(32 32)"/>
-</clipPath>
-</defs>
-</svg>