@oobe-protocol-labs/sap-mcp-server 0.3.0 → 0.7.1

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@oobe-protocol-labs/sap-mcp-server",
-  "version": "0.3.0",
+  "version": "0.7.1",
+  "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",
   "main": "dist/index.js",
@@ -13,7 +14,8 @@
     "sap-signing-proxy": "dist/signer/signing-proxy.js",
     "sap-mcp-remote": "dist/bin/sap-mcp-remote.js",
     "sap-mcp-facilitator": "dist/payments/oobe-facilitator-server.js",
-    "sap-mcp-pay-sh-spec": "dist/payments/pay-sh-spec.js"
+    "sap-mcp-pay-sh-spec": "dist/payments/pay-sh-spec.js",
+    "sap-mcp-x402-paid-call": "dist/payments/x402-paid-call.js"
   },
   "files": [
     "dist",
@@ -24,6 +26,7 @@
     "README.md",
     "CHANGELOG.md",
     "LICENSE",
+    "server.json",
     ".env.example",
     "config.example.json",
     "config.secure-example.json",
@@ -43,6 +46,10 @@
     "build": "pnpm run clean && tsc && tsc -p tsconfig.tui.json",
     "build:core": "tsc",
     "build:tui": "tsc -p tsconfig.tui.json",
+    "desktop:renderer": "vite --config apps/desktop/vite.config.ts",
+    "desktop:renderer:build": "vite build --config apps/desktop/vite.config.ts",
+    "desktop:build": "pnpm run build && pnpm run desktop:renderer:build && electron-builder --config apps/desktop/electron-builder.cjs --publish never",
+    "desktop:verify-artifact": "node scripts/verify-desktop-artifact.mjs",
     "dev": "tsx src/cli.ts",
     "start": "node dist/cli.js",
     "config": "tsx src/config-cli.ts",
@@ -67,6 +74,14 @@
   ],
   "author": "OOBE Protocol Labs",
   "license": "MIT",
+  "homepage": "https://mcp.sap.oobeprotocol.ai/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OOBE-PROTOCOL/sap-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/OOBE-PROTOCOL/sap-mcp/issues"
+  },
   "dependencies": {
     "@bonfida/spl-name-service": "3.0.9",
     "@coral-xyz/anchor": "^0.30.1",
@@ -94,17 +109,23 @@
     "js-sha256": "^0.11.0",
     "jsonwebtoken": "^9.0.0",
     "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "tweetnacl": "^1.0.3",
     "ws": "^8.21.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
+    "@electron/notarize": "2.5.0",
     "@eslint/js": "^9.39.4",
     "@types/bn.js": "^5.2.0",
     "@types/cors": "^2.8.0",
     "@types/express": "^4.17.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.0",
+    "electron": "^39.2.7",
+    "electron-builder": "^26.0.12",
     "eslint": "^9.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",

package/server.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "ai.oobeprotocol.sap.mcp/sap-mcp",
+  "title": "SAP MCP Server",
+  "description": "Solana-native MCP gateway for SAP, DeFi tools, SNS identity, and x402 payments.",
+  "version": "0.7.1",
+  "websiteUrl": "https://mcp.sap.oobeprotocol.ai/",
+  "repository": {
+    "url": "https://github.com/OOBE-PROTOCOL/sap-mcp",
+    "source": "github",
+    "id": "1283972695"
+  },
+  "icons": [
+    {
+      "src": "https://mcp.sap.oobeprotocol.ai/favicon.png",
+      "mimeType": "image/png",
+      "sizes": [
+        "512x512"
+      ]
+    }
+  ],
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://mcp.sap.oobeprotocol.ai/mcp"
+    }
+  ],
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@oobe-protocol-labs/sap-mcp-server",
+      "version": "0.7.1",
+      "transport": {
+        "type": "stdio"
+      },
+      "runtimeHint": "npx",
+      "runtimeArguments": [
+        {
+          "type": "positional",
+          "value": "--yes"
+        },
+        {
+          "type": "positional",
+          "value": "--package"
+        },
+        {
+          "type": "positional",
+          "value": "@oobe-protocol-labs/sap-mcp-server@0.7.1"
+        },
+        {
+          "type": "positional",
+          "value": "sap-mcp-server"
+        }
+      ],
+      "environmentVariables": [
+        {
+          "name": "SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE",
+          "description": "Keep SAP MCP pointed at the active profile manager instead of stale client env overrides.",
+          "format": "boolean",
+          "value": "false"
+        },
+        {
+          "name": "SAP_LOG_LEVEL",
+          "description": "Runtime log level for local SAP MCP stdio sessions.",
+          "format": "string",
+          "default": "info"
+        }
+      ]
+    }
+  ]
+}

package/skills/sap-defi/SKILL.md

@@ -44,8 +44,16 @@ staking protocols.
    `jupiter_swapInstructions`.
 3. Explain slippage, route, token mints, amount units, and expected output.
 4. Preview and policy-check before signing.
+5. For any unsigned or partially signed transaction returned by Jupiter, use
+   `sap_preview_transaction`, `sap_sign_transaction`, and
+   `sap_submit_signed_transaction`. Do not write ad-hoc signing scripts.
 
 ## Safety
 
 DeFi execution can lose funds through slippage, MEV, wrong decimals, or bad
 mints. Do not proceed from ticker symbols alone when mint addresses are needed.
+Never read, print, export, or pass keypair bytes through shell commands,
+environment variables, temporary scripts, screenshots, prompts, or MCP client
+config. If a transaction cannot be decoded by SAP MCP transaction tools, stop
+and report the unsupported transaction format instead of manually signing raw
+message bytes.

package/skills/sap-mcp/SKILL.md

@@ -54,6 +54,14 @@ 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.
+
 ## Hosted Remote MCP
 
 Canonical hosted endpoint:
@@ -98,6 +106,12 @@ Hosted users still need a local SAP MCP profile when they sign x402/pay.sh
 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.
+
 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
 tool surface is unavailable. Do not silently switch to local stdio just because
@@ -105,6 +119,22 @@ 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.
 
+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.
+
+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",
+"writes unavailable", or "remote MCP broken" unless a specific tool returns
+that exact operational error.
+
 ## Profile Tools
 
 | Tool | Purpose |

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

@@ -7,6 +7,7 @@ workflows, and hosted SAP MCP x402/pay.sh monetization.
 
 - `sap_x402_prepare_payment`
 - `sap_x402_get_balance`
+- `sap_x402_paid_call`
 - `sap_create_subscription`
 - `sap_fund_subscription`
 - `sap_cancel_subscription`
@@ -29,6 +30,10 @@ requests. Local `stdio` usage remains free and should not attempt x402 payment.
 Do not treat hosted `402 Payment Required` as a failure; it is the expected
 payment handshake. Do not silently bypass hosted paid tools by switching to a
 local free stdio MCP server unless the user explicitly asks for local execution.
+If `sap_profile_current` says the hosted server has no signer, treat that as
+the non-custodial model: OOBE does not hold user keys. Paid and value-moving
+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`.
@@ -46,16 +51,43 @@ it for browser/manual checkout flows.
 For fast x402 execution:
 
 1. Reuse the MCP session returned by `initialize`.
-2. Replay the exact same paid JSON-RPC body after payment; changing the body
-   changes the request hash and invalidates the payment intent.
+2. Retry the same MCP method and params after payment. The JSON-RPC `id` may
+   change, but the tool name and arguments must match the challenge.
 3. Use `PAYMENT-SIGNATURE` first; use `X-PAYMENT` only for clients that require
    the alternate header.
 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/signing bridge instead of falling back to
-   local stdio automatically.
+   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.
+
+## Transient Settlement Errors
+
+If a hosted paid call fails with `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 failure. Do not say the SAP MCP server is down unless `/health`
+also fails. Do not switch to terminal/direct RPC to bypass payment, and do not
+reuse the old signed payment payload.
+
+Correct recovery:
+
+1. Call the local `sap_x402_paid_call` 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.
+4. If all attempts fail, report that x402 settlement is temporarily unavailable
+   and ask the user to retry or repair the facilitator/RPC deployment.
 
 References: `USER_DOCS/03_PAYMENTS_X402_PAYSH.md` and
 `docs/06_PAYMENTS_X402_AND_PAYSH.md`.