PayRam Crypto Card Payment Gateway

官方

面向代理、openclaw、hermes等的自托管支付网关

GitHub

158

你可以用 PayRam Crypto Card Payment Gateway MCP 做什么？

规划个性化安装 — 通过 payram_setup_plan 请求一份包含人工交接的分步 PayRam 部署计划。
诊断服务器健康状态 — 使用 payram_doctor 对任意 PayRam URL 执行免凭证检查，以识别问题及修复方案。
排查错误 — 粘贴错误信息或症状，通过 payram_troubleshoot 获取已知原因、确认步骤及后续操作。
获取管理员运行手册 — 通过 payram_runbook 请求 SSL、备份或域名变更等分步管理员任务指南。
执行第2天运维操作 — 让代理通过 payram_ops_playbook 运行 API 配方，用于日常检查、节点同步或支付链接。
生成集成代码 — 请求适用于 Express 或 Next.js 等框架的即用型支付、付款或 Webhook 代码片段。

文档

PayRam MCP Server — 面向 AI 智能体的自托管加密货币支付

自托管加密货币与稳定币支付：无账户锁定、无资金冻结、客户数据绝不外泄。您的 AI 智能体可以通过 MCP 自行规划、安装并运维它。 托管端点：https://mcp.payram.com/mcp · 网站 · 文档 · Agentic · OpenClaw

这是一个 MCP（Model Context Protocol）服务器，可让任何支持 MCP 的 AI 智能体——OpenClaw、Hermes、Claude、Cursor、GitHub Copilot 等——部署、集成并运维一套自托管的 PayRam 加密货币支付栈。

从这里开始： 四个工具引领整个目录：

工具	功能
`payram_setup_plan`	个性化安装计划，标注所有需要人工介入的环节
`payram_doctor`	通过 URL 对 PayRam 服务器进行公开、无需凭证的检查
`payram_troubleshoot`	描述问题或粘贴错误信息：已知原因、确认方法、修复方案以及下一步该用的工具
`payram_runbook`	管理任务：站点 URL、域名、SSL、防火墙、升级、备份、链、Smart Bridge、Shopify/WooCommerce
`payram_ops_playbook`	智能体使用自身凭证直接执行的 Day-2 API 操作手册

围绕这些工具，还有代码库评估、入门应用脚手架、多语言代码片段和内置文档。

托管服务器（mcp.payram.com）绝不保存商户凭证。 Day-2 操作通过 payram_ops_playbook 执行：智能体直接调用您的 PayRam API，凭证从不离开其所在机器。实时数据工具（支付搜索、支付链接、节点同步、工作进程重启）和 assess_payram_project 仅在您以本地模式自行运行 MCP 时才可用。

面向智能体与爬虫： 服务器卡片 · 技能索引 · llms.txt · 站点地图。服务器还会在 / 上以智能体可读的摘要回答 Accept: text/markdown。

什么是 PayRam？· What is PayRam?

PayRam 是一个您完全自托管、自主拥有的多链加密货币支付网关——运行它无需注册、无需 KYC/KYB。 AI 智能体（或开发者）无需在 PayRam、银行或任何支付处理商处注册账户，即可搭建店铺并开始收款。在自己的 VPS 上部署，本地生成 API 密钥，即刻上线。

核心差异：

没有人能把你锁在门外 — 没有可被封禁的账户，也没有可被冻结的资金；客户数据从不外泄，也没有任何上报或监控。原因很简单：PayRam 运行在你自己的服务器上，资金直接进入你自己的钱包。
免注册、免许可 — 无需注册、无需 KYC、无需 KYB。没有人审批你，也没有人能关停你。非常适合自主搭建店铺的智能体，以及像中国这样难以在西方支付处理商处注册的市场。
银行卡转加密货币结算 — 没有加密货币的买家也能用信用卡/借记卡付款，你直接收到加密货币并结算到自托管的钱包。这是内置的支付渠道，在「Payments（支付）」页面开启；银行卡服务商会对买家进行其自身的审核。
多链支持 — 原生支持在 Bitcoin、Ethereum、Base、Polygon、Tron 上接受 BTC、ETH、USDT、USDC、TRX，自动检测充值、链上确认、归集冷钱包并发送带签名的 Webhook。Smart Bridge 通道还可接收 Solana、Bitcoin、Tron（USDT）和 BNB Chain 上的付款，并以 Base 上的 USDC 结算。
服务器上没有充值私钥 — 智能合约把充值资金归集到你的冷钱包，即便服务器被攻破也无法改变资金去向。服务器上的热钱包负责支付 Gas 并签署出款，请只保留少量余额。

