@oobe-protocol-labs/sap-mcp-server 0.9.16 → 0.9.20

package/docs/14_DESKTOP_WIZARD_RELEASE.md

@@ -66,7 +66,7 @@ url = "https://mcp.sap.oobeprotocol.ai/mcp"
 ```toml
 [mcp_servers.sap_payments]
 command = "npx"
-args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.9.16", "sap-mcp-server"]
+args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.9.20", "sap-mcp-server"]
 startup_timeout_sec = 300
 tool_timeout_sec = 300
 
@@ -279,8 +279,8 @@ npm pack --dry-run --cache ./.npm-cache
 The current local macOS arm64 build produces:
 
 ```txt
-SAP-MCP-Wizard-0.9.16-arm64.dmg
-SAP-MCP-Wizard-0.9.16-arm64.zip
+SAP-MCP-Wizard-0.9.20-arm64.dmg
+SAP-MCP-Wizard-0.9.20-arm64.zip
 ```
 
 Windows EXE and Linux artifacts are produced by the GitHub Actions matrix.

package/docs/16_SAP_AGENT_IDENTITY_PIPELINE.md

@@ -235,6 +235,12 @@ Then call:
   confirms the agent account and reports a non-failing `protocolFee` audit.
 - Do not call profile/image update complete until `sap_payments_update_agent`
   confirms and a fresh `sap_get_agent_profile` read shows the intended fields.
+- If an update returns Anchor 3012, `AccountNotInitialized`, or a
+  `pricing_menu` error, do not classify it as missing `sap_payments` and do not
+  ask the user to repair/restart the runtime. The local signer route worked; the
+  SAP registry account lifecycle is missing a required on-chain PDA. Call
+  `sap_agent_next_action` and `sap_protocol_invariants`, then use the current
+  SDK/server initializer path before retrying the update.
 - Do not create temporary signing scripts.
 - Do not read keypair JSON.
 - Do not pay x402 for writes that the hosted server says require local signer.

package/docs/18_PREMIUM_PLUGIN_RUNTIME.md

@@ -0,0 +1,108 @@
+# SAP MCP Premium Plugin Runtime
+
+SAP MCP includes a typed premium plugin contract for paid streams, webhooks, and enterprise capabilities. The goal is to let agents discover paid real-time capabilities, validate schemas before spending, and bind future x402/pay.sh receipts to a clear session id without exposing private provider code or user key material.
+
+This layer is deliberately strict:
+
+- no fake stream data
+- no implicit provider claims
+- no execution of plugin code from user input
+- no keypair bytes or provider secrets in public metadata
+- no x402 charge for invalid catalog/session planning requests
+
+## What Ships In The Open Server
+
+The public MCP server exposes free discovery and planning tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `sap_premium_plugin_catalog` | Lists premium plugin manifests, schemas, pricing contracts, provider readiness, and private plugin loader guidance. |
+| `sap_stream_catalog` | Lists stream capability contracts such as quote deltas, price ticks, registry events, and x402 ledger events. |
+| `sap_webhook_catalog` | Lists webhook delivery contracts and signed callback event types. |
+| `sap_premium_validate_plugin_manifest` | Validates a manifest before publication or enterprise loading. |
+| `sap_premium_plugin_template` | Builds a strict data-only manifest template for custom stream, webhook, or premium tool contracts. |
+| `sap_premium_session_start` | Creates an unpaid, bounded session plan for a premium capability. |
+| `sap_premium_session_status` | Reads in-memory premium session planning status. |
+
+Planning is free because it prevents wasted x402 attempts. Live premium delivery should be charged by the delivery rail once the provider is configured and the session is activation-ready.
+
+## Public HTTP Discovery
+
+The hosted server also exposes the same premium contracts as public, machine-readable JSON:
+
+| Endpoint | Purpose |
+| --- | --- |
+| `/premium/catalog.json` | Full premium plugin catalog with provider readiness, pricing contracts, stream/webhook/tool capability ids, and private loader guidance. |
+| `/premium/streams.json` | Stream-only discovery for price ticks, quote deltas, registry events, and x402 ledger streams. |
+| `/premium/webhooks.json` | Webhook-only discovery for signed callback subscriptions and event delivery contracts. |
+
+These endpoints are discovery-only. They do not activate paid streams, execute private plugins, expose provider secrets, or return live provider data while readiness is false.
+
+## Provider Readiness
+
+Capabilities that depend on external streaming or webhook infrastructure include explicit provider env vars. If a required env var is missing, the capability returns:
+
+```txt
+status: requires-provider
+```
+
+Agents must not attempt paid activation when provider readiness is false. They should tell the user that the capability is contract-ready but not live on this deployment.
+
+## Built-In Premium Contracts
+
+The open catalog currently defines contract-level manifests for:
+
+| Plugin | Capability Examples |
+| --- | --- |
+| `sap-premium-market-data` | Jupiter quote deltas, Pyth price ticks, price threshold webhooks. |
+| `sap-premium-trading-streams` | Cross-DEX arbitrage scanning, volatility breakout detection, MEV-protected route optimization. |
+| `sap-premium-meme-radar` | New listing alerts, social sentiment, rugpull risk, DEX volume anomalies. |
+| `sap-premium-tech-fundamentals` | GitHub activity spikes, TVL changes, tokenomics analysis. |
+
+These are not mock feeds. They are typed contracts that become live only when the corresponding provider env is configured.
+
+## Private Enterprise Plugins
+
+Enterprise/private plugin code should live outside the public repository. The public server exposes the contract and validation path only.
+
+Supported loader env contract:
+
+```txt
+SAP_MCP_ENABLE_PREMIUM_PLUGINS=true
+SAP_MCP_PLUGIN_DIR=/secure/path/to/private/plugins
+SAP_MCP_PREMIUM_EXPOSE_PRIVATE_DISCOVERY=false
+```
+
+Private plugins must provide manifests that pass:
+
+```txt
+sap_premium_validate_plugin_manifest
+```
+
+The runtime loads private manifests as data only from the configured directory.
+It does not execute plugin code supplied through MCP tool input. Private and
+enterprise manifests are not exposed in public catalog responses unless
+`SAP_MCP_PREMIUM_EXPOSE_PRIVATE_DISCOVERY=true` is set deliberately, which
+should be reserved for authenticated or explicitly shared deployments.
+
+Use `sap_premium_plugin_template` to generate a starter manifest, then store the
+reviewed JSON in the private plugin subrepo under `manifests/`. Plugging and
+unplugging a private capability is a file/deploy operation: add or remove the
+manifest, validate it, and restart the hosted server with the intended env.
+
+## Agent Flow
+
+Recommended agent behavior:
+
+1. Call `sap_premium_plugin_catalog` with `includeSchemas:true`.
+2. Use `sap_stream_catalog` or `sap_webhook_catalog` to pick an exact capability id.
+3. Check `providerStatus` and the capability-level `providerReady` boolean.
+4. Call `sap_premium_session_start` to get a bounded session plan and estimated price.
+5. Activate only through the future paid delivery rail when provider readiness is true.
+6. Bind x402/pay.sh receipt, session id, plugin id, capability id, and event ids in the audit output.
+
+If the provider is not ready, stop cleanly and do not request payment.
+
+## Why This Matters
+
+Agent commerce needs more than one-shot tools. Trading agents, research agents, protocol monitors, and marketplace agents need fast event access with clear payment boundaries. SAP MCP premium plugins create the contract layer for that: typed schemas, bounded sessions, x402/pay.sh pricing, signed delivery, and enterprise provider isolation.

package/docs/README.md

@@ -65,6 +65,7 @@ For paid/write hosted tools, also configure the local `sap_payments` bridge. The
 - [Payments: x402 And pay.sh](user/03_PAYMENTS_X402_PAYSH.md)
 - [Smithery And MCP Marketplaces](user/07_SMITHERY_AND_MARKETPLACES.md)
 - [SAP Agent Identity Pipeline](16_SAP_AGENT_IDENTITY_PIPELINE.md)
+- [Premium Plugin Runtime](18_PREMIUM_PLUGIN_RUNTIME.md)
 
 ## What The Hosted Server Provides
 
@@ -118,6 +119,7 @@ Read these first:
 6. [Configuration And Wizard](03_CONFIGURATION_AND_WIZARD.md)
 7. [Endpoints And Clients](07_ENDPOINTS_AND_CLIENTS.md)
 8. [SAP Agent Identity Pipeline](16_SAP_AGENT_IDENTITY_PIPELINE.md)
+9. [Premium Plugin Runtime](18_PREMIUM_PLUGIN_RUNTIME.md)
 
 ## Public Endpoints
 
@@ -127,6 +129,16 @@ 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 /premium/catalog.json` | Public premium plugin contracts, pricing models, schemas, and provider readiness. |
+| `GET /premium/streams.json` | Public premium stream contracts for future x402/pay.sh real-time delivery rails. |
+| `GET /premium/webhooks.json` | Public premium webhook contracts with signed delivery expectations. |
+
+Premium plugin authors can use `sap_premium_plugin_template` and
+`sap_premium_validate_plugin_manifest` to build strict data-only contracts,
+then deploy reviewed manifests from a private plugin directory. The public
+server never executes plugin code supplied through MCP input and does not expose
+private/enterprise manifests unless the operator explicitly enables private
+discovery.
 | `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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oobe-protocol-labs/sap-mcp-server",
-  "version": "0.9.16",
+  "version": "0.9.20",
   "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",
@@ -145,16 +145,15 @@
   "engines": {
     "node": ">=22.12.0"
   },
-  "packageManager": "pnpm@11.7.0",
   "overrides": {
-    "bigint-buffer": "file:vendor/bigint-buffer",
-    "brace-expansion@<1.1.16": "1.1.16",
-    "brace-expansion@>=2.0.0 <2.1.2": "2.1.2",
-    "esbuild": "^0.28.1",
-    "js-yaml@>=4.0.0 <4.3.0": "4.3.0",
+    "@hono/node-server": "2.0.10",
+    "body-parser": "1.20.6",
+    "fast-uri": "3.1.4",
+    "hono": "4.12.27",
     "langsmith": "^0.6.0",
+    "postcss": "8.5.18",
     "uuid": "^11.1.1",
-    "vite": "8.1.0",
     "ws": "^8.21.0"
-  }
+  },
+  "packageManager": "pnpm@11.7.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.16",
+  "version": "0.9.20",
   "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.16",
+      "version": "0.9.20",
       "transport": {
         "type": "stdio"
       },
@@ -45,7 +45,7 @@
         },
         {
           "type": "positional",
-          "value": "@oobe-protocol-labs/sap-mcp-server@0.9.16"
+          "value": "@oobe-protocol-labs/sap-mcp-server@0.9.20"
         },
         {
           "type": "positional",

package/skills/sap-agent-registry/SKILL.md

@@ -76,6 +76,12 @@ state, global directory listing, and agent profile inspection.
 - After `sap_payments_update_agent`, fetch the agent profile again and verify
   the changed fields. For image/profile updates, `agentUri` or `metadataUri`
   must resolve to public metadata containing the image URL.
+- If `sap_payments_update_agent` returns Anchor 3012, `AccountNotInitialized`,
+  or mentions `pricing_menu`, do not run runtime repair and do not retry the
+  same write. This means the write reached the SAP on-chain program but a
+  required registry lifecycle PDA is missing or stale. Call
+  `sap_agent_next_action` and `sap_protocol_invariants`, then upgrade the
+  SDK/server or use the initializer path before retrying.
 - For full agent identity setup, follow
   `docs/16_SAP_AGENT_IDENTITY_PIPELINE.md`: SAP registration first, optional
   Metaplex/MPL Core identity, optional SNS domain and records, then a final SAP

package/skills/sap-mcp/SKILL.md

@@ -12,6 +12,12 @@ available, then call `sap_agent_runtime_status` with the closest intent and
 `sap_skills_bundle` with `includeContents: true`. Load the returned SAP MCP
 skill contents into context before selecting advanced tools.
 
+If the MCP runtime exposes prompts, use `sap-agent-intent-router` as the compact
+decision prompt before paid calls, registry writes, escrow flows, identity
+updates, or after SAP/x402/MCP errors. It routes the user intent to hosted
+reads, `sap_payments_*`, unsigned builders, transaction finalization, or repair
+without requiring a long pasted prompt from the user.
+
 Always inspect runtime context through MCP tools, not by reading config files:
 
 1. `sap_agent_start`
@@ -47,6 +53,10 @@ and error strings unchanged.
 
 ## Discovery Rules
 
+- Treat SAP registry, balances, SNS ownership, quotes, settlement status, and
+  agent profile reads as fresh data. Do not rely on old chat memory when the
+  user asks for current state; use exact lightweight reads first, then paid
+  discovery only when enrichment or broad search is needed.
 - Use free exact/base reads first when the wallet, PDA, or a small orientation
   page is enough: `sap_agent_context`, `sap_get_agent`, `sap_get_agent_profile`,
   `sap_get_agent_stats`, `sap_is_agent_active`, `sap_get_global_state`, and
@@ -175,10 +185,19 @@ 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
-server. Do not send these balance checks through `sap_payments_call_paid_tool`,
-and do not summarize a balance read as a facilitator `BlockhashNotFound`
-problem unless a paid tool actually returned that error.
+`spl-token_getBalance`, `spl-token_getTokenAccounts`, and `magicblock_balance`
+directly on the hosted server. Do not send these balance checks through
+`sap_payments_call_paid_tool`, and do not summarize a balance read as a
+facilitator `BlockhashNotFound` problem unless a paid tool actually returned
+that error. Use `jupiter_getHoldings` only when the user needs enriched paid
+portfolio context.
+
+Before any paid tool call, use `sap_estimate_tool_cost` with the tool name to
+get the exact pricing tier, estimated USD cost, and recommended `maxPriceUsd`.
+This prevents silent cap aborts and failed x402 attempts on local-signer-only
+tools. For local-signer-only tools (e.g. `sap_register_agent`), the estimate
+will say `tier: "local-signer-only"` and tell you to use the local
+`sap_payments_*` equivalent instead of `sap_payments_call_paid_tool`.
 
 If a hosted paid tool returns `BlockhashNotFound`,
 `transaction_simulation_failed`, `smart_wallet_simulation_failed`, `node is
