README.md•10.7 kB
# MCP SSE Server Python
Model Context Protocol (MCP) Server với SSE transport được viết bằng Python, tích hợp với n8n instance tại `n8n-prod.iconiclogs.com`.
## Tính năng
- **MCP Protocol Implementation**: Triển khai đầy đủ MCP protocol với JSON-RPC 2.0
- **SSE Transport**: Server-Sent Events để real-time communication
- **n8n Integration**: Webhook endpoints để tích hợp với n8n workflows
- **Natural Language Support**: Hỗ trợ Tiếng Việt và English cho queries
- **Async API Calls**: Gọi 5 APIs của hệ thống ABC song song với asyncio
- **Health Monitoring**: Health check và Prometheus metrics
- **Production Ready**: Docker support, graceful shutdown, comprehensive logging
## Kiến trúc
```
mcp-sse-server-python/
├── src/
│ ├── main.py # FastAPI application
│ ├── models.py # Pydantic models
│ ├── mcp_protocol.py # MCP protocol handler
│ ├── sse_handler.py # SSE connection manager
│ ├── api_client.py # Async HTTP client cho ABC system
│ ├── n8n_integration.py # n8n webhook handler
│ └── tools/
│ ├── nlp_parser.py # Natural language parser
│ └── system_check.py # System check tool
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md
```
## 5 APIs của Hệ thống ABC
1. **GET /api/system/health** - Kiểm tra system health
2. **GET /api/users/status** - Lấy user status
3. **GET /api/services/list** - Danh sách services
4. **POST /api/logs/query** - Query logs với timeframe
5. **GET /api/metrics/current** - Metrics hiện tại
## Cài đặt
> **🚀 DEMO MODE**: Không có API thật? Xem [DEMO.md](DEMO.md) để chạy ngay với Mock API!
### Yêu cầu
- Python 3.11+
- Docker & Docker Compose (optional)
- n8n instance tại `n8n-prod.iconiclogs.com` (optional cho demo)
- API key cho ABC System (hoặc dùng Mock API)
### 1. Clone và Setup
```bash
cd mcp-sse-server-python
# Copy .env.example thành .env
cp .env.example .env
# Chỉnh sửa .env với thông tin thực tế
nano .env
```
### 2. Cấu hình .env
```bash
# ABC System Configuration
ABC_SYSTEM_BASE_URL=https://api.abc.com
ABC_API_KEY=your_actual_api_key_here
# n8n Integration
N8N_INSTANCE_URL=n8n-prod.iconiclogs.com
N8N_API_KEY=your_n8n_api_key_here
N8N_WEBHOOK_PATH=mcp-system-check
```
### 3. Installation Options
#### Option A: Local Python
```bash
# Tạo virtual environment
python3.11 -m venv venv
source venv/bin/activate # Linux/Mac
# hoặc: venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
# Run server
python src/main.py
```
#### Option B: Docker
```bash
# Build và run với Docker Compose
docker-compose up -d
# Xem logs
docker-compose logs -f mcp-server
# Stop
docker-compose down
```
#### Option C: Docker only (không compose)
```bash
# Build image
docker build -t mcp-sse-server .
# Run container
docker run -d \
-p 3001:3001 \
--name mcp-server \
--env-file .env \
mcp-sse-server
```
## API Endpoints
### SSE Endpoint
```bash
# Kết nối SSE cho MCP protocol
curl -N http://localhost:3001/sse
# Với connection ID
curl -N "http://localhost:3001/sse?connection_id=my-client-123"
```
### n8n Webhook
```bash
# Gọi từ n8n workflow
POST http://localhost:3001/n8n/webhook/mcp-system-check
# Request body
{
"tool": "check_system_abc",
"params": {
"query": "Kiểm tra toàn bộ hệ thống"
}
}
```
### Health Check
```bash
# Health check
curl http://localhost:3001/health
# Liveness probe (K8s)
curl http://localhost:3001/health/live
# Readiness probe (K8s)
curl http://localhost:3001/health/ready
```
### Metrics
```bash
# Prometheus metrics
curl http://localhost:3001/metrics
```
### Information
```bash
# Server info
curl http://localhost:3001/info
# List tools
curl http://localhost:3001/tools
# List n8n tools
curl http://localhost:3001/n8n/tools
# List connections
curl http://localhost:3001/connections
```
## Sử dụng với MCP Protocol
### 1. Kết nối SSE
```javascript
const eventSource = new EventSource('http://localhost:3001/sse');
eventSource.addEventListener('connection', (e) => {
const data = JSON.parse(e.data);
console.log('Connected:', data);
});
eventSource.addEventListener('message', (e) => {
const response = JSON.parse(e.data);
console.log('MCP Response:', response);
});
eventSource.addEventListener('heartbeat', (e) => {
console.log('Heartbeat:', e.data);
});
```
### 2. Initialize MCP
```json
// Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"clientInfo": {
"name": "my-client",
"version": "1.0.0"
}
}
}
```
### 3. List Tools
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}
```
### 4. Call Tool
```json
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "check_system_abc",
"arguments": {
"query": "Kiểm tra toàn bộ hệ thống"
}
}
}
```
## Natural Language Examples
Tool `check_system_abc` hỗ trợ natural language queries:
### Tiếng Việt
```json
{"query": "Kiểm tra toàn bộ hệ thống"}
{"query": "Xem logs 24h gần đây"}
{"query": "Kiểm tra user status và services"}
{"query": "Lấy metrics hiện tại"}
{"query": "Tìm lỗi trong logs 1 giờ qua"}
```
### English
```json
{"query": "Check all systems"}
{"query": "Get recent logs from last 24 hours"}
{"query": "Check user status and services"}
{"query": "Get current metrics"}
{"query": "Search for errors in logs from last hour"}
```
## n8n Workflow Setup
### 1. Tạo Webhook Node trong n8n
```
Workflow: MCP System Check
├── Webhook (Trigger)
│ Path: mcp-system-check
│ Method: POST
│
├── Function (Parse Input)
│ // Extract query and params
│
├── HTTP Request (Call MCP Server)
│ URL: http://mcp-server:3001/n8n/webhook/mcp-system-check
│ Method: POST
│ Body: {{$json}}
│
├── IF (Check Success)
│ Condition: {{$json.success}} === true
│
├── Send Email / Slack Notification
│ Success: ✅ System check passed
│ Error: ❌ System check failed
│
└── End
```
### 2. Trigger từ n8n Schedule
```
Workflow: Daily System Check
├── Schedule (Trigger)
│ Cron: 0 9 * * * (9 AM daily)
│
├── HTTP Request
│ URL: http://mcp-server:3001/n8n/webhook/mcp-system-check
│ Body:
│ {
│ "tool": "check_system_abc",
│ "params": {
│ "query": "Kiểm tra toàn bộ hệ thống"
│ }
│ }
│
└── Process results...
```
## Monitoring
### Prometheus Metrics
Server expose các metrics sau:
- `mcp_requests_total` - Total requests
- `mcp_request_duration_seconds` - Request duration
- `mcp_sse_connections_active` - Active SSE connections
- `mcp_tool_executions_total` - Tool executions
### Grafana Dashboard
Nếu dùng docker-compose, Grafana có sẵn tại:
- URL: http://localhost:3000
- User: `admin`
- Pass: `admin`
Import Prometheus datasource: `http://prometheus:9090`
## Development
### Run Tests
```bash
# Install dev dependencies
pip install pytest pytest-asyncio pytest-cov
# Run tests
pytest
# With coverage
pytest --cov=src --cov-report=html
```
### Code Formatting
```bash
# Format code
black src/
# Lint code
ruff check src/
# Type checking
mypy src/
```
## Production Deployment
### Docker Compose (Recommended)
```bash
# Production deployment
docker-compose -f docker-compose.yml up -d
# Scale workers
docker-compose up -d --scale mcp-server=3
```
### Kubernetes
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: mcp-server
spec:
replicas: 3
selector:
matchLabels:
app: mcp-server
template:
metadata:
labels:
app: mcp-server
spec:
containers:
- name: mcp-server
image: mcp-sse-server:latest
ports:
- containerPort: 3001
env:
- name: ABC_API_KEY
valueFrom:
secretKeyRef:
name: mcp-secrets
key: abc-api-key
livenessProbe:
httpGet:
path: /health/live
port: 3001
initialDelaySeconds: 5
periodSeconds: 30
readinessProbe:
httpGet:
path: /health/ready
port: 3001
initialDelaySeconds: 5
periodSeconds: 10
```
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `MCP_SERVER_HOST` | Server host | `0.0.0.0` |
| `MCP_SERVER_PORT` | Server port | `3001` |
| `MCP_SERVER_WORKERS` | Number of workers | `4` |
| `ABC_SYSTEM_BASE_URL` | ABC System API URL | Required |
| `ABC_API_KEY` | ABC System API key | Required |
| `ABC_TIMEOUT` | API timeout (seconds) | `30` |
| `N8N_INSTANCE_URL` | n8n instance URL | Required |
| `N8N_API_KEY` | n8n API key | Optional |
| `SSE_HEARTBEAT_INTERVAL` | SSE heartbeat interval | `30` |
| `SSE_MAX_CONNECTIONS` | Max SSE connections | `100` |
| `LOG_LEVEL` | Logging level | `INFO` |
## Troubleshooting
### 1. Connection refused
```bash
# Kiểm tra server đang chạy
curl http://localhost:3001/health
# Kiểm tra logs
docker-compose logs mcp-server
```
### 2. API timeouts
```bash
# Tăng timeout trong .env
ABC_TIMEOUT=60
# Restart server
docker-compose restart mcp-server
```
### 3. SSE không kết nối được
```bash
# Kiểm tra CORS settings
# Kiểm tra firewall/proxy
# Kiểm tra browser console
```
### 4. n8n webhook không hoạt động
```bash
# Kiểm tra n8n có thể access được MCP server
curl -X POST http://localhost:3001/n8n/webhook/test \
-H "Content-Type: application/json" \
-d '{"tool": "check_system_abc", "params": {"query": "test"}}'
```
## Security Best Practices
1. **API Keys**: Luôn dùng environment variables, không commit vào git
2. **CORS**: Configure CORS cho production (`allow_origins` trong main.py)
3. **Rate Limiting**: Implement rate limiting cho webhooks
4. **HTTPS**: Dùng HTTPS cho production (reverse proxy như nginx)
5. **Authentication**: Thêm authentication cho sensitive endpoints
## License
MIT License
## Support
- Issues: GitHub Issues
- Email: support@example.com
- Documentation: [MCP Protocol Docs](https://modelcontextprotocol.io)
## Changelog
### v1.0.0 (2024-01-17)
- Initial release
- MCP protocol support với SSE
- n8n integration
- 5 ABC System APIs
- Natural language support (VI/EN)
- Prometheus metrics
- Docker support