spring-ai-mcp-server

rk31339/spring-ai-mcp-server

3.2

If you are the rightful owner of spring-ai-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 dayong@mcphub.com.

The Equity Order Management System is a Spring Boot-based Model Context Protocol (MCP) server that provides AI-powered trading tools and workflows for equity order management.

Tools
10
Resources
0
Prompts
0

Equity Order Management System - MCP Server

A Spring Boot-based Model Context Protocol (MCP) server that provides AI-powered trading tools and workflows for equity order management.

Overview

This MCP server exposes a comprehensive set of tools for equity trading operations, including order placement, modification, cancellation, market data retrieval, and portfolio management. It's designed to integrate with AI clients via the Model Context Protocol, enabling natural language-based trading interactions.

Features

Trading Tools

  • Order Placement - Place BUY/SELL orders with support for MARKET, LIMIT, and STOP order types
  • Order Management - Modify or cancel existing orders
  • Order Tracking - Query order status and retrieve order history
  • Market Data - Real-time market prices with simulated price fluctuations
  • Cash Account Management - Retrieve and validate cash accounts for trading
  • Position Management - Track current stock positions with live market valuations
  • Portfolio Summary - Comprehensive portfolio overview

AI Prompts

  • Market Analysis - Analyze market conditions and identify trading opportunities
  • Safe Order Workflow - Step-by-step guidance for placing orders safely
  • User Greetings - Generate personalized greetings (friendly/formal/casual)

System Features

  • Mock market data with scheduled price fluctuations (every 10 seconds)
  • Order validation (cash/share sufficiency)
  • Asynchronous order execution
  • Multi-currency support (USD, EUR, JPY)
  • Thread-safe concurrent operations
  • Comprehensive logging

Prerequisites

  • Java 17 or higher
  • Maven 3.6+
  • Spring Boot 3.5.6
  • Spring AI 1.1.0

Installation

  1. Clone the repository:
git clone <repository-url>
cd mcp-server
  1. Build the project:
./mvnw clean install
  1. Run the application:
./mvnw spring-boot:run

The server will start on port 9901 by default.

Configuration

Key configuration options in application.properties:

# Application
spring.application.name=eq-oms-mcp-server
server.port=9901

# MCP Server Settings
spring.ai.mcp.server.type=sync
spring.ai.mcp.server.protocol=STREAMABLE
spring.ai.mcp.server.streamable-http.keep-alive-interval=30s

# Thread Pool
spring.task.execution.pool.core-size=4
spring.task.execution.pool.max-size=8
spring.task.execution.pool.queue-capacity=100

MCP Tools Reference

1. place_equity_order

Places a new equity order (BUY or SELL).

Parameters:

  • clientId (required) - Client identifier
  • symbol (required) - Ticker symbol (e.g., AAPL, GOOGL, TSLA)
  • side (required) - Order direction: BUY or SELL
  • quantity (required) - Number of shares (positive integer)
  • orderType (required) - MARKET, LIMIT, or STOP
  • limitPrice (optional) - Required for LIMIT orders
  • stopPrice (optional) - Required for STOP orders
  • cashAccountId (required) - Valid cash account ID

Example:

{
  "clientId": "CLIENT123",
  "symbol": "AAPL",
  "side": "BUY",
  "quantity": 10,
  "orderType": "LIMIT",
  "limitPrice": 245.00,
  "cashAccountId": "CASH-1001"
}

2. modify_equity_order

Modify an existing order.

Parameters:

  • orderId (required) - Order ID to modify
  • newQuantity (optional) - New share quantity
  • newLimitPrice (optional) - New limit price
  • newStopPrice (optional) - New stop price

3. cancel_equity_order

Cancel an existing order.

Parameters:

  • orderId (required) - Order ID to cancel

4. get_order_status

Get the current status of an order.

Parameters:

  • orderId (required) - Order ID to query

5. get_market_price

Get current market price for a symbol.

Parameters:

  • symbol (required) - Stock symbol (e.g., AAPL, GOOGL)

6. get_cash_accounts

Retrieve cash accounts for a client.

Parameters:

  • clientId (required) - Client ID
  • currency (optional) - Filter by currency (e.g., USD, EUR)

7. list_active_orders

List all active (non-filled, non-cancelled) orders.

Parameters:

  • symbol (optional) - Filter by symbol

8. get_order_history

Get order history with optional filters.

