@oobe-protocol-labs/sap-mcp-server 0.1.0

package/package.json

@@ -0,0 +1,132 @@
+{
+  "name": "@oobe-protocol-labs/sap-mcp-server",
+  "version": "0.1.0",
+  "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",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "sap-mcp-server": "./dist/cli.js",
+    "sap-mcp-config": "./dist/config-cli.js",
+    "sap-mcp-wizard": "./dist/tui/config-wizard.js",
+    "sap-signing-proxy": "./dist/signer/signing-proxy.js",
+    "sap-mcp-remote": "./dist/remote/server.js",
+    "sap-mcp-facilitator": "./dist/payments/oobe-facilitator-server.js",
+    "sap-mcp-pay-sh-spec": "./dist/payments/pay-sh-spec.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "docs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    ".env.example",
+    "config.example.json",
+    "config.secure-example.json",
+    "config.schema.json",
+    "ecosystem.config.example.cjs"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "pnpm run clean && tsc && tsc -p tsconfig.tui.json",
+    "build:core": "tsc",
+    "build:tui": "tsc -p tsconfig.tui.json",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js",
+    "config": "tsx src/config-cli.ts",
+    "tui:config": "tsx src/tui/config-wizard.tsx",
+    "typecheck": "tsc --noEmit --skipLibCheck",
+    "lint": "eslint src/",
+    "test": "vitest",
+    "verify:release": "pnpm run typecheck && pnpm run lint && pnpm test -- --run && pnpm run build && npm pack --dry-run --cache ./.npm-cache",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "solana",
+    "sap",
+    "synapse",
+    "oobe",
+    "agent",
+    "ai",
+    "blockchain"
+  ],
+  "author": "OOBE Protocol Labs",
+  "license": "MIT",
+  "dependencies": {
+    "@bonfida/spl-name-service": "3.0.9",
+    "@coral-xyz/anchor": "^0.30.1",
+    "@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",
+    "@solana/kit": "^5.5.1",
+    "@solana/sysvars": "^5.5.1",
+    "@solana/web3.js": "^1.95.0",
+    "@x402/core": "^2.17.0",
+    "@x402/express": "^2.17.0",
+    "@x402/svm": "^2.17.0",
+    "bn.js": "^5.2.1",
+    "bs58": "^6.0.0",
+    "cli-spinners": "^3.4.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.0",
+    "express": "^4.18.0",
+    "ink": "^7.1.0",
+    "ink-select-input": "^6.2.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "ioredis": "^5.4.0",
+    "js-sha256": "^0.11.0",
+    "jsonwebtoken": "^9.0.0",
+    "react": "^19.2.7",
+    "tweetnacl": "^1.0.3",
+    "ws": "^8.18.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@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",
+    "eslint": "^9.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.62.0",
+    "vitest": "^2.0.0"
+  },
+  "peerDependencies": {
+    "@bentoguard/sdk": ">=0.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@bentoguard/sdk": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "packageManager": "pnpm@10.33.0+sha512.10568bb4a6afb58c9eb3630da90cc9516417abebd3fabbe6739f0ae795728da1491e9db5a544c76ad8eb7570f5c4bb3d6c637b2cb41bfdcdb47fa823c8649319",
+  "overrides": {
+    "langsmith": "^0.6.0",
+    "uuid": "^11.1.1"
+  },
+  "pnpm": {
+    "overrides": {
+      "langsmith": "^0.6.0",
+      "uuid": "^11.1.1"
+    }
+  }
+}

package/skills/README.md

