@oobe-protocol-labs/sap-mcp-server 0.9.7 → 0.9.9

package/skills/sap-agent-registry/SKILL.md

@@ -7,7 +7,10 @@ state, global directory listing, and agent profile inspection.
 
 1. Call `sap_profile_current`.
 2. Call `sap_get_network_overview` for ecosystem counters when needed.
-3. Use `sap_list_all_agents` for global current agent lists.
+3. Use `sap_discover_agents` with `query`, `wallet`, `protocol`, or
+   `capability` for targeted paid hosted directory reads.
+4. Use `sap_list_all_agents` for global current agent lists and follow
+   `pagination.nextCursor` for additional pages.
 
 ## Tools
 
@@ -28,7 +31,17 @@ state, global directory listing, and agent profile inspection.
 
 ## Routing
 
-- "List all agents" means `sap_list_all_agents`.
+- Hosted accountless SAP MCP cannot sign user-owned registry writes. If
+  `sap_register_agent`, `sap_update_agent`, or another registry write returns
+  `hosted_local_signer_required`, no x402 payment was charged; run the write on
+  the local SAP MCP profile or use a production unsigned builder/finalizer flow
+  when available.
+- "Find XONA Agent" or "find an agent by name" means `sap_discover_agents` with
+  `query`.
+- "Find x402 agents" means `sap_discover_agents` with
+  `hasX402Endpoint: true`.
+- "List all agents" means `sap_list_all_agents` with a small `limit`, then
+  `pagination.nextCursor` if the user wants more.
 - "Agent by wallet" means `sap_get_agent` or `sap_get_agent_profile`.
 - "Is this agent live?" means `sap_is_agent_active`.
 - "Network totals" means `sap_get_network_overview`.

package/skills/sap-defi/SKILL.md

@@ -40,12 +40,16 @@ staking protocols.
 ## Flow
 
 1. Use quote/read tools first.
-2. For swaps, prefer `jupiter_getQuote` then `jupiter_smartSwap` or
-   `jupiter_swapInstructions`.
+2. In hosted mode, prefer quote/read tools and unsigned builders such as
+   `jupiter_getOrder`, `jupiter_swapInstructions`, or supported private swap
+   builders. Direct signer tools such as `jupiter_swap`, `jupiter_smartSwap`,
+   and `jupiter_executeOrder` require a local SAP MCP profile or external
+   signer and are rejected before x402 payment on hosted accountless servers.
 3. Explain slippage, route, token mints, amount units, and expected output.
 4. Preview and policy-check before signing.
-5. For any unsigned or partially signed transaction returned by Jupiter, use
-   `sap_preview_transaction`, `sap_sign_transaction`, and
+5. For any unsigned or partially signed transaction returned by hosted SAP MCP,
+   use `sap_payments_finalize_transaction`. For local SAP MCP stdio builders,
+   use `sap_preview_transaction`, `sap_sign_transaction`, and
    `sap_submit_signed_transaction`. Do not write ad-hoc signing scripts.
 
 ## Safety

package/skills/sap-discovery-indexing/SKILL.md

@@ -18,16 +18,27 @@ indexes, and filtered agent discovery.
 
 ## Rules
 
-- Use `sap_list_all_agents` for global directory requests.
-- Use `sap_discover_agents` only with `protocol`, `capability`, or
-  `capabilities`.
+- Use `sap_discover_agents` for paid hosted agent directory search. It supports
+  `query`, `wallet`, `agentPda`, `protocol`, `capability`, `capabilities`,
+  `capabilityMode`, `hasX402Endpoint`, `limit`, `cursor`, and `view`.
+- Use `sap_list_all_agents` for global directory requests or when the user asks
+  for the whole SAP ecosystem. Keep the first page small and follow
+  `pagination.nextCursor` only when the previous page is useful.
+- Prefer exact filters before broad scans: `wallet` when a wallet is known,
+  `query` for an agent name such as `XONA`, and `capability` for one exact
+  capability such as `creative:imageGeneration`.
 - Use `sap_fetch_protocol_index` when the protocol ID is known.
 - Use `sap_fetch_capability_index` when the capability ID is known.