@@ -220,6 +239,10 @@ and protocol fee invariant were verified. If `success` is false while
 protocol registration lifecycle is not complete. After
 `sap_payments_update_agent`, fetch the agent again and confirm the changed
 fields before saying an image, metadata, pricing, or capability update is done.
+If an update returns Anchor 3012, `AccountNotInitialized`, or `pricing_menu`, do
+not call runtime repair or retry the same write. Route it through
+`sap_agent_next_action` and `sap_protocol_invariants`; it is an SAP on-chain
+registry lifecycle issue, not a missing local bridge.
 
 Before any write-like operation, use this routing order:
 

package/skills/sap-mcp/TOOL_REFERENCE.md

@@ -201,7 +201,10 @@ Protocol routing shortcuts:
 
 | User intent | Most specific tools |
 | --- | --- |
-| SOL or SPL balance | `sol_get_balance`, `spl-token_getBalance`, `spl-token_getTokenAccounts` |
+| SOL or SPL balance (free) | `sol_get_balance`, `spl-token_getBalance`, `spl-token_getTokenAccounts`, `magicblock_balance` |
+| Enriched holdings (paid read-premium) | `jupiter_getHoldings` |
+| Pre-call cost estimate (free) | `sap_estimate_tool_cost` |
+| Pricing catalog (free) | `sap_pricing_catalog` |
 | SOL or SPL transfer | `spl-token_transferSol`, `spl-token_transfer` |
 | Token launch/mint/burn | `spl-token_deployToken`, `spl-token_mintTo`, `spl-token_burn` |
 | Jupiter quote/swap | `jupiter_getQuote`, `jupiter_smartSwap`, `jupiter_swap`, `jupiter_swapInstructions` |

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

