steveo-ocheng/my-mcp-server-java

My MCP Server (Java)

A Java implementation of a Model Context Protocol (MCP) server that provides example tools for Claude Desktop.

Features

This MCP server provides three example tools:

1. calculate - Perform basic math operations (add, subtract, multiply, divide)
2. reverse_text - Reverse any text string
3. word_count - Analyze text and return statistics (word count, character count, line count, sentence count)

Requirements

• Java 17 or higher
• Gradle 8.5 or higher (wrapper included)

Installation

1. Clone or navigate to the project directory:

cd /Users/steveo/projects/my-mcp-server-java

2. Build the project using Gradle:

./gradlew build

This will create an executable JAR file at build/libs/my-mcp-server-1.0.0.jar

Testing the Server

You can test the server by running it directly:

java -jar build/libs/my-mcp-server-1.0.0.jar

The server will start and wait for JSON-RPC messages via stdin/stdout.

Alternatively, you can run it using Gradle:

./gradlew run

Configuration for Claude Desktop

To use this server with Claude Desktop, add it to your Claude configuration file:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

On Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "my-mcp-server-java": {
      "command": "java",
      "args": [
        "-jar",
        "/Users/steveo/projects/my-mcp-server-java/build/libs/my-mcp-server-1.0.0.jar"
      ]
    }
  }
}

Important: Update the path above to match your actual installation location.

After adding the configuration:

1. Restart Claude Desktop
2. The tools should now be available in Claude
3. Try asking Claude to:
   • "calculate 5 + 3"
   • "reverse the text hello world"
   • "analyze the word count of this text: The quick brown fox jumps over the lazy dog"

Development

Project Structure

my-mcp-server-java/
├── build.gradle              # Gradle build configuration
├── settings.gradle           # Gradle settings
├── gradlew                   # Gradle wrapper script (Unix)
├── gradlew.bat              # Gradle wrapper script (Windows)
├── gradle/
│   └── wrapper/             # Gradle wrapper files
└── src/
    └── main/
        └── java/
            └── com/
                └── example/
                    └── mcp/
                        ├── MCPServer.java           # Main server implementation
                        ├── Tool.java                # Tool interface
                        ├── ToolRegistry.java        # Tool management
                        ├── TextContent.java         # Response content wrapper
                        ├── CalculateTool.java       # Calculator tool
                        ├── ReverseTextTool.java     # Text reversal tool
                        └── WordCountTool.java       # Word count tool

Adding New Tools

To add new tools to your server:

1. Create a new class that implements the Tool interface
2. Implement the three required methods:
   • getName() - returns the tool name
   • getDefinition(ObjectMapper mapper) - returns the JSON tool definition
   • execute(JsonNode arguments) - executes the tool logic
3. Register the tool in MCPServer.registerTools() method
4. Rebuild the project: ./gradlew build
5. Restart Claude Desktop to reload the server

Example tool implementation:

public class MyTool implements Tool {
    @Override
    public String getName() {
        return "my_tool";
    }

    @Override
    public JsonNode getDefinition(ObjectMapper mapper) {
        ObjectNode tool = mapper.createObjectNode();
        tool.put("name", "my_tool");
        tool.put("description", "Description of what my tool does");

        // Define input schema
        ObjectNode inputSchema = mapper.createObjectNode();
        inputSchema.put("type", "object");
        // ... add properties

        tool.set("inputSchema", inputSchema);
        return tool;
    }

    @Override
    public List<TextContent> execute(JsonNode arguments) throws Exception {
        // Tool implementation
        String result = "Tool result";
        return Collections.singletonList(new TextContent(result));
    }
}

Building

# Build the project
./gradlew build

# Run tests
./gradlew test

# Create JAR file
./gradlew shadowJar

# Clean build artifacts
./gradlew clean

Logging

The server uses Java's built-in logging (java.util.logging) which logs to stderr by default to avoid corrupting the JSON-RPC messages sent via stdout. You can check the logs in Claude Desktop's developer console or your terminal.

Implementation Notes

This is a standalone implementation that demonstrates the MCP protocol without relying on an official Java SDK (which may not be available yet). The server:

• Uses JSON-RPC 2.0 for communication
• Implements the MCP protocol specification
• Communicates via stdin/stdout
• Uses Jackson for JSON processing
• Follows the same architecture as the Python reference implementation

Resources

• MCP Documentation
• MCP Specification
• Example MCP Servers
• Python Reference Implementation

License

This is example code for demonstration purposes.