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

package/docs/14_DESKTOP_WIZARD_RELEASE.md

@@ -0,0 +1,264 @@
+# 14. Desktop Wizard Release
+
+## 14.1 Purpose
+
+The Desktop Wizard packages SAP MCP onboarding as a GUI/TUI-style installer for users who should not need to hand-edit agent runtime config.
+
+It is a wrapper around the same production setup modules used by:
+
+```bash
+sap-mcp-config wizard
+```
+
+The desktop app must not maintain a second config format, wallet model, signer model, or x402 flow.
+
+## 14.2 Source Layout
+
+| Path | Purpose |
+| --- | --- |
+| `src/wizard-core/desktop-flow.ts` | Shared desktop setup core: defaults, validation, runtime detection, save orchestration. |
+| `apps/desktop/main.mjs` | Electron main process and IPC boundary. |
+| `apps/desktop/preload.cjs` | Safe renderer bridge. |
+| `apps/desktop/src/main.tsx` | React wizard UI. |
+| `apps/desktop/src/styles.css` | Accessible aqua-themed desktop styling. |
+| `apps/desktop/electron-builder.cjs` | DMG/ZIP, NSIS EXE, and Linux tar.gz packaging config. |
+| `apps/desktop/build/icon.png` | 1024x1024 installer icon derived from the public SAP MCP logo. |
+
+## 14.3 Trust Boundary
+
+The renderer receives profile metadata and user-entered form values only.
+
+It must never receive:
+
+1. keypair bytes;
+2. private signer payloads;
+3. facilitator secrets;
+4. RPC API keys;
+5. hosted deployment env values;
+6. payment recipient private material.
+
+Profile creation and runtime config writes happen through the main-process IPC handler, which calls shared setup modules.
+
+## 14.4 Runtime Integrations
+
+The desktop wizard supports two setup modes:
+
+| Mode | Behavior |
+| --- | --- |
+| Full SAP MCP setup | Creates or updates the local SAP MCP profile, wallet boundary, policy limits, hosted MCP runtime entries, and x402 bridge. |
+| x402 payment client only | Skips profile/wallet writes and only installs or repairs hosted MCP plus local `sap_payments` runtime entries. |
+
+The x402-only mode is for users who already ran a wizard, can see hosted SAP MCP tools, but cannot execute paid/write calls because their runtime does not yet attach payment proofs.
+
+### 14.4.1 Codex
+
+Codex uses native Streamable HTTP MCP support for hosted SAP MCP and a local command-backed bridge for payment replay:
+
+1. hosted remote MCP entry:
+
+```toml
+[mcp_servers.sap]
+url = "https://mcp.sap.oobeprotocol.ai/mcp"
+```
+
+2. local payment bridge entry:
+
+```toml
+[mcp_servers.sap_payments]
+command = "npx"
+args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server", "sap-mcp-server"]
+enabled_tools = ["sap_x402_paid_call", "sap_profile_current", "sap_x402_estimate_cost"]
+tool_timeout_sec = 300
+```
+
+On Windows, use `npx.cmd`.
+
+### 14.4.2 Claude Desktop
+
+Claude Desktop receives a root `mcpServers` JSON config. The hosted server uses Claude's HTTP MCP shape:
+
+```json
+{
+  "mcpServers": {
+    "sap": {
+      "type": "http",
+      "url": "https://mcp.sap.oobeprotocol.ai/mcp"
+    }
+  }
+}
+```
+
+The desktop wizard writes platform-native Claude paths:
+
+| OS | Path |
+| --- | --- |
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.json` |
+| Linux | `~/.config/Claude/claude_desktop_config.json` |
+
+### 14.4.3 Hermes
+
+Hermes global `mcp.json` receives flat server entries:
+
+```json
+{
+  "sap": {
+    "url": "https://mcp.sap.oobeprotocol.ai/mcp",
+    "transport": "streamable-http"
+  }
+}
+```
+
+Hermes profile YAML receives entries under top-level `mcp_servers`.
+
+### 14.4.4 OpenClaw
+
+OpenClaw receives root `mcpServers` JSON when `~/.openclaw/mcp.json` is selected or created. Existing YAML config receives top-level `mcp_servers` entries.
+
+### 14.4.5 Payment Bridge Invariant
+
+Every supported runtime may also receive a local `sap_payments` server with only these enabled tools:
+
+```txt
+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.
+
+## 14.5 Build Commands
+
+Renderer only:
+
+```bash
+pnpm run desktop:renderer:build
+```
+
+Full local desktop build:
+
+```bash
+pnpm run desktop:build
+```
+
+The full command runs:
+
+1. TypeScript build for server/core/TUI.
+2. Vite renderer build.
+3. Electron Builder packaging with `--publish never`.
+
+Artifacts are written to:
+
+```txt
+release/desktop
+```
+
+Generated renderer and release files are ignored by git.
+
+## 14.6 GitHub Release Workflow
+
+Native multi-OS artifacts are built by:
+
+```txt
+.github/workflows/desktop-release.yml
+```
+
+Triggers:
+
+1. manual `workflow_dispatch`;
+2. tag push such as `0.6.0`.
+
+Artifact matrix:
+
+| Runner | Artifact |
+| --- | --- |
+| `macos-15` | `.dmg`, `.zip` |
+| `windows-2025` | NSIS `.exe` |
+| `ubuntu-24.04` | `.tar.gz` |
+
+Tagged runs attach artifacts to a draft GitHub release.
+
+## 14.7 Signing Requirements
+
+Local unsigned builds are acceptable when the release notes clearly mark the macOS artifact as unsigned and provide the quarantine removal command.
+
+Public release requirements:
+
+1. macOS Developer ID Application certificate;
+2. macOS notarization credentials;
+3. Windows code signing certificate for SmartScreen reputation;
+4. checksum publication in GitHub release notes;
+5. changelog section for the exact released version.
+
+Do not publish unsigned binaries as final user-facing installers without an explicit warning.
+
+For signed tagged GitHub release builds, the macOS job uses these secrets when they are configured:
+
+| Secret | Purpose |
+| --- | --- |
+| `MACOS_CSC_LINK` or `CSC_LINK` | Base64-encoded `.p12` Developer ID Application certificate, or a secure URL supported by Electron Builder. |
+| `MACOS_CSC_KEY_PASSWORD` or `CSC_KEY_PASSWORD` | Password for the certificate bundle. |
+| `APPLE_ID` | Apple Developer account email used for notarization. |
+| `APPLE_APP_SPECIFIC_PASSWORD` | App-specific password for notarization. |
+| `APPLE_TEAM_ID` | Apple Developer Team ID. |
+
+The Electron Builder macOS config uses:
+
+1. hardened runtime;
+2. explicit Electron entitlements;
+3. `afterSign` notarization through `apps/desktop/notarize.cjs`;
+4. ad-hoc signing mode when `CSC_LINK` is not present;
+5. signed/notarized mode when Apple Developer ID secrets are present.
+
+If macOS shows this message:
+
+```txt
+"SAP MCP Wizard" is damaged and cannot be opened.
+```
+
+the downloaded app was blocked by Gatekeeper because it was not signed and notarized for public distribution, or because the browser applied a quarantine attribute to an unsigned build.
+
+Temporary local-only workaround for a trusted internal build:
+
+```bash
+xattr -dr com.apple.quarantine "/Applications/SAP MCP Wizard.app"
+```
+
+or, before dragging from the mounted image:
+
+```bash
+xattr -dr com.apple.quarantine "/Volumes/SAP MCP Wizard/SAP MCP Wizard.app"
+```
+
+Unsigned/ad-hoc macOS release note text:
+
+```txt
+macOS note: this build is ad-hoc signed but not Apple-notarized. After copying the app to /Applications, run:
+xattr -dr com.apple.quarantine "/Applications/SAP MCP Wizard.app"
+```
+
+A zero-warning public macOS release still requires Apple Developer ID signing and notarization.
+
+## 14.8 Verification Gates
+
+Before publishing:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm run typecheck
+pnpm run lint
+pnpm run test:run
+pnpm audit --audit-level moderate
+pnpm run build
+pnpm run desktop:build
+npm pack --dry-run --cache ./.npm-cache
+```
+
+The current local macOS arm64 build produces:
+
+```txt
+SAP-MCP-Wizard-0.6.0-arm64.dmg
+SAP-MCP-Wizard-0.6.0-arm64.zip
+```
+
+Windows EXE and Linux artifacts are produced by the GitHub Actions matrix.

package/docs/README.md

@@ -0,0 +1,104 @@
+# SAP MCP Documentation
+
+SAP MCP is the hosted and local Model Context Protocol gateway for Synapse Agent Protocol, Solana execution tools, x402/pay.sh monetization, SNS identity, and agent operations.
+
+The primary hosted endpoint is:
+
+```txt
+https://mcp.sap.oobeprotocol.ai/mcp
+```
+
+Use this documentation when you need to install the wizard, connect Claude/Hermes/Codex/OpenClaw or another MCP client, configure a local SAP profile and signer, understand hosted payments, or operate the server on a VPS.
+
+## Fastest Hosted Setup
+
+Most users should connect agents to the hosted remote MCP server while keeping signing local and user-controlled.
+
+```bash
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard
+```
+
+Users who prefer a GUI can download the Desktop Wizard from GitHub releases:
+
+```txt
+https://github.com/OOBE-PROTOCOL/sap-mcp/releases
+```
+
+The desktop wizard creates the same local SAP MCP profile, signer boundary, hosted MCP client config, and optional x402 paid-call bridge as the CLI wizard.
+
+The wizard creates an isolated SAP MCP profile under:
+
+```txt
+~/.config/mcp-sap
+```
+
+Then configure your MCP client with:
+
+```json
+{
+  "mcpServers": {
+    "sap": {
+      "url": "https://mcp.sap.oobeprotocol.ai/mcp",
+      "transport": "streamable-http"
+    }
+  }
+}
+```
+
+## What The Hosted Server Provides
+
+SAP MCP groups tools into three practical buckets:
+
+| Bucket | What Agents Can Do |
+| --- | --- |
+| Solana DeFi protocol tools | Use Jupiter, Raydium, Orca, Meteora, Drift, Pyth, Metaplex, SPL Token, bridging, staking, and related Solana protocol integrations. |
+| Solana RPC and chain methods | Read balances, token accounts, transactions, DAS assets, NFTs, network state, program data, and chain metadata. |
+| Synapse Agent Protocol methods | Register and discover agents, use SAP reputation, escrow, settlement, memory, proofs, SNS identity, policy context, and coordination flows. |
+
+## Trust Boundary
+
+The hosted server does not custody user wallets. Users create a local SAP MCP profile and signer with the wizard. Value-moving flows, x402/pay.sh payment payloads, and transaction signatures remain authorized by the user machine or an external signer.
+
+Keypair bytes must never be pasted into MCP client config, sent to the hosted server, logged, or shown to agents.
+
+## Remote Payment Model
+
+Hosted paid tools use x402 and pay.sh:
+
+- free: MCP handshake, `tools/list`, prompts, resources, base profile/context tools
+- paid reads: premium registry, discovery, and analytics tools
+- builders: batch/domain/enriched operations
+- value flows: fixed or percentage pricing only where it is operationally appropriate
+
+For agents that cannot replay x402 challenges natively, install the optional paid-call helper:
+
+```bash
+npx --yes --package @oobe-protocol-labs/sap-mcp-server sap-mcp-x402-paid-call \
+  --tool sap_list_all_agents \
+  --arguments '{"limit":5}' \
+  --max-usd 0.02 \
+  --confirm
+```
+
+## Start Here
+
+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)
+
+## Public Endpoints
+
+| Endpoint | Purpose |
+| --- | --- |
+| `GET /` | Public landing page and payment/server overview. |
+| `GET /docs` | This documentation site. |
+| `POST /mcp` | Streamable HTTP MCP endpoint for agents. |
+| `GET /server.json` | Public, secret-free machine-readable server metadata. |
+| `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

