Paypal Java MCP Server

PayPal Java MCP服务器

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

特性

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

运行服务器

Web模式（默认）

要在web模式下运行服务器，这将在端口8080上公开REST API：

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

在这种模式下，您可以访问API http://localhost:8080/api/mcp.

标准输入模式下的JSON-RPC

要在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方法：

初始化

初始化服务器并返回其功能：

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

getTools

返回可用工具的列表：

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

execute函数

使用指定的参数执行函数：

{"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配置文件
• 在交互式和非交互式模式下运行的脚本
• 带有部署说明的自述文件

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. 这 "interactive": true 在Smithery配置中设置标志
2. 这 -Djsonrpc.stdio.interactive=true 参数包含在启动命令中
3. 您正在使用JSON-RPC over stdio接口，并且没有尝试通过HTTP连接到服务器
4. 如果您的环境不支持交互式流程，请使用 start-non-interactive.sh 改为脚本

非交互式部署

如果您的Smithery环境不支持交互式流程，您有两个选择：

1. 使用start-non-interactive.sh脚本：此脚本创建命名管道并为您处理stdin/stdout连接。

1. 修改Smithery配置：设置 "interactive": false 在Smithery配置中，并确保服务器以 -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

JSON-RPC over stdio接口在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 （可选）：交易类型过滤器（默认：“全部”）

计算器工具

此工具执行基本的数学运算。

参数：

• operation （必填）：要执行的操作（加、减、乘、除）
• a （必需）：第一个操作数
• b （必需）：第二个操作数

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服务器通常不直接与docker compose一起运行，因为它需要stdin/stdout交互。

故障排除

常见问题

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

如果您看到一个错误，表明无法通过网络连接访问服务器的工具列表，这可能是因为：

1. 当服务器在stdio模式下运行时，您正试图通过HTTP访问服务器
2. 服务器未在交互模式下运行，因此无法接收输入或发送输出
3. 这 -Djsonrpc.stdio.interactive=true 启动命令中缺少标志

解决方案:

• 确保您通过stdio接口使用JSON-RPC
• 使用运行服务器 -i 如果使用Docker，则标记
• 添加 -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许可证获得许可-有关详细信息，请参阅许可证文件。