SAP MCP Server

SAP MCP 服务

面向生产环境的 Model Context Protocol 服务，适用于 OOBE Synapse Agent Protocol、Solana、Synapse AgentKit、SNS 和可变现的托管 Agent 工作流。

SAP MCP 通过两种受支持的 MCP 启动模式公开同一套类型化工具注册表：

1. 面向桌面 Agent 和本地开发的本地 stdio。
2. 面向托管客户和编排器的远程 Streamable HTTP，路径为 /mcp。

它还包含专业的设置向导、由配置文件管理且位于 ~/.config/mcp-sap 下的配置、可选的 Bento 策略集成、本地和外部签名模式、x402 变现、可自托管的 OOBE facilitator、pay.sh 提供商 YAML 生成，以及兼容 A2A 的发现卡片。

面向用户的设置文档位于 USER_DOCS/。运维和工程文档位于 docs/。

1. 状态

领域	当前行为
软件包版本	0.9.85
MCP 传输	本地使用 stdio，远程使用 Streamable HTTP
远程访问	面向托管 Agent 的无 Bearer 公共模式；私有模式使用 API 密钥或 JWT
配置目录	仅限 ~/.config/mcp-sap
Agent 钱包	默认使用 ~/.config/mcp-sap/keypairs/ 下的专用钱包路径
Solana CLI 密钥对	向导绝不会修改
策略	默认使用本地策略，可选 Bento 或混合策略
变现	可选的仅限远程的 x402/pay.sh 支付流程，并按工具定价
签名	根据配置文件模式，使用本地专用钱包或外部签名器
发现	位于 /.well-known/agent-card.json 的兼容 A2A 卡片

2. 安装

先决条件：

node --version   # >= 22.12.0
corepack enable
corepack prepare [email protected] --activate
pnpm --version   # 11.7.0

从源代码安装：

pnpm install
pnpm run build

源代码部署请勿使用 npm install。此仓库使用 pnpm 锁定并验证。

从已发布的软件包安装：

npm install -g @oobe-protocol-labs/sap-mcp-server

3. 快速入门

创建或选择配置文件：

npx sap-mcp-config wizard

修复托管 SAP MCP 运行时条目，无需重新创建配置文件：

npx sap-mcp-config repair

在 Agent 运行时连接托管 SAP MCP 后，用一条简短消息启动 Agent 上下文：

Start SAP MCP.

Agent 应调用免费的 sap_agent_start 工具或 sap-agent-start 提示词，加载 sap_skills_bundle，并在付费或写入型托管调用中使用本地 sap_payments 桥接工具。

检查当前配置文件：

npx sap-mcp-config show
npx sap-mcp-config doctor
npx sap-mcp-config pubkey
npx sap-mcp-config profiles

启动本地 stdio MCP：

sap-mcp-server

或从源代码启动：

node dist/cli.js

托管客户将 Agent 连接到 https://mcp.sap.oobeprotocol.ai/mcp，但签名仍由用户控制。建议大多数用户使用由向导管理的一对 MCP 条目：

• sap：位于 https://mcp.sap.oobeprotocol.ai/mcp 的托管 Streamable HTTP SAP MCP；
• sap_payments：用于 x402/pay.sh 付费或写入型调用的本地非托管支付桥接工具。

任何希望支付 x402/pay.sh 费用、注册或运行 SAP 身份，或执行转移 Solana/SAP 资产的工具的用户，都应先运行向导，并将专用钱包保存在 ~/.config/mcp-sap/keypairs/ 下或置于外部签名器之后。只读托管发现可通过远程 URL 使用，无需本地签名器。

4. 本地客户端配置

对于本地 Agent，让 SAP MCP 使用当前的配置文件管理器，而不是硬编码钱包路径或过时的 RPC 覆盖配置：

{
  "mcpServers": {
    "sap": {
      "command": "sap-mcp-server",
      "env": {
        "SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE": "false",
        "SAP_LOG_LEVEL": "info"
      }
    }
  }
}

