mcp-server

davidchanit/mcp-server

3.3

If you are the rightful owner of mcp-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 henry@mcphub.com.

A simple Model Context Protocol (MCP) server implementation in Java using Spring Boot.

Tools
2
Resources
0
Prompts
0

Spring AI MCP Server

A Model Context Protocol (MCP) server implementation using Spring AI framework with custom HTTP transport. This server provides tools for mathematical calculations and games, accessible via JSON-RPC over HTTP.

Features

  • āœ… Custom HTTP MCP Server: Implements MCP protocol over HTTP with JSON-RPC
  • āœ… Spring AI Framework Integration: Built on Spring AI MCP framework
  • āœ… Tool Auto-Discovery: Automatic tool registration via @Tool annotations
  • āœ… Multiple Transport Support: HTTP (custom) + SSE (framework-provided)
  • āœ… Real-time Communication: Support for both HTTP and SSE transport methods
  • āœ… Cursor IDE Integration: Compatible with Cursor's MCP client

Quick Start

Prerequisites

  • Java 17 or higher
  • Maven 3.6+
  • Cursor IDE (for testing MCP integration)

1. Build the Project

mvn clean package -DskipTests

2. Run the Server

java -jar target/mcp-server-0.0.1-SNAPSHOT.jar --spring.profiles.active=prod

The server will start on port 8090.

3. Test the API

Test the MCP endpoint:

# Test ping
curl -X POST http://localhost:8090/api/v1/mpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "ping", "params": {}}'

# Test calculate tool
curl -X POST http://localhost:8090/api/v1/mpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "calculate", "arguments": {"expression": "22+2"}}}'

Configuration

Server Configuration (application.yml)

server:
  port: 8090

spring:
  application:
    name: mcp-server

ai:
  mcp:
    server:
      name: mcp-server # MCP server name
      version: 0.0.1   # Server version

logging:
  level:
    org.springframework.ai: DEBUG
    com.example.mcpserver: DEBUG

Cursor IDE Configuration

Add this to your Cursor MCP configuration file (~/.cursor/mcp.json):

{
  "mcpServers": {
    "spring-ai-mcp-server": {
      "command": "http",
      "args": {
        "url": "http://localhost:8090/api/v1/mpc"
      }
    }
  }
}

Available Tools

Calculator Tools (CalculatorService)

  • calculate: Execute basic mathematical expressions
  • add: Add two numbers
  • subtract: Subtract two numbers
  • multiply: Multiply two numbers
  • divide: Divide two numbers

Game Tools (GameService)

  • rockPaperScissors: Play Rock, Paper, Scissors - randomly returns one of the three options
  • playRockPaperScissors: Play Rock, Paper, Scissors against a computer - you choose your move
  • getRandomChoice: Get a random choice from Rock, Paper, Scissors

Adding New Tools

  1. Create a new service class with @Service annotation
  2. Add @Tool annotation to methods
  3. Add @ToolParam annotation to parameters

Example:

@Service
public class MyToolsService {

    @Tool(description = "Tool description")
    public String myTool(@ToolParam(description = "Parameter description") String parameter) {
        // Tool implementation
        return "Result: " + parameter;
    }
}

Project Structure

src/main/java/com/example/mcpserver/
ā”œā”€ā”€ McpServerApplication.java          # Main application class
ā”œā”€ā”€ controller/
ā”‚   ā””ā”€ā”€ McpController.java            # Custom MCP HTTP controller
ā”œā”€ā”€ service/
ā”‚   ā”œā”€ā”€ CalculatorService.java        # Calculator tools service
ā”‚   ā””ā”€ā”€ GameService.java              # Game tools service
ā””ā”€ā”€ resources/
    ā””ā”€ā”€ application.yml               # Application configuration

Transport Methods

This project supports multiple transport methods:

1. HTTP Transport (Custom Implementation)

  • Endpoint: POST http://localhost:8090/api/v1/mpc
  • Protocol: JSON-RPC over HTTP
  • Usage: Direct HTTP requests, Cursor IDE integration
  • Response: Immediate JSON responses

2. SSE Transport (Framework-Provided)

  • Endpoint: Automatically provided by Spring AI framework
  • Protocol: Server-Sent Events for streaming
  • Usage: Real-time, persistent connections
  • Response: Streaming events

Dependencies

Core Dependencies (pom.xml)

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>

Repository Configuration

<repositories>
    <repository>
        <id>spring-snapshots</id>
        <name>Spring Snapshots</name>
        <url>https://repo.spring.io/snapshot</url>
        <releases>
            <enabled>false</enabled>
        </releases>
    </repository>
    <repository>
        <name>Central Portal Snapshots</name>
        <id>central-portal-snapshots</id>
        <url>https://central.sonatype.com/repository/maven-snapshots/</url>
        <releases>
            <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

Troubleshooting

Common Issues

  1. Port Already in Use: Change the port in application.yml
  2. Tools Not Appearing: Ensure service classes have @Service annotation
  3. API Not Responding: Check if server is running on correct port
  4. Cursor Connection Issues: Verify MCP configuration in ~/.cursor/mcp.json

Logs

The application uses SLF4J logging. Check console output for detailed log information.

Development

Building for Development

mvn clean compile

Running Tests

mvn test

Docker Support

Build Docker image:

# Build the JAR first
mvn clean package -DskipTests

# Build Docker image
docker build -t mcp-server .

Run with Docker:

# Run with Docker
docker run -p 8090:8090 mcp-server

# Or run with docker-compose
docker-compose up -d

Test Docker container:

# Test POST endpoint (JSON-RPC)
curl -X POST http://localhost:8090/api/v1/mpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "ping", "params": {}}'

# Test GET endpoint (SSE/Streamable HTTP)
curl -X GET http://localhost:8090/api/v1/mpc \
  -H "Accept: text/event-stream"

Web Test Client

A web-based test client is available at:

http://localhost:8090/mcp-client.html

This client provides a user-friendly interface to test all MCP endpoints and tools.

For Production: The client automatically detects the server URL, so it works both locally and on Heroku:

https://your-app-name.herokuapp.com/mcp-client.html

CI/CD Testing

For CI/CD pipelines, use the provided test script:

# Make script executable
chmod +x ci-test.sh

# Run the test
./ci-test.sh

Or manually:

docker run -d --name mcp-test -p 8090:8090 mcp-server:latest
sleep 10
curl -f -X POST http://localhost:8090/api/v1/mpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "ping", "params": {}}' || exit 1
docker stop mcp-test
docker rm mcp-test

Deployment

Heroku

Deploy to Heroku using the provided script:

# Make script executable
chmod +x deploy-heroku.sh

# Deploy to Heroku
./deploy-heroku.sh

Or manually:

# Build the application
mvn clean package -DskipTests

# Create Heroku app (if not exists)
heroku create

# Set environment variables
heroku config:set SPRING_PROFILES_ACTIVE=prod

# Deploy
git push heroku main

Docker

Build and run with Docker:

# Build the JAR first
mvn clean package -DskipTests

# Build Docker image
docker build -t mcp-server .

# Run with Docker
docker run -p 8090:8090 mcp-server

# Or run with docker-compose
docker-compose up -d

License

This project is licensed under the MIT License - see the LICENSE file for details.