PayPal Java MCP Server

This is a Java implementation of a PayPal MCP (Merchant Capability Platform) server that provides tools for analyzing and improving payment processing.

Features

• JSON-RPC over HTTP API for web clients
• JSON-RPC over stdio interface for Smithery integration
• Tools for analyzing authorization rates
• Basic calculator functionality for testing

Running the Server

Web Mode (Default)

To run the server in web mode, which exposes a REST API on port 8080:

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

In this mode, you can access the API at http://localhost:8080/api/mcp.

JSON-RPC over stdio Mode

To run the server in stdio mode, which uses JSON-RPC over standard input/output:

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

In this mode, the server reads JSON-RPC requests from stdin and writes responses to stdout. All logs are written to stderr and a log file.

IMPORTANT: The JSON-RPC stdio interface requires stdin/stdout connectivity. When deploying, ensure that the process has access to stdin/stdout, typically by running it in interactive mode.

You can test the stdio mode using the provided test script:

./test-stdio.sh

Running in Non-Interactive Environments

If you need to run the server in a non-interactive environment (where stdin/stdout connectivity is not available), you can use the provided start-non-interactive.sh script:

./start-non-interactive.sh

This script:

1. Creates named pipes for stdin and stdout
2. Starts background processes to handle the pipes
3. Starts the server with the -Djsonrpc.stdio.interactive=false flag
4. Automatically sends an initialize request to the server
5. Provides the pipe paths for you to interact with the server

The server will pre-initialize all capabilities and tools, so it's ready to respond to requests even without initial input. You can then interact with the server by writing to the input pipe and reading from the output pipe:

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

# Read responses
cat /path/to/output_pipe

Running with Docker

When running the server in a Docker container, you MUST use the -i flag to provide stdin connectivity:

docker run -i paypal-mcp-jsonrpc

The provided run-docker.sh script handles this for you:

./run-docker.sh

JSON-RPC Protocol

The server supports the following JSON-RPC methods:

initialize

Initializes the server and returns its capabilities:

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

getTools

Returns a list of available tools:

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

executeFunction

Executes a function with the specified arguments:

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

Deployment with Smithery

This server is designed to be deployed with Smithery, which requires the JSON-RPC over stdio interface.

To prepare the server for Smithery deployment:

./prepare-smithery.sh

This will create a smithery-deploy directory with all the necessary files for deployment, including:

• The server JAR file
• The Smithery configuration file
• Scripts for running in interactive and non-interactive modes
• A README with deployment instructions

Smithery Configuration

The server includes a smithery-config.json file that configures the server for 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"
  ]
}

CRITICAL: When using the server with Smithery, ensure that:

1. The "interactive": true flag is set in the Smithery configuration
2. The -Djsonrpc.stdio.interactive=true argument is included in the startup command
3. You are using the JSON-RPC over stdio interface and not attempting to connect to the server via HTTP
4. If your environment does not support interactive processes, use the start-non-interactive.sh script instead

Non-Interactive Deployment

If your Smithery environment does not support interactive processes, you have two options:

1. Use the start-non-interactive.sh script: This script creates named pipes and handles the stdin/stdout connectivity for you.

2. Modify the Smithery configuration: Set "interactive": false in the Smithery configuration and ensure the server is started with the -Djsonrpc.stdio.interactive=false flag.

Prerequisites

• Java 17 or higher
• Maven 3.6 or higher

Getting Started

Configuration

Configure the application in application.properties:

# Server configuration
server.port=8080

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

Building and Running

Build the application:

mvn clean package

API Usage

REST API

Health Check

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

Completions Endpoint

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"
    }
  }'

Authorization Rate Improvement Tool

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"
  }'

Calculator Tool

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

JSON-RPC over stdio

The JSON-RPC over stdio interface accepts JSON-RPC 2.0 requests on stdin and writes responses to stdout. Each request and response is a single line of JSON.

Completions Request

{"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"}

Execute Function Request

{"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"}

Response Format

REST API Response

{
  "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 Response

{"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"}

Available Tools

Authorization Rate Improvement Tool

This tool analyzes transaction data and provides recommendations to improve authorization rates.

Parameters:

• merchantId (required): The merchant ID to analyze
• timeframe (optional): The timeframe for analysis (default: "last_30_days")
• transactionType (optional): Transaction type filter (default: "all")

Calculator Tool

This tool performs basic math operations.

Parameters:

• operation (required): The operation to perform (add, subtract, multiply, divide)
• a (required): First operand
• b (required): Second operand

Docker Deployment

The project includes Docker support for both the REST API server and the JSON-RPC stdio server.

Building Docker Images

Build Both Images Using Docker Compose

docker-compose build

Build REST API Server Image Only

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

Build JSON-RPC Server Image Only

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

Running with Docker

Run REST API Server

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

Run JSON-RPC Server

The JSON-RPC server reads from stdin and writes to stdout, so it MUST be run with interactive mode:

docker run -i paypal-mcp-jsonrpc

Or use the provided script:

./run-docker.sh

Using Docker Compose

Start the REST API server:

docker-compose up rest-api

Note: The JSON-RPC stdio server is not typically run directly with docker-compose since it requires stdin/stdout interaction.

Troubleshooting

Common Issues

"The server's tool list is not accessible"

If you see an error indicating that the server's tool list is not accessible via a network connection, this is likely because:

1. You're trying to access the server via HTTP when it's running in stdio mode
2. The server is not running in interactive mode, so it can't receive input or send output
3. The -Djsonrpc.stdio.interactive=true flag is missing from the startup command

Solution:

• Ensure you're using the JSON-RPC over stdio interface
• Run the server with the -i flag if using Docker
• Add the -Djsonrpc.stdio.interactive=true flag to the startup command
• Use the start-non-interactive.sh script if running in a non-interactive environment

"Server fails to initialize in a non-interactive environment"

If the server fails to initialize in a non-interactive environment:

1. Use the start-non-interactive.sh script, which is specifically designed for non-interactive environments
2. Run the server with the -Djsonrpc.stdio.interactive=false flag
3. Ensure the named pipes are properly set up and accessible

Solution:

./start-non-interactive.sh

"No response from server"

If the server doesn't respond to requests:

1. Check that the server is running in the correct mode
2. Verify that stdin/stdout are properly connected
3. Check the logs for any errors

Solution:

• Run the server with the test-stdio.sh script to verify it works correctly
• Use the start-non-interactive.sh script and check the named pipes
• Check the log file for any errors

License

This project is licensed under the MIT License - see the LICENSE file for details.