Codex 使用 TOML，而不是 JSON 格式的 mcpServers 结构。对于托管远程 MCP，请将以下内容添加到 ~/.codex/config.toml 并重启 Codex：

[mcp_servers.sap]
url = "https://mcp.sap.oobeprotocol.ai/mcp"

对于付费或写入型托管工具，也添加本地非托管支付桥接工具：

[mcp_servers.sap_payments]
command = "npx"
args = ["--yes", "--package", "@oobe-protocol-labs/[email protected]", "sap-mcp-server"]
startup_timeout_sec = 300
tool_timeout_sec = 300

[mcp_servers.sap_payments.env]
SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE = "false"
SAP_MCP_PAYMENTS_BRIDGE_ONLY = "true"
SAP_ALLOWED_TOOLS = "all"
SAP_LOG_LEVEL = "info"

在 Windows 上，使用 command = "npx.cmd"。向导可以自动写入此配置。

Codex 支持在 config.toml 中通过基于 URL 的条目配置 Streamable HTTP MCP 服务。只有在确实希望 Codex 启动本地 SAP MCP 进程时，才通过 npx 使用本地 stdio：

[mcp_servers.sap]
command = "npx"
args = ["--yes", "--package", "@oobe-protocol-labs/[email protected]", "sap-mcp-server"]

[mcp_servers.sap.env]
SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE = "false"
SAP_LOG_LEVEL = "info"

在 Windows 上，使用 command = "npx.cmd"。

参阅 04. 本地 Stdio MCP 运行手册。

5. 远程服务

远程部署通过 Streamable HTTP 提供 MCP：

node dist/remote/server.js

生产环境的值应来自私有密钥库或私有部署文件，而非公开文档。启用了 x402、速率限制和策略的公开托管 Agent 部署可以使用 SAP_MCP_AUTH_TYPE=none。API 密钥或 JWT 身份验证仍可用于私有测试版、企业和管理部署。

远程端点：

GET     /
GET     /docs
GET     /server.json
GET     /favicon.png
GET     /favicon.ico
GET     /health
GET     /openapi.json
GET     /.well-known/x402
GET     /pay/provider.yml
GET     /.well-known/agent-card.json
GET     /.well-known/sap-mcp-wizard.json
GET     /.well-known/sap-mcp-tool-catalog.json
GET     /tool-catalog.json
GET     /wizard/install.sh
POST    /mcp
GET     /mcp
DELETE  /mcp

GET / 是公开且可安全分享的落地页，带有 Open Graph/Twitter 元数据。它仅公开服务器信息；其中绝不能出现密钥对字节、私有钱包路径、RPC 查询密钥和 VPS 本地路径。

GET /docs 提供公开文档站点，内容涵盖安装、启动、配置、托管远程 MCP、x402/pay.sh 支付和 MCP 客户端设置。

Smithery 等市场列表可以使用 smithery.config.schema.json 来说明托管设置路径。该架构有意不要求提供任何 密钥：SAP MCP 托管读取操作可远程执行，而付费/写入调用使用 向导管理的本地 sap_payments 桥接、本地配置文件策略和 由用户控制的签名器。

请参阅 05. 托管 Streamable HTTP 部署 和 07. HTTP 端点、MCP 客户端和冒烟测试。

6. 变现

托管 HTTP 部署可以对付费的 tools/call 请求收费，同时保持本地 stdio 和基础 MCP 协议调用免费。

初始模式：

