Keeping you up to date on AI and Model Context Protocol (MCP)

MCP API Service

Máy chủ Model Context Protocol (MCP) để tương tác với các API hệ thống nội bộ

Kiến Trúc Hệ Thống

Tổng Quan

MCP API Service là một máy chủ trung gian hoạt động theo giao thức Model Context Protocol (MCP), giúp kết nối Claude AI với các API hệ thống nội bộ. Hệ thống này:

Nhận lệnh từ Claude: Người dùng yêu cầu thực hiện một tác vụ thông qua Claude
Xử lý và chuyển đổi: MCP chuyển đổi các yêu cầu từ người dùng sang định dạng API nội bộ
Gọi API: Thực hiện cuộc gọi đến các API nội bộ
Trả kết quả: Kết quả được định dạng và trả về Claude để hiển thị cho người dùng

Cơ Chế Hoạt Động

Máy chủ MCP hoạt động bằng cách giao tiếp qua stdio (standard input/output):

Standard Input (stdin): Nhận yêu cầu từ Claude (ví dụ: lệnh tìm kiếm nhân viên)
Standard Output (stdout): Trả kết quả về cho Claude (ví dụ: thông tin nhân viên tìm được)
Standard Error (stderr): Ghi log lỗi (ví dụ: lỗi kết nối đến API)

Quy trình khi một yêu cầu được gửi:

Claude gửi yêu cầu dạng JSON qua stdin
MCP Server xử lý yêu cầu và gọi API thích hợp
MCP Server trả kết quả về cho Claude qua stdout
Claude hiển thị kết quả cho người dùng

Tính Năng (Kịch Bản)

Các kịch bản hiện có:

check_connection - Kiểm tra kết nối tới API server
search_employee - Tìm kiếm nhân viên theo tên hoặc mã
register_breakfast - Đăng ký ăn sáng cho nhân viên
update_hoa_chat - Cập nhật thông tin hóa chất theo ca
chuyen_nhan_vien_thi_cong - Chuyển nhân viên thi công giao khoán

Thêm Kịch Bản Mới

1. Thêm Endpoint

Định nghĩa endpoint mới trong src/config.ts:

export const CONFIG = {
  // ...existing code...
  TOOLS: {
    // ...existing code...
    TEN_NHOM_API: {
      ACTION_API: '/api/services/app/TenService/TenAction'
    }
  }
}

2. Thêm Interface

Tạo interface trong src/types.ts cho dữ liệu đầu vào/đầu ra:

export interface TenActionInput {
  Param1: string;
  Param2: number;
  // Các tham số khác...
}

3. Tạo Service Mới hoặc Thêm Vào Service Hiện Có

Tạo file mới trong src/services/ hoặc thêm vào service hiện có:

// src/services/ten-service.service.ts
import { TenActionInput } from '../types.js';
import { ApiClient } from '../utils/api-client.js';
import { Logger } from '../utils/logger.js';
import { CONFIG } from '../config.js';

export class TenService {
  private logger = new Logger();

  async tenAction(input: TenActionInput) {
    try {
      this.logger.debug('Calling ten action API', {
        url: CONFIG.TOOLS.TEN_NHOM_API.ACTION_API,
        input
      });
      
      const response = await ApiClient.post(
        CONFIG.TOOLS.TEN_NHOM_API.ACTION_API, 
        null,
        { params: input }
      );
      
      this.logger.info('Action completed successfully', { input });
      return response.result;
    } catch (error) {
      this.logger.error('Error performing action', { error, input });
      throw error;
    }
  }
}

4. Cập Nhật Index

Trong src/index.ts:

Thêm service mới (nếu có)
Định nghĩa tool mới trong danh sách tools
Thêm case xử lý trong hàm handleToolCall

Phát Triển

Cài đặt thư viện:

npm install

Build server:

npm run build

Chạy chế độ phát triển với tự động build lại:

npm run watch

Gỡ Lỗi

Thách Thức

Việc gỡ lỗi MCP gặp khó khăn vì:

Không thể đặt breakpoint như ứng dụng thông thường
Khó theo dõi luồng dữ liệu vào/ra
Log lỗi có thể bị trộn lẫn với output

Giải Pháp

Sử dụng MCP Inspector để:

Theo dõi yêu cầu gửi đến máy chủ
Xem kết quả trả về của từng yêu cầu
Kiểm tra log lỗi riêng biệt
Giám sát hiệu năng

Khởi động Inspector:

npm run inspector

Inspector sẽ cung cấp URL truy cập giao diện web để theo dõi hoạt động của hệ thống.

Best Practices

Nhất Quán
- Tuân thủ cấu trúc đặt tên hiện có
- Sử dụng mẫu code đã được thiết lập
Xử Lý Lỗi
- Luôn implement try/catch
- Log đầy đủ thông tin lỗi
- Trả về thông báo lỗi rõ ràng
Logging
- Log đầy đủ các bước: debug trước khi gọi API, info khi thành công
- Bao gồm đầy đủ parameters trong log
Validation
- Kiểm tra tham số bắt buộc
- Validate kiểu dữ liệu của input

Xem thêm chi tiết trong docs/add-new-scenario.md.