PayPal Java MCP Server

PayPal Java MCP サーバー

これは、決済処理の分析と改善に役立つツールを提供する、PayPal MCP（Merchant Capability Platform）サーバーの Java 実装です。

機能

• Web クライアント向けの HTTP API を介した JSON-RPC
• Smithery との統合向けの stdio インターフェースを介した JSON-RPC
• オーソリ率を分析するツール
• テスト用の基本的な計算機能

サーバーの実行

Web モード（デフォルト）

ポート 8080 で REST API を公開する Web モードでサーバーを実行するには、次のようにします。

java -jar target/paypal-java-mcp-server-0.0.1-SNAPSHOT.jar

このモードでは、http://localhost:8080/api/mcp で API にアクセスできます。

stdio モードでの JSON-RPC

標準入力／出力を介して JSON-RPC を使用する stdio モードでサーバーを実行するには、次のようにします。

java -Dspring.profiles.active=stdio -Dspring.main.web-application-type=NONE -Djsonrpc.stdio.interactive=true -jar target/paypal-java-mcp-server-0.0.1-SNAPSHOT-stdio.jar

このモードでは、サーバーは stdin から JSON-RPC リクエストを読み取り、stdout にレスポンスを書き込みます。すべてのログは stderr とログファイルに書き込まれます。

重要：JSON-RPC stdio インターフェースでは、stdin/stdout への接続が必要です。デプロイ時には、通常はインタラクティブモードで実行するなど、プロセスが stdin/stdout にアクセスできることを確認してください。

付属のテストスクリプトを使用して、stdio モードをテストできます。

./test-stdio.sh

非インタラクティブ環境での実行

stdin/stdout に接続できない非インタラクティブ環境でサーバーを実行する必要がある場合は、付属の start-non-interactive.sh スクリプトを使用できます。

./start-non-interactive.sh

このスクリプトは次の処理を行います。

1. 名前付きパイプを作成して stdin と stdout に接続します
2. パイプを処理するバックグラウンドプロセスを起動します
3. -Djsonrpc.stdio.interactive=false フラグを指定してサーバーを起動します
4. サーバーに初期化リクエストを自動送信します
5. サーバーと通信するためのパイプのパスを提示します

サーバーはすべての機能とツールを事前に初期化するため、最初の入力がなくてもリクエストに応答できます。その後、入力パイプに書き込み、出力パイプから読み取ることで、サーバーと通信できます。

# Send a request
echo '{"jsonrpc":"2.0","method":"getTools","id":"1"}' > /path/to/input_pipe

# Read responses
cat /path/to/output_pipe

Docker での実行

Docker コンテナでサーバーを実行する際は、stdin への接続を確保するため、必ず -i フラグを使用してください。

docker run -i paypal-mcp-jsonrpc

付属の run-docker.sh スクリプトを使用すると、この処理が行われます。

./run-docker.sh

JSON-RPC プロトコル

サーバーは次の JSON-RPC メソッドに対応しています。

initialize

サーバーを初期化し、その機能を返します。

{"jsonrpc":"2.0","method":"initialize","id":"1"}

getTools

利用可能なツールの一覧を返します。

{"jsonrpc":"2.0","method":"getTools","id":"2"}

executeFunction

指定された引数で関数を実行します。

{"jsonrpc":"2.0","method":"executeFunction","params":{"function":"calculate","arguments":{"operation":"add","a":5,"b":3}},"id":"3"}

Smithery へのデプロイ

このサーバーは、stdio インターフェースを介した JSON-RPC を必要とする Smithery へのデプロイを想定して設計されています。

Smithery へのデプロイに向けてサーバーを準備するには、次のようにします。

./prepare-smithery.sh

これにより、デプロイに必要なすべてのファイルを含む smithery-deploy ディレクトリが作成されます。内容は次のとおりです。

• サーバーの JAR ファイル
• Smithery 設定ファイル
• インタラクティブモードと非インタラクティブモードで実行するためのスクリプト
• デプロイ手順を記載した README

Smithery の設定

サーバーには、Smithery 向けにサーバーを設定する smithery-config.json ファイルが含まれています。

{
  "name": "paypal-java-mcp-server",
  "type": "stdio",
  "interactive": true,
  "command": "java",
  "args": [
    "-Dspring.profiles.active=stdio",
    "-Dspring.main.web-application-type=NONE",
    "-DLOG_FILE=/logs/mcp-server.log",
    "-Dlogging.config=classpath:logback-stdio.xml",
    "-Djsonrpc.stdio.interactive=true",
    "-jar",
    "/app/app.jar"
  ]
}

重要：Smithery でサーバーを使用する場合は、次の点を確認してください。