@@ -0,0 +1,31 @@
+- Getting Started
+  - [Overview](README.md)
+  - [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)
+  - [Skills And Tools](user/05_SKILLS_AND_TOOLS.md)
+  - [Desktop GUI Wizard](user/06_DESKTOP_GUI_WIZARD.md)
+
+- Payments
+  - [x402 And pay.sh](user/03_PAYMENTS_X402_PAYSH.md)
+  - [Protocol Spec](x402-protocol-spec.md)
+  - [Payments Architecture](06_PAYMENTS_X402_AND_PAYSH.md)
+
+- Configuration
+  - [Configuration And Wizard](03_CONFIGURATION_AND_WIZARD.md)
+  - [Security Policy And Signing](08_SECURITY_POLICY_AND_SIGNING.md)
+  - [Endpoints And Clients](07_ENDPOINTS_AND_CLIENTS.md)
+
+- Operations
+  - [Product Overview](01_PRODUCT_OVERVIEW.md)
+  - [Architecture And Request Flow](02_ARCHITECTURE_AND_REQUEST_FLOW.md)
+  - [Local Stdio Usage](04_LOCAL_STDIO_USAGE.md)
+  - [Remote VPS Deployment](05_REMOTE_VPS_DEPLOYMENT.md)
+  - [Operations Release And PM2](10_OPERATIONS_RELEASE_AND_PM2.md)
+  - [Desktop Wizard Release](14_DESKTOP_WIZARD_RELEASE.md)
+  - [Code Quality Audit](11_CODE_QUALITY_AUDIT.md)
+
+- Advanced
+  - [Tools Skills And Agent Guide](09_TOOLS_SKILLS_AND_AGENT_GUIDE.md)
+  - [On-Chain Agent Chat](12_ONCHAIN_AGENT_CHAT.md)
+  - [Bounty Program Proposal](13_BOUNTY_PROGRAM_PROPOSAL.md)