AI 智能体如何使用 PayRam · How AI agents use PayRam

PayRam 是智能体优先（agent-first）的基础设施。由于集成基于 MCP 协议，它可与任何兼容 MCP 的运行时配合使用——OpenClaw、Hermes、Claude Desktop、Cursor、GitHub Copilot、n8n、LangChain 等。典型的智能体使用流程：

连接 — 将 https://mcp.payram.com/mcp 添加到智能体的 MCP 配置中（仅连接无需 API 密钥）。
规划 — 调用 payram_setup_plan。它会返回有序的步骤、每一步由谁执行，以及智能体必须在何处停下来等待人工处理（冷钱包、主网 Gas、仅 root 可用的设置）。
安装 — 在 VPS 上，在交互式终端中一次性运行 bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet（或 --mainnet；安装程序默认主网，因此务必传入该标志）。切勿将其通过管道传给 bash。
交接 — 人工立即认领 root 账户，并从公网域名保存 Settings → Site URL；在此之前，支付链接指向 http://localhost。
检查 — 使用公网 URL 调用 payram_doctor（无需凭证）。
收款 — 从代码片段工具中引入框架特定的集成代码。Webhook 带签名（X-Payram-Signature，使用项目 API 密钥对原始请求体进行 HMAC-SHA256）。
运维 — payram_ops_playbook（daily_check、payment_options、node_sync、unswept_funds、create_payment_link、…）为智能体提供使用自身凭证执行的确切 API 调用。payram_runbook 涵盖管理变更。

{
  "mcpServers": {
    "payram": { "url": "https://mcp.payram.com/mcp" }
  }
}

有关 OpenClaw 专属的逐步指南（注册、Base Sepolia 测试网、WhatsApp/Telegram/Discord 的聊天商务模式），请参阅 payram-openclaw-integration 技能和 payram.com/openclaw。

PayRam 是智能体优先（agent-first）的基础设施。由于集成基于 MCP 协议，它可与任何兼容 MCP 的运行时配合使用——OpenClaw、Hermes、Claude Desktop、Cursor、GitHub Copilot、n8n、LangChain 等。典型的智能体使用流程：连接 MCP 端点 → 调用 payram_setup_plan 规划安装 → 在交互式终端中用 bash <(curl …) --testnet 部署网关 → 由人工立即创建 root 账户并在公网域名下保存 Site URL → 用 payram_doctor 检查 → 用集成代码收款（Webhook 带 X-Payram-Signature 签名）→ 通过 payram_ops_playbook 用智能体自己的凭证运维。托管的 MCP 服务器从不保存商户凭证。

如果你的网络难以访问 GitHub，可以把本仓库镜像到其他 Git 托管平台（git clone --mirror https://github.com/PayRam/payram-mcp.git）。 If GitHub is hard to reach from your network, you can mirror this repository to another Git host (git clone --mirror https://github.com/PayRam/payram-mcp.git).

智能体技能

智能体入口： https://mcp.payram.com/SKILL.md — 一个根技能，描述 PayRam 并将智能体引导至四个起始工具。同时提供：/llms.txt。

本仓库包含 19 个面向 AI 编码助手的智能体技能。通过 skills.sh 安装：

单独安装

