mcp-installation

ProAbono MCP 安装

一个本地 MCP 服务，可从 IDE 将 ProAbono 安装到你的网站中。

它会向你的编码助手提供 ProAbono 文档、API Live 合约以及 你自己的 ProAbono 配置，让它能够端到端地陪你完成站内安装，生成已填入真实业务标识符、Segment、优惠和 Features 的集成代码，读取你的账户以验证结果，并根据真实合约回答 API 问题，而不是凭空猜测。

它在本地通过 stdio 运行，使用你的凭据所能访问的账户。它没有自己的环境概念：你的凭据是唯一的边界。

安装

Claude Code

claude mcp add --transport stdio proabono --scope user -- npx -y @proabono/mcp-installation

VS Code

在 .vscode/mcp.json 中：

{
  "servers": {
    "proabono": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@proabono/mcp-installation"]
    }
  }
}

Cursor

在 .cursor/mcp.json 中（或在 ~/.cursor/mcp.json 中为每个项目配置）：

{
  "mcpServers": {
    "proabono": {
      "command": "npx",
      "args": ["-y", "@proabono/mcp-installation"]
    }
  }
}

需要 Node.js 20 或更高版本。

配置

该服务只读取七个环境变量，不读取其他内容。如果有任何变量缺失，它会拒绝启动，并指出所需的变量。

变量	内容
PROABONO_API_BASE	API 端点，https://api-{business_id}.proabono.com
PROABONO_BUSINESS_ID	你的数字业务标识符
PROABONO_SEGMENT_REF	你的客户和优惠所属的 Segment
PROABONO_AGENT_KEY	Basic auth 用户名
PROABONO_API_KEY	Basic auth 密码
PROABONO_PORTAL_SECRET	用于门户安全哈希的 HMAC 密钥
PROABONO_WEBHOOK_SECRET	用于通知签名的密钥

这七项都可以在 ProAbono BackOffice 的同一页面找到：集成 → MCP。PROABONO_API_BASE 必须以 https:// 开头，且 PROABONO_BUSINESS_ID 只能包含数字。

将它们放入 MCP 客户端配置项的 env 块中，并将文件设为 Git 忽略。 这样，每组七个变量都会关联到一个项目和一个 ProAbono 账户——当你有两组变量时，这一点尤其重要，因为沙盒和生产环境是两个拥有不同端点、标识符和密钥的账户。为每个账户声明一个配置项，例如 proabono-sandbox 和 proabono-production，并分别配置自己的 env。

• .vscode/mcp.json 和 .cursor/mcp.json 位于你的仓库中：在将值粘贴到文件前，先将它们加入 .gitignore。Cursor 也会读取位于所有仓库之外的 ~/.cursor/mcp.json。
• Claude Code：使用 --scope user 可将配置项放在仓库之外。项目中的 .mcp.json 通常会提交到仓库，因此应在其中写入 ${PROABONO_API_KEY} 和其他六个变量，而不是直接写入变量值——Claude Code 会从你的环境中展开它们。
• VS Code 还可以通过 mcp.json 的 inputs 部分提示输入变量值，从而避免将其写入文件。
• 避免使用 Shell 导出变量：每个 Shell 和每台机器只能保存一组变量，而且会将生产密钥提供给你打开的每个项目。
• 该服务不会读取 .env 文件，只读取其进程环境。

你提供的任何值都不会被记录、由工具返回、写入错误消息或内联到生成的代码中。生成的代码引用的是变量名。

第一个提示词

添加服务器并设置好七个变量后，打开项目并将以下内容粘贴到助手中：

Help me install ProAbono in this project.

1. Call get_server_info to confirm the server is reachable, and tell me which version you are talking to.
2. Call installation_status to see whether an installation was already started here.
3. Run install_insite: tell me which stack you detected and why, check the prerequisites with me, then take me through the three In-Site steps and the notification endpoint in order, placing the generated code where my signed-in user is known.
4. List what I still have to do by hand in the ProAbono BackOffice.
5. When the code is in place, run verify_insite_installation and walk me through the go-live checklist.

Answer every question about the ProAbono API from search_documentation and get_api_reference, never from memory.

成功运行时，步骤 1 会返回服务器版本，以及状态为 complete 的配置，其中列出七个变量名——绝不会显示任何变量值。如果完全没有 ProAbono 工具，说明服务器拒绝启动：有变量缺失，错误日志中会指出具体变量名，日志位于 MCP 客户端中。get_server_info 不会报告不完整的配置，因为服务器在这种情况下不会启动。

生成器会返回代码，不会编辑你的任何文件；由助手将代码放入文件。服务器写入的唯一文件是 .proabono/installation.json，即安装状态文件：其中不包含任何凭据；该文件旨在提交到版本控制中，以便后续会话从本次停止的位置继续；使用 record_state: false 调用工具时不会写入该文件。