@@ -0,0 +1,146 @@
+# SAP MCP Skill Pack
+
+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:
+
+- `sap-overview`
+- `sap-mcp`
+- `sap-client`
+- `sap-advanced`
+- `sap-memory`
+- `sap-defi`
+- `sap-merchant`
+- `sap-nft`
+- `sap-metaplex`
+- `sap-gaming`
+- `sap-enterprise`
+- `sap-social`
+- `sns-skill`
+
+## Upstream References
+
+Use these upstream references when the agent needs the latest SAP SDK context
+or wants to compare this bundled MCP skill pack with the source SDK skills:
+
+- Synapse SAP SDK docs: https://github.com/OOBE-PROTOCOL/synapse-sap-sdk/tree/main/docs
+- Synapse SAP SDK skills: https://github.com/OOBE-PROTOCOL/synapse-sap-sdk/tree/main/skills
+
+## Skills
+
+| Skill | Use For |
+| --- | --- |
+| `sap-mcp` | MCP setup, profile inspection, wizard/CLI usage, safe signing rules |
+| `sap-operations` | SAP registry, memory, reputation, x402, escrow, settlement, staking |
+| `sap-sns` | SNS domain checks, records, wallet resolution, agent domain registration |
+| `sap-agentkit` | Synapse AgentKit Solana, NFT, DeFi, market, staking, gaming, social tools |
+| `sap-agent-registry` | Agent registration, profile inspection, activation, global agent directory |
+| `sap-discovery-indexing` | Network overview, global directory, protocol/capability/category indexes |
+| `sap-tool-registry` | Publish, update, fetch, deactivate, and report SAP tool descriptors |
+| `sap-reputation-attestation` | Feedback, reputation, attestations, FairScale trust gates |
+| `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-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 |
+| `sap-market-data` | Pyth, CoinGecko, Jupiter token intelligence, prices, OHLCV, risk data |
+| `sap-nft-metaplex` | DAS, Metaplex NFT, 3.Land collections, mints, listings, authorities |
+| `sap-social-gaming` | Blinks, Gibwork bounties, Send Arcade gaming |
+
+## Agent Behavior
+
+- Answer in the same natural language as the user's latest request.
+- Use `sap_list_all_agents` for current global SAP ecosystem agent lists.
+- 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.
+
+## Install With MCP
+
+Use the MCP tools exposed by this server:
+
+1. `sap_skills_list`
+2. `sap_skills_bundle`
+3. `sap_skills_install`
+
+For a dry run:
+
+```json
+{
+  "name": "sap_skills_install",
+  "arguments": {
+    "agent": "claude",
+    "confirm": false
+  }
+}
+```
+
+For a real install:
+
+```json
+{
+  "name": "sap_skills_install",
+  "arguments": {
+    "agent": "claude",
+    "confirm": true
+  }
+}
+```
+
+For custom agents:
+
+```json
+{
+  "name": "sap_skills_install",
+  "arguments": {
+    "agent": "custom",
+    "targetDir": "/absolute/path/to/agent/skills",
+    "confirm": true
+  }
+}
+```
+
+## Configure SAP MCP Locally
+
+Use the config CLI to create and manage profiles:
+
+```bash
+npx sap-mcp-config wizard
+npx sap-mcp-config show
+npx sap-mcp-config profiles
+npx sap-mcp-config profile-info
+npx sap-mcp-config pubkey
+npx sap-mcp-config wallet
+```
+
+For MCP clients such as Claude, Hermes, OpenClaw, or Codex, prefer the dynamic
+profile manager. In this mode the server reads `~/.config/mcp-sap/.active-profile`,
+so users can change profiles with `sap-mcp-config profile <name>` and then
+restart the MCP client:
+
+```yaml
+env:
+  SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE: "false"
+  SAP_LOG_LEVEL: info
+```
+
+Only pin `SAP_MCP_PROFILE` and `SAP_MCP_CONFIG_PATH` when the MCP client must
+always load one fixed profile regardless of the active profile marker.
+
+## Safety Contract
+
+- Agents must never read keypair JSON files.
+- Agents must never print secret key bytes, seed phrases, or wallet file paths.
+- Agents should use `sap_profile_current`, `sap_profile_list`, and
+  `sap_profile_public_key` for context.
+- Agents must use `sap_profile_switch` with `confirm: true` when changing
+  runtime profile.
+- Agents must use `sap_preview_transaction` before signing.
+- Agents must treat `sap_sign_transaction` and `sap_submit_signed_transaction`
+  as high-risk operations.

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

@@ -0,0 +1,39 @@
+# SAP Agent Registry
+
+Use this skill for SAP agent identity, registration, profile updates, activation
+state, global directory listing, and agent profile inspection.
+
+## First Steps
+
+1. Call `sap_profile_current`.
+2. Call `sap_get_network_overview` for ecosystem counters when needed.
+3. Use `sap_list_all_agents` for global current agent lists.
+
+## Tools
+
+- `sap_register_agent`
+- `sap_update_agent`
+- `sap_deactivate_agent`
+- `sap_reactivate_agent`
+- `sap_close_agent`
+- `sap_get_agent`
+- `sap_get_agent_profile`
+- `sap_get_agent_stats`
+- `sap_get_global_state`
+- `sap_get_network_overview`
+- `sap_list_all_agents`
+- `sap_is_agent_active`
+- `sap_report_calls`
+- `sap_update_reputation_metrics`
+
+## Routing
+
+- "List all agents" means `sap_list_all_agents`.
+- "Agent by wallet" means `sap_get_agent` or `sap_get_agent_profile`.
+- "Is this agent live?" means `sap_is_agent_active`.
+- "Network totals" means `sap_get_network_overview`.
+
+## Safety
+
+Registration and update tools are write operations. Explain the action, read
+policy context, and never inspect keypair files.

package/skills/sap-agentkit/SKILL.md

@@ -0,0 +1,40 @@
+# SAP AgentKit
+
+Use this skill for Synapse AgentKit tools exposed through SAP MCP: Solana RPC,
+SPL token, DAS, NFT, Metaplex, DeFi, market, staking, bridge, Blinks, bounty,
+and gaming workflows.
+
+This skill maps to upstream skill domains such as `sap-defi`, `sap-nft`,
+`sap-metaplex`, `sap-gaming`, and `sap-social`.
+
+## General Rules
+
+- Read `sap_profile_current` before acting.
+- Use read-only tools first.
+- Treat swap, bridge, staking, liquidity, mint, transfer, market, and order
+  tools as write/high-risk operations.
+- For tools that produce or submit transactions, preview and policy-check
+  before signing.
+- Never inspect keypair files or ask the user for secret key bytes.
+
+## Solana And Token
+
+Use `sol_get_balance`, `spl-token_*`, `pyth_*`, `coingecko_*`, and `das_*`
+tools for wallet, token, price, and asset context.
+
+## NFT And Metaplex
+
+Use `3land_*` and `metaplex-nft_*` tools for collection, minting, royalty,
+authority, and verification flows.
+
+## DeFi And Markets
+
+Use `adrena_*`, `drift_*`, `lulo_*`, `manifest_*`, `meteora_*`,
+`openbook_*`, `orca_*`, `raydium-pools_*`, `pump_*`, `bridging_*`,
+`staking_*`, and `jito_*` tools for DeFi execution.
+
+## Social, Blinks, Gaming
+
+Use `blinks_*`, `gibwork_*`, and `send-arcade_*` tools when the task is about
+actions, bounties, or games rather than direct SAP protocol operations.
+

package/skills/sap-defi/SKILL.md

@@ -0,0 +1,51 @@
+# SAP DeFi
+
+Use this skill for Jupiter swaps, DCA, limit orders, Drift, Adrena, Lulo,
+Raydium, Orca, Meteora, OpenBook, Manifest, Pump.fun, Jito, bridges, and
+staking protocols.
+
+## Jupiter
+
+- `jupiter_getQuote`
+- `jupiter_smartSwap`
+- `jupiter_swap`
+- `jupiter_swapInstructions`
+- `jupiter_getOrder`
+- `jupiter_executeOrder`
+- `jupiter_createLimitOrder`
+- `jupiter_executeTrigger`
+- `jupiter_cancelLimitOrder`
+- `jupiter_cancelLimitOrders`
+- `jupiter_getLimitOrders`
+- `jupiter_createDCA`
+- `jupiter_executeDCA`
+- `jupiter_cancelDCA`
+- `jupiter_getDCAOrders`
+
+## Protocol Tools
+
+- `drift_*`
+- `adrena_*`
+- `lulo_*`
+- `raydium-pools_*`
+- `orca_*`
+- `meteora_*`
+- `openbook_*`
+- `manifest_*`
+- `pump_*`
+- `jito_*`
+- `bridging_*`
+- `staking_*`
+
+## Flow
+
+1. Use quote/read tools first.
+2. For swaps, prefer `jupiter_getQuote` then `jupiter_smartSwap` or
+   `jupiter_swapInstructions`.
+3. Explain slippage, route, token mints, amount units, and expected output.
+4. Preview and policy-check before signing.
+
+## 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.

package/skills/sap-discovery-indexing/SKILL.md

@@ -0,0 +1,33 @@
+# SAP Discovery And Indexing
+
+Use this skill for SAP protocol indexes, capability indexes, tool category
+indexes, and filtered agent discovery.
+
+## Tools
+
+- `sap_discover_agents`
+- `sap_list_agents`
+- `sap_list_all_agents`
+- `sap_fetch_capability_index`
+- `sap_fetch_protocol_index`
+- `sap_fetch_tool_category_index`
+- `sap_find_tools_by_category`
+- `sap_get_tool_category_summary`
+- `sap_network_stats`
+- `sap_get_network_overview`
+
+## Rules
+
+- Use `sap_list_all_agents` for global directory requests.
+- Use `sap_discover_agents` only with `protocol`, `capability`, or
+  `capabilities`.
+- Use `sap_fetch_protocol_index` when the protocol ID is known.
+- Use `sap_fetch_capability_index` when the capability ID is known.
+- Do not guess that global enumeration is impossible; try `sap_list_all_agents`
+  first.
+
+## Common Inputs
+
+- Protocol IDs: `sap`, `jupiter`, `pyth`, `sns`, `mcp-v1`, or the exact
+  protocol ID returned by protocol indexes.
+- Capability IDs usually use namespaced form such as `jupiter:swap`.

package/skills/sap-escrow-settlement/SKILL.md

@@ -0,0 +1,37 @@
+# SAP Escrow Settlement
+
+Use this skill for escrow v1/v2, deposits, settlement, batch settlement,
+withdrawal, closing, pending settlements, and disputes.
+
+## 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`
+- `sap_finalize_settlement_v2`
+- `sap_file_dispute_v2`
+- `sap_withdraw_escrow_v2`
+- `sap_close_escrow_v2`
+- `sap_fetch_escrow_v2`
+- `sap_fetch_pending_settlement`
+- `sap_next_settlement_index`
+- `sap_fetch_dispute`
+
+## Flow
+
+1. Fetch 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.
+
+## Safety
+
+Escrow tools can lock, move, or release funds. Use preview/signing policy and
+explicit user approval for high-value actions.