npx skills add payram/payram-mcp/payram-setup
npx skills add payram/payram-mcp/payram-agent-onboarding
npx skills add payram/payram-mcp/payram-auth
npx skills add payram/payram-mcp/payram-analytics
npx skills add payram/payram-mcp/payram-crypto-payments
npx skills add payram/payram-mcp/payram-payment-integration
npx skills add payram/payram-mcp/payram-self-hosted-payment-gateway
npx skills add payram/payram-mcp/payram-checkout-integration
npx skills add payram/payram-mcp/payram-widget-integration
npx skills add payram/payram-mcp/payram-webhook-integration
npx skills add payram/payram-mcp/payram-stablecoin-payments
npx skills add payram/payram-mcp/payram-bitcoin-payments
npx skills add payram/payram-mcp/payram-payouts
npx skills add payram/payram-mcp/payram-no-kyc-crypto-payments
npx skills add payram/payram-mcp/payram-openclaw-integration
npx skills add payram/payram-mcp/compare-crypto-payments
npx skills add payram/payram-mcp/payram-agent-journey
npx skills add payram/payram-mcp/payram-topup-wallet-integration
npx skills add payram/payram-mcp/payram-testnet-testing

技能	用途
`payram-setup`	安装计划与服务器设置：要求、安装程序、站点 URL、钱包、第一个支付链接
`payram-agent-onboarding`	智能体无头安装：智能体 CLI 命令、环境变量、人工交接
`payram-auth`	JWT 认证流程 — 登录、令牌刷新、登出、外部平台详情
`payram-analytics`	通过直接 REST API（JWT）进行支付搜索、交易量、余额和归集历史
`payram-crypto-payments`	架构概览、为什么选择 PayRam、MCP 工具
`payram-payment-integration`	快速入门支付集成指南
`payram-self-hosted-payment-gateway`	部署并拥有你的支付基础设施
`payram-checkout-integration`	使用 SDK + HTTP 的结账流程，覆盖 6 种框架
`payram-widget-integration`	安全的「添加余额」按钮（后端端点，绝不使用公网 API 密钥）+ 签名 Webhook 处理器
`payram-webhook-integration`	签名 Webhook（HMAC）处理器，适用于 Express、Next.js、FastAPI、Gin、Laravel、Spring Boot
`payram-stablecoin-payments`	在 EVM 链和 Tron 上接受 USDT/USDC
`payram-bitcoin-payments`	使用 HD 钱包派生和移动签名的 BTC
`payram-payouts`	发送加密货币出款并管理推荐计划
`payram-no-kyc-crypto-payments`	无 KYC、无注册、免许可的支付收款
`payram-openclaw-integration`	将 PayRam 集成到 OpenClaw / 智能体运行时 — MCP 注册、测试网、聊天商务
`compare-crypto-payments`	网关对比：Stripe、BitPay、Coinbase、NOWPayments、BTCPay、PayRam、x402
`payram-agent-journey`	起始地图：安装（商户或运营者）→ 钱包 → Gas/归集 → 集成 → 测试
`payram-topup-wallet-integration`	现有应用：将加密货币计入用户余额、从中扣款生成发票 — 账本 + 流程
`payram-testnet-testing`	在主网上线前，先在测试网上端到端支付自己的支付链接

项目目标

加速上手：提供个性化设置计划、操作手册、环境变量模板和按框架划分的剧本。
不持有凭证即可运维：托管服务器通过 URL 检查 PayRam（payram_doctor），并向智能体提供精确的 API 操作手册（payram_ops_playbook），由其使用自身凭证执行。
改造现有仓库：通过项目评估工具（本地模式）扫描包清单和 .env 文件，然后推荐合适的集成代码片段。
提供即用代码片段：涵盖 Payments、Payouts、Referrals、Webhooks 以及多语言后端（Express、Next.js、FastAPI、Laravel、Gin、Spring Boot 等）。
保持文档本地化：让 Copilot 无需离开编辑器即可解释 PayRam 概念、流程和推荐仪表盘。
验证连通性：使用只读探测，绝不创建支付（payram_doctor、test_payram_connection）。

快速开始

大多数智能体只需要托管端点 https://mcp.payram.com/mcp（参见从 MCP 客户端连接）。要自行运行服务器：

安装依赖
```
yarn install
```
配置环境（仅本地模式数据工具需要）
- 将 .env.example 复制为 .env。
- 将 PAYRAM_BASE_URL 设置为你的 PayRam URL，与仪表盘同源（例如 https://pay.example.com）。
- 设置 PAYRAM_API_KEY，以及数据工具所需的 JWT 变量。参见本地模式。