+- If a capability-filtered lookup returns zero results, retry with `query` or
+  `wallet` before claiming the agent does not exist; capability indexes can lag
+  the canonical AgentAccount directory.
 - Do not guess that global enumeration is impossible; try `sap_list_all_agents`
-  first.
+  first and report the exact failure if it fails.
 
 ## Common Inputs
 
 - Protocol IDs: `sap`, `jupiter`, `pyth`, `sns`, `mcp-v1`, or the exact
   protocol ID returned by protocol indexes.
 - Capability IDs usually use namespaced form such as `jupiter:swap`.
+- For x402-enabled agents, set `hasX402Endpoint: true` and use `view:
+  "compact"` until the user selects one row.

package/skills/sap-mcp/SKILL.md

@@ -36,11 +36,17 @@ and error strings unchanged.
 ## Discovery Rules
 
 - Use `sap_get_network_overview` for live ecosystem counters.
+- Use `sap_discover_agents` for targeted paid hosted discovery. Prefer
+  `query`, `wallet`, `agentPda`, `protocol`, `capability`, `capabilities`,
+  `hasX402Endpoint`, and small `limit` values before broad scans.
 - Use `sap_list_all_agents` when the user asks for all current SAP ecosystem
-  agents. It performs global on-chain `AgentAccount` enumeration.
-- Use `sap_discover_agents` or `sap_list_agents` only for filtered lookups by
-  `protocol`, `capability`, or `capabilities`.
+  agents. It performs global on-chain `AgentAccount` enumeration and returns
+  `pagination.nextCursor` when more pages are available.
+- Use `sap_list_agents` as a compatibility alias for `sap_discover_agents`.
 - Use `sap_fetch_protocol_index` when a specific protocol ID is known.
+- If a capability lookup returns zero results, retry with `query` or `wallet`
+  before saying an agent is absent. AgentAccount rows are canonical; indexes can
+  lag.
 - Do not tell the user that all-agent enumeration is impossible unless
   `sap_list_all_agents` fails and you report the exact failure.
 
@@ -169,6 +175,12 @@ another unsigned Solana transaction payload, finalize it locally with
 for a user-owned signer, do not create `.js`/`.mjs` signing scripts, and do not
 read keypair JSON.
 
+If hosted SAP MCP returns `hosted_local_signer_required`, no x402 payment was
+charged. The tool requires a local user signature or has no hosted unsigned
+builder yet. Do not retry the same hosted direct write; use the local SAP MCP
+profile or an unsigned hosted builder plus `sap_payments_finalize_transaction`
+when one exists.
+
 When summarizing a hosted connection, use language like:
 "server is non-custodial; user signatures come from the local SAP profile or
 external signer." Avoid saying "signer not configured", "read-only only",

package/skills/sap-mcp/TOOL_REFERENCE.md

@@ -49,9 +49,12 @@ SAP registry and discovery:
 `sap_deactivate_tool`, `sap_reactivate_tool`,
 `sap_report_tool_invocations`, `sap_report_calls`.
 
-Use `sap_list_all_agents` for user requests such as "give me a list of all
-agents in the SAP ecosystem rn". Use `sap_discover_agents` only when the user
-provides a protocol or capability filter.
+Use `sap_discover_agents` for targeted paid hosted agent search by `query`,
+`wallet`, `agentPda`, `protocol`, `capability`, `capabilities`, or
+`hasX402Endpoint`. Use `sap_list_all_agents` for user requests such as "give me
+a list of all agents in the SAP ecosystem rn"; start with a small `limit` and
+continue with `pagination.nextCursor`. If a capability lookup returns zero,
+retry with `query` or `wallet` before reporting that the agent is absent.
 
 SAP memory and sessions:
 