请将密钥指向一个 Sandbox 账户来运行。verify_insite_installation 会确保它验证的客户存在——如果你没有指定客户，它会使用 mcp-verify- 引用创建一个；通常接下来会用到的工具——create_update_customer、create_subscription、Usage 写入工具、bill_customer——会在凭据所访问的账户中创建真实数据。

示例提示词

安装开始后，开发者接下来会提出这些问题。助手会选择工具；第二列列出了它通常会调用的工具。

你提出的问题	它通常会调用的工具
“我的 Segment 暴露了哪些优惠？它们包含哪些 Features？”	list_offers、list_features
“根据我的真实优惠，为此页面生成一个定价表，并确保已登录客户可以直接在页面中订阅。”	generate_pricing_table
“有人已经在这个项目中开始安装 ProAbono。安装进展如何？BackOffice 中还剩下哪些工作？”	installation_status
“将通知端点接入这个应用，并告诉我如何在 BackOffice 中启用它。”	scaffold_notification_endpoint
“为我规划门户的生命周期：升级、降级、催收。”	plan_integration
“创建一个客户，为其订阅我的第一个优惠，并显示其 Usages。”	create_update_customer、create_subscription、get_usages
“这个客户的座位数从 5 个增加到 10 个需要多少钱？是否允许这样做？”	quote_usage_change
“哪个端点可以列出客户的发票？它会返回什么？用 Go 写出调用代码。”	search_documentation、get_api_reference、generate_integration_code

当前涵盖的内容

你安装的版本见 CHANGELOG.md，get_server_info 会报告该版本：

• In-Site 的三个步骤，端到端涵盖：带安全哈希的 Customer Portal 嵌入、Subscription Workflow 往返流程，以及带缓存、门控和重新同步的 Usage 同步。
• 通知端点，包含签名验证、去重，以及用于激活它的 BackOffice 流程。
• 验证：针对你的账户执行步骤 2 和 3，根据你自己的文件检查上线规则，以及包含十二项的检查清单。
• 目录与账户信息查询：套餐、Features、客户、订阅、Usages、发票。
• 覆盖生命周期的写入操作：客户及其设置、账单地址、订阅及其四种状态转换、针对所有三种 Feature 类型的 Usage 写入、余额明细和账单。
• 文档与 API 参考：对 ProAbono 文档语料库和 API Live 合约进行自然语言搜索。

目前尚未涵盖、计划后续支持的内容：高级 In-Site 选项——托管页面的 CSS 自定义，以及更多特定工作流。

小组件和插件安装（WordPress 等）按设计不在范围内：无论你的技术栈适合什么，这个服务都通过代码安装 ProAbono In-Site。

套餐、Features、webhook、定价页面和工作流重定向 URL 都在你的 ProAbono BackOffice 中配置，API 无法创建它们：该服务会读取这些配置、指出缺少的内容，并提供对应的 BackOffice 操作路径。

工具

写入表示某个工具会更改你的凭据所能访问账户中的数据。助手一旦调用它就会立即运行，无需确认步骤：你的凭据是唯一的边界。

文档

工具	功能	写入
search_documentation	对 ProAbono 文档和 API Live 合约进行自然语言搜索。
get_api_reference	查询指定端点或对象的参数和架构。

安装

工具	功能	写入
install_insite	完整的 In-Site 安装，端到端涵盖：技术栈检测、前置条件门控、按顺序执行三个步骤，以及将进度记录到 .proabono/installation.json。
installation_status	查看安装进度：已完成的内容、生成内容及其位置、BackOffice 中待处理的事项，以及跳过的内容。
install_customer_portal	针对你的技术栈，嵌入带安全哈希的 In-Site 步骤 1。
link_subscription_workflow	步骤 2：从 Links 读取加密查询参数、两种打开工作流的方式，以及涵盖全部五种结果的单一返回路由。
sync_usage_rights	步骤 3 的权益模块：读取 Usage、缓存及其过期时间、门控、针对应用更改的 Feature 写回，以及重新同步。
scaffold_notification_endpoint	webhook 端点：签名验证、验证握手、去重、快速确认，以及用于激活它的 BackOffice 流程。
verify_insite_installation	针对你的账户执行步骤 2 和 3——在你指定的客户上执行（若不存在则创建），或在新客户上执行；根据你的文件检查上线规则，并提供包含十二项的检查清单。	是

代码生成

工具	功能	写入
generate_pricing_table	基于你的真实套餐生成定价表。
plan_integration	为某个流程生成有序计划：安装、订阅漏斗、门户生命周期、用量计量、通知。
generate_integration_code	根据合约和文档，使用你指定的语言为某项任务生成代码。

目录

