PayPal Java Payment Utility Host

This repository contains a Spring Boot application built in Java, serving as a Merchant Capability Platform (MCP) backend. It exposes transactional analysis features and foundational computational routines through dual interfaces: a standard web API and a low-latency streaming interface for platform integration (Smithery).

Core Capabilities

• Authorization Rate Diagnostics: Tools dedicated to evaluating and providing actionable intelligence for improving payment authorization success ratios.
• Arithmetic Engine: A fundamental component offering basic mathematical processing capabilities.
• Connectivity Options: Supports standard request/response communication over HTTP/REST and streaming, line-delimited JSON-RPC messaging via standard input/output streams.

Server Deployment Configurations

Standard Web Deployment (REST Endpoint)

Execute the JAR to launch the HTTP server, typically listening on port 8080:

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

API interactions are routed via http://localhost:8080/api/mcp.

Streaming Interface Mode (JSON-RPC via stdio)

Activate the specialized mode for seamless integration with tooling platforms like Smithery, relying on standard I/O:

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

Requests enter via stdin; responses and system output are directed to stdout/stderr respectively.

Operational Note: Utilizing the stdio path mandates continuous access to interactive terminal streams. Verification can be done using the provided invocation script:

./test-stdio.sh

Handling Non-Interactive Streams

For environments lacking inherent stdio connectivity, the utility script start-non-interactive.sh manages setup:

1. Establishes necessary named pipes (FIFOs) for input and output streams.
2. Launches auxiliary processes to bridge these pipes.
3. Starts the service with stream isolation (-Djsonrpc.stdio.interactive=false).
4. Automatically injects an initialization signal.
5. Outputs the path details required for manual pipe interaction:

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

# Retrieving the server's reply
cat /path/to/output_pipe

Containerized Execution (Docker)

When deploying within a container runtime, the standard execution command requires the interactive flag (-i) to maintain necessary stream connectivity:

docker run -i paypal-mcp-jsonrpc

This step is automated by the wrapper script: ./run-docker.sh.

Communication Protocol (JSON-RPC 2.0)

The streaming interface supports the following RPC methods:

initialize

Initiates handshake and reports service configuration.

getTools

Fetches the inventory of accessible operational tools.

executeFunction

Invokes a specified function with provided parameters. Example for computation:

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

Deployment Integration with Smithery

To ready the service package for deployment managed by Smithery's orchestration layer, execute the preparation utility:

./prepare-smithery.sh

This generates a deployment bundle within smithery-deploy/, containing the necessary binary, configuration manifest, and operational scripts.

Smithery Manifest (smithery-config.json)

The configuration mandates stream interaction settings:

{
  "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 Deployment Constraints for Smithery: 1. Smithery configuration must specify "interactive": true. 2. The startup arguments must include -Djsonrpc.stdio.interactive=true. 3. Only the JSON-RPC stdio path should be utilized; HTTP access is unavailable in this configuration. 4. For environments lacking native stream support, revert to using start-non-interactive.sh.

Alternative: Non-Interactive Provisioning

If interactive streams are impossible within the Smithery setup:

1. Utilize start-non-interactive.sh to abstract stream handling via pipes.
2. Alternatively, set "interactive": false in the manifest and ensure the server is started with -Djsonrpc.stdio.interactive=false.

System Requirements

• Runtime Environment: Java SE Development Kit (JDK) version 17 or newer.
• Build Tool: Apache Maven version 3.6 or newer.

Initial Setup and Build Cycle

Application Parameterization

Tune parameters within the configuration file located at application.properties:

# Network Binding
server.port=8080

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

Compilation and Packaging

Execute the build sequence:

mvn clean package

Interface Interaction Examples

RESTful Interface Operations

System Status Endpoint

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

General Inquiry 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 Enhancement Tool Invocation

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

Calculation Utility Execution

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 Streaming Interaction

Requests and responses are single, line-delimited JSON objects transmitted via stdio.

Inquiry Request Example

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

Function Execution Request Examples

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

Result Formatting

REST API Output Structure

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

JSON-RPC Streamed Output Structure

{"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 Tool Definitions

Tool: Authorization Rate Analysis Utility

Analyzes transactional history to prescribe methods for boosting payment acceptance ratios.

Parameters Schema: - merchantId (Mandatory): Unique identifier for the merchant account. - timeframe (Optional): Duration for data aggregation (Default: "last_30_days"). - transactionType (Optional): Filter for specific transaction categories (Default: "all").

Tool: Mathematical Computation Service

Executes basic arithmetic operations.

Parameters Schema: - operation (Mandatory): Required action (e.g., add, subtract, multiply, divide). - a (Mandatory): The primary numeric input. - b (Mandatory): The secondary numeric input.

Containerization Strategy

Docker artifacts are provided for both primary modes of operation.

Image Construction

Combined Build Orchestration

docker-compose build

REST Service Image Build

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

Streamed Service Image Build (Smithery Target)

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

Execution via Docker

Launching the REST Gateway

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

Launching the Streaming Backend

Crucially, the stdio interface requires interactive mode (-i):

docker run -i paypal-mcp-jsonrpc

Leverage the helper script for standard Docker orchestration:

./run-docker.sh

Docker Compose Service Startup

docker-compose up rest-api

Note: The streaming component is generally not initiated via docker-compose due to its reliance on external stream piping.

Troubleshooting Guide

Issue: Inaccessibility of Tool Inventory over Network

This error typically surfaces when attempting HTTP access on a service configured strictly for streaming I/O, or when interactivity fails.

Root Causes: 1. Using HTTP protocol against a running stdio service. 2. The server lacks interactive stream access. 3. The required flag -Djsonrpc.stdio.interactive=true is absent during launch.

Remedy: - Confirm usage of the JSON-RPC stdio interface. - Ensure the Docker -i flag is present. - Verify the presence of the activation JVM argument. - If working in an isolated environment, deploy using start-non-interactive.sh.

Issue: Initialization Failure in Unattended Contexts

When the service fails during bootstrap outside an interactive shell:

1. Prioritize the use of the specialized start-non-interactive.sh utility.
2. Run the service explicitly with stream handling disabled: -Djsonrpc.stdio.interactive=false.
3. Confirm that the necessary named pipe structures are correctly mounted and accessible.

Recommended Action:

./start-non-interactive.sh

Issue: Server Silent or Unresponsive

If requests yield no reply, systemic connectivity issues are likely.

Diagnosis Steps: 1. Confirm the current operational mode (REST vs. stdio). 2. Validate that input/output streams are correctly linked. 3. Review server logs for startup errors.

Verification Methods: - Test the entire I/O path using ./test-stdio.sh. - In pipe-based setups, inspect the named pipes for data flow. - Examine the service log files for exception traces.

Licensing Information

This software package is distributed under the terms of the MIT License (refer to the LICENSE file for full details).

WIKIPEDIA CONTEXT: Business operation management tools encompass the entire spectrum of systems, computational methods, organizational controls, and established practices utilized by enterprises to navigate dynamic markets, sustain competitive parity, and drive overall organizational efficacy. These solutions span functional areas like resource planning, operational process control, data record-keeping, personnel management, and crucial strategic decision support mechanisms. Modern management technology has experienced exponential growth catalyzed by rapid technological advancements, making the selection and correct integration of suitable software solutions a complex strategic undertaking driven by imperatives such as cost optimization, revenue augmentation, deep customer need comprehension, and precise product fulfillment delivery.