surajbadhe/ecommerce-mcp-server

E-commerce MCP Server with Spring AI

Table of Contents

• Description
• Architecture
• Key Features
• Getting Started
  • Prerequisites
    • Installation
• Usage
• Configuration
• Available Tools
• Contributing
• Contact

Description

This project is an intelligent Model Context Protocol (MCP) Server built with Java and Spring AI. It acts as a "toolbelt" for an AI, bridging the gap between a natural language model (LLM) and a traditional e-commerce REST API.

Instead of exposing standard CRUD endpoints, this server exposes the core functionalities of an e-commerce backend (like searching for products or adding items to a cart) as discrete tools. These tools can be discovered and executed by an MCP client, allowing for complex, natural language-driven interactions with the e-commerce platform.

Architecture

This MCP server is a middle layer that sits between an MCP client (which handles the AI logic) and your core business logic API.

Key Features

• Model Context Protocol (MCP) Compliant: Follows the MCP standard for AI-to-tool communication.
• AI Tool Exposure: Exposes e-commerce functions as well-defined tools for an LLM.
• Powered by Spring AI: Leverages the powerful spring-ai-starter-mcp-server for implementation.
• Dual Transport Support: Can be run in two modes:
  • STDIO: For local interaction with clients like Claude Desktop.
    • HTTP (SSE): For network-based interaction with clients like Postman or custom gateways.
• Decoupled Design: Separates the AI interaction layer from the core e-commerce business logic.

Getting Started

Prerequisites

• Java JDK 21
• Maven 3.8.1 or higher
• A running instance of the E-commerce REST API (this server depends on it):
  E-commerce Store Spring

Installation

1. Clone the repository:

	 git clone https://github.com/surajbadhe/ecommerce-mcp-server.git
	 cd ecommerce-mcp-server

2. Build the project using Maven:

	 mvn clean install

Usage

This server can be run in two modes, configured in application.properties. You interact with it using an MCP client, not by calling REST endpoints directly.

1. Running in HTTP Mode

• Recommended for connecting to Postman or your custom MCP Client Gateway.

• Run:

	java -jar target/ecommerce-mcp-server-<version>.jar

• Connect:
  • MCP client connects to SSE endpoint: http://localhost:8089/mcp/sse

2. Running in STDIO Mode

• For local use with clients like Claude Desktop.
• Configuration:
  • Set spring.main.web-application-type=none
  • Set 'spring.main.banner-mode=off'
• Run:

	java -jar target/ecommerce-mcp-server-<version>.jar

• Connect:
  • MCP client connects directly to the running Java process.

You can also run the application using Maven:

mvn spring-boot:run

The server will start on the configured port (default: 8089). All interactions are via MCP clients.

Configuration

Application settings are managed in src/main/resources/application.properties.

Key properties to configure:

• server.port: The port for the server to run on in HTTP mode (e.g., 8089)
• spring.ai.mcp.server.transport-type: The transport mode (HTTP or STDIO)
• ecommerce.api.base.url: The URL of the main e-commerce REST API (e.g., http://localhost:8088)

To modify settings, edit the application.properties file and restart the application.

Available Tools

This server exposes the following functions from the e-commerce API as tools:

• getProducts: Get a list of available products, with optional filters for brand and type.
• getProductById: Get the details of a single product.
• getBrands: Get a list of all product brands.
• getTypes: Get a list of all product types.
• getUserBasket: Get the current user's shopping basket.
• addItemToBasket: Add a product to the user's basket.
• removeItemFromBasket: Remove a product from the user's basket.
• createOrder: Create an order from a basket.
• getOrderById: Get the details of a specific order.

Building & Deployment

To build a deployable JAR file:

mvn clean package

Deploy the JAR to any Java 17+ environment:

java -jar target/ecommerce-mcp-server-<version>.jar

Contributing

Contributions are welcome! To contribute:

• Fork the repository and create a feature branch
• Follow standard Java and Spring Boot coding conventions
• Submit pull requests with a description of changes
• Report bugs or request features via GitHub Issues

Contact

Maintainer: Suraj Badhe
GitHub: surajbadhe