1. Smithery の設定で "interactive": true フラグが設定されていること
2. 起動コマンドに -Djsonrpc.stdio.interactive=true 引数が含まれていること
3. stdio インターフェースを介した JSON-RPC を使用し、HTTP 経由でサーバーに接続しようとしていないこと
4. 環境がインタラクティブプロセスに対応していない場合は、代わりに start-non-interactive.sh スクリプトを使用すること

非インタラクティブ環境へのデプロイ

Smithery 環境がインタラクティブプロセスに対応していない場合は、次の 2 つの方法があります。

1. start-non-interactive.sh スクリプトを使用する：このスクリプトは名前付きパイプを作成し、stdin/stdout への接続を処理します。

2. Smithery の設定を変更する：Smithery の設定で "interactive": false を設定し、-Djsonrpc.stdio.interactive=false フラグを指定してサーバーが起動されるようにします。

前提条件

• Java 17 以降
• Maven 3.6 以降

はじめに

設定

application.properties でアプリケーションを設定します。

# Server configuration
server.port=8080

# Logging
logging.level.com.example.mcpserver=DEBUG

ビルドと実行

アプリケーションをビルドします。

mvn clean package

API の使用方法

REST API

ヘルスチェック

curl http://localhost:8080/api/v1/health

補完エンドポイント

curl -X POST http://localhost:8080/api/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How can I improve my authorization rate?",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful PayPal assistant."
      },
      {
        "role": "user",
        "content": "I need to improve my authorization rate. My merchant ID is MERCH123."
      }
    ],
    "context": {
      "merchantId": "MERCH123"
    }
  }'

オーソリ率改善ツール

curl -X POST http://localhost:8080/api/v1/tools/improveAuthorizationRate/execute \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "MERCH123",
    "timeframe": "last_30_days",
    "transactionType": "card"
  }'

計算ツール

curl -X POST http://localhost:8080/api/v1/tools/calculate/execute \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "multiply",
    "a": 6,
    "b": 7
  }'

stdio 経由の JSON-RPC

stdio 経由の JSON-RPC インターフェースは、stdin で JSON-RPC 2.0 リクエストを受け取り、stdout にレスポンスを書き込みます。各リクエストとレスポンスは、それぞれ 1 行の JSON です。

補完リクエスト

{"jsonrpc":"2.0","method":"completions","params":{"query":"How can I improve my authorization rate?","messages":[{"role":"system","content":"You are a helpful PayPal assistant."},{"role":"user","content":"I need to improve my authorization rate. My merchant ID is MERCH123."}],"context":{"merchantId":"MERCH123"}},"id":"1"}

関数実行リクエスト

{"jsonrpc":"2.0","method":"executeFunction","params":{"function":"improveAuthorizationRate","arguments":{"merchantId":"MERCH123","timeframe":"last_30_days","transactionType":"card"}},"id":"2"}

{"jsonrpc":"2.0","method":"executeFunction","params":{"function":"calculate","arguments":{"operation":"multiply","a":6,"b":7}},"id":"3"}

レスポンス形式

REST API レスポンス

{
  "content": "Based on the analysis of your authorization rates, here are the recommendations:

Current Authorization Rate: 85.3%
Current Decline Rate: 14.7%
Total Transactions: 12500

Top Decline Reasons:
- insufficient funds: 42.5%
- risk triggers: 23.8%
- expired card: 12.3%
- invalid data: 10.7%
- other: 10.7%

Recommendations to Improve Authorization Rate:
1. Implement Account Updater (Priority: high, Est. Impact: +3.5%)
   Use PayPal's Account Updater service to automatically update expired or replaced cards

2. Optimize AVS Settings (Priority: medium, Est. Impact: +2.1%)
   Adjust Address Verification Service settings to reduce false declines

3. Implement Intelligent Retry Logic (Priority: high, Est. Impact: +4.2%)
   Add smart retry logic for declined transactions with specific reason codes

4. Review Risk Rules (Priority: medium, Est. Impact: +2.8%)
   Analyze and adjust risk rules to reduce false positives",
  "toolCalls": [
    {
      "id": "12345-67890",
      "type": "function",
      "function": {
        "name": "improveAuthorizationRate",
        "arguments": "{\"merchantId\":\"MERCH123\",\"timeframe\":\"last_30_days\",\"transactionType\":\"all\"}"
      }
    }
  ],
  "metadata": {
    "merchantId": "MERCH123",
    "timeframe": "last_30_days"
  }
}

JSON-RPC レスポンス