运行服务器

yarn dev
# Streamable HTTP on http://127.0.0.1:3333/mcp (local mode; there is no SSE transport)

将 MCP 服务器添加到你的客户端：参见从 MCP 客户端连接。本地模式 URL 为 http://localhost:3333/mcp。
健康检查
```
curl http://localhost:3333/healthz
```

提示： 当你告诉 Copilot "test payram" 时，它会自动运行就绪检查清单，确保 .env 存在，然后才使用你的真实凭据调用 test_payram_connection。该行为由 Copilot 自动化提示词定义——无需手动提示。

从 MCP 客户端连接

端点： https://mcp.payram.com/mcp（Streamable HTTP，基于 POST 的 JSON-RPC）。没有 SSE 端点，/mcp/sse 返回 410。无需认证头：托管服务器从不保存商户凭据，因此你的凭据只保留在你的机器上，绝不会进入聊天。

客户端	位置	设置
VS Code (Copilot Chat)	设置 → Copilot: Model Context Protocol → 添加 HTTP 服务器	名称 `payram`，URL 如上，请求头为空
Cursor	设置 → MCP 服务器 → 添加 → HTTP	名称 `payram`，URL 如上
Claude Desktop / Code	设置 → MCP 服务器 → 添加 HTTP 服务器	名称 `payram`，URL 如上
任意 MCP 客户端	注册一个 HTTP 端点	URL 如上，无请求头

验证： 工具列表应以 payram_setup_plan、payram_doctor、payram_troubleshoot、payram_runbook 和 payram_ops_playbook 开头，随后是 scaffold_payram_app 和 generate_* 代码片段工具。然后尝试："plan a PayRam install on pay.example.com"、"check https://pay.example.com"、"generate a FastAPI create-payment route"、"give me a Next.js webhook handler"。

提示词： setup-payram、setup-payram-agent、integrate-payment、troubleshoot-payment、daily-ops。 资源： payram://docs/setup-guide、payram://docs/api-reference，以及模板 payram://ops/playbook/{task} 和 payram://runbooks/{task}。

Copilot 自动化提示词

将以下内容粘贴到新工作区一次，即可让 "test payram" 自动运行完整的就绪流程：

You have access to the `payram` MCP server in this workspace.

Whenever I ask you to "test my Payram connection" (or I type "test payram"), follow this order:

1. Call `prepare_payram_test` (no inputs) and share the checklist verbatim.
2. Look for a `.env` in the workspace root; create one if missing.
3. Ensure `.env` defines `PAYRAM_BASE_URL` and `PAYRAM_API_KEY`. If either is
   missing, call `generate_env_template` and append it (with TODOs) to `.env`.
   Do NOT call `test_payram_connection` until real values are provided.
4. Once real values exist, call `test_payram_connection` with baseUrl/apiKey
   from `.env`, show the structured result, and explain whether the
   connection is healthy. If anything fails, run `payram_doctor` and follow
   its ranked fixes.

本地模式

在你自己的 PayRam 旁边运行 MCP，以获取实时数据工具：

list_platforms、search_payments、lookup_payment、get_payment_summary、get_daily_volume、get_unswept_balances、list_currencies、list_recipients
create_payment_link、check_payment_readiness、check_node_sync、restart_payram_worker
assess_payram_project

PAYRAM_MCP_MODE=local yarn dev        # or: yarn build && PAYRAM_MCP_MODE=local yarn start