@@ -46,9 +46,13 @@ or external signer.
 
 - Free: `tools/list`, `prompts/list`, `resources/list`, `sap_profile_current`,
   `sap_agent_start`, `sap_agent_runtime_status`, `sap_agent_context`,
-  `sap_agent_next_action`, exact SAP agent/profile reads, compact
-  `sap_list_agents` pages with `limit <= 20`, `sap_get_network_overview`, `sol_get_balance`,
-  `spl-token_getBalance`, and `spl-token_getTokenAccounts`.
+  `sap_agent_next_action`, `sap_estimate_tool_cost`, `sap_pricing_catalog`,
+  exact SAP agent/profile reads, compact `sap_list_agents` pages with
+  `limit <= 20`, `sap_get_network_overview`, core balance checks
+  (`sol_get_balance`, `spl-token_getBalance`, `spl-token_getTokenAccounts`,
+  `spl-token_getMint`, `spl-token_getSupply`, `magicblock_balance`,
+  `sap_x402_get_balance`). Enriched holdings such as `jupiter_getHoldings`
+  are paid read-premium.
 - Read premium: `sap_discover_agents`, `sap_list_all_agents`, full/enriched or
   large `sap_list_agents` pages, indexed discovery, network stats,
   protocol/capability indexes.
@@ -73,16 +77,26 @@ For fast x402 execution:
    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.
