goodgo-platform/docs/audits/MCP_QUICK_REFERENCE_2.md

# Module MCP - Tài Liệu Tham Khảo Nhanh & Hướng Dẫn Kiểm Thử

## 📋 Tổng Quan Module

| Khía Cạnh | Chi Tiết |
|--------|---------|
| **Vị Trí** | `apps/api/src/modules/mcp/` |
| **Tổng Số Tệp** | 4 tệp nguồn |
| **Tệp Kiểm Thử** | 1 tệp kiểm thử (174 dòng) |
| **Kiến Trúc** | Chỉ có tầng Presentation |
| **Framework Kiểm Thử** | Vitest |
| **Độ Phủ Kiểm Thử** | Controller được kiểm thử đầy đủ ✅ |

## 📁 Danh Sách Tệp Đầy Đủ

```
Các Tệp Module MCP:
✅ index.ts (1 dòng)
✅ mcp.module.ts (22 dòng)
✅ presentation/mcp-transport.controller.ts (102 dòng)
✅ presentation/__tests__/mcp-transport.controller.spec.ts (174 dòng)
```

## 🏗️ Kiến Trúc

### Hiện Tại (Đơn Giản Hóa - Chỉ Có Tầng Presentation)
```
Tầng Presentation ✅
├── McpTransportController
│   ├── GET /mcp/servers
│   ├── GET /mcp/:serverName/sse  
│   └── POST /mcp/:serverName/messages
└── Kiểm Thử (174 dòng)

McpIntegrationModule (22 dòng)
├── Cấu hình module
├── Thiết lập service
└── Vòng đời module
```

### Các Tầng Còn Thiếu (Chưa Được Triển Khai)
```
❌ Tầng Domain (không có entity, event, business logic)
❌ Tầng Application (không có handler, command, query)
❌ Tầng Infrastructure (không có repository, adapter)
```

## 🧪 Tổng Quan Kiểm Thử

### Tệp Kiểm Thử: mcp-transport.controller.spec.ts (174 dòng)
- **Tổng Số Kiểm Thử**: 11
- **Bộ Kiểm Thử**: 4 khối describe
- **Độ Phủ**: 100% các endpoint của controller

### Phân Tích Kiểm Thử
```
1. Decorator Bảo Mật (4 kiểm thử)
   ├── JwtAuthGuard được áp dụng
   ├── Giới hạn tốc độ listServers (30 yêu cầu/60 giây)
   ├── Giới hạn tốc độ handleSse (5 yêu cầu/60 giây) ⚡ chặt chẽ hơn
   └── Giới hạn tốc độ handleMessage (30 yêu cầu/60 giây)

2. listServers (2 kiểm thử)
   ├── Trả về danh sách server
   └── Xử lý danh sách rỗng

3. handleSse (3 kiểm thử)
   ├── Ném NOT_FOUND khi server không tồn tại
   ├── Tạo transport & kết nối
   └── Dọn dẹp khi đóng kết nối

4. handleMessage (2 kiểm thử)
   ├── Ném BAD_REQUEST khi thiếu sessionId
   └── Ném NOT_FOUND khi session đã hết hạn
```

## 🎯 Các Lớp Chính

### McpIntegrationModule
```typescript
class McpIntegrationModule implements OnModuleInit {
  constructor(
    typesenseClient: TypesenseClientService,
    mcpRegistry: McpRegistryService,
    logger: LoggerService,
  ) {}
  
  async onModuleInit(): Promise<void> {
    // Thiết lập typesense client, khởi tạo lại server, ghi log kết quả
  }
}
```

### McpTransportController
```typescript
@Controller('mcp')
@UseGuards(JwtAuthGuard)
class McpTransportController {
  listServers(): { servers: string[] }
  
  async handleSse(serverName, user, req, res): Promise<void>
  
  async handleMessage(serverName, user, req, res): Promise<void>
}
```

## 🔧 Các Mẫu Kiểm Thử

### Mock Module
```typescript
vi.mock('@goodgo/mcp-servers', () => ({
  SSEServerTransport: class MockSSE {
    sessionId = 'mock-session-id';
    handlePostMessage = vi.fn().mockResolvedValue(undefined);
  },
}));
```

### Mock Service
```typescript
mockRegistry = {
  getServerNames: vi.fn(),
  getServer: vi.fn(),
};
```

### Xác Minh Decorator
```typescript
const guards = Reflect.getMetadata('__guards__', McpTransportController);
const throttleLimit = Reflect.getMetadata('THROTTLER:LIMITdefault', method);
```

## 📚 Ví Dụ Kiểm Thử Từ Các Module Khác

### Mẫu Module Auth (Đơn Giản)
- Ít phụ thuộc
- Khởi tạo handler trực tiếp
- Tập trung vào xác minh hành vi

### Mẫu Module Payments (Phức Tạp)
- Nhiều mock phụ thuộc
- Kiểm thử quy tắc nghiệp vụ
- Xác minh event bus

### Mẫu Domain Entity
- Import vitest tường minh
- Kiểm thử chuyển đổi trạng thái
- Xác minh domain event
- Xử lý lỗi với kiểu Result

### Mẫu Infrastructure
- Mô phỏng dịch vụ bên ngoài
- Kiểm thử bảo mật (crypto)
- Các builder dữ liệu kiểm thử phức tạp

## 🚀 Chạy Kiểm Thử

```bash
# Chạy tất cả kiểm thử MCP
pnpm test -- src/modules/mcp

# Chạy ở chế độ watch
pnpm test -- --watch src/modules/mcp

# Chạy với coverage
pnpm test -- --coverage src/modules/mcp

# Chạy kiểm thử cụ thể
pnpm test -- src/modules/mcp/presentation/__tests__/mcp-transport.controller.spec.ts
```

## 💡 Khuyến Nghị

### Ưu Tiên Cao
- ✅ Controller được kiểm thử tốt - duy trì điều này
- 📝 Thêm kiểm thử cho McpIntegrationModule.onModuleInit()
- 📝 Kiểm thử dependency injection của module

### Ưu Tiên Thấp Hơn
- 🏗️ Nếu thêm domain logic, theo mẫu payments
- 🏗️ Nếu thêm handler, sử dụng mẫu CQRS
- 🏗️ Thêm kiểm thử tích hợp cho vòng đời SSE