模式： PAYRAM_MCP_MODE=local 选择本地模式。当服务器未在 Vercel 上运行时，这也是默认模式。PAYRAM_MCP_MODE=hosted 从不读取凭据。
绑定： 本地模式默认绑定到 127.0.0.1（端口 PORT，默认 3333）。
非回环绑定： 设置 HOST（例如 HOST=0.0.0.0），然后：
- 设置 MCP_ALLOWED_HOSTS（在 Host 请求头中接受逗号分隔的主机名）。
- 设置 MCP_SERVER_TOKEN；客户端随后发送 Authorization: Bearer <token>。
- 如果设置了 PAYRAM_* 凭据，服务器在未设置 MCP_SERVER_TOKEN 的情况下拒绝在非回环 HOST 上启动。建议优先使用回环加 SSH 隧道。
凭据： 数据工具从环境变量（或 .env）读取 PAYRAM_*：
- PAYRAM_BASE_URL
- PAYRAM_API_KEY（支付链接）
- PAYRAM_ACCESS_TOKEN / PAYRAM_REFRESH_TOKEN（JWT，数据工具）
- PAYRAM_EXTERNAL_PLATFORM_ID（可选默认项目）

本地服务器的客户端配置示例（仅本地模式）：

{
  "mcpServers": {
    "payram-local": { "url": "http://localhost:3333/mcp" }
  }
}

凭据：哪个密钥用于什么

PayRam 有两种凭据——当代理混淆它们时会卡住：

凭据	外观	用途	代理如何获取（无需仪表盘）
商户 API 密钥（`PAYRAM_API_KEY`，请求头 `API-Key`）	每个项目的密钥	`POST /api/v1/payment`（支付链接）、商户付款、所有商户服务器到服务器调用，并为 Webhook 签名（`X-Payram-Signature`）	`bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) ensure-api-key` — 通过 `POST /api/v1/external-platform/{id}/api-key` 重用或生成项目密钥，并保存到 `~/.payraminfo/merchant-api-key.env`
JWT（`Authorization: Bearer`）	登录时获得的访问+刷新令牌	管理/设置 API（项目、钱包、分析）— `payram_ops_playbook` 配方和本地模式数据工具	`bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) signin`（环境变量 `PAYRAM_EMAIL`/`PAYRAM_PASSWORD`）；保存到 `~/.payraminfo/headless-tokens.env`

一步设置流程（bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet）自动生成两者，并打印它们的存储位置。API 与仪表盘同源，位于端口 80/443（https://<your-domain>/api/v1/...，或服务器上的 http://localhost，绝不是 :8080）。API 密钥可以创建付款，因此请将其保存在服务器端，切勿放入浏览器代码或聊天中。使用 payram_ops_playbook 任务 connect 为直接 API 调用设置两者。

工具目录