+4. Cache only static MCP surface metadata such as `tools/list`, `prompts/list`,
+   and `resources/list` inside the runtime when useful. Do not cache on-chain
+   balances, SAP agent rows, pricing, SNS ownership, quotes, or settlement
+   state when the user expects fresh data.
 5. Treat `PAYMENT-RESPONSE` as the receipt bound to the tool output.
 6. If the client runtime cannot sign or attach x402 payment headers itself, use
    the local SAP MCP `sap_payments_call_paid_tool` bridge configured by the SAP
    MCP wizard instead of falling back to local stdio automatically.
 
-Do not use x402 for basic balance reads. `sol_get_balance`,
-`spl-token_getBalance`, and `spl-token_getTokenAccounts` are free hosted tools
-and should be called directly through the remote SAP MCP connection.
+Do not use x402 for core balance reads. `sol_get_balance`,
+`spl-token_getBalance`, `spl-token_getTokenAccounts`, `magicblock_balance`,
+and `sap_x402_get_balance` are free hosted tools and should be called directly
+through the remote SAP MCP connection. Use `jupiter_getHoldings` only when the
+user needs enriched paid portfolio context. Always verify USDC and SOL balances
+before attempting paid calls — an agent without USDC cannot make paid calls.
+
+Before any paid tool call, use `sap_estimate_tool_cost` with the tool name to
+get the exact tier, estimated USD cost, and recommended `maxPriceUsd`. This
+prevents silent cap aborts and avoids wasting x402 attempts on local-signer-only
+tools that never issue a 402 challenge.
 
 When available locally, call `sap_payments_call_paid_tool` with `toolName`,
 `arguments`, `maxPriceUsd`, and `confirm: true`. It initializes the hosted MCP