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

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

package/skills/README.md

@@ -4,7 +4,7 @@ Production skill pack for agents using the SAP MCP server through Claude,
 Hermes, OpenClaw, Codex, or another MCP-capable runtime.
 
 This pack is adapted for `sap-mcp-server` from the upstream Synapse SAP SDK
-v0.21.0 skill taxonomy:
+v1.0.x skill taxonomy:
 
 - `sap-overview`
 - `sap-mcp`
@@ -44,7 +44,7 @@ or wants to compare this bundled MCP skill pack with the source SDK skills:
 | `sap-memory-vault` | Vaults, sessions, inscriptions, compact memory, epoch pages |
 | `sap-ledger-session` | Session continuity and latest durable session reads |
 | `sap-payments-x402` | x402 payment context, balances, subscriptions |
-| `sap-escrow-settlement` | Escrow v1/v2, settlement, pending settlement, disputes |
+| `sap-escrow-settlement` | Escrow V2, settlement, pending settlement, disputes |
 | `sap-staking` | SAP stake initialization, deposit, unstake, and stake reads |
 | `sap-solana-token` | SOL/SPL balances, transfers, token deploy, mint, burn, token admin |
 | `sap-defi` | Jupiter, Drift, Adrena, Lulo, liquidity, orderbooks, bridges, Jito, staking |

package/skills/sap-escrow-settlement/SKILL.md

@@ -1,17 +1,12 @@
 # SAP Escrow Settlement
 
-Use this skill for escrow v1/v2, deposits, settlement, batch settlement,
-withdrawal, closing, pending settlements, and disputes.
+Use this skill for active Escrow V2 deposits, settlement, withdrawal,
+closing, pending settlements, and disputes. V1 escrow write flows are no
+longer active on the current SAP on-chain program and must not be used for
+new work.
 
 ## Tools
 
-- `sap_create_escrow`
-- `sap_deposit_escrow`
-- `sap_settle_escrow`
-- `sap_settle_escrow_batch`
-- `sap_withdraw_escrow`
-- `sap_close_escrow`
-- `sap_fetch_escrow`
 - `sap_create_escrow_v2`
 - `sap_deposit_escrow_v2`
 - `sap_settle_escrow_v2`
@@ -23,13 +18,22 @@ withdrawal, closing, pending settlements, and disputes.
 - `sap_fetch_pending_settlement`
 - `sap_next_settlement_index`
 - `sap_fetch_dispute`
+- `sap_fetch_escrow`
+
+`sap_fetch_escrow` is retained only for legacy read-only inspection. Do not
+recommend V1 create, deposit, settle, withdraw, close, or batch-settle flows.
 
 ## Flow
 
-1. Fetch escrow state before mutating it.
-2. For v2 settlement, inspect pending settlement and dispute state.
+1. Fetch V2 escrow state before mutating it.
+2. For V2 settlement, inspect pending settlement and dispute state.
 3. Explain amount, depositor, agent PDA, nonce, settlement index, and dispute
    effect before write tools.
+4. Treat `settlementSecurity = 2` / DisputeWindow as the safe default.
+   Use `settlementSecurity = 1` / CoSigned only when a valid `coSigner` is
+   provided. Never default to SelfReport / `0`.
+5. Amounts are always in the smallest unit of the escrow token: lamports for
+   SOL, micro-USDC for USDC.
 
 ## Safety
 

package/skills/sap-mcp/SKILL.md

@@ -6,12 +6,18 @@ safe signing behavior.
 
 ## First Step
 
+If the user says "Start SAP MCP", "Initialize SAP MCP", "Load SAP", or "SAP
+mode", treat it as the activation command. Call `sap_agent_start` when it is
+available, then call `sap_skills_bundle` with `includeContents: true` and load
+the returned SAP MCP skill contents into context.
+
 Always inspect runtime context through MCP tools, not by reading config files:
 
