E-Commerce MCP Server
felixhuhao/ecommerce-mcp-server
Backend MCP para assistentes de IA em e-commerce com aprovação de operações
Ver no GitHubServidor Spring Boot que expõe capacidades de negócio de e-commerce como ferramentas MCP, com backend MySQL e aprovação human-in-the-loop para operações críticas. Gerencia produtos, inventário, clientes, pedidos e fornecedores, com controle de segurança através de tokens de aprovação vinculados a atores confiáveis.
Instalação
npx convez-ai felixhuhao/ecommerce-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Integrar assistentes de IA com sistemas de e-commerce existentes
- Automatizar operações de pedidos e inventário com verificação humana
- Consultar dados de produtos, clientes e fornecedores via MCP tools
- Gerenciar ordens de compra com fornecedores de forma segura
Veredito

Solução robusta e bem-estruturada para integração de IA em sistemas e-commerce reais. Implementação madura com segurança, testes containerizados e aprovação HITL, mas requer expertise em Java/Spring e infra MySQL para operação.
README
A tradução para o português deste README ainda está na fila.
E-Commerce MCP Server
Spring Boot MCP server for an e-commerce AI assistant. This service owns the MySQL-backed business data, exposes read/write business capability as MCP tools, and enforces human-in-the-loop approval for risky writes.
Detailed design lives in docs/2026-06-05-ecommerce-mcp-server-spec.md.
What This Service Owns
- Product, inventory, customer, order, supplier, and purchase-order queries
- Supplier purchase-order creation and receiving
- Customer order fulfillment status updates
- Server-side approval payload generation, hashing, binding, expiry, and one-time consumption
- Streamable HTTP MCP endpoint at
/mcp
The Python/Agent project owns orchestration, LangGraph checkpoints, frontend HITL flow, sandbox tools, and visualization MCP servers.
Tech Stack
- Java 21
- Spring Boot 4.0.6
- Spring AI MCP Server WebMVC 2.0.0-M8
- MyBatis-Plus 3.5.x
- MySQL 8
- JUnit 5 + Testcontainers MySQL
- Maven Wrapper
MCP Tools
Read tools:
product_queryproduct_searchorder_queryinventory_queryinventory_low_stockuser_querysupplier_querysupplier_toppurchase_order_queryget_statistics
Write/approval tools:
request_approvalpurchase_order_createpurchase_order_receiveorder_update
Write tools require a valid approval_id. Approvals are bound to the trusted actor, session, tool name, canonical operation payload, and are one-time use.
Prerequisites
- Java 21
- Docker, required for tests
- MySQL 8 on port
3306, required for local app runtime - Maven is optional because the repo includes
./mvnw
Configuration
Runtime config is read from src/main/resources/application.properties. Local secrets should go in .env.properties, which is ignored by git.
Create .env.properties in the project root:
DB_USERNAME=your_mysql_user
DB_PASSWORD=your_mysql_password
APP_SERVICE_TOKEN=dev-service-token
APP_SERVICE_TOKEN is required for all non-actuator HTTP requests. If it is blank, /mcp and /approvals/* return 401.
Database Setup
The app expects database ecommerce_db.
Load schema and seed data into local MySQL:
mysql -u root -p < src/main/resources/schema.sql
mysql -u root -p ecommerce_db < src/main/resources/data.sql
schema.sql creates the database if needed. data.sql seeds products, users, suppliers, inventory, orders, purchase orders, reviews, and approval tables.
Run Tests
Tests use the test profile and Testcontainers:
./mvnw test
This starts a temporary MySQL container and initializes it from the same schema.sql and data.sql. Tests do not require a local MySQL server on port 3306, but they do require Docker.
Run a focused test class:
./mvnw -Dtest=StatsMapperTest test
Run Locally
After configuring .env.properties and loading MySQL data:
./mvnw spring-boot:run
Health check:
curl http://localhost:8080/actuator/health
MCP endpoint:
POST http://localhost:8080/mcp
Non-actuator requests must include:
X-Service-Token: dev-service-token
X-User-Id: 1
X-Session-Id: local-session
The TrustedActorFilter derives the actor from these headers. Tool parameters never accept userId or sessionId directly.
Run With Docker
The Docker setup runs only the Spring Boot app. It assumes MySQL is already running and already seeded.
chmod +x scripts/docker-run.sh
./scripts/docker-run.sh
The script builds ecommerce-mcp-server:local, removes any existing container named
ecommerce-mcp-server, then starts the app on port 8080.
By default the container connects to MySQL through:
host.docker.internal:3306/ecommerce_db
You can override these values:
MYSQL_HOST=host.docker.internal \
MYSQL_PORT=3306 \
MYSQL_DATABASE=ecommerce_db \
APP_PORT=8080 \
./scripts/docker-run.sh
Required secrets still come from .env.properties or the environment:
DB_USERNAME=your_mysql_user
DB_PASSWORD=your_mysql_password
APP_SERVICE_TOKEN=dev-service-token
The Docker app runtime does not run schema.sql or data.sql; database setup remains manual or test-only.
Approval Flow
- Agent calls
request_approvalwith a write tool name and structured operation params. - Java reads live DB state, builds the canonical authorization payload, renders the approval detail, hashes the payload, and stores
approval_record. - Human approval happens through REST, not MCP:
GET /approvals/{id}
POST /approvals/{id}/approve
POST /approvals/{id}/reject
- Agent retries the write tool with the same operation params and the returned
approval_id. - Java verifies approval status, actor/session binding, tool binding, payload hash, expiry, and one-time use before executing the write.
Approval records default to a 15-minute TTL. Expired open approvals are lazily marked expired when read, approved/rejected, or consumed.
Statistics Semantics
get_statistics returns aggregation-first data for:
- Inventory health
- Orders by status
- Products by category
- Purchase orders by status
- Top products by revenue
Top products use realized sales only: paid, shipped, and completed orders. pending and cancelled orders are excluded.
Project Layout
src/main/java/com/ecommerce/agent/
├── approval/ canonical approval payload/detail builder
├── auth/ trusted actor context
├── config/ request auth and app config
├── controller/ approval REST endpoints, not MCP tools
├── domain/ database domain objects
├── dto/ tool and service response DTOs
├── mapper/ MyBatis/MyBatis-Plus mappers
├── service/ business logic and approval enforcement
└── tool/ Spring AI @McpTool classes
Useful Commands
./mvnw test
./mvnw spring-boot:run
./scripts/docker-run.sh
git status --short
Current Scope
The Java MCP server scope is implemented: read tools, write tools, HITL enforcement, REST approval transitions, Testcontainers-backed tests, and get_statistics.
Cross-project end-to-end verification from the Python MultiServerMCPClient caller is intentionally left to the parent Agent project.