# mcp-java-server

**Repository Path**: ujj-chao/mcp-java-server

## Basic Information

- **Project Name**: mcp-java-server
- **Description**: mcp java server
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-15
- **Last Updated**: 2026-03-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

    public static class LoggingCapability {
        @JsonProperty("enabled")
        private boolean enabled = true;
        
        public LoggingCapability() {}
        
        public boolean isEnabled() {
            return enabled;
        }
        
        public void setEnabled(boolean enabled) {
            this.enabled = enabled;
        }
    }
}
# 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:
   ```bash
   mvn clean package
   ```

3. Run the server:
   ```bash
   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

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

### 2. Execute a Tool via HTTP API

```bash
# 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

```bash
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

```bash
# 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`:

```yaml
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:

```bash
# 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.