@oobe-protocol-labs/sap-mcp-server 0.7.3 → 0.8.0

package/docs/README.md

@@ -14,6 +14,13 @@ Use this documentation when you need to install the wizard, connect Claude/Herme
 
 Most users should connect agents to the hosted remote MCP server while keeping signing local and user-controlled.
 
+Choose one integration path:
+
+| Path | Best For | Steps |
+| --- | --- | --- |
+| Native Desktop Wizard | Non-technical users and first-time setup | Download the app, choose **Full hosted SAP MCP setup**, select detected runtimes, then restart the agent. |
+| CLI Wizard | Developers and terminal users | Run the npm command, accept hosted `hosted-api`, and let the wizard install hosted `sap` plus local `sap_payments`. |
+
 ```bash
 npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard
 ```
@@ -24,7 +31,13 @@ Users who prefer a GUI can download the Desktop Wizard from GitHub releases:
 https://github.com/OOBE-PROTOCOL/sap-mcp/releases
 ```
 
-The desktop wizard creates the same local SAP MCP profile, signer boundary, hosted MCP client config, and optional x402 paid-call bridge as the CLI wizard.
+The desktop wizard creates the same local SAP MCP profile, signer boundary, hosted MCP client config, and local `sap_payments` bridge as the CLI wizard.
+
+Native download metadata:
+
+```txt
+https://mcp.sap.oobeprotocol.ai/wizard/downloads.json
+```
 
 The wizard creates an isolated SAP MCP profile under:
 
@@ -45,6 +58,12 @@ Then configure your MCP client with:
 }
 ```
 
+For paid/write hosted tools, also configure the local `sap_payments` bridge. The wizard does this automatically for supported runtimes. See:
+
+- [Desktop GUI Wizard](user/06_DESKTOP_GUI_WIZARD.md)
+- [Client Configs](user/04_CLIENT_CONFIGS.md)
+- [Payments: x402 And pay.sh](user/03_PAYMENTS_X402_PAYSH.md)
+
 ## What The Hosted Server Provides
 
 SAP MCP groups tools into three practical buckets:
@@ -70,7 +89,9 @@ Hosted paid tools use x402 and pay.sh:
 - builders: batch/domain/enriched operations
 - value flows: fixed or percentage pricing only where it is operationally appropriate
 
-For agents that cannot replay x402 challenges natively, install the optional paid-call helper:
+For agents that cannot replay x402 challenges natively, configure the local
+`sap_payments` MCP bridge and call `sap_payments_call_paid_tool`. The standalone
+helper remains available as a terminal/custom-wrapper fallback:
 
 ```bash
 npx --yes --package @oobe-protocol-labs/sap-mcp-server sap-mcp-x402-paid-call \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oobe-protocol-labs/sap-mcp-server",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "mcpName": "ai.oobeprotocol.sap.mcp/sap-mcp",
   "description": "Official MCP gateway for OOBE Protocol SAP — AI agents can interact with SAP identity, registry, reputation, tools, memory, payments, settlement, and proof-of-execution on Solana",
   "type": "module",

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.7.3",
+  "version": "0.8.0",
   "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.7.3",
+      "version": "0.8.0",
       "transport": {
         "type": "stdio"
       },
@@ -45,7 +45,7 @@
         },
         {
           "type": "positional",
-          "value": "@oobe-protocol-labs/sap-mcp-server@0.7.3"
+          "value": "@oobe-protocol-labs/sap-mcp-server@0.8.0"
         },
         {
           "type": "positional",

package/skills/sap-mcp/SKILL.md

@@ -107,10 +107,13 @@ payments, SAP transactions, Solana transactions, SNS operations, or settlement
 actions. The hosted MCP server is not a wallet custodian.
 
 For hosted paid tools, use the native x402 flow. If the client runtime cannot
-attach `PAYMENT-SIGNATURE` itself, use the local `x402_paid_call` addon installed
-by the wizard or the local MCP helper `sap_x402_paid_call`. That helper signs
-payment payloads with the user's local SAP MCP profile and retries the hosted
-tool call. It must not be treated as a remote hosted signing service.
+attach `PAYMENT-SIGNATURE` itself, use the local SAP MCP `sap_payments` bridge
+and call `sap_payments_call_paid_tool`. This is not a separate hosted signing
+plugin: it is the local SAP MCP process using the user's configured SAP profile
+wallet or external signer to sign the x402 payment payload, retry the hosted
+tool call, and return the receipt. `sap_x402_paid_call` is a backward-compatible
+alias only for older runtime snippets. Neither helper must be treated as a
+remote hosted signing service.
 
 When connected to hosted SAP MCP, `signerConfigured: false` on the remote
 server means the hosted server is non-custodial. It does not mean the remote
@@ -119,15 +122,28 @@ a hosted call requires x402 payment or because the hosted server does not hold
 the user's signer. Use the hosted x402 flow first; ask the user before using a
 local stdio fallback.
 
+Hosted remote is accountless. If `sap_profile_current` returns
+`accountModel: hosted-remote-accountless`, do not describe `default` as the
+user's profile and do not infer the user's wallet from the hosted server. To
+inspect the local user profile, wallet, or signer status, call the local
+`sap_payments.sap_payments_profile_current` bridge when it is configured.
+
+Basic wallet reads are free on hosted SAP MCP. Call `sol_get_balance`,
+`spl-token_getBalance`, and `spl-token_getTokenAccounts` directly on the hosted
+server. Do not send these balance checks through `sap_payments_call_paid_tool`,
+and do not summarize a balance read as a facilitator `BlockhashNotFound`
+problem unless a paid tool actually returned that error.
+
 If a hosted paid tool returns `BlockhashNotFound`,
 `transaction_simulation_failed`, `smart_wallet_simulation_failed`, `node is
 behind`, `minimum context slot`, `fetch failed`, `gateway timeout`, or a
 response marked `retryable: true`, treat it as a transient x402/Solana RPC
 settlement error. Do not claim that SAP MCP is down unless `/health` also
 fails. Do not bypass the paid hosted path with terminal/direct RPC. Retry
-through the local `sap_x402_paid_call` bridge with the same tool name and
-arguments, `confirm: true`, and `maxAttempts: 5` so a fresh payment payload is
-created.
+through the local `sap_payments_call_paid_tool` bridge with the same tool name
+and arguments, `confirm: true`, and `maxAttempts: 5` so a fresh payment payload
+is created. Use `sap_x402_paid_call` only when a runtime still exposes the
+legacy alias.
 
 When summarizing a hosted connection, use language like:
 "server is non-custodial; user signatures come from the local SAP profile or

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

@@ -7,6 +7,11 @@ workflows, and hosted SAP MCP x402/pay.sh monetization.
 
 - `sap_x402_prepare_payment`
 - `sap_x402_get_balance`
+- `sap_payments_profile_current`
+- `sap_payments_call_paid_tool`
+- `sap_payments_prepare_challenge`
+- `sap_payments_sign_challenge`
+- `sap_payments_verify_receipt`
 - `sap_x402_paid_call`
 - `sap_create_subscription`
 - `sap_fund_subscription`
@@ -36,7 +41,8 @@ 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`.
+  `sap_get_network_overview`, `sol_get_balance`, `spl-token_getBalance`, and
+  `spl-token_getTokenAccounts`.
 - Read premium: `sap_list_all_agents`, indexed discovery, network stats,
   protocol/capability indexes.
 - Builder: batch SNS/domain checks, analytics, transaction builders.
