PayPal Java MCP Server

PayPal Java MCP 服务

这是一个用 Java 实现的 PayPal MCP（Merchant Capability Platform，商户能力平台）服务，提供用于分析和改进支付处理的工具。

功能

• 面向 Web 客户端的 HTTP JSON-RPC API
• 用于 Smithery 集成的 stdio JSON-RPC 接口
• 用于分析授权率的工具
• 用于测试的基础计算器功能

运行服务

Web 模式（默认）

如需以 Web 模式运行服务（在端口 8080 上提供 REST API）：

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

在此模式下，可通过 http://localhost:8080/api/mcp 访问 API。

JSON-RPC over stdio 模式

如需以 stdio 模式运行服务（通过标准输入/输出使用 JSON-RPC）：

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 容器中运行服务时，必须使用 -i 标志来提供 stdin 连接：

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 部署

此服务旨在通过 Smithery 部署，Smithery 要求使用 stdio JSON-RPC 接口。

为 Smithery 部署准备服务：

./prepare-smithery.sh

这会创建一个 smithery-deploy 目录，其中包含部署所需的所有文件，包括：

• 服务 JAR 文件
• Smithery 配置文件
• 用于以交互式和非交互式模式运行的脚本
• 包含部署说明的 README

Smithery 配置

服务包含一个 smithery-config.json 文件，用于为 Smithery 配置服务：

{
  "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 环境不支持交互式进程，有以下两种选择：

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。每个请求和响应都是单行 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（必需）：第一个操作数
• b（必需）：第二个操作数

Docker 部署

此项目支持使用 Docker 部署 REST API 服务和 JSON-RPC stdio 服务。

构建 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

注意：通常不会直接使用 docker-compose 运行 JSON-RPC stdio 服务，因为它需要通过 stdin/stdout 进行交互。

故障排查

常见问题

“无法访问服务的工具列表”

如果你看到错误提示，表示无法通过网络连接访问服务的工具列表，可能是因为：

1. 你尝试通过 HTTP 访问以 stdio 模式运行的服务
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 许可协议，详情请参阅 LICENSE 文件。