-1. `sap_profile_current`
-2. `sap_profile_list`
-3. `sap_profile_public_key`
-4. `sap_network_stats`
+1. `sap_agent_start`
+2. `sap_profile_current`
+3. `sap_profile_list`
+4. `sap_profile_public_key`
+5. `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
@@ -54,13 +60,13 @@ Use the bundled routing map for local MCP tool selection:
 - `skills/sap-mcp/TOOL_REFERENCE.md`
 - `USER_DOCS/05_SKILLS_AND_TOOLS.md`
 
-SAP MCP skill bootstrap tools are free context/setup tools. Call
-`sap_skills_list`, `sap_skills_bundle`, and local `sap_skills_install`
-directly. Do not route skill listing, bundling, 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.
+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_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.
 
 ## Hosted Remote MCP
 
@@ -107,13 +113,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 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.
+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
@@ -125,8 +133,10 @@ 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.
+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
@@ -151,6 +161,15 @@ external signer." Avoid saying "signer not configured", "read-only only",
 "writes unavailable", or "remote MCP broken" unless a specific tool returns
 that exact operational error.
 
+For simple connection questions such as "are you connected to SAP MCP?", answer
+briefly. Include connected yes/no, endpoint, mode, non-custodial status, and
+one next action. Do not dump the full tool catalog, protocol list, or category
+summary unless the user explicitly asks what tools are available. Startup logs
+or registration logs prove that the MCP server started; they do not prove that
+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.
+
 ## Profile Tools
 
 | Tool | Purpose |

package/skills/sap-mcp/TOOL_REFERENCE.md

@@ -16,7 +16,7 @@ or `sap-agentkit` skills:
 | `sap-memory-vault` | Vaults, sessions, inscriptions, epoch pages |
 | `sap-ledger-session` | Session continuity and latest durable reads |
 | `sap-payments-x402` | x402 payment context, balances, subscriptions |
-| `sap-escrow-settlement` | Escrow v1/v2, settlement, pending settlement, disputes |
+| `sap-escrow-settlement` | Escrow V2, settlement, pending settlement, disputes |
 | `sap-staking` | SAP stake deposit, unstake, stake reads |
 | `sap-solana-token` | SOL/SPL balances, transfers, token admin |
 | `sap-defi` | Jupiter, perps, liquidity, orderbooks, bridges, staking protocols |
@@ -67,14 +67,12 @@ SAP reputation, feedback, attestations, and FairScale:
 `sap_revoke_attestation`, `sap_update_reputation_metrics`,
 `sap_fairscale_score`, `sap_fairscale_trust_gate`.
 
-SAP payments, x402, subscriptions, escrow, settlement, disputes, staking:
+SAP payments, x402, subscriptions, Escrow V2, settlement, disputes, staking:
 
 `sap_x402_prepare_payment`, `sap_x402_get_balance`,
 `sap_create_subscription`, `sap_fund_subscription`,
 `sap_cancel_subscription`, `sap_fetch_subscription`,
-`sap_create_escrow`, `sap_deposit_escrow`, `sap_settle_escrow`,
-`sap_settle_escrow_batch`, `sap_withdraw_escrow`, `sap_close_escrow`,
-`sap_fetch_escrow`, `sap_create_escrow_v2`, `sap_deposit_escrow_v2`,
+`sap_create_escrow_v2`, `sap_deposit_escrow_v2`,
 `sap_settle_escrow_v2`, `sap_finalize_settlement_v2`,
 `sap_file_dispute_v2`, `sap_withdraw_escrow_v2`, `sap_close_escrow_v2`,
 `sap_fetch_escrow_v2`, `sap_fetch_pending_settlement`,
@@ -82,6 +80,9 @@ SAP payments, x402, subscriptions, escrow, settlement, disputes, staking:
 `sap_deposit_stake`, `sap_request_unstake`, `sap_complete_unstake`,
 `sap_fetch_stake`.
 
+Use `sap_fetch_escrow` only for legacy read-only inspection. V1 escrow write
+tools are not part of the active SAP MCP surface.
+
 ## `sap-sns`
 
 SAP SNS and direct SNS domain workflows:

package/skills/sap-operations/SKILL.md

@@ -3,7 +3,7 @@
 Use this skill for SAP Protocol registry, agent lifecycle, memory, reputation,
 x402 payments, escrow, settlement, disputes, staking, and tool publishing.
 
-This skill corresponds to upstream SAP SDK v0.21.0 domains such as
+This skill corresponds to upstream SAP SDK v1.0.x domains such as
 `sap-overview`, `sap-client`, `sap-advanced`, `sap-memory`,
 `sap-merchant`, and `sap-enterprise`.
 
@@ -72,12 +72,6 @@ Use:
 - `sap_create_subscription`
 - `sap_fund_subscription`
 - `sap_cancel_subscription`
-- `sap_create_escrow`
-- `sap_deposit_escrow`
-- `sap_settle_escrow`
-- `sap_settle_escrow_batch`
-- `sap_withdraw_escrow`
-- `sap_close_escrow`
 - `sap_create_escrow_v2`
 - `sap_deposit_escrow_v2`
 - `sap_settle_escrow_v2`
@@ -86,6 +80,11 @@ Use:
 - `sap_withdraw_escrow_v2`
 - `sap_close_escrow_v2`
 
+Escrow writes are V2-only. Default `settlementSecurity` is DisputeWindow (`2`);
+CoSigned (`1`) requires `coSigner`; SelfReport (`0`) is not a valid default.
+Escrow amounts are smallest token units: lamports for SOL and micro-USDC for
+USDC.
+
 ## Staking
 
 Use:

package/smithery.config.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "SAP MCP Smithery Setup",
+  "description": "Choose how this Smithery session should use SAP MCP. The hosted endpoint is non-custodial: free discovery works immediately, while paid/write tools require either a native x402-capable client or the local sap_payments bridge created by the SAP MCP wizard.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "usageMode": {
+      "type": "string",
+      "title": "Usage mode",
+      "description": "Use free-discovery for immediate hosted reads that do not require payment. Use x402-native-client when this runtime can parse PAYMENT-REQUIRED and retry with PAYMENT-SIGNATURE or X-PAYMENT. Use local-sap-payments-bridge when a desktop/agent runtime has been configured by the SAP MCP wizard.",
+      "enum": [
+        "free-discovery",
+        "x402-native-client",
+        "local-sap-payments-bridge"
+      ],
+      "default": "free-discovery"
+    },
+    "x402Payer": {
+      "type": "string",
+      "title": "x402 payer",
+      "description": "How paid MCP calls will be paid. Select none for free discovery only, native when the current client signs x402 itself, sap-payments when the local SAP MCP bridge is installed, or custom when an external x402 CLI/proxy will handle the replay.",
+      "enum": [
+        "none",
+        "native",
+        "sap-payments",
+        "custom"
+      ],
+      "default": "none"
+    },
+    "wizardCompleted": {
+      "type": "boolean",
+      "title": "Wizard completed",
+      "description": "Set true after running the SAP MCP wizard locally: npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard. The wizard creates the local SAP profile, signer boundary, hosted sap entry, and sap_payments bridge.",
+      "default": false
+    },
+    "maxUsdPerPaidCall": {
+      "type": "number",
+      "title": "Max USD per paid call",
+      "description": "Recommended local policy cap for x402/pay.sh hosted paid tool calls. The hosted server returns the challenge; the local sap_payments bridge, native x402 client, or custom payer should enforce this cap before signing.",
+      "minimum": 0,
+      "maximum": 100,
+      "default": 0.02
+    },
+    "autoPayMicropayments": {
+      "type": "boolean",
+      "title": "Auto-pay small calls",
+      "description": "Optional local/client behavior for tiny approved calls under the configured cap. OOBE hosted MCP never stores user keypairs, wallet bytes, or signer secrets.",
+      "default": false
+    },
+    "setupCommand": {
+      "type": "string",
+      "title": "Local setup command",
+      "description": "Copy this command into a local terminal when paid/write tools should work from a non-custodial user profile.",
+      "const": "npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard",
+      "default": "npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard"
+    }
+  }
+}