@@ -92,13 +95,16 @@ SAP SNS and direct SNS domain workflows:
 `sap_sns_get_domain_records`, `sap_sns_get_record`,
 `sap_sns_resolve_wallet`, `sap_sns_check_ownership`,
 `sap_sns_get_domain_pda`, `sap_sns_get_record_pda`,
-`sap_sns_build_register_domain_transaction`,
 `sap_sns_build_manage_record_transaction`,
-`sap_sns_build_set_primary_domain_transaction`,
 `sap_sns_register_agent_domain`, `sns_registerDomain`, `sns_resolveDomain`,
 `sns_reverseLookup`, `alldomains_getOwnedDomains`,
 `alldomains_registerDomain`, `alldomains_resolveDomain`.
 
+`sap_sns_register_agent_domain` is local-signer-only. Hosted accountless SAP MCP
+rejects that direct write before x402 payment. For hosted record changes, use
+`sap_sns_build_manage_record_transaction` and finalize the unsigned transaction
+locally with `sap_payments_finalize_transaction`.
+
 ## `sap-agentkit`
 
 Solana RPC, SPL token, pricing, DAS:

package/skills/sap-operations/SKILL.md

@@ -30,9 +30,10 @@ Use:
 - `sap_list_agents`
 - `sap_list_all_agents`
 
-Use `sap_list_all_agents` for global current ecosystem requests. Use
-`sap_discover_agents` and `sap_list_agents` only when the user provides a
-protocol or capability filter.
+Use `sap_discover_agents` for targeted hosted directory reads by `query`,
+`wallet`, `agentPda`, `protocol`, `capability`, `capabilities`, or
+`hasX402Endpoint`. Use `sap_list_all_agents` for global current ecosystem
+requests, keep pages small, and continue with `pagination.nextCursor`.
 
 ## Memory
 

package/skills/sap-sns/SKILL.md

@@ -9,15 +9,19 @@ This skill is adapted from upstream `sns-skill` plus SAP MCP's
 ## Safe Flow
 
 1. Check the loaded profile with `sap_profile_current`.
-2. Check domain availability with `sap_sns_check_domain`.
+2. Check one domain availability for free with `sap_sns_check_domain`.
 3. Validate records with `sap_sns_validate_records`.
-4. Build unsigned transactions when possible:
-   - `sap_sns_build_register_domain_transaction`
-   - `sap_sns_build_manage_record_transaction`
-   - `sap_sns_build_set_primary_domain_transaction`
-5. Preview transaction with `sap_preview_transaction`.
-6. Sign only through `sap_sign_transaction` or the direct tool
-   `sap_sns_register_agent_domain` when policy allows it.
+4. For hosted record updates, build an unsigned transaction with
+   `sap_sns_build_manage_record_transaction`.
+5. Preview and finalize hosted builder transactions locally with
+   `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.
+
+Hosted accountless SAP MCP cannot register a .sol domain directly because the
+purchase requires the user wallet signature. If a hosted direct registration is
+rejected with `hosted_local_signer_required`, no x402 payment was charged; switch
+to the local profile flow instead of retrying the hosted write.
 
 ## Tools
 
@@ -31,9 +35,7 @@ This skill is adapted from upstream `sns-skill` plus SAP MCP's
 - `sap_sns_check_ownership`
 - `sap_sns_get_domain_pda`
 - `sap_sns_get_record_pda`
-- `sap_sns_build_register_domain_transaction`
 - `sap_sns_build_manage_record_transaction`
-- `sap_sns_build_set_primary_domain_transaction`
 - `sap_sns_register_agent_domain`
 - `sns_registerDomain`
 - `sns_resolveDomain`
@@ -48,4 +50,7 @@ This skill is adapted from upstream `sns-skill` plus SAP MCP's
 - Never read the local wallet file.
 - 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.