package/skills/sap-ledger-session/SKILL.md

@@ -0,0 +1,24 @@
+# SAP Ledger Session
+
+Use this skill for higher-level session continuity workflows backed by SAP
+memory and ledger primitives.
+
+## Tools
+
+- `sap_session_start`
+- `sap_session_read_latest`
+- `sap_session_status`
+- `sap_fetch_session`
+- `sap_fetch_epoch_page`
+
+## Flow
+
+1. Start with `sap_session_status` when a session identifier is available.
+2. Use `sap_session_start` to create or resume durable session context.
+3. Use `sap_session_read_latest` before appending new context.
+4. Use `sap_fetch_epoch_page` for finalized historical pages.
+
+## Safety
+
+Session storage is durable. Summarize sensitive context rather than storing raw
+secrets or private user data.

package/skills/sap-market-data/SKILL.md

@@ -0,0 +1,36 @@
+# SAP Market Data
+
+Use this skill for token prices, price history, OHLCV, liquidity pools,
+trending assets, token metadata, and security/intelligence checks.
+
+## Tools
+
+- `pyth_getPrice`
+- `pyth_getPriceHistory`
+- `pyth_listPriceFeeds`
+- `coingecko_getTokenPrice`
+- `coingecko_getTokenInfo`
+- `coingecko_getOHLCV`
+- `coingecko_getPoolsByToken`
+- `coingecko_getTrending`
+- `coingecko_getTopGainersLosers`
+- `jupiter_getPrice`
+- `jupiter_getTokenInfo`
+- `jupiter_searchTokens`
+- `jupiter_getTokenList`
+- `jupiter_programLabels`
+- `jupiter_shield`
+- `jupiter_getHoldings`
+
+## Flow
+
+1. Resolve token mints with `jupiter_searchTokens` when the user gives only a
+   ticker.
+2. Use Pyth for oracle-style price feeds.
+3. Use CoinGecko for market data, OHLCV, pools, trending, gainers, and losers.
+4. Use `jupiter_shield` and `jupiter_getTokenInfo` for token risk context.
+
+## Safety
+
+Market data is informational. Do not treat it as financial advice, and do not
+execute trades from market data without explicit user intent.