ShaBaas Pay MCP Server

ShaBaas AI

本仓库是一站式平台，可用于在 ShaBaasPay 之上构建 AI 驱动的产品和工作流。

其中包含用于将 ShaBaasPay 与大模型及 Agent 框架连接的 SDK 和集成资源，包括：

• @shabaaspay/agent-toolkit - 通过函数调用将 ShaBaasPay API 与热门 Agent 框架集成（TypeScript）。
• API 资源：openapi/ 下的 MCP 契约，以及 restapi/ 下供 ReadMe 使用的公开 REST 规范。

在自助式暂存环境中开始使用

1. 使用电子邮件和密码、Google 或 GitHub创建账户。账户将进入暂存仪表板。
2. 如需试用仪表板，请选择 创建发票，填写详细信息并分享生成的付款页面链接。可选的电子邮件流程会将链接发送给客户。
3. 如需试用 API，请在仪表板中创建 API 密钥，并将其兑换为 bearer token。请将密钥和 token 保存在服务器端。

# Set SHABAAS_API_KEY securely in your shell first.
curl -X POST 'https://dev-api.shabaas.com/api/public/authorization' \
  -H "Authorization: ${SHABAAS_API_KEY}"

请按照 REST OpenAPI 规范和 API 参考，使用生成的 bearer token 调用受支持的端点。API 响应不能证明付款已结算。生产环境访问需要完成接入流程，并获得针对预期用例的批准。

实现参考：付款发起状态 · PayTo 付款错误 · PayTo 协议错误 · webhook 通知示例。

Model Context Protocol (MCP)

ShaBaasPay 支持面向 Agent 客户端的 MCP 集成。

远程 MCP 端点：

• 暂存环境（沙盒评估）：https://mcp-staging.shabaas.com/mcp
• 生产环境（需批准访问）：https://mcp.shabaas.com/mcp

有关客户端设置和当前公布的托管工具列表，请参阅 MCP 连接指南。本地工具包、OpenAPI 契约和已部署的端点可能提供不同的工具清单；请核对当前环境和所用凭据对应的工具列表。

本地工具包和 MCP 示例见下文及 tools/typescript/packages/agent-toolkit/README.md。

Agent 工具包

ShaBaasPay 的 Agent 工具包支持 LangChain 和 Vercel 的 AI SDK 等框架通过函数调用工具调用 ShaBaasPay API。

安装

除非要修改此软件包，否则无需获取此源代码。如果只想使用该软件包，请运行：

npm install @shabaaspay/agent-toolkit

要求

• Node 22+

用法

该库需要配置账户的 API 密钥，可在 ShaBaas Developer Dashboard 中获取。我们强烈建议使用受限 API 密钥，以提高安全性并细化权限。工具是否可用取决于为该密钥配置的权限。

import { ShabaasAgentToolkit } from '@shabaaspay/agent-toolkit';

const toolkit = new ShabaasAgentToolkit({
  apiKey: process.env.SHABAAS_API_KEY!,
  environment: 'sandbox'
});

工具

该工具包适用于 LangChain 和 Vercel 的 AI SDK，可作为工具列表或映射传入。

const tools = toolkit.getTools();
const getAuthTokenTool = tools.find((t) => t.name === 'get_auth_token');

const result = await getAuthTokenTool?.execute({
  include_token_in_response: false
});

上下文

在某些情况下，你可能希望为多次调用设置共享默认值。目前，该工具包支持通过工具包初始化来设置环境级默认值。

const toolkit = new ShabaasAgentToolkit({
  apiKey: process.env.SHABAAS_API_KEY!,
  environment: 'sandbox'
});

LangChain

import { ShabaasAgentToolkitLangChain } from '@shabaaspay/agent-toolkit/langchain';

const toolkit = new ShabaasAgentToolkitLangChain({
  apiKey: process.env.SHABAAS_API_KEY!,
  environment: 'sandbox'
});

const tools = await toolkit.getLangChainTools();

Vercel AI SDK

import { ShabaasAgentToolkitAiSdk } from '@shabaaspay/agent-toolkit/ai-sdk';
import { generateText } from 'ai';

const toolkit = new ShabaasAgentToolkitAiSdk({
  apiKey: process.env.SHABAAS_API_KEY!,
  environment: 'sandbox'
});

const tools = await toolkit.getAiSdkTools();

const response = await generateText({
  model: yourModel,
  tools,
  prompt: 'Retrieve details for payment agreement pa_123'
});

Model Context Protocol (工具包)

import { StdioMcpServer, HttpMcpServer } from '@shabaaspay/agent-toolkit/modelcontextprotocol';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new StdioMcpServer({
  apiKey: process.env.SHABAAS_API_KEY!,
  environment: 'sandbox'
});

await server.connect(new StdioServerTransport());

故障排除

• Missing SHABAAS_API_KEY：运行示例前，请先设置 API 密钥。
  • export SHABAAS_API_KEY=your_key
• LangChain adapter requires @langchain/core：
  • npm install @langchain/core
• AI SDK adapter requires the "ai" package：
  • npm install ai
• 本地开发时出现 Cannot find module '@shabaaspay/agent-toolkit/*'：
  • 在 tools/typescript 目录下运行 npm install 和 npm run build。

快速开始（仓库）

cd tools/typescript
npm install
npm run build

OpenAPI

• OpenAPI
• MCP 契约映射了八项操作：授权；创建、获取和修改 PayTo 协议；创建和获取支付发起；直接借记发起；以及发票生成。已发布的连接指南可能会列出其他托管工具。将任何工具描述为受支持工具之前，请确认其已部署并可用。

REST API

• RestAPI
• 涵盖身份验证、协议、发起、Webhook、PayID 收款和发票端点的 REST OpenAPI 规范。