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

package/server.json

@@ -3,7 +3,7 @@
   "name": "ai.oobeprotocol.sap.mcp/sap-mcp",
   "title": "SAP MCP Server | OOBE Protocol",
   "description": "Solana-native MCP gateway for SAP tools, DeFi, SNS identity, x402/pay.sh, and agent operations.",
-  "version": "0.9.15",
+  "version": "0.9.16",
   "websiteUrl": "https://mcp.sap.oobeprotocol.ai/",
   "repository": {
     "url": "https://github.com/OOBE-PROTOCOL/sap-mcp",
@@ -29,7 +29,7 @@
     {
       "registryType": "npm",
       "identifier": "@oobe-protocol-labs/sap-mcp-server",
-      "version": "0.9.15",
+      "version": "0.9.16",
       "transport": {
         "type": "stdio"
       },
@@ -45,7 +45,7 @@
         },
         {
           "type": "positional",
-          "value": "@oobe-protocol-labs/sap-mcp-server@0.9.15"
+          "value": "@oobe-protocol-labs/sap-mcp-server@0.9.16"
         },
         {
           "type": "positional",

package/skills/README.md

@@ -55,12 +55,20 @@ or wants to compare this bundled MCP skill pack with the source SDK skills:
 ## Agent Behavior
 
 - Answer in the same natural language as the user's latest request.
+- Use free exact/base SAP reads before paid discovery when possible:
+  `sap_agent_context`, `sap_get_agent`, `sap_get_agent_profile`,
+  `sap_get_agent_stats`, `sap_is_agent_active`, `sap_get_global_state`, and
+  compact `sap_list_agents` pages with `limit <= 20`.
 - Use `sap_discover_agents` for targeted hosted agent search by query, wallet,
   PDA, protocol, capability, capability list, or x402 endpoint presence.
-- Use `sap_list_all_agents` for current global SAP ecosystem agent lists and
-  continue with `pagination.nextCursor` when more pages are needed.
+- Use `sap_list_all_agents` for current global SAP ecosystem agent lists only
+  when the user needs more than the free compact orientation page, and continue
+  with `pagination.nextCursor` when more pages are needed.
 - Treat `mcp_sap_<tool>` as a client display prefix; the callable MCP tool name
   inside this server is the suffix, for example `jupiter_getQuote`.
+- Call `sap_agent_next_action` before retrying after `payment_required`,
+  `hosted_local_signer_required`, transient Solana RPC errors, a missing local
+  bridge, or a submitted signature that has not confirmed.
 - Use `skills/sap-mcp/TOOL_REFERENCE.md` and `USER_DOCS/05_SKILLS_AND_TOOLS.md`
   as the bundled routing maps when deciding which SAP MCP tool or skill domain
   applies to a user request.

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

@@ -12,10 +12,16 @@ state, global directory listing, and agent profile inspection.
    full identity setup, call `sap_agent_identity_plan` before any write. It is
    free and returns normalized fields, local-signer routing, metadata contract,
    forbidden actions, and verification checklist.
-4. Call `sap_get_network_overview` for ecosystem counters when needed.
-5. Use `sap_discover_agents` with `query`, `wallet`, `protocol`, or
-   `capability` for targeted paid hosted directory reads.
-6. Use `sap_list_all_agents` for global current agent lists and follow
+4. Use free exact/base reads before paid discovery: `sap_agent_context`,
+   `sap_get_agent`,
+   `sap_get_agent_profile`, `sap_get_agent_stats`, `sap_is_agent_active`,
+   `sap_get_global_state`, and `sap_list_agents` with `limit <= 20`,
+   `view: "compact"`, and `includeProtocolIndexes: false`.
+5. Call `sap_get_network_overview` for ecosystem counters when needed.
+6. Use `sap_discover_agents` with `query`, `wallet`, `protocol`, or
+   `capability` for targeted paid hosted directory reads when free exact/base
+   reads are not enough.
+7. Use `sap_list_all_agents` for global current agent lists and follow
    `pagination.nextCursor` for additional pages.
 
 ## Tools
@@ -23,6 +29,8 @@ state, global directory listing, and agent profile inspection.
 - `sap_register_agent`
 - `sap_protocol_invariants`
 - `sap_agent_identity_plan`
+- `sap_agent_context`
+- `sap_agent_next_action`
 - `sap_update_agent`
 - `sap_deactivate_agent`
 - `sap_reactivate_agent`
@@ -32,6 +40,7 @@ state, global directory listing, and agent profile inspection.
 - `sap_get_agent_stats`
 - `sap_get_global_state`
 - `sap_get_network_overview`
+- `sap_list_agents`
 - `sap_list_all_agents`
 - `sap_is_agent_active`
 - `sap_report_calls`
@@ -50,6 +59,10 @@ state, global directory listing, and agent profile inspection.
   `confirm: true`. For other registry writes, run the write on the local SAP
   MCP profile or use a production unsigned builder/finalizer flow when
   available.
+- Before any retry after `payment_required`, `hosted_local_signer_required`,
+  `BlockhashNotFound`, timeout, missing `sap_payments`, or a submitted
+  signature that did not confirm, call `sap_agent_next_action`. Follow its
+  `safeToRetryNow`, `nextTool`, and `forbiddenActions` fields.
 - Agent pictures must be public metadata, not desktop file paths. Upload the
   image or metadata JSON to IPFS, Arweave, Kommodo, or HTTPS, then set
   `agentUri`/`metadataUri` with `sap_payments_update_agent`.
@@ -71,8 +84,10 @@ state, global directory listing, and agent profile inspection.
   `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.
+- "List all agents" means first call free `sap_list_agents` with
+  `limit <= 20`, `view: "compact"`, and `includeProtocolIndexes: false`; then
+  use paid `sap_list_all_agents` with `pagination.nextCursor` if the user wants
+  more, full rows, or ecosystem-scale enumeration.
 - "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-discovery-indexing/SKILL.md

@@ -18,12 +18,21 @@ indexes, and filtered agent discovery.
 
 ## Rules
 
+- Start with free orientation when possible:
+  - `sap_agent_context` for a one-shot compact context read and routing hints.
+  - `sap_get_agent` or `sap_get_agent_profile` for a known owner wallet.
+  - `sap_is_agent_active` for a known owner wallet status check.
+  - `sap_get_global_state` for compact registry state.
+  - `sap_list_agents` with `limit <= 20`, `view: "compact"`, and
+    `includeProtocolIndexes: false` for a small current directory page.
 - 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.
+- Use paid discovery only when the user needs search, enrichment, full rows,
+  large pages, analytics, or global enumeration beyond the free compact page.
 - 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`.
@@ -34,6 +43,8 @@ indexes, and filtered agent discovery.
   the canonical AgentAccount directory.
 - Do not guess that global enumeration is impossible; try `sap_list_all_agents`
   first and report the exact failure if it fails.
+- If discovery hits `payment_required`, a transient RPC error, or a missing
+  local bridge, call `sap_agent_next_action` before retrying or changing route.
 
 ## Common Inputs
 

package/skills/sap-mcp/SKILL.md

@@ -16,16 +16,18 @@ 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_skills_bundle` with `includeContents: true`
-4. `sap_pricing_catalog` before estimating hosted paid call tiers
-5. `sap_skills_upgrade_plan` when local skills are missing or stale
-6. `sap_runtime_repair_plan` when hosted tools are connected but `sap_payments` is missing
-7. `sap_protocol_invariants` before SAP registry writes or when treasury, protocol fee, hosted write routing, or local signer routing is unclear
-8. `sap_agent_identity_plan` before agent registration, profile-image updates, Metaplex identity, SNS linking, or full identity setup
-9. `sap_profile_current`
-10. `sap_profile_list`
-11. `sap_profile_public_key`
-12. `sap_network_stats`
+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`
 
 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
@@ -45,6 +47,11 @@ and error strings unchanged.
 
 ## Discovery Rules
 
+- 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
+  `sap_list_agents` with `limit <= 20`, `view: "compact"`, and
+  `includeProtocolIndexes: false`.
 - 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`,
@@ -52,7 +59,9 @@ and error strings unchanged.
 - Use `sap_list_all_agents` when the user asks for all current SAP ecosystem
   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_list_agents` for a free compact orientation page first. Larger
+  pages, `view: "full"`, hydration, protocol index summaries, and global scans
+  are paid read-premium.
 - 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
@@ -80,7 +89,8 @@ Use the bundled routing map for local MCP tool selection:
 - `USER_DOCS/05_SKILLS_AND_TOOLS.md`
 
 SAP MCP startup and skill bootstrap tools are free context/setup tools. Call
-`sap_agent_start`, `sap_agent_runtime_status`, `sap_pricing_catalog`,
+`sap_agent_start`, `sap_agent_runtime_status`, `sap_agent_context`,
+`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,

package/skills/sap-mcp/TOOL_REFERENCE.md

@@ -49,12 +49,22 @@ SAP registry and discovery:
 `sap_deactivate_tool`, `sap_reactivate_tool`,
 `sap_report_tool_invocations`, `sap_report_calls`.
 
-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.
+Use free exact/base reads before paid discovery when possible:
+`sap_agent_context`, `sap_get_agent`, `sap_get_agent_profile`,
+`sap_get_agent_stats`, `sap_is_agent_active`, `sap_get_global_state`, and
+`sap_list_agents` with `limit <= 20`, `view: "compact"`, and
+`includeProtocolIndexes: false`.
+Use `sap_discover_agents` for targeted paid hosted search by `query`, `wallet`,
+`agentPda`, `protocol`, `capability`, `capabilities`, or `hasX402Endpoint`.
+Use paid `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.
+
+Use `sap_agent_next_action` before retrying any SAP MCP error or partial write
+result. It normalizes `payment_required`, `hosted_local_signer_required`,
+transient Solana RPC failures, missing local bridge tools, and unconfirmed
+submitted signatures into the next safe tool route.
 
 Use `sap_protocol_invariants` before registry writes when the program id,
 protocol treasury, source-level 0.1 SOL registration fee invariant, hosted

package/skills/sap-operations/SKILL.md

@@ -36,6 +36,12 @@ 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`.
+For first-pass orientation, prefer free reads: `sap_agent_context`,
+`sap_get_agent`, `sap_get_agent_profile`, `sap_get_agent_stats`,
+`sap_is_agent_active`, `sap_get_global_state`, and `sap_list_agents` with `limit <= 20`,
+`view: "compact"`, and `includeProtocolIndexes: false`. Use paid discovery
+only when the user needs search, enrichment, full rows, large pages, analytics,
+or global enumeration beyond the compact page.
 
 Before registering or updating an agent profile, call free
 `sap_protocol_invariants` when treasury, registration fee, hosted write route,
@@ -52,6 +58,11 @@ Hosted accountless SAP MCP cannot sign wallet-owned registry writes. If hosted
 `confirmationStatus`, and `protocolFee.status`; after update, fetch the agent
 profile again and compare the changed fields.
 
+If any SAP operation returns `payment_required`, `hosted_local_signer_required`,
+`BlockhashNotFound`, timeout, missing `sap_payments`, or a submitted signature
+that did not confirm, call `sap_agent_next_action` before retrying. Follow its
+`safeToRetryNow` and `nextTool` fields.
+
 ## Memory
 
 Use:

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

@@ -45,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
@@ -58,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`.