spring-boot-ai-mcp-server by dpolishuk - MCP Server

🚀 Spring Boot MCP Server - Crypto News

A Spring Boot implementation of the Model Context Protocol (MCP) server that provides cryptocurrency news analysis tools for AI assistants like Cursor and Cline.

📋 Requirements

Java 17+
Maven 3.6+
Port 8080 available

🏗️ Architecture

System Architecture

graph TB
    subgraph "AI Assistants"
        A1[Cursor]
        A2[Cline]
    end
    
    subgraph "Transport Layer"
        T1[HTTP Transport]
        T2[SSE Transport]
    end
    
    subgraph "Spring Boot MCP Server"
        C1[McpJsonRpcController]
        C2[McpStandardSseController]
        S1[JsonRpcMcpServer]
        S2[NewsService]
        S3[TrackedTokenService]
    end
    
    subgraph "Data Layer"
        D1[SQLite Database]
        D2[Caffeine Cache]
    end
    
    A1 -->|HTTP| T1
    A2 -->|SSE| T2
    T1 --> C1
    T2 --> C2
    C1 --> S1
    C2 --> S1
    S1 --> S2
    S1 --> S3
    S2 --> D1
    S2 --> D2
    S3 --> D1

Class Diagram

classDiagram
    class JsonRpcMcpServer {
        -NewsService newsService
        -TrackedTokenService tokenService
        -ObjectMapper objectMapper
        -Map~String,SseEmitter~ sessions
        +handleMessage(sessionId, message)
        +createSession(sessionId) SseEmitter
        +initialize(params) Map
        +listTools() Map
        +callTool(name, arguments) Map
    }
    
    class McpStandardSseController {
        -JsonRpcMcpServer mcpServer
        +handleSse() SseEmitter
        +handleMessage(message, sessionId)
    }
    
    class NewsService {
        -NewsRepository newsRepository
        +searchNews(keyword) List~News~
        +getLatestNews(limit) List~News~
        +analyzeSentiment(token) SentimentAnalysis
    }
    
    class TrackedTokenService {
        -TrackedTokenRepository tokenRepository
        +trackToken(symbol) TrackedToken
        +getTrackedTokens() List~TrackedToken~
    }
    
    McpStandardSseController --> JsonRpcMcpServer
    JsonRpcMcpServer --> NewsService
    JsonRpcMcpServer --> TrackedTokenService

MCP Protocol Sequence Diagram

sequenceDiagram
    participant AI as AI Assistant<br/>(Cursor/Cline)
    participant SSE as SSE Endpoint<br/>(/mcp/v1/sse)
    participant MSG as Message Endpoint<br/>(/mcp/v1/messages)
    participant MCP as JsonRpcMcpServer
    participant SVC as Services<br/>(News/Token)
    participant DB as SQLite DB

    Note over AI,DB: SSE Transport Flow
    
    AI->>SSE: GET /mcp/v1/sse
    SSE->>SSE: Create session
    SSE-->>AI: SSE Stream opened
    SSE-->>AI: event: endpoint<br/>data: /mcp/v1/messages?sessionId=xxx

    AI->>MSG: POST /mcp/v1/messages?sessionId=xxx<br/>{"method": "initialize", ...}
    MSG->>MCP: handleMessage(sessionId, message)
    MCP->>MCP: process initialize
    MCP-->>SSE: Send response via SSE
    SSE-->>AI: event: message<br/>data: {"result": {...}}

    AI->>MSG: POST {"method": "tools/list", ...}
    MSG->>MCP: handleMessage(sessionId, message)
    MCP->>MCP: listTools()
    MCP-->>SSE: Send tools list
    SSE-->>AI: event: message<br/>data: {"result": {"tools": [...]}}

    AI->>MSG: POST {"method": "tools/call",<br/>"params": {"name": "search_news",<br/>"arguments": {"keyword": "bitcoin"}}}
    MSG->>MCP: handleMessage(sessionId, message)
    MCP->>SVC: searchNews("bitcoin")
    SVC->>DB: SELECT * FROM news WHERE ...
    DB-->>SVC: News results
    SVC-->>MCP: List<News>
    MCP-->>SSE: Send results
    SSE-->>AI: event: message<br/>data: {"result": {"content": [...]}}

    Note over AI,DB: HTTP Transport Flow (Cursor)
    
    AI->>MSG: POST /mcp/messages<br/>{"method": "initialize", ...}
    MSG->>MCP: handleMessage(null, message)
    MCP->>MCP: process initialize
    MCP-->>MSG: Synchronous response
    MSG-->>AI: HTTP 200<br/>{"result": {...}}