层级	示例	价格
免费	tools/list、prompts/list、resources/list、引导/状态/修复、成本估算、本地支付桥接控制、SOL/SPL/x402 余额就绪状态、单资产价格快照、记忆/审计、交易预览/最终确认助手	免费
微型读取	精确的 Agent/配置文件读取、紧凑目录页面、SNS 可用性、托管状态、轻量交易者上下文	$0.001
高级读取	广泛发现、增强型持仓/DAS、代币列表、报价/路由、历史记录/OHLCV、分析、更大的页面	$0.002
构建或批量处理	复杂构建器、SNS/域名批量检查、未签名交易构建器、路由准备	$0.006，批量 = 付费调用总和
价值操作	选定的价值关联操作	标准固定 $0.06，选定的高负载路径 $0.035，另加可选 bps

启用 x402：

SAP_MCP_MONETIZATION_ENABLED=true
SAP_MCP_MONETIZATION_PROVIDER=x402
SAP_MCP_MONETIZATION_PAY_TO=YOUR_SOLANA_USDC_RECIPIENT
SAP_MCP_X402_FACILITATOR_URL=YOUR_PRIVATE_OR_HOSTED_FACILITATOR_URL

初始化并运行 OOBE facilitator：

npx sap-mcp-facilitator init
npx sap-mcp-facilitator start

生成 pay.sh 提供方 YAML：

托管的公开目录可通过 https://mcp.sap.oobeprotocol.ai/pay/provider.yml 获取。 该目录不含密钥，供 pay.sh 目录/代理发现使用。

npx sap-mcp-pay-sh-spec \
  --out sap-mcp-pay-sh.yml \
  --upstream-url https://mcp.sap.oobeprotocol.ai \
  --network mainnet \
  --recipient YOUR_SOLANA_USDC_RECIPIENT

请参阅 06. x402/pay.sh 变现结算。

对于无法原生重放 x402 挑战的本地 Agent 运行时，请安装 向导提供的本地 sap_payments 桥接，并调用 sap_payments_call_paid_tool。 旧版 CLI 助手仍可在终端中使用：

npm exec --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

该助手使用用户的本地 SAP MCP 配置文件签署支付载荷， 绝不会将密钥对字节发送到托管服务。

7. 命令

pnpm run typecheck
pnpm run lint
pnpm test -- --run
pnpm run build
pnpm run verify:release

已安装的二进制文件：

命令	用途
sap-mcp-server	本地 stdio MCP 服务和 CLI 入口点
sap-mcp-remote	支持无 bearer、API 密钥和 JWT 模式的远程 MCP 服务
sap-mcp-config	配置 CLI、配置文件管理器、审批工作流和向导
sap-mcp-wizard	TUI 配置向导
sap-signing-proxy	本地签名代理
sap-mcp-facilitator	可自托管的 x402 SVM facilitator
sap-mcp-pay-sh-spec	pay.sh 提供方 YAML 生成器
sap-mcp-x402-paid-call	托管 x402 付费 MCP 工具的旧版终端/自定义包装器回退方案

8. 文档

请从 00. 工程文档索引 开始。

文档	用途
01. 产品范围与部署模型	产品模型、用户、公共／私有代码库指南和向导分发。
02. 运行时架构与信任边界	运行时模块、本地流程、远程流程、签名、支付和信任边界。
03. 配置档案配置、向导与注入	配置档案管理器、向导、钱包隔离、客户端注入和配置 CLI。
04. 本地 Stdio MCP 运行手册	Claude、Hermes、Codex、OpenClaw 和开发 Agent 的本地设置。
05. 托管式 Streamable HTTP 部署	托管部署、反向代理、PM2 和客户入门。
06. x402/pay.sh 变现与结算	定价、x402 门控、pay.sh 提供方 YAML、facilitator 签名者和结算。
07. HTTP 端点、MCP 客户端与冒烟测试	HTTP 端点、标头、冒烟测试和客户端示例。
08. 安全策略签名运行手册	密钥材料规则、签名者模式、Bento 策略和交易安全。
09. 工具、技能路由与 Agent 运维	工具系列、SDK 文档指引、技能和 Agent 行为。
10. 发布运维 PM2 运行手册	质量门禁、PM2、密钥、发布打包和变更日志规范。
11. 工程质量审计报告	当前工程评分卡、发布门禁、质量规则和剩余风险。
12. 已签名 Agent 聊天协议	已签名主题群聊、房间清单、检索、链接分享、隐私边界和 SDK 路线图。
13. 悬赏计划技术规范	合作伙伴悬赏范围、评审标准和技术要求。
14. 桌面向导发布产物	原生向导打包、签名、校验和发布产物。
15. 演示仪表板屏幕共享运行手册	托管落地页、仪表板、向导和支付界面的演示流程。
16. Agent 身份注册表流水线	注册表数据源、信息补充、验证和展示流水线。
18. 高级插件运行时契约	高级插件清单契约、提供方就绪状态、流和 Webhook。
19. Agent 标准互操作性	MCP、A2A、市场、x402/pay.sh 和运行时对齐。
20. 工程运营模式边界	分支归属、服务契约、发布角色和企业级门禁。

9. 仓库结构

该仓库是一个模块化单仓库。实际源代码位于 packages/*/src/；对应的 src/ 目录是轻量兼容包装层（export * from '../../packages/...'），用于保留现有导入路径。

packages/
  core/              Shared runtime types, errors, logger, constants, guards, result
  config-runtime/    Runtime config, secure config manager, setup wizard, runtime doctor, client injection
  server-runtime/    MCP server factory, capability registration, server metadata
  hosted-gateway/    Streamable HTTP MCP server, public home, premium routes, rate limiter, tx relay
  local-bridge/      Local stdio MCP bridge, payment bridge process diagnostics
  mcp-adapter/       Model Context Protocol adapter compatibility layer
  schemas/           Public Zod schemas and protocol contracts
  tools/             SAP, Solana, AgentKit, SNS, profile, skill, chat, payment, perps, and premium tools
  ui-cards/          MCP Apps Card rendering, card builder, templates, protocol logos
  wizard-core/       Shared CLI and desktop wizard flow
  tool-plugin-template/  Trusted external tool-family plugin template
  adapters/          Solana connection and public key adapter utilities
  bin/               npx-safe bootstrap entrypoints for remote and local servers
  memory/            Agent memory store, tool call store, stream buffer, Hermes bridge
  observability/     Metrics collection and exporter
  perps/             Perpetual futures analytics, Adrena builders, chart indicators, risk engine
  payments/          x402 monetization, facilitator, usage ledger, pay.sh spec, pricing
  policy/            Local, Bento, and hybrid policy engines, spending limits, permission checks
  premium/           Premium runtime plugins, streams, webhooks, session management
  prompts/           MCP prompt templates for developer, payments, context, execution-proof, registry
  resources/         MCP resource templates for memory, execution-proof, reputation, profile, registry, stats
  runtime/           Module resolution and payment bridge process management
  sap/               SAP SDK client manager, types, and error classes
  security/          Private-key guard, tool permissions, prompt injection notes, approval gates
  session/           Session store, delegated sessions, agent sessions, session limits
  signer/            Local, delegated, and external signer adapters, wallet guard, policy-enforcing wallet
  solana/            Solana ATA utilities
  strategies/        Strategy store and trade journal
  transports/        stdio and HTTP transport layers
  tui/               Terminal UI wizard save helper (legacy, source in src/tui/)

根目录的 package.json 会重新导出所有包的接口，因此使用方无需直接引用内部包，即可从 @oobe-protocol-labs/sap-mcp-server 导入。

10. 许可证

SAP MCP Server 根据 MIT 许可证 发布。

11. 合作伙伴产品

合作伙伴 / 产品	集成方式
@bentoguard / Bento Guard	可选的策略层，用于 AI 辅助的意图评分、升级处理，以及本地与 Bento Guard 混合防护措施。使用可选的 @bentoguard/sdk 软件包，以及从 app.bentoguard.xyz 获取的凭据。