@oobe-protocol-labs/sap-mcp-server 0.9.13 → 0.9.16

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

@@ -11,6 +11,7 @@ workflows, and hosted SAP MCP x402/pay.sh monetization.
 - `sap_payments_call_paid_tool`
 - `sap_payments_call_external_x402`
 - `sap_payments_register_agent`
+- `sap_payments_update_agent`
 - `sap_payments_finalize_transaction`
 - `sap_payments_prepare_challenge`
 - `sap_payments_sign_challenge`
@@ -44,9 +45,12 @@ hosted calls still proceed through x402/pay.sh plus the user's local SAP profile
 or external signer.
 
 - Free: `tools/list`, `prompts/list`, `resources/list`, `sap_profile_current`,
-  `sap_get_network_overview`, `sol_get_balance`, `spl-token_getBalance`, and
-  `spl-token_getTokenAccounts`.
-- Read premium: `sap_list_all_agents`, indexed discovery, network stats,
+  `sap_agent_start`, `sap_agent_runtime_status`, `sap_agent_context`,
+  `sap_agent_next_action`, exact SAP agent/profile reads, compact
+  `sap_list_agents` pages with `limit <= 20`, `sap_get_network_overview`, `sol_get_balance`,
+  `spl-token_getBalance`, and `spl-token_getTokenAccounts`.
+- Read premium: `sap_discover_agents`, `sap_list_all_agents`, full/enriched or
+  large `sap_list_agents` pages, indexed discovery, network stats,
   protocol/capability indexes.
 - Builder: batch SNS/domain checks, analytics, transaction builders.
 - Value action: fixed fee plus configured basis-points fee when public USD
@@ -57,6 +61,11 @@ instructions, create a payment, retry with `PAYMENT-SIGNATURE`, and capture
 `PAYMENT-RESPONSE` after settlement. If a `payShCheckoutUrl` is present, surface
 it for browser/manual checkout flows.
 
+Before retrying `payment_required`, `hosted_local_signer_required`,
+`BlockhashNotFound`, timeout, missing `sap_payments`, or an unconfirmed
+signature, call `sap_agent_next_action`. Use its `safeToRetryNow`, `nextTool`,
+and `paymentCharged` fields as the retry guard.
+
 For fast x402 execution:
 
 1. Reuse the MCP session returned by `initialize`.
@@ -98,6 +107,22 @@ accountless by design and cannot sign user-owned registry writes. Call local
 `sap_payments_register_agent` with the same registration fields and
 `confirm: true`; it uses the active local SAP MCP profile signer, submits the
 SAP registry transaction locally, and does not charge a hosted x402 access fee.
+After it returns, verify `success`, `agentRegistered`, `confirmationStatus`,
+`agentPda`, `protocolComplete`, and `protocolFee.status`. The expected protocol
+fee is `100000000` lamports to treasury
+`J7PyZAGKvprCz4SQ5DKBLAHstJxgVqZcz6kguUoWpP7P`. `success: true` means the agent
+account and protocol fee invariant were both verified. If `success` is false
+while `agentRegistered` is true, the account may exist but registration is not
+SAP protocol-complete; report that state and do not retry automatically.
+
+For hosted-user SAP agent profile updates, do not retry hosted
+`sap_update_agent` after `hosted_local_signer_required`. Call local
+`sap_payments_update_agent` with the intended replacement fields and
+`confirm: true`; it signs locally and does not charge a hosted x402 access fee.
+Use this for agent picture/profile metadata by first uploading the image or
+metadata JSON to a public URI such as IPFS, Arweave, Kommodo, or HTTPS, then
+setting `agentUri` or `metadataUri`. Do not use desktop file paths.
+After update, fetch the agent profile again and verify the changed fields.
 
 If the hosted paid tool returns `transactionBase64`, `transaction`, or an
 unsigned transaction object, call `sap_payments_finalize_transaction` with
@@ -109,6 +134,16 @@ default and returns `confirmationStatus` plus `retrySafe`. Treat
 signing scripts, read keypair JSON, or call hosted `sap_sign_transaction` for
 user-owned signatures.
 
+For Escrow V2 hosted workflows, use the unsigned builder family first:
+`sap_escrow_build_create_transaction`,
+`sap_escrow_build_deposit_transaction`,
+`sap_escrow_build_settle_transaction`,
+`sap_escrow_build_finalize_transaction`,
+`sap_escrow_build_withdraw_transaction`, or
+`sap_escrow_build_close_transaction`, then finalize locally with
+`sap_payments_finalize_transaction`. Use direct escrow write tools only when a
+local SAP MCP profile with signer is the selected runtime.
+
 Use low-level helpers only for custom clients:
 
 - `sap_payments_prepare_challenge` returns the parsed hosted x402 challenge

package/skills/sap-sns/SKILL.md

@@ -17,6 +17,8 @@ This skill is adapted from upstream `sns-skill` plus SAP MCP's
    `sap_payments_finalize_transaction`.
 6. Register domains directly only from a local SAP MCP profile using
    `sap_sns_register_agent_domain` after explicit user confirmation.
+7. After SNS ownership or records are ready, update the SAP agent metadata with
+   `sap_payments_update_agent` so `metadataUri` references the `.sol` identity.
 
 Hosted accountless SAP MCP cannot register a .sol domain directly because the
 purchase requires the user wallet signature. If a hosted direct registration is
@@ -48,9 +50,24 @@ to the local profile flow instead of retrying the hosted write.
 
 - Never assume mainnet/devnet; read the profile RPC first.
 - Never read the local wallet file.
+- `sap_sns_check_ownership` canonical field is `owner`; `wallet` is accepted as
+  an alias for agent ergonomics.
 - Prefer build/preview/sign flows over direct register flows when the user
   needs to review transaction details.
 - Do not claim `sap_sns_build_register_domain_transaction` exists unless it is
   returned by `tools/list`.
 - Do not route hosted direct registration through x402; hosted accountless
   servers reject local-signer writes before payment.
+
+## SAP Agent Identity Link
+
+For “use my .sol as my SAP identity”:
+
+1. Resolve or check ownership with `sap_sns_resolve_wallet` and
+   `sap_sns_check_ownership`.
+2. If a record must change from hosted mode, build the unsigned record
+   transaction and finalize with `sap_payments_finalize_transaction`.
+3. Update the agent metadata JSON to include:
+   `{ "sns": { "domain": "name.sol" } }`.
+4. Call local `sap_payments_update_agent` with the public `metadataUri` and
+   `confirm: true`.