Abhishek-Aditya-bs/java-mcp-server-experiment

Simple Java MCP Server

A simple Model Context Protocol (MCP) server implementation in Java that provides mathematical tools for calculating Greatest Common Divisor (GCD) and Least Common Multiple (LCM) of two numbers.

Features

• GCD Tool: Calculate the Greatest Common Divisor of two positive integers using the Euclidean algorithm
• LCM Tool: Calculate the Least Common Multiple of two positive integers using the formula LCM(a,b) = (a × b) / GCD(a,b)
• Error Handling: Comprehensive input validation and error reporting
• Logging: Built-in logging support for debugging and monitoring

Prerequisites

• Java 17 or higher
• Maven 3.6 or higher

Project Structure

simple-java-mcp/
├── pom.xml                           # Maven configuration
├── README.md                         # This file
└── src/
    └── main/
        └── java/
            └── com/
                └── example/
                    └── mcp/
                        └── MathMcpServer.java    # Main server implementation

Building the Project

1. Clone or navigate to the project directory:

   cd simple-java-mcp
   

2. Compile the project:

   mvn clean compile
   

3. Package the application:

   mvn clean package
   

   This will create a fat JAR file in the target/ directory: simple-java-mcp-1.0.0.jar

Running the Server

Option 1: Using Maven

mvn exec:java -Dexec.mainClass="com.example.mcp.MathMcpServer"

Option 2: Using the JAR file

java -jar target/simple-java-mcp-1.0.0.jar

The server will start and listen for MCP requests via STDIO (standard input/output).

Available Tools

1. GCD Tool

• Name: gcd
• Description: Calculate the Greatest Common Divisor (GCD) of two positive integers
• Parameters:
  • a (integer): The first positive integer
  • b (integer): The second positive integer

Example Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "gcd",
    "arguments": {
      "a": 48,
      "b": 18
    }
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": {
          "operation": "gcd",
          "input_a": 48,
          "input_b": 18,
          "result": 6,
          "explanation": "GCD of 48 and 18 is 6"
        }
      }
    ]
  }
}

2. LCM Tool

• Name: lcm
• Description: Calculate the Least Common Multiple (LCM) of two positive integers
• Parameters:
  • a (integer): The first positive integer
  • b (integer): The second positive integer

Example Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "lcm",
    "arguments": {
      "a": 12,
      "b": 8
    }
  }
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": {
          "operation": "lcm",
          "input_a": 12,
          "input_b": 8,
          "result": 24,
          "explanation": "LCM of 12 and 8 is 24"
        }
      }
    ]
  }
}

Testing the Server

You can test the server using any MCP client or by sending JSON-RPC messages directly via STDIO.

Using curl (for testing purposes):

# First, list available tools
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | java -jar target/simple-java-mcp-1.0.0.jar

# Test GCD calculation
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "gcd", "arguments": {"a": 48, "b": 18}}}' | java -jar target/simple-java-mcp-1.0.0.jar

# Test LCM calculation
echo '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "lcm", "arguments": {"a": 12, "b": 8}}}' | java -jar target/simple-java-mcp-1.0.0.jar

Error Handling

The server includes comprehensive error handling for:

• Missing parameters
• Invalid number formats
• Non-positive integers
• Integer overflow (for LCM calculations)

Example error response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": {
          "error": "Both numbers must be positive integers"
        }
      }
    ],
    "isError": true
  }
}

Development

Adding New Tools

To add new mathematical tools:

1. Create a new tool registration method similar to createGcdTool() or createLcmTool()
2. Register the tool in the main() method using server.addTool()
3. Implement the tool logic with proper error handling

Dependencies

The project uses the following key dependencies:

• MCP Java SDK Core (0.5.0): Core MCP protocol implementation
• Jackson Databind (2.17.0): JSON processing
• SLF4J Simple (2.0.9): Logging framework

License

This project is provided as an example implementation of the Model Context Protocol in Java.

Contributing

Feel free to submit issues and enhancement requests!