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

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

@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

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

Mock Service

mockRegistry = {
  getServerNames: vi.fn(),
  getServer: vi.fn(),
};

Xác Minh Decorator

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ử

# 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