ShaBaas Pay MCP Server

ShaBaas AI

このリポジトリは、ShaBaasPay を基盤に AI を活用した製品やワークフローを構築するためのワンストップショップです。

LLM やエージェントフレームワークと ShaBaasPay を連携するための SDK と統合用アセットが含まれています。対象は次のとおりです。

• @shabaaspay/agent-toolkit - 関数呼び出しを通じて、ShaBaasPay API を一般的なエージェントフレームワークと連携するためのツール（TypeScript）。
• API アーティファクト：openapi/ にある MCP コントラクト、restapi/ にある ReadMe 用の公開 REST 仕様。

セルフサービスのステージング環境を始める

1. メールアドレスとパスワード、Google または GitHub を使用してアカウントを作成します。アカウントを作成すると、ステージングダッシュボードが開きます。
2. ダッシュボードを試すには、Create Invoice を選択し、詳細を入力して、生成された決済ページのリンクを共有します。任意のメール送信フローを使用すると、顧客にリンクが送信されます。
3. API を試すには、ダッシュボードで API キーを作成し、ベアラートークンと交換します。キーとトークンはサーバー側で保管してください。

# 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 リファレンスに従って、対応するエンドポイントで使用してください。API の応答は、決済が精算されたことの証明にはなりません。本番環境へのアクセスには、利用目的に応じたオンボーディングと承認が必要です。

実装リファレンス：決済開始ステータス · PayTo 決済エラー · PayTo 契約エラー · Webhook 通知の例。

Model Context Protocol（MCP）

ShaBaasPay は、エージェントクライアント向けの MCP 連携に対応しています。

リモート MCP エンドポイント：

• ステージング（サンドボックスでの評価）：https://mcp-staging.shabaas.com/mcp
• 本番環境（承認済みのアクセス）：https://mcp.shabaas.com/mcp

クライアントのセットアップ方法と、現在公開されているホスト型ツールの一覧については、MCP 接続ガイドをご覧ください。ローカルツールキット、OpenAPI コントラクト、デプロイ済みエンドポイントで公開されるツールの一覧は異なる場合があります。使用する環境と認証情報に応じたツール一覧を確認してください。

ローカルツールキットと MCP の例は、以下と tools/typescript/packages/agent-toolkit/README.md で確認できます。

エージェントツールキット

ShaBaasPay のエージェントツールキットを使うと、LangChain や Vercel の AI SDK などのフレームワークから、関数呼び出しツールを通じて ShaBaasPay API を呼び出せます。

インストール

パッケージを変更する予定がない場合、このソースコードは必要ありません。パッケージを利用するだけの場合は、次を実行してください。

npm install @shabaaspay/agent-toolkit

要件

• Node 22+

使い方

このライブラリを使用するには、ShaBaas Developer Dashboard で確認できるアカウントの API キーを設定する必要があります。セキュリティを高め、権限を細かく設定できるよう、制限付き 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 コントラクトでは、8 つの操作を対応付けています。認証、PayTo 契約の作成／取得／変更、支払い開始の作成／取得、口座振替の開始、請求書の生成です。公開されている接続ガイドには、ホスト型ツールがさらに記載されている場合があります。ツールがサポート対象であると説明する前に、デプロイ環境で利用可能か確認してください。

REST API

• RestAPI
• 認証、契約、支払い開始、Webhook、PayID コレクション、請求書エンドポイントの REST OpenAPI カバレッジが含まれています。