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

package/docs/README.md

@@ -63,6 +63,7 @@ For paid/write hosted tools, also configure the local `sap_payments` bridge. The
 - [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)
+- [Smithery And MCP Marketplaces](user/07_SMITHERY_AND_MARKETPLACES.md)
 
 ## What The Hosted Server Provides
 
@@ -108,9 +109,10 @@ Read these first:
 1. [Hosted Remote MCP](user/01_HOSTED_REMOTE_MCP.md)
 2. [Client Configs](user/04_CLIENT_CONFIGS.md)
 3. [Payments: x402 And pay.sh](user/03_PAYMENTS_X402_PAYSH.md)
-4. [Desktop GUI Wizard](user/06_DESKTOP_GUI_WIZARD.md)
-5. [Configuration And Wizard](03_CONFIGURATION_AND_WIZARD.md)
-6. [Endpoints And Clients](07_ENDPOINTS_AND_CLIENTS.md)
+4. [Smithery And MCP Marketplaces](user/07_SMITHERY_AND_MARKETPLACES.md)
+5. [Desktop GUI Wizard](user/06_DESKTOP_GUI_WIZARD.md)
+6. [Configuration And Wizard](03_CONFIGURATION_AND_WIZARD.md)
+7. [Endpoints And Clients](07_ENDPOINTS_AND_CLIENTS.md)
 
 ## Public Endpoints
 
@@ -120,6 +122,7 @@ Read these first:
 | `GET /docs` | This documentation site. |
 | `POST /mcp` | Streamable HTTP MCP endpoint for agents. |
 | `GET /server.json` | Public, secret-free machine-readable server metadata. |
+| `GET /smithery.config.schema.json` | Optional Smithery setup schema for free discovery, native x402 clients, and local `sap_payments` bridge users. |
 | `GET /.well-known/agent-card.json` | A2A-style agent card. |
 | `GET /.well-known/sap-mcp-wizard.json` | Wizard install descriptor for agents that cannot see local config. |
 | `GET /wizard/install.sh` | One-line wizard installer. |

package/docs/_sidebar.md

@@ -3,6 +3,7 @@
   - [Hosted Remote MCP](user/01_HOSTED_REMOTE_MCP.md)
   - [Local Stdio MCP](user/02_LOCAL_STDIO_MCP.md)
   - [Client Configs](user/04_CLIENT_CONFIGS.md)
+  - [Smithery And Marketplaces](user/07_SMITHERY_AND_MARKETPLACES.md)
   - [Skills And Tools](user/05_SKILLS_AND_TOOLS.md)
   - [Desktop GUI Wizard](user/06_DESKTOP_GUI_WIZARD.md)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oobe-protocol-labs/sap-mcp-server",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "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",
@@ -27,6 +27,7 @@
     "CHANGELOG.md",
     "LICENSE",
     "server.json",
+    "smithery.config.schema.json",
     ".env.example",
     "config.example.json",
     "config.secure-example.json",
@@ -88,7 +89,7 @@
     "@langchain/core": "^0.3.80",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@oobe-protocol-labs/synapse-client-sdk": "^2.0.6",
-    "@oobe-protocol-labs/synapse-sap-sdk": "^0.21.0",
+    "@oobe-protocol-labs/synapse-sap-sdk": "^1.0.2",
     "@solana/kit": "^5.5.1",
     "@solana/sysvars": "^5.5.1",
     "@solana/web3.js": "^1.95.0",

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