@oobe-protocol-labs/sap-mcp-server 0.9.2 → 0.9.6

package/docs/14_DESKTOP_WIZARD_RELEASE.md

@@ -66,7 +66,7 @@ url = "https://mcp.sap.oobeprotocol.ai/mcp"
 ```toml
 [mcp_servers.sap_payments]
 command = "npx"
-args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.9.2", "sap-mcp-server"]
+args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.9.6", "sap-mcp-server"]
 startup_timeout_sec = 300
 tool_timeout_sec = 300
 
@@ -128,12 +128,11 @@ Every supported runtime may also receive a local `sap_payments` server with only
 ```txt
 sap_payments_readiness
 sap_payments_call_paid_tool
+sap_payments_finalize_transaction
 sap_payments_prepare_challenge
 sap_payments_sign_challenge
 sap_payments_verify_receipt
 sap_x402_paid_call
-sap_profile_current
-sap_x402_estimate_cost
 ```
 
 The hosted `sap` entry must not include wallet paths, RPC API-key overrides, profile names, keypair bytes, or private signer data.

package/docs/README.md

@@ -91,8 +91,11 @@ Hosted paid tools use x402 and pay.sh:
 - value flows: fixed or percentage pricing only where it is operationally appropriate
 
 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:
+`sap_payments` MCP bridge and call `sap_payments_call_paid_tool`. If a hosted
+builder returns an unsigned transaction, finalize it with
+`sap_payments_finalize_transaction` so the local signer previews, signs, and
+optionally submits without exposing keypair bytes. 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/docs/magicblock-tools.md

@@ -24,21 +24,30 @@ additional configuration needed.
 
 ## Pricing
 
-Two tiers, priced in USDC base units (6 decimals):
+Hosted pricing is resolved centrally by `src/payments/pricing.ts` and returned
+as an x402/pay.sh challenge before the paid tool executes.
 
-| Tier | Price | Count | Tools |
-|------|-------|-------|-------|
-| READ | $0.01 | 14 | ER Router queries, health, auth, balances, swap quotes, mint checks, VRF result |
-| WRITE | $0.05 | 6 | deposit, transfer, withdraw, swap, initializeMint, VRF request |
+| Tier | Tools |
+|------|-------|
+| Free/readiness | MCP discovery, SAP skill bootstrap, payment readiness, transaction decode/preview |
+| Read-premium | ER Router queries, balances, swap quotes, mint checks, VRF result |
+| Builder | Deposit, transfer, withdraw, initialize mint, VRF request transaction builders |
+| Value-action | Public/private swap transaction builders and other value-moving actions |
 
-Every tool description includes its price. Every successful response
-includes `priceUsd` and `priceBaseUnits` fields for SAP escrow settlement.
+Do not hard-code MagicBlock prices in agents. Call `sap_x402_estimate_cost` or
+the local `sap_payments_call_paid_tool` helper and enforce the user profile's
+`maxPriceUsd` / spend policy.
+
+When a hosted MagicBlock builder returns an unsigned transaction, hosted SAP MCP
+remains non-custodial. Finalize the returned `transactionBase64` with the local
+`sap_payments_finalize_transaction` bridge. Do not call hosted
+`sap_sign_transaction`, create temporary signing scripts, or read keypair JSON.
 
 ---
 
 ## Tools (20 total)
 
-### ER Router (6 read-only — $0.01)
+### ER Router (6 read-only)
 
 | Tool | Description |
 |------|-------------|
@@ -49,7 +58,7 @@ includes `priceUsd` and `priceBaseUnits` fields for SAP escrow settlement.
 | `magicblock_getBlockhashForAccounts` | Get a blockhash for a batch of accounts (max 100) |
 | `magicblock_getSignatureStatuses` | Check transaction confirmation status |
 
-### Private Payments — Meta & Auth (3 — $0.01)
+### Private Payments — Meta & Auth (3)
 
 | Tool | Description |
 |------|-------------|
@@ -57,14 +66,14 @@ includes `priceUsd` and `priceBaseUnits` fields for SAP escrow settlement.
 | `magicblock_challenge` | Generate a challenge string for wallet auth |
 | `magicblock_login` | Exchange signed challenge for bearer token |
 
-### Private Payments — Balance (2 — $0.01)
+### Private Payments — Balance (2)
 
 | Tool | Description |
 |------|-------------|
 | `magicblock_balance` | Read base-chain SPL token balance |
 | `magicblock_privateBalance` | Read ephemeral-rollup SPL balance (requires auth) |
 
-### Private Payments — SPL Token Flows (3 — $0.05)
+### Private Payments — SPL Token Flows (3)
 
 | Tool | Description |
 |------|-------------|
@@ -74,24 +83,24 @@ includes `priceUsd` and `priceBaseUnits` fields for SAP escrow settlement.
 
 ### Private Payments — Swap (2)
 
-| Tool | Price | Description |
-|------|-------|-------------|
-| `magicblock_swapQuote` | $0.01 | Get a swap quote between two SPL mints |
-| `magicblock_swap` | $0.05 | Build unsigned swap tx (public or private) |
+| Tool | Description |
+|------|-------------|
+| `magicblock_swapQuote` | Get a swap quote between two SPL mints |
+| `magicblock_swap` | Build unsigned swap tx (public or private) |
 
 ### Private Payments — Mint Init (2)
 
-| Tool | Price | Description |
-|------|-------|-------------|
-| `magicblock_initializeMint` | $0.05 | Build unsigned mint transfer queue init tx |
-| `magicblock_isMintInitialized` | $0.01 | Check if a mint's transfer queue exists |
+| Tool | Description |
+|------|-------------|
+| `magicblock_initializeMint` | Build unsigned mint transfer queue init tx |
+| `magicblock_isMintInitialized` | Check if a mint's transfer queue exists |
 
 ### VRF (2 — on-chain via @solana/web3.js)
 
-| Tool | Price | Description |
-|------|-------|-------------|
-| `magicblock_requestRandomness` | $0.05 | Build unsigned tx invoking request_randomness on the VRF program (Vrf1RNUjXmQGjmQrQLvJHs9SNkvDJEsRVFPkfSQUwGz) |
-| `magicblock_getRandomnessResult` | $0.01 | Read the RandomnessRequest account on-chain to check fulfillment and retrieve random bytes |
+| Tool | Description |
+|------|-------------|
+| `magicblock_requestRandomness` | Build unsigned tx invoking request_randomness on the VRF program (Vrf1RNUjXmQGjmQrQLvJHs9SNkvDJEsRVFPkfSQUwGz) |
+| `magicblock_getRandomnessResult` | Read the RandomnessRequest account on-chain to check fulfillment and retrieve random bytes |
 
 ---
 
@@ -126,21 +135,27 @@ Write tools return an unsigned transaction:
 Expected flow:
 
 1. Call the MagicBlock tool (e.g. `magicblock_deposit`) → get `transactionBase64`
-2. Sign with `sap_sign_transaction`
-3. Submit with `sap_submit_signed_transaction` to the RPC indicated by `sendTo`
+2. If the transaction came from hosted SAP MCP, call local
+   `sap_payments_finalize_transaction` with `confirm: true` and `submit: false`
+   for preview/sign, or `submit: true` after user approval.
+3. If the transaction came from local stdio SAP MCP, use
+   `sap_preview_transaction` → `sap_sign_transaction` →
+   `sap_submit_signed_transaction`.
+4. Record the signed transaction or submitted signature in the audit trail.
+
+Agents must not create temporary JavaScript signing scripts, read keypair JSON,
+or sign raw message bytes outside SAP MCP transaction tools.
 
 ---
 
 ## Response Format
 
-Every successful response is wrapped with pricing metadata:
+Successful tool responses are wrapped by SAP MCP:
 
 ```json
 {
   "success": true,
   "tool": "magicblock_deposit",
-  "priceUsd": "$0.05",
-  "priceBaseUnits": "50000",
   "data": { ... }
 }
 ```
@@ -163,4 +178,4 @@ Error responses:
 | `src/tools/magicblock-tools.ts` | 20 tool registrations with HTTP client |
 | `src/tools/__tests__/magicblock-tools.test.ts` | 10 smoke tests |
 | `src/tools/index.ts` | Barrel export |
-| `src/tools/register-tools.ts` | Registration call during server init |
+| `src/tools/register-tools.ts` | Registration call during server init |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oobe-protocol-labs/sap-mcp-server",
-  "version": "0.9.2",
+  "version": "0.9.6",
   "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.9.2",
+  "version": "0.9.6",
   "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.2",
+      "version": "0.9.6",
       "transport": {
         "type": "stdio"
       },
@@ -45,7 +45,7 @@
         },
         {
           "type": "positional",
-          "value": "@oobe-protocol-labs/sap-mcp-server@0.9.2"
+          "value": "@oobe-protocol-labs/sap-mcp-server@0.9.6"
         },
         {
           "type": "positional",

package/skills/sap-mcp/SKILL.md

@@ -14,10 +14,13 @@ the returned SAP MCP skill contents into context.
 Always inspect runtime context through MCP tools, not by reading config files:
 
 1. `sap_agent_start`
-2. `sap_profile_current`
-3. `sap_profile_list`
-4. `sap_profile_public_key`
-5. `sap_network_stats`
+2. `sap_skills_bundle` with `includeContents: true`
+3. `sap_skills_upgrade_plan` when local skills are missing or stale
+4. `sap_runtime_repair_plan` when hosted tools are connected but `sap_payments` is missing
+5. `sap_profile_current`
+6. `sap_profile_list`
+7. `sap_profile_public_key`
+8. `sap_network_stats`
 
 The server profile is the source of truth. Environment variables from the MCP
 client must not override profile-owned RPC or wallet settings unless
@@ -61,12 +64,17 @@ 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_skills_list`, `sap_skills_bundle`, and local
-`sap_skills_install` directly. Do not route startup, skill listing, bundling, or
-installation through `sap_x402_paid_call`. On hosted remote MCP, use
+`sap_agent_start`, `sap_skills_list`, `sap_skills_bundle`,
+`sap_skills_upgrade_plan`, `sap_runtime_repair_plan`, and local
+`sap_skills_install` directly. Do not route startup, skill listing, bundling,
+upgrade planning, runtime repair planning, or installation through
+`sap_x402_paid_call`. On hosted remote MCP, use
 `sap_skills_bundle` to download skill contents; the hosted server cannot
 install files onto the caller's local machine. Local installation belongs to the
 wizard, desktop app, addon installer, or a local stdio SAP MCP process.