package/docs/magicblock-tools.md

@@ -0,0 +1,166 @@
+# MagicBlock Tools
+
+> 20 MCP tools wrapping the MagicBlock ER Router, Private Payment API, and Solana VRF.
+
+---
+
+## Overview
+
+The SAP MCP server now includes 20 MagicBlock tools that wrap two MagicBlock
+API surfaces:
+
+1. **ER Router** — JSON-RPC 2.0 at `https://(devnet-)router.magicblock.app`
+2. **Private Payment API** — REST at `https://payments.magicblock.app`
+
+A third protocol (VRF) is implemented on-chain using `@solana/web3.js` —
+it builds unsigned transactions that invoke the VRF program
+(`Vrf1RNUjXmQGjmQrQLvJHs9SNkvDJEsRVFPkfSQUwGz`) and reads
+`RandomnessRequest` accounts to check fulfillment.
+
+All tools are registered automatically when the MCP server starts — no
+additional configuration needed.
+
+---
+
+## Pricing
+
+Two tiers, priced in USDC base units (6 decimals):
+
+| 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 |
+
+Every tool description includes its price. Every successful response
+includes `priceUsd` and `priceBaseUnits` fields for SAP escrow settlement.
+
+---
+
+## Tools (20 total)
+
+### ER Router (6 read-only — $0.01)
+
+| Tool | Description |
+|------|-------------|
+| `magicblock_getRoutes` | List available ER nodes (identity, FQDN, fee, block time, country) |
+| `magicblock_getIdentity` | Get the identity and FQDN of the current ER validator |
+| `magicblock_getDelegationStatus` | Check if a Solana account is delegated to an ER |
+| `magicblock_getAccountInfo` | Fetch account info via the Magic Router |
+| `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)
+
+| Tool | Description |
+|------|-------------|
+| `magicblock_health` | Check Private Payments API health |
+| `magicblock_challenge` | Generate a challenge string for wallet auth |
+| `magicblock_login` | Exchange signed challenge for bearer token |
+
+### Private Payments — Balance (2 — $0.01)
+
+| 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)
+
+| Tool | Description |
+|------|-------------|
+| `magicblock_deposit` | Build unsigned deposit tx (Solana → ER) |
+| `magicblock_transfer` | Build unsigned SPL transfer (public or private) |
+| `magicblock_withdraw` | Build unsigned withdraw tx (ER → Solana) |
+
+### 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) |
+
+### 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 |
+
+### 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 |
+
+---
+
+## Auth Flow (Private Ephemeral Rollup)
+
+```
+1. magicblock_challenge({ pubkey })          → { challenge: "..." }
+2. Wallet signs the challenge string
+3. magicblock_login({ pubkey, challenge, signature })  → { token: "..." }
+4. Pass authToken on magicblock_privateBalance and magicblock_transfer (private)
+```
+
+---
+
+## Transaction Flow (Write Tools)
+
+Write tools return an unsigned transaction:
+
+```json
+{
+  "kind": "deposit",
+  "version": "legacy",
+  "transactionBase64": "AQAAAA...",
+  "sendTo": "base",
+  "recentBlockhash": "9A4VhP8M...",
+  "lastValidBlockHeight": 284512337,
+  "instructionCount": 3,
+  "requiredSigners": ["3rXKwQ1kpjBd..."]
+}
+```
+
+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`
+
+---
+
+## Response Format
+
+Every successful response is wrapped with pricing metadata:
+
+```json
+{
+  "success": true,
+  "tool": "magicblock_deposit",
+  "priceUsd": "$0.05",
+  "priceBaseUnits": "50000",
+  "data": { ... }
+}
+```
+
+Error responses:
+
+```json
+{
+  "error": "MagicBlock tool magicblock_deposit failed",
+  "message": "MagicBlock API 400: ..."
+}
+```
+
+---
+
+## File Reference
+
+| File | Description |
+|------|-------------|
+| `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 |