Content
# 🚀 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
```mermaid
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
```mermaid
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
```mermaid
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
```bash
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
```bash
mvn spring-boot:run
```
### 3. Verify Installation
```bash
curl http://localhost:8080/actuator/health
# Should return: {"status":"UP"}
```
## 🔧 Configuration
### For Cursor
1. Create `.cursor/mcp.json` in your project root:
```json
{
"mcpServers": {
"crypto-news": {
"url": "http://localhost:8080/mcp/messages",
"transport": "http"
}
}
}
```
2. Restart Cursor
3. Test in chat:
```
"What crypto news tools are available?"
```
### For Cline (VS Code)
1. Open settings: `Cmd+Shift+P` → "Cline: Open Settings"
2. Add to "MCP Servers" section:
```json
{
"mcpServers": {
"crypto-news": {
"type": "sse",
"url": "http://localhost:8080/mcp/v1/sse"
}
}
}
```
3. 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:
```bash
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:
```bash
curl http://localhost:8080/mcp/v1/sse -H "Accept: text/event-stream"
```
### Test tool invocation:
```bash
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
```bash
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`:
```yaml
logging:
level:
com.example: DEBUG
```
## 📚 Additional Resources
- [Full MCP Documentation](MCP-DOCUMENTATION.md)
- [MCP Protocol Specification](https://modelcontextprotocol.io)
- 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**