+If skills or runtime bridge config are stale, call `sap_skills_upgrade_plan` or
+`sap_runtime_repair_plan` first. These tools return the pinned latest-release
+commands and preserve the non-custodial local signing model.
 
 ## Hosted Remote MCP
 
@@ -155,6 +163,12 @@ 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 a hosted paid/write builder returns `transactionBase64`, `transaction`, or
+another unsigned Solana transaction payload, finalize it locally with
+`sap_payments_finalize_transaction`. Do not call hosted `sap_sign_transaction`
+for a user-owned signer, do not create `.js`/`.mjs` signing scripts, and do not
+read keypair JSON.
+
 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",
@@ -170,6 +184,11 @@ the current agent runtime injected every tool as callable. If `tools/list`
 works but callable functions are missing, report a runtime reload/injection
 issue and ask the user to restart the runtime.
 
+If `sap_payments` tools are missing after the user says the wizard completed,
+call `sap_runtime_repair_plan`. Do not ask the user to manually rebuild their
+runtime config unless the repair plan has already failed or runtime startup logs
+show a concrete package/runtime error.
+
 ## Profile Tools
 
 | Tool | Purpose |

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

@@ -9,6 +9,7 @@ workflows, and hosted SAP MCP x402/pay.sh monetization.
 - `sap_x402_get_balance`
 - `sap_payments_profile_current`
 - `sap_payments_call_paid_tool`
+- `sap_payments_finalize_transaction`
 - `sap_payments_prepare_challenge`
 - `sap_payments_sign_challenge`
 - `sap_payments_verify_receipt`
@@ -81,6 +82,12 @@ 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.
 
+If the hosted paid tool returns `transactionBase64`, `transaction`, or an
+unsigned transaction object, call `sap_payments_finalize_transaction` with
+`confirm: true`. Set `submit: false` for preview/sign only, or `submit: true`
+after the user approves execution. Never create temporary signing scripts, read
+keypair JSON, or call hosted `sap_sign_transaction` for user-owned signatures.
+
 Use low-level helpers only for custom clients:
 
 - `sap_payments_prepare_challenge` returns the parsed hosted x402 challenge