@oobe-protocol-labs/sap-mcp-server 0.2.1 → 0.7.0

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@oobe-protocol-labs/sap-mcp-server",
-  "version": "0.2.1",
+  "version": "0.7.0",
+  "mcpName": "io.github.OOBE-PROTOCOL/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": "io.github.OOBE-PROTOCOL/sap-mcp",
+  "title": "SAP MCP Server",
+  "description": "Solana-native MCP gateway for SAP, DeFi tools, SNS identity, and x402 payments.",
+  "version": "0.7.0",
+  "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.0",
+      "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.0"
+        },
+        {
+          "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/README.md

@@ -59,8 +59,9 @@ or wants to compare this bundled MCP skill pack with the source SDK skills:
 - Use `sap_discover_agents` only for protocol/capability-filtered discovery.
 - Treat `mcp_sap_<tool>` as a client display prefix; the callable MCP tool name
   inside this server is the suffix, for example `jupiter_getQuote`.
-- Use `docs/SAP_SDK_SKILLS.md` as the complete routing map when deciding which
-  SAP MCP tool or skill domain applies to a user request.
+- Use `skills/sap-mcp/TOOL_REFERENCE.md` and `USER_DOCS/05_SKILLS_AND_TOOLS.md`
+  as the bundled routing maps when deciding which SAP MCP tool or skill domain
+  applies to a user request.
 
 ## Install With MCP
 

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

@@ -51,7 +51,89 @@ source skill taxonomy:
 
 Use the bundled routing map for local MCP tool selection:
 
-- `docs/SAP_SDK_SKILLS.md`
+- `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:
+
+```text
+https://mcp.sap.oobeprotocol.ai/mcp
+```
+
+Public server metadata:
+
+```json
+{
+  "name": "sap-mcp-server",
+  "title": "SAP MCP Server | OOBE Protocol",
+  "status": "online",
+  "protocol": {
+    "primary": "mcp",
+    "transport": "streamable-http",
+    "protocolVersion": "2025-06-18"
+  },
+  "endpoints": {
+    "landing": "https://mcp.sap.oobeprotocol.ai/",
+    "mcp": "https://mcp.sap.oobeprotocol.ai/mcp",
+    "serverInfo": "https://mcp.sap.oobeprotocol.ai/server.json",
+    "wizardDescriptor": "https://mcp.sap.oobeprotocol.ai/.well-known/sap-mcp-wizard.json",
+    "wizardInstallScript": "https://mcp.sap.oobeprotocol.ai/wizard/install.sh"
+  },
+  "authentication": {
+    "schemes": ["none", "x402"],
+    "bearerRequired": false
+  },
+  "security": {
+    "keypairBytesExposed": false,
+    "storesUserKeypairs": false,
+    "rpcSecretsExposed": false,
+    "wizardConfigDirectory": "~/.config/mcp-sap"
+  }
+}
+```
+
+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
+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
 
@@ -156,6 +238,39 @@ Avoid passing `SAP_WALLET_PATH` or `SAP_MCP_RPC_URL` from the MCP client unless
 the user intentionally wants env overrides and has set
 `SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE=true`.
 
+Hosted Claude/Codex/OpenClaw-style JSON:
+
+```json
+{
+  "mcpServers": {
+    "sap": {
+      "url": "https://mcp.sap.oobeprotocol.ai/mcp",
+      "transport": "streamable-http"
+    }
+  }
+}
+```
+
+Hosted Hermes global `~/.hermes/mcp.json` JSON:
+
+```json
+{
+  "sap": {
+    "url": "https://mcp.sap.oobeprotocol.ai/mcp",
+    "transport": "streamable-http"
+  }
+}
+```
+
+Hosted Hermes profile YAML:
+
+```yaml
+mcp_servers:
+  sap:
+    url: https://mcp.sap.oobeprotocol.ai/mcp
+    transport: streamable-http
+```
+
 Show active profile:
 
 ```bash
@@ -177,7 +292,7 @@ Start local MCP over stdio:
 npx sap-mcp-server start
 ```
 
-Start remote MCP over Streamable HTTP:
+Operator-only: start your own remote MCP over Streamable HTTP:
 
 ```bash
 SAP_MCP_AUTH_TYPE=api_key \
@@ -185,6 +300,13 @@ SAP_MCP_API_KEYS=<api-key>=<operator-id> \
 npx sap-mcp-remote
 ```
 
+Do not ask hosted users to run their own HTTP server unless they are deploying
+their own VPS/operator instance.
+
+Do not call a local free `stdio` SAP MCP server as an implicit substitute for
+hosted paid tools. Local stdio is a developer fallback only when the user asks
+for local execution or the client cannot perform remote Streamable HTTP/x402.
+
 ## Signing Rules
 
 - Do not read wallet/keypair files.

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`
@@ -22,8 +23,17 @@ workflows, and hosted SAP MCP x402/pay.sh monetization.
 
 ## Hosted MCP Monetization
 
+Canonical hosted endpoint: `https://mcp.sap.oobeprotocol.ai/mcp`.
+
 Remote `/mcp` deployments can require x402 v2 payment for paid `tools/call`
-requests. Local `stdio` usage remains free.
+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`.
@@ -38,7 +48,49 @@ instructions, create a payment, retry with `PAYMENT-SIGNATURE`, and capture
 `PAYMENT-RESPONSE` after settlement. If a `payShCheckoutUrl` is present, surface
 it for browser/manual checkout flows.
 
-Reference: `docs/MONETIZATION.md`.
+For fast x402 execution:
+
+1. Reuse the MCP session returned by `initialize`.
+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 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`.
 
 ## Safety