{"jsonrpc":"2.0","result":{"content":"Based on the analysis of your authorization rates, here are the recommendations:\n\nCurrent Authorization Rate: 85.3%\nCurrent Decline Rate: 14.7%\nTotal Transactions: 12500\n\nTop Decline Reasons:\n- insufficient funds: 42.5%\n- risk triggers: 23.8%\n- expired card: 12.3%\n- invalid data: 10.7%\n- other: 10.7%\n\nRecommendations to Improve Authorization Rate:\n1. Implement Account Updater (Priority: high, Est. Impact: +3.5%)\n   Use PayPal's Account Updater service to automatically update expired or replaced cards\n\n2. Optimize AVS Settings (Priority: medium, Est. Impact: +2.1%)\n   Adjust Address Verification Service settings to reduce false declines\n\n3. Implement Intelligent Retry Logic (Priority: high, Est. Impact: +4.2%)\n   Add smart retry logic for declined transactions with specific reason codes\n\n4. Review Risk Rules (Priority: medium, Est. Impact: +2.8%)\n   Analyze and adjust risk rules to reduce false positives","toolCalls":[{"id":"12345-67890","type":"function","function":{"name":"improveAuthorizationRate","arguments":"{\"merchantId\":\"MERCH123\",\"timeframe\":\"last_30_days\",\"transactionType\":\"all\"}"}}],"metadata":{"merchantId":"MERCH123","timeframe":"last_30_days"}},"id":"1"}

利用可能なツール

オーソリ率改善ツール

このツールは取引データを分析し、オーソリ率を改善するための推奨事項を提示します。

パラメーター：

• merchantId（必須）：分析する加盟店 ID
• timeframe（任意）：分析対象期間（デフォルト："last_30_days"）
• transactionType（任意）：取引タイプのフィルター（デフォルト："all"）

計算ツール

このツールは基本的な数学演算を実行します。

パラメーター：

• operation（必須）：実行する演算（add、subtract、multiply、divide）
• a（必須）：第 1 オペランド
• b（必須）：第 2 オペランド

Docker でのデプロイ

このプロジェクトでは、REST API サーバーと JSON-RPC stdio サーバーの両方で Docker を利用できます。

Docker イメージのビルド

Docker Compose を使用して両方のイメージをビルド

docker-compose build

REST API サーバーのイメージのみをビルド

docker build --target rest-api -t paypal-mcp-rest-api .

JSON-RPC サーバーのイメージのみをビルド

docker build -f Dockerfile.smithery -t paypal-mcp-jsonrpc .

Docker で実行

REST API サーバーを実行

docker run -p 8080:8080 paypal-mcp-rest-api

JSON-RPC サーバーを実行

JSON-RPC サーバーは stdin から読み取り、stdout に書き込むため、インタラクティブモードで実行する必要があります。

docker run -i paypal-mcp-jsonrpc

または、付属のスクリプトを使用します。

./run-docker.sh

Docker Compose を使用

REST API サーバーを起動します。

docker-compose up rest-api

注：JSON-RPC stdio サーバーは stdin/stdout とのやり取りが必要なため、通常は docker-compose で直接実行しません。

トラブルシューティング

よくある問題

「サーバーのツール一覧にアクセスできません」

ネットワーク接続経由でサーバーのツール一覧にアクセスできないというエラーが表示される場合、次の原因が考えられます。

1. stdio モードで動作しているサーバーに HTTP 経由でアクセスしようとしている
2. サーバーがインタラクティブモードで動作していないため、入力を受け取ったり出力を送信したりできない
3. 起動コマンドに -Djsonrpc.stdio.interactive=true フラグが指定されていない

解決策：

• stdio 経由の JSON-RPC インターフェースを使用していることを確認します
• Docker を使用している場合は、-i フラグを指定してサーバーを実行します
• 起動コマンドに -Djsonrpc.stdio.interactive=true フラグを追加します
• 非インタラクティブ環境で実行する場合は、start-non-interactive.sh スクリプトを使用します

「非インタラクティブ環境でサーバーの初期化に失敗する」

非インタラクティブ環境でサーバーの初期化に失敗する場合：

1. 非インタラクティブ環境向けに設計された start-non-interactive.sh スクリプトを使用します
2. -Djsonrpc.stdio.interactive=false フラグを指定してサーバーを実行します
3. 名前付きパイプが正しく設定され、アクセス可能であることを確認します

解決策：

./start-non-interactive.sh

「サーバーから応答がありません」

サーバーがリクエストに応答しない場合：

1. サーバーが正しいモードで動作していることを確認します
2. stdin/stdout が正しく接続されていることを確認します
3. ログにエラーがないか確認します

解決策：

• test-stdio.sh スクリプトでサーバーを実行し、正しく動作することを確認します
• start-non-interactive.sh スクリプトを使用し、名前付きパイプを確認します
• ログファイルにエラーがないか確認します

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細については LICENSE ファイルを参照してください。