🛠️ Quick Start

1. Clone and Build

git clone https://github.com/dpolishuk/spring-boot-ai-mcp-server.git
cd spring-boot-ai-mcp-server
mvn clean install

2. Start the Server

mvn spring-boot:run

3. Verify Installation

curl http://localhost:8080/actuator/health
# Should return: {"status":"UP"}

🔧 Configuration

For Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "crypto-news": {
      "url": "http://localhost:8080/mcp/messages",
      "transport": "http"
    }
  }
}

Restart Cursor
Test in chat:

"What crypto news tools are available?"

For Cline (VS Code)

Open settings: Cmd+Shift+P → "Cline: Open Settings"
Add to "MCP Servers" section:

{
  "mcpServers": {
    "crypto-news": {
      "type": "sse",
      "url": "http://localhost:8080/mcp/v1/sse"
    }
  }
}

Save and restart Cline

📡 Available Endpoints

1. HTTP Transport (Direct API)

URL: http://localhost:8080/mcp/messages
Method: POST
Content-Type: application/json

2. SSE Transport (Server-Sent Events)

SSE URL: http://localhost:8080/mcp/v1/sse
Messages URL: http://localhost:8080/mcp/v1/messages?sessionId={sessionId}

🛠️ Available Tools

Tool	Description	Parameters	Example Usage
`search_news`	Search crypto news by keyword	`keyword` (string, required)	"Search for bitcoin news"
`get_latest_news`	Get latest crypto news	`limit` (integer, optional)	"Get latest crypto news"
`track_token`	Track a cryptocurrency token	`symbol` (string, required)	"Track ETH token"
`get_tracked_tokens`	List tracked tokens	none	"Show tracked tokens"
`analyze_sentiment`	Analyze token sentiment	`token` (string, required)	"Analyze BTC sentiment"

📝 Usage Examples

In Cursor/Cline:

User: Find news about Ethereum
Assistant: I'll search for Ethereum news...
[Calls search_news with keyword="Ethereum"]

User: What's the sentiment for BTC?
Assistant: Let me analyze Bitcoin sentiment...
[Calls analyze_sentiment with token="BTC"]

🧪 Testing

Test HTTP endpoint:

curl -X POST http://localhost:8080/mcp/messages \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

Test SSE endpoint:

curl http://localhost:8080/mcp/v1/sse -H "Accept: text/event-stream"

Test tool invocation:

curl -X POST http://localhost:8080/mcp/messages \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search_news",
      "arguments": {"keyword": "bitcoin"}
    },
    "id": 2
  }'

🌟 Features

✅ Full MCP protocol support (v1.0 and v2025-03-26)
✅ Multiple transport mechanisms (HTTP, SSE)
✅ SQLite database for persistent storage
✅ Caffeine caching for performance
✅ RESTful API for direct access
✅ Sentiment analysis for cryptocurrencies
✅ Real-time SSE updates
✅ Comprehensive logging

🏛️ Project Structure

spring-boot-ai-mcp-server/
├── src/main/java/com/example/
│   ├── mcp/
│   │   └── JsonRpcMcpServer.java      # Core MCP implementation
│   ├── controller/
│   │   ├── McpJsonRpcController.java   # HTTP/SSE endpoint /mcp/*
│   │   ├── McpStandardSseController.java # SSE endpoint /mcp/v1/*
│   │   ├── NewsController.java         # REST API for news
│   │   └── TokenController.java        # REST API for tokens
│   ├── service/
│   │   ├── NewsService.java            # News business logic
│   │   └── TrackedTokenService.java    # Token management
│   └── entity/
│       ├── News.java                   # JPA entity for news
│       └── TrackedToken.java           # JPA entity for tokens
├── crypto_news.db                      # SQLite database
├── application.yml                     # Spring configuration
└── pom.xml                            # Maven configuration

🐛 Troubleshooting

Port already in use

lsof -i :8080
kill -9 <PID>

SSE connection fails (Cline)

Verify URL is http://localhost:8080/mcp/v1/sse
Check server logs
Ensure server is running

No tools available

Ensure server is running
Check crypto_news.db file exists
Verify initialization was called

Enable debug logging

In application.yml:

logging:
  level:
    com.example: DEBUG

📚 Additional Resources

MCP Protocol Specification
Server logs: app.log

🔒 Protocol Support

MCP Protocol Versions: 1.0 and 2025-03-26
JSON-RPC Version: 2.0
Transport Types: HTTP, SSE
Content Types: application/json, text/event-stream

Built with ❤️ using Spring Boot and MCP