类别	工具	用途
从这里开始 – 安装	`payram_setup_plan`	个性化、有序的安装计划（准备 → 安装 → 认领根账户 + 站点 URL → 钱包 + Smart Bridge → API 密钥 + 首个链接 → 加固 → 集成），包含代理与人工步骤及硬性停止点。
从这里开始 – 诊断	`payram_doctor`, `payram_troubleshoot`	`payram_doctor`：公开、无需凭据的分阶段 URL 检查（可达性 → 健康 → TLS → 版本 → 工作进程），附有排序后的可能原因 + 精确修复。可选的 API 密钥有效性检查，不创建任何内容。任何故障时首先运行此项。`payram_troubleshoot`：将症状或粘贴的错误匹配到已知原因和修复。
从这里开始 – 管理	`payram_runbook`	带人工门控的分步管理任务：`set_site_url`, `change_domain`, `ssl_setup`, `ssl_renewal_fix`, `firewall_ports`, `upgrade`, `backup`, `restore`, `add_chain`, `smart_bridge`, `mainnet_cutover`, `operator_setup`, `rotate_api_key`, `reset_test_install`, `shopify_connector`, `woocommerce_plugin`, `secure_analytics_mcp`.
从这里开始 – 运维	`payram_ops_playbook`	代理自行运行的直接 API 配方：`connect`, `health`, `version_check`, `workers`, `restart_worker`, `node_sync`, `site_url`, `payment_options`, `unswept_funds`, `payments_today`, `payment_lookup`, `stuck_payment`, `create_payment_link`, `payouts`, `webhooks`, `logs`, `daily_check`.
连接性	`test_payram_connection`	只读可达性/健康检查，外加可选的 API 密钥验证。绝不创建支付。
设置	`generate_env_template`, `generate_setup_checklist`, `suggest_file_structure`, `get_agent_setup_flow`, `onboard_agent_setup`	提供环境变量样板、商户检查清单、推荐的项目布局，以及无头代理入门指南。
上下文 / 文档	`explain_payram_basics`, `explain_payram_concepts`, `explain_payment_flow`, `explain_payram_security`, `get_payram_links`, `prepare_payram_test`, `get_payram_doc_by_id`, `list_payram_docs`, 等。	提供源自 `docs/` 的内联 Markdown 知识，使 Copilot 能够回答概念性问题。部分工具会自动附加“请说 `test payram`”提醒。
集成 – 支付	`generate_payment_sdk_snippet`, `generate_payment_http_snippet`, `generate_payment_status_snippet`, `generate_payment_route_snippet`	为创建 + 状态流程生成 SDK、原始 HTTP 或 Express/Next.js 路由代码。
集成 – 付款	`generate_payout_sdk_snippet`, `generate_payout_recipient_flow_snippet`, `generate_payout_status_snippet`	直接（无 OTP）付款、三步已保存收款人流程（创建收款人 → 验证 OTP → 付款），以及状态轮询。
集成 – 推荐	`generate_referral_sdk_snippet`, `generate_referral_validation_snippet`, `generate_referral_status_snippet`, `generate_referral_route_snippet`	涵盖推荐认证、关联、验证、状态，以及 express/next 路由。
集成 – Webhooks	`generate_webhook_handler`, `generate_webhook_event_router`, `generate_mock_webhook_event`	为 Express/Next/FastAPI/Gin/Laravel/Spring Boot 生成处理器、扇出路由器，以及 cURL/Python/Go/PHP/Java webhook 测试器。
集成 – 多语言支付	`snippet_*` 系列（`snippet_express_payment_route`, `snippet_nextjs_payment_route`, `snippet_fastapi_payment_route`, `snippet_laravel_payment_route`, `snippet_go_payment_handler`, `snippet_spring_payment_controller`）	为 Express、Next.js App Router、FastAPI、Gin、Laravel 和 Spring Boot 预构建的路由处理器。
集成 – 钱包充值	`generate_topup_integration_snippet`	适用于现有应用：账本模式 + 累计信用 webhook + 原子发票结算，使超额/不足/延迟/重复的加密货币支付变为余额状态而非支付异常。与 `payram-topup-wallet-integration` 技能配合使用。
集成 – 项目评估（本地模式）	`assess_payram_project`	扫描 `package.json`, `requirements.txt`, `composer.json`, `go.mod`, `pom.xml`, `.env`, 等。报告检测到的框架、环境状态、PayRam 依赖项，以及带工具建议的优先下一步。
脚手架	`scaffold_payram_app`	生成完整的入门应用（Express、Next.js、FastAPI、Laravel、Gin、Spring Boot），包含支付、付款、webhooks 和浏览器控制台。部署前请将付款端点置于您自己的管理员认证之后。
实时数据（只读，本地模式）	`list_platforms`, `search_payments`, `lookup_payment`, `get_payment_summary`, `get_daily_volume`, `get_unswept_balances`, `list_currencies`, `list_recipients`	查询实时 PayRam 数据。`list_currencies` 是公开的（无需密钥）；其余使用 `.env` 中的 JWT 令牌。`list_recipients` 与付款收款人流程配合使用。
实时运维（本地模式）	`create_payment_link`（写入），`check_payment_readiness`, `check_node_sync`, `restart_payram_worker`（写入）	`create_payment_link` 通过 `API-Key` 创建真实的结账链接。`check_payment_readiness` 报告各链的缺口（缺失钱包 / 货币 / 监听器）以接受支付。`check_node_sync` 报告监听器工作进程 + RPC 节点健康及区块陈旧度。在托管服务器上，使用匹配的 `payram_ops_playbook` 任务。

工具注册位于 src/tools/index.ts；各实现位于 src/tools/**，语言特定模板位于 templates/ 文件夹下。

引导式工作流

0. 安装 PayRam

询问：“在 pay.example.com 上设置 PayRam”（或使用 setup-payram / setup-payram-agent 提示）。
助手调用 payram_setup_plan 并逐步执行各阶段，在每个人工步骤（根账户、站点 URL、冷钱包、主网 gas）处停止。
最后以 payram_doctor、备份（payram_runbook backup）和每日检查（payram_ops_playbook daily_check）结束。

1. 评估并改造现有项目

询问 Copilot：“你能将 PayRam 集成到这个项目中吗？”
助手运行 assess_payram_project（本地模式），检查依赖清单和 .env。
按照推荐步骤操作（安装 payram，请求 Express/FastAPI/Spring 路由片段，添加 webhooks 等）。
在凭据真实后使用 test_payram_connection，以确保后端能够访问你的自托管服务器。

2. 搭建全新示例项目

“创建一个 PayRam Express 演示项目”→ scaffold_payram_app 构建一个包含支付、付款、webhooks 和 UI 控制台的 Express 项目。
将生成的文件放入一个空仓库，或与现有目录进行对比，以参考接线方式。

3. 运行“测试 PayRam”就绪流程

说“test payram”。助手会自动：
- 调用 prepare_payram_test 分享就绪检查清单。
- 使用 generate_env_template 确保 .env 存在（如果缺失则创建）。
- 在调用 test_payram_connection 之前等待真实凭据。
查看结构化的 JSON 结果，确认 PayRam API 可访问。

4. 接入支付、付款、推荐和 Webhooks

支付：generate_payment_sdk_snippet（JS SDK）或 generate_payment_http_snippet（Python/Go/PHP/Java）。
多语言路由：snippet_nextjs_payment_route、snippet_fastapi_payment_route 等。
付款：generate_payout_sdk_snippet 用于创建 + generate_payout_status_snippet 用于轮询。
推荐：generate_referral_route_snippet、generate_referral_validation_snippet。
Webhooks：generate_webhook_handler 加上 generate_webhook_event_router 用于扇出 + generate_mock_webhook_event 用于测试每种状态。

开发

命令	描述
`yarn dev`	通过 `tsx` 以热重载方式运行 MCP 服务器。
`yarn build`	将 TypeScript 编译到 `dist/`。
`yarn lint` / `yarn format`	在整个仓库中运行 ESLint + Prettier。
`yarn test`	执行 Vitest 测试套件（`tests/`）。
`make precommit-test`	依次运行 format → lint → test → build。

项目以 TypeScript 优先（ESM）。Prettier 配置位于 .prettierrc.json；ESLint 通过 eslint.config.mjs 配置。顺畅的贡献流程遵循 Makefile → make commit 中的提交辅助工具。

故障排查

从 payram_doctor 开始 — 一次只读调用，依次检查可达性 → 健康状态 → TLS → 版本 → 工作进程，并返回带有精确修复方法的排序原因。如需更深入的检查，请遵循 payram_ops_playbook（stuck_payment、node_sync、webhooks、logs）。

Copilot 没有调用正确的工具： 检查 Copilot 自动化提示已安装，并且你的 MCP 客户端已加载服务器。重新运行“test payram”或“assess my project”以触发预期的自动化。
test_payram_connection 返回 401： 确认该密钥是有效的项目 API 密钥（作为 API-Key 请求头发送，而不是 Authorization）。
数据工具提示凭据不可用： 托管服务器从不保存商户凭据。使用匹配的 payram_ops_playbook 任务，或在本地模式下运行 MCP。
支付链接显示 http://localhost： 用户必须从公共域名保存设置 → 站点 URL（payram_runbook 任务 set_site_url）。
文档工具提示文件缺失： 验证你的本地 docs/payram-docs-live/ 目录树包含所请求的 markdown 文件（get_payram_doc_by_id 拒绝包含 .. 的路径）。
服务器无法启动： 确保 Node 20+ 并运行 yarn install。在本地模式下，如果设置了非回环 HOST 和 PAYRAM_* 凭据，服务器将拒绝启动，直到设置 MCP_SERVER_TOKEN（参见本地模式）。

对于其他问题，请检查从 src/utils/logger.ts 发出的结构化日志（设置 LOG_LEVEL=debug），并附带复现细节提交 issue/PR。