Parameters:

  • symbol (optional) - Filter by symbol
  • status (optional) - Filter by status (FILLED, CANCELLED, etc.)
  • clientId (optional) - Filter by client ID

9. get_positions

Get current stock positions for a client.

Parameters:

  • clientId (required) - Client ID
  • symbol (optional) - Filter by symbol

10. greet

Simple greeting tool.

Parameters:

  • Meta data containing userName

MCP Prompts Reference

market_analysis

Analyze current market conditions and identify trading opportunities.

Parameters:

  • symbols - Symbols to analyze (comma-separated)
  • analysisType - Technical, Fundamental, or Both

greet_user

Generate a greeting message with specified style.

Parameters:

  • name (required) - User's name
  • style (optional) - friendly, formal, or casual (default: friendly)

safe_order_workflow

Provides step-by-step workflow for placing orders safely:

  1. Call get_cash_accounts to find a valid account
  2. Call get_market_price to check current price
  3. Verify sufficient funds (price × quantity ≤ balance)
  4. Call place_equity_order

Architecture

Project Structure

src/main/java/com/rk/mcp/
├── McpServerApplication.java          # Main application entry point
└── tools/
    ├── EquityOrderMgmtTools.java      # Trading MCP tools
    ├── MiscellaneousTools.java        # Utility MCP tools
    ├── McpServerPrompts.java          # MCP prompts
    ├── McpServerResources.java        # Trading rules resource
    ├── model/                          # Data models (14 classes)
    │   ├── Order.java
    │   ├── Position.java
    │   ├── OrderStatus.java
    │   ├── CashAccount.java
    │   ├── MarketData.java
    │   └── ...
    └── service/                        # Business logic (9 classes)
        ├── OrderService.java
        ├── OrderExecutionService.java
        ├── OrderValidationService.java
        ├── CashAccountService.java
        ├── PositionService.java
        ├── MarketDataServiceImpl.java
        ├── MarketPriceService.java
        └── NotificationService.java

Key Components

  • EquityOrderMgmtTools - Exposes trading operations as MCP tools
  • OrderService - Core order management logic
  • OrderExecutionService - Asynchronous order execution
  • OrderValidationService - Order validation rules
  • CashAccountService - Cash account management and balance adjustments
  • PositionService - Position tracking and P&L calculation
  • MarketDataServiceImpl - Mock market data with simulated price updates

Market Data Simulation

The server includes pre-configured market data for popular symbols:

  • US Stocks: AAPL, GOOGL, MSFT, TSLA, AMZN, META, NVDA
  • European: SAP (EUR)
  • Asian: SONY (JPY)

Prices fluctuate by ±0.5% every 10 seconds to simulate real market conditions.

Order Workflow

Safe Order Placement

  1. Validate Account - Ensure cash account exists and has NORMAL status
  2. Check Market Price - Retrieve current market price for the symbol
  3. Verify Funds - For BUY orders: price × quantity ≤ account balance
  4. Verify Shares - For SELL orders: ensure sufficient shares in position
  5. Place Order - Submit order with validated parameters
  6. Monitor Status - Track order execution status

Order Execution Flow

  1. Order validated and created with PENDING status
  2. Order stored in concurrent order map
  3. Async execution service processes the order
  4. On fill: Cash balance/positions updated
  5. Notifications sent on status changes

Development

Running Tests

./mvnw test

Building for Production

./mvnw clean package
java -jar target/mcp-0.0.1-SNAPSHOT.jar

Logging Configuration

Adjust logging levels in application.properties:

logging.level.io.modelcontextprotocol=DEBUG
logging.level.com.rk.mcp=DEBUG

API Client Integration

Connect to the MCP server using any MCP-compatible client:

Endpoint: http://localhost:9901
Protocol: STREAMABLE (HTTP-based)
Keep-Alive Interval: 30 seconds

Security Considerations

This is a development/demo server with mock data. For production use:

  • Implement proper authentication/authorization
  • Add API rate limiting
  • Secure sensitive endpoints
  • Use real market data feeds
  • Implement comprehensive audit logging
  • Add transaction rollback mechanisms
  • Implement proper error handling for failed orders

Known Limitations

  • Mock market data only (not connected to real exchanges)
  • No persistent storage (in-memory only)
  • No real-time WebSocket feeds
  • Basic test coverage
  • No multi-user session management

License

[Add your license information here]

Contributing

[Add contribution guidelines here]

Support

For issues or questions, please open an issue in the repository.