laplus-x/stocks-mcp-server

📈 stocks-mcp-server

Spring Boot + MCP Server based AI tool service for Taiwan Stock Query

📝 Project Overview

stocks-mcp-server is a backend service built with Spring Boot and Model Context Protocol (MCP) for querying Taiwan stock information. It provides APIs for searching by stock name/symbol, real-time price, and volume, and exposes these as AI tools for easy integration with AI agents or automation workflows.

🏗️ Architecture

• Spring Boot WebFlux: High-performance, non-blocking REST API
• Spring AI MCP Server: AI tool registration and STDIO/SSE communication
• TWSE API: Integration with Taiwan Stock Exchange public data
• ModelMapper: Data object mapping
• Lombok: Simplified Java POJO syntax

Main modules:

• Config.java: Bean registration (RestClient, ModelMapper)
• StocksMcpServerApplication.java: Main entry, AI tool registration
• repositories/TwseRepository.java: TWSE API integration and data parsing
• tools/StockTool.java: AI tool method (getStock)
• usecases/StockService.java: Business logic
• dao/, dto/: Data structures
• exceptions/: Error handling

🚀 Installation & Startup

1. Requirements

• Java 17+
• Maven 3.9+

2. Local Startup

./mvnw spring-boot:run

or

mvn spring-boot:run

🛠️ API Tool (MCP)

getStock

• Description: Query real-time stock info by name or symbol
• Parameter: name (stock name or symbol)
• Response:

  {
  	"code": "2330",
  	"name": "TSMC",
  	"price": "800.00",
  	"volume": "10000"
  }
  

SSE Endpoints

• /mcp/sse: MCP Server SSE communication
• /mcp/sse/messages: Message push

📦 Tech Stack

• Spring Boot 3.5
• Spring AI MCP Server WebFlux
• ModelMapper
• Lombok
• JUnit 5

🧩 Directory Structure

src/
	main/
		java/dev/laplus/stocks_mcp_server/
			Config.java
			StocksMcpServerApplication.java
			repositories/
			tools/
			usecases/
			dao/
			dto/
			exceptions/
		resources/application.properties
	test/
		java/dev/laplus/stocks_mcp_server/
			StocksMcpServerApplicationTests.java
Taskfile.yml
pom.xml

🧪 Testing

./mvnw test

🤝 Contributing

Issues, PRs, and discussions are welcome!

📄 License

Apache License 2.0