@@ -58,16 +64,34 @@ For fast x402 execution:
 4. Cache free `tools/list`, `prompts/list`, and `resources/list` locally rather
    than paying or re-fetching repeatedly.
 5. Treat `PAYMENT-RESPONSE` as the receipt bound to the tool output.
-6. If the client runtime cannot sign or attach x402 payment headers, ask the
-   user to run the SAP MCP wizard and install the local `x402_paid_call` addon
-   instead of falling back to local stdio automatically.
-
-When available locally, call `sap_x402_paid_call` with `toolName`, `arguments`,
-`maxPriceUsd`, and `confirm: true`. It initializes the hosted MCP session,
-signs the x402 payment with the user SAP MCP profile wallet, retries the hosted
-tool call, and returns the settlement receipt. The OOBE hosted server should
-not expose this helper when it has no local user wallet because payment signing
-belongs on the user's machine.
+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
+   MCP wizard instead of falling back to local stdio automatically.
+
+Do not use x402 for basic balance reads. `sol_get_balance`,
+`spl-token_getBalance`, and `spl-token_getTokenAccounts` are free hosted tools
+and should be called directly through the remote SAP MCP connection.
+
+When available locally, call `sap_payments_call_paid_tool` with `toolName`,
+`arguments`, `maxPriceUsd`, and `confirm: true`. It initializes the hosted MCP
+session, obtains the x402 challenge, signs with the user SAP MCP profile wallet
+or external signer, retries the hosted tool call, and returns the settlement
+receipt. Do not ask the user to install a separate x402 plugin when the local
+SAP MCP `sap_payments` bridge is already configured. The legacy
+`sap_x402_paid_call` alias is acceptable only when a runtime has not refreshed
+to the new tool name.
+
+Use low-level helpers only for custom clients:
+
+- `sap_payments_prepare_challenge` returns the parsed hosted x402 challenge
+  without signing.
+- `sap_payments_sign_challenge` signs a parsed challenge and returns a one-time
+  payment header. Treat that header as authorization material.
+- `sap_payments_verify_receipt` decodes a `PAYMENT-RESPONSE` or
+  `X-PAYMENT-RESPONSE` receipt.
+
+The OOBE hosted server should not expose local signing helpers when it has no
+local user wallet because payment signing belongs on the user's machine.
 
 ## Transient Settlement Errors
 
@@ -81,8 +105,8 @@ reuse the old signed payment payload.
 
 Correct recovery:
 
-1. Call the local `sap_x402_paid_call` bridge again with the same `toolName`
-   and `arguments`.
+1. Call the local `sap_payments_call_paid_tool` bridge again with the same
+   `toolName` and `arguments`.
 2. Set `maxAttempts: 5` when the runtime supports it.
 3. Let the helper create a fresh x402 challenge and payment payload for each
    attempt.