mcp-java-server

praveenmenon76/mcp-java-server

3.1

If you are the rightful owner of mcp-java-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The MCP Java Server is a robust implementation of the Model Context Protocol, designed to facilitate dynamic tool registration and API gateway functionalities.

Tools
3
Resources
0
Prompts
0

MCP Java Server

A Model Context Protocol (MCP) server implementation in Java with dynamic tool registration and API gateway functionality.

Features

  • MCP Protocol Compliance: Implements the Model Context Protocol specification
  • Dynamic Tool Registration: Register and unregister tools at runtime via REST API
  • API Gateway: Expose registered tools as HTTP endpoints
  • Multiple Transport Options: Support for HTTP POST and Server-Sent Events (SSE)
  • Built-in Tools: Comes with example tools (echo, calculator, greeting)
  • Spring Boot: Built on Spring Boot for easy deployment and configuration

Quick Start

Prerequisites

  • Java 17 or higher
  • Maven 3.6 or higher

Building and Running

  1. Clone or download the project

  2. Build the project:

    mvn clean package

  3. Run the server:

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

The server will start on port 8080 by default.

API Endpoints

MCP Protocol Endpoints

  • POST /mcp/message - Send MCP protocol messages
  • GET /mcp/sse - Server-Sent Events endpoint for real-time communication
  • POST /mcp/sse/message - Send MCP messages via SSE

Tool Management API

  • GET /api/tools - List all registered tools
  • GET /api/tools/{toolName} - Get specific tool details
  • POST /api/tools/register - Register a new tool
  • DELETE /api/tools/{toolName} - Unregister a tool
  • POST /api/tools/{toolName}/execute - Execute a tool directly via HTTP

Usage Examples

1. List Available Tools

curl -X GET http://localhost:8080/api/tools

2. Execute a Tool via HTTP API

# Execute calculator tool
curl -X POST http://localhost:8080/api/tools/calculator/execute \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "add",
    "a": 5,
    "b": 3
  }'

# Execute echo tool
curl -X POST http://localhost:8080/api/tools/echo/execute \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, World!"
  }'

3. Register a New Tool

curl -X POST http://localhost:8080/api/tools/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-custom-tool",
    "description": "A custom tool example",
    "handlerType": "echo",
    "inputSchema": {
      "type": "object",
      "properties": {
        "input": {
          "type": "string",
          "description": "Input parameter"
        }
      },
      "required": ["input"]
    }
  }'

4. MCP Protocol Communication

# Initialize MCP connection
curl -X POST http://localhost:8080/mcp/message \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'

# List tools via MCP
curl -X POST http://localhost:8080/mcp/message \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "tools/list",
    "params": {}
  }'

# Call a tool via MCP
curl -X POST http://localhost:8080/mcp/message \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "tools/call",
    "params": {
      "name": "calculator",
      "arguments": {
        "operation": "multiply",
        "a": 6,
        "b": 7
      }
    }
  }'

Built-in Tools

The server comes with several pre-registered tools:

1. Echo Tool

  • Name: echo
  • Description: Echoes back the provided message
  • Parameters:
    • message (string, required): The message to echo

2. Calculator Tool

  • Name: calculator
  • Description: Performs basic arithmetic operations
  • Parameters:
    • operation (string, required): One of "add", "subtract", "multiply", "divide"
    • a (number, required): First number
    • b (number, required): Second number

3. Greeting Tool

  • Name: greeting
  • Description: Generates greetings in different languages
  • Parameters:
    • name (string, required): The name to greet
    • language (string, optional): Language for greeting ("english", "spanish", "french", "german")

Tool Handler Types

When registering tools, you can specify different handler types:

  • echo: Simple echo handler that returns the input arguments
  • calculator: Arithmetic operations handler
  • http: Mock HTTP request handler (for demonstration)
  • custom: Custom handler with configurable behavior

Configuration

The server can be configured via application.yml:

server:
  port: 8080  # Change server port

logging:
  level:
    com.mcpserver: DEBUG  # Adjust logging level

Architecture

The server is built with the following components:

  • McpProtocolHandler: Handles MCP protocol messages
  • ToolRegistry: Manages tool registration and execution
  • McpController: REST endpoints for MCP communication
  • ToolManagementController: REST API for tool management
  • DefaultToolsInitializer: Registers built-in tools on startup

Development

To extend the server with new functionality:

  1. Add new tool handler types in ToolManagementController.createToolHandler()
  2. Implement custom tool logic by creating new ToolHandler implementations
  3. Add new MCP methods in McpProtocolHandler.processRequest()
  4. Register default tools in DefaultToolsInitializer

Testing

The server includes health check endpoints:

# Check server health
curl http://localhost:8080/actuator/health

# Get server info
curl http://localhost:8080/actuator/info

License

This project is open source and available under the MIT License.