工具	功能	写入
list_offers	列出你的 Segment 提供的套餐。
list_offers_for_customer	列出某位客户可以选择的套餐，以及当前订阅的升级选项。
get_offer	按引用获取单个套餐。
list_features	列出你的 Business 的功能。

客户

工具	功能	写入
get_customer	按引用获取客户。
create_update_customer	创建客户，或更新已有该引用的客户。一个工具即可：此端点执行插入或更新。	是
get_billing_address	获取开具发票时使用的地址。
update_billing_address	更新该地址，只更改你提供的字段。	是
get_payment_settings	一次读取付款类型、账单模式、灰名单标记、发票备注和下一次账单日期。
set_next_billing_date	设置客户下一次账单日期。	是
set_invoice_note	设置显示在该客户所有后续发票底部的备注。	是
set_payment_method	记录手动付款方式；Card 和 DirectDebit 由支付网关处理。	是
anonymize_customer	不可逆。 GDPR 擦除流程：擦除个人数据，并保留发票和订阅历史记录。如果客户有到期未付的发票，ProAbono 会拒绝执行，且不会擦除任何内容。	是

订阅

工具	功能	写入
get_subscription、list_subscriptions	查看客户订阅的内容。
create_subscription	为客户订阅一个套餐。	是
start_subscription	启动草稿订阅，或重新启动已暂停的订阅。	是
upgrade_subscription	将订阅转到另一个套餐。	是
suspend_subscription	暂停订阅；start_subscription 可撤销此操作。	是
terminate_subscription	终止订阅，默认在当前期限结束时生效。	是

用量和权益

工具	功能	写入
get_usages	获取 ProAbono 所见的客户当前用量。
quote_usage_change	在应用变更前为预期变更定价，并检查是否允许。
push_usage_increment	报告 Consumption 功能的消耗量。	是
push_usage_quantity	设置 Limitation 功能的已配置数量。	是
push_usage_enabling	切换 OnOff 功能。	是

开票和余额

工具	功能	写入
get_invoice	获取借项发票；如果发票已发布，则一并返回其 PDF URL。刚开具后立即读取发票时，PDF 可能尚未发布。
get_credit_note	获取贷项通知单，以及其 TypeCredit、原因和已发布时的 PDF URL。
list_invoices	一并列出客户的两种账单文件。
create_balance_line	创建借项；金额为负数时则创建贷项。	是
bill_customer	为余额中的所有项目开具发票。	是

服务端

工具	功能	写入
get_server_info	获取版本和配置状态，不包含具体值。

此服务端中的工具不会销毁账单历史记录：在任何账户中，删除客户、订阅或发票都不在支持范围内；ProAbono 提供的客户暂停、失效处理和撤销关联端点也不会开放，这是有意为之。anonymize_customer 是唯一无法撤销其影响的工具，但它并非销毁操作——它会擦除个人数据，并保留发票和订阅历史记录，这正是 GDPR 对账单系统擦除操作的要求。

故障排除

症状	原因	解决方法
ProAbono 工具未显示在助手中，且 MCP 客户端的日志提示缺少配置变量	服务拒绝启动：某个变量缺失或为空	在条目的 env 块中设置消息指出的所有变量，然后重启客户端
日志提示 PROABONO_API_BASE must be an https:// endpoint	端点不是以 https:// 开头	使用 https://api-{business_id}.proabono.com，并替换为你自己的业务标识符
日志提示 PROABONO_BUSINESS_ID must be the numeric business identifier	标识符中包含数字以外的内容	只保留数字：不加前缀、不加引号、不留空格
工具返回 ProAbono API error 401	Agent 密钥或 API 密钥有误	从 BackOffice 重新复制两者
工具返回 ProAbono API error 401，且两个密钥都正确	端点和密钥来自两个不同的账户	从同一个账户获取全部七个变量

从源代码构建

发布的软件包是自包含的：构建时会将 ProAbono API 合约和文档复制到 dist/resources/，因此运行时无需获取任何内容。

克隆仓库后，也可以用相同方式构建，无需凭据，也无需访问我们的任何资源：

npm ci && npm run build && npm test

构建所打包的两个源文件都位于此仓库的 resources/ 下：resources/open-api/ 中的 API Live 合约，以及 resources/docs/ 中的文档语料库。该合约是 ProAbono 内部维护版本的副本。当源文件可访问时，npm run build 和 npm test 会从该处刷新副本；不可访问时（CI 和此仓库的任何克隆都属于这种情况），则会使用已提交的副本，并在每次运行时说明使用了哪种方式。请参阅 resources/open-api/index.md。

支持

问题和疑问：[email protected]。

报告问题时，请附上 get_server_info 的输出——它会报告服务版本以及已配置的变量，但绝不会显示变量的值。

关于此服务的更多信息：

• ProAbono 文档
• API 参考
• 创建 ProAbono 账户

许可证

MIT。请参阅 LICENSE。