Content
# Tool List
Based on DDD hexagonal architecture of MCP (Model Context Protocol) gateway service, proxying multiple MCP Server, providing a unified access point for AI clients. Supports OpenAPI protocol automatic parsing, SSE transmission, authentication and current limiting, and embedded LLM one-click testing.
## Features
- **MCP SSE Gateway** — Proxying multiple backend HTTP services, exposing a unified MCP SSE endpoint
- **OpenAPI Automatic Parsing** — Import Swagger JSON, automatically generate protocol configuration and field mapping
- **Authentication + Current Limiting** — API Key strong verification, Guava token bucket dimension current limiting
- **Management Console** — Gateway/tool/protocol/authentication full life cycle management, day/night mode
- **LLM Embedded Testing** — Management end direct messaging, LLM through gateway to MCP tool verification full link
- **DDD Hexagonal Architecture** — 7 module stratification, dependency inversion, bloated model
## Effects Display
<table>
<tr>
<td align="center"><b>Management Background Overview</b></td>
<td align="center"><b>LLM Gateway Test</b></td>
</tr>
<tr>
<td><img src="docs/images/admin-dashboard.png" alt="Management Background Overview" width="480" /></td>
<td><img src="docs/images/admin-llm-test.png" alt="LLM Gateway Test" width="480" /></td>
</tr>
<tr>
<td align="center" colspan="2"><b>Protocol Mapping Expansion</b></td>
</tr>
<tr>
<td align="center" colspan="2"><img src="docs/images/admin-protocol-mapping.png" alt="Protocol Mapping Expansion" width="480" /></td>
</tr>
</table>
## Technical Stack
JDK 21 · Spring Boot 3.5 · Spring AI 1.1.2 · MyBatis · MySQL 8.0 · Project Reactor · Guava · Retrofit2
## Quick Start
**Environmental Requirements:** JDK 21, Maven 3.9, Docker
### Local Development
```bash
# 1. Start MySQL
docker compose -f docs/dev-ops/docker-compose-environment.yml up -d
# 2. Start demo-server (optional, for testing gateway HTTP routing)
git clone https://github.com/laterya/mcp-gateway-demo-server.git ../mcp-gateway-demo-server
cd ../mcp-gateway-demo-server && mvn spring-boot:run
# 3. Start gateway
mvn spring-boot:run -pl mcp-gateway-app
```
After the gateway starts, visit:
- Management Console: `http://localhost:8090/api-gateway/index.html` (`admin` / `password123`)
- MCP SSE Endpoint: `http://localhost:8090/api-gateway/{gatewayId}/mcp/sse`
### Docker Deployment
```bash
docker pull ghcr.io/laterya/mcp-gateway:latest
docker run -d --name mcp-gateway \
-p 8090:8090 \
-e SPRING_DATASOURCE_URL='jdbc:mysql://YOUR_MYSQL_HOST:3306/mcp_gateway?...' \
-e SPRING_DATASOURCE_USERNAME=root \
-e SPRING_DATASOURCE_PASSWORD=your-password \
ghcr.io/laterya/mcp-gateway:latest
```
The image only contains the Gateway application, and MySQL needs to be provided by itself and pointed to through environment variables.
### Configure LLM (optional)
Set environment variables to enable the embedded LLM test function:
```bash
export OPENAI_API_KEY=your-key
export OPENAI_BASE_URL=your-proxy-url
export OPENAI_MODEL=gpt-5.2 # Optional, default gpt-5.2
```
## Architecture
```
┌──────────────────────────────────┐
│ Admin Console │
│ (Management Console · Static HTML) │
└──────────────┬───────────────────┘
│
┌──────────┐ SSE ┌───────────▼────────────┐ HTTP/LLM ┌──────────────┐
│ AI Client │◄────────►│ MCP Gateway │◄──────────────►│ Backend HTTP Service │
│ (Claude etc.) │ │ (SSE + JSON-RPC) │ │ (demo-server)│
└──────────┘ └────────────────────────┘ └──────────────┘
```
### Module Structure
```
trigger ──→ case ──→ domain
│ │ │
│ └── types ┘
│
infrastructure (implement domain Port)
api (DTO + Facade interface)
app (Spring Boot startup module)
```
| Module | Responsibility |
|------|------|
| `types` | General response, constants, exceptions |
| `domain` | 6 bounded contexts: session / auth / protocol / gateway / admin / llm |
| `case` | Use case orchestration, responsibility chain (session creation / message processing / Admin CRUD) |
| `infrastructure` | Port implementation, MyBatis DAO, HTTP client |
| `api` | External Facade interface + DTO |
| `trigger` | HTTP Controller |
| `app` | Spring Boot startup module, assembly layer |
### MCP Call Process
```
1. AI Client GET /{gatewayId}/mcp/sse → Establish SSE connection
2. Gateway returns endpoint event (including sessionId) → Handshake completed
3. AI Client POST initialize → Tool list pull
4. AI Client POST tools/call → Gateway routes to backend HTTP interface → Return result
```
## Data Model
```
mcp_gateway ──1:1── mcp_gateway_auth
│
└──1:N── mcp_gateway_tool
│
└──N:1── mcp_protocol_http
│
└──1:N── mcp_protocol_mapping
```
- **gateway** — Gateway configuration (name, version, authentication mode)
- **auth** — API Key + rate limit + expiration time
- **tool** — MCP tool description (name, type, binding protocol)
- **protocol_http** — HTTP protocol details (URL, method, timeout)
- **protocol_mapping** — MCP field ↔ HTTP field mapping (request + response)
## Common Commands
```bash
mvn clean install -DskipTests # Full build
mvn spring-boot:run -pl mcp-gateway-app # Start gateway
mvn test -pl mcp-gateway-app # Run test
mvn test -pl mcp-gateway-app -Dtest="cn.laterya.ai.dao.**" # DAO test
mvn test -pl mcp-gateway-app -Dtest="cn.laterya.ai.domain.auth.**" # Authentication test
```
## Project Structure
```
mcp-gateway/
├── mcp-gateway-app/ # Startup module (application.yml, MyBatis mapper, static resources)
├── mcp-gateway-api/ # External interface + DTO
├── mcp-gateway-case/ # Use case orchestration (responsibility chain, Admin orchestration, LLM orchestration)
├── mcp-gateway-domain/ # Domain layer (6 bounded contexts)
├── mcp-gateway-infrastructure/ # Infrastructure (DAO, Repository, HTTP Client)
├── mcp-gateway-trigger/ # HTTP Controller
├── mcp-gateway-types/ # General type
├── Dockerfile # Multi-stage build (Maven → JRE)
├── docs/
│ ├── images/ # Effect screenshot
│ └── dev-ops/
│ ├── docker-compose-environment.yml # Local development MySQL
│ └── mysql/sql/ai_mcp_gateway.sql # Create table + seed data
```
