@oobe-protocol-labs/sap-mcp-server 0.7.4 → 0.9.0

package/docs/15_DASHBOARD_SCREENSHARE_SCRIPT.md

@@ -0,0 +1,137 @@
+# SAP MCP Dashboard Screenshare Script
+
+## Purpose
+
+Use this script for a 4-6 minute product walkthrough of <https://mcp.sap.oobeprotocol.ai/>. The tone should be direct, technical, and commercial: SAP MCP is not just another MCP server; it is a Solana-native operations gateway for agent runtimes.
+
+## 0. Opening Hook
+
+**Screen:** Open <https://mcp.sap.oobeprotocol.ai/>.
+
+**Say:**
+
+Agent runtimes are moving from chat and retrieval into real execution. The missing piece is a clean operations layer: identity, wallet boundaries, payments, protocol tools, and a way to keep user keys under user control.
+
+This is SAP MCP by OOBE Protocol: a hosted Solana-native MCP gateway for agents. It gives Claude, Codex, Hermes, OpenClaw, and custom agents one standard endpoint for Solana DeFi, Solana RPC, and Synapse Agent Protocol operations.
+
+## 1. Dashboard Overview
+
+**Screen:** Point to the hero, hosted endpoint, payment counters, and public navigation.
+
+**Say:**
+
+The hosted MCP endpoint is `https://mcp.sap.oobeprotocol.ai/mcp`. Agents connect through standard Streamable HTTP MCP. The public dashboard gives builders the important operational signals without exposing secrets: endpoint metadata, docs, downloads, x402 discovery, pay.sh provider data, and live payment activity.
+
+The model is remote tools, local signatures. The hosted server provides the tool surface and monetization rails, while the user's local SAP profile or external signer authorizes paid and value-moving calls.
+
+## 2. Three Protocol Buckets
+
+**Screen:** Scroll to the protocol surface / bento grid section.
+
+**Say:**
+
+SAP MCP is organized around three core buckets.
+
+First: Solana DeFi protocols. Agents can access integrations across Jupiter, Raydium, Orca, Meteora, Drift, market data, swaps, quotes, and related execution flows.
+
+Second: Solana RPC and asset primitives. Balances, token accounts, DAS assets, NFT metadata, program reads, transactions, simulations, and chain inspection are exposed as MCP tools.
+
+Third: Synapse Agent Protocol. This is the coordination layer: agent registry, reputation, tool registry, escrow, settlement, attestations, SNS identity, x402 flows, pay.sh metadata, skills, and proof-oriented agent operations.
+
+The point is simple: one MCP gateway can turn a normal agent runtime into a protocol-aware on-chain operator.
+
+## 3. Installation Path
+
+**Screen:** Scroll to the integration/install section and download cards.
+
+**Say:**
+
+There are two installation paths.
+
+For most users, use the native desktop wizard. Download Windows, macOS, or Linux directly from the GitHub release. The wizard creates an isolated SAP MCP profile, wallet boundary, policy defaults, hosted MCP config, and the local `sap_payments` bridge for paid calls.
+
+For developers and servers, use the TUI from npm:
+
+```bash
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard
+```
+
+The desktop GUI and the TUI both end in the same production model: hosted MCP at `/mcp`, plus local non-custodial signing and x402 payment handling.
+
+## 4. Wizard Walkthrough
+
+**Screen:** Open the SAP MCP Wizard.
+
+**Say:**
+
+The wizard is built for both normal users and technical operators.
+
+The default path is full hosted SAP MCP setup. It creates or repairs the local profile, configures the selected runtime, and installs the local payment bridge.
+
+If a user already has a profile, they can choose the repair path. That fixes only the SAP MCP runtime entries, keeps other MCP servers intact, and updates only OOBE's own `sap` and `sap_payments` blocks.
+
+The important security rule is that keypair bytes are never pasted into remote configs. The hosted server never custodies user keys. Paid and write tools require the user-controlled local profile or an external signer.
+
+## 5. Runtime Connection
+
+**Screen:** Show Codex, Hermes, Claude, or another runtime with SAP MCP connected.
+
+**Say:**
+
+Once the runtime restarts, it gets two surfaces.
+
+The remote SAP MCP namespace exposes the full hosted tool catalog. Read tools work immediately.
+
+The local `sap_payments` bridge handles paid or write calls when the runtime cannot natively replay x402 challenges. It signs the payment proof locally, retries the hosted MCP call, and returns the receipt and tool output without sending private key material to OOBE.
+
+That is the trust boundary: global hosted tools, local authorization.
+
+## 6. Payments And Monetization
+
+**Screen:** Point to payment/x402/pay.sh cards and `.well-known/x402`.
+
+**Say:**
+
+SAP MCP supports x402 and pay.sh for agent-native monetization.
+
+Paid tools return a standard HTTP 402 challenge. The local bridge or a native x402-capable runtime resolves the challenge, settles through the OOBE facilitator, and binds payment to the tool call.
+
+This lets hosted MCP tools become revenue-generating APIs without bearer tokens, custodial wallets, or hardcoded runtime secrets.
+
+For builders, this means paid discovery, premium analytics, transaction builders, registry operations, SNS checks, settlement flows, and future subscription-style products can all live behind one MCP interface.
+
+## 7. Solana Value Proposition
+
+**Screen:** Return to the hero or protocol surface.
+
+**Say:**
+
+For Solana, SAP MCP is a distribution layer for protocols.
+
+Instead of every agent integration being custom, protocols can be exposed as well-described MCP tools, enriched with skills and docs, and monetized with x402 or pay.sh.
+
+For agents, it is a coordination layer. They can discover tools, inspect state, register identity, link SNS, handle payments, and execute operations through a standard interface.
+
+For users, it is non-custodial by default. The remote server provides access; the local signer controls authorization.
+
+## 8. Closing CTA
+
+**Screen:** Show install button and docs.
+
+**Say:**
+
+You can try SAP MCP today at `mcp.sap.oobeprotocol.ai`.
+
+Download the native wizard, or run the TUI from npm. Connect your agent runtime, keep signing local, and start building Solana-native agent operations with SAP MCP.
+
+This is the path from agent profiles to on-chain operators.
+
+## Short Social Cut
+
+SAP MCP turns agent runtimes into Solana-native operators.
+
+One hosted MCP endpoint gives agents access to Solana DeFi, Solana RPC, and Synapse Agent Protocol tools. The wizard creates the local profile, signer boundary, runtime config, and x402 payment bridge.
+
+Remote tools. Local signatures. Smooth payments. No custodial key handling.
+
+Try it at <https://mcp.sap.oobeprotocol.ai/>.

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

package/skills/sap-mcp/SKILL.md

@@ -107,10 +107,15 @@ 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.
+Call `sap_payments_readiness` first to verify the active profile, signer,
+SOL/USDC balance, policy limits, and bridge status. Then call
+`sap_payments_call_paid_tool` for the hosted 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 +124,30 @@ 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, signer status, and payment policy, call
+the local `sap_payments.sap_payments_readiness` bridge when it is configured.
+Use `sap_payments.sap_payments_profile_current` only as a narrower compatibility
+profile check.
+
+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.