sf-log-mcp: Máy chủ MCP giúp AI tự động gỡ lỗi Salesforce bằng cách phát hiện lỗi ẩn

sf-log-mcp là một máy chủ MCP (Model Context Protocol) mã nguồn mở được phát triển nhằm giúp các trợ lý AI như Claude, Copilot hay Cursor có khả năng tự động lấy, phân tích và quản lý các log gỡ lỗi trên nền tảng Salesforce. Điểm đặc biệt của công cụ này là phát hiện các lỗi “im lặng” mà Salesforce thường đánh dấu là “Success” nhưng thực tế là các giao dịch hoặc tích hợp đã gặp sự cố đáng kể.

Tác giả Likhit Kumar đã xây dựng sf-log-mcp như một cầu nối giữa Salesforce và AI assistants, thay đổi hoàn toàn cách debug Salesforce vốn thường rất thủ công và mất thời gian.

Vấn đề ít ai nói tới trong debug Salesforce

Khi debug các tích hợp Salesforce, người dùng có thể quen với việc:

• Mở phần Setup > Debug Logs
• Xem toàn bộ đống log với trạng thái Status = "Success"
• Tải từng file .log về máy thủ công
• Dùng Ctrl+F để tìm kiếm lỗi trong hàng chục nghìn dòng log
• Rơi vào tình huống “giao dịch thành công” nhưng nội dung trả về lại chứa lỗi như {"error":"rate_limit_exceeded"} mặc dù HTTP code là 200

Điều này cho thấy trường Status rất thiếu chính xác và là “một lời nói dối” phổ biến – hơn 90% lỗi thực sự là silent failures (lỗi im lặng): mã không bị crash, Apex không throw lỗi không được xử lý, nhưng quy trình chính không diễn ra đúng.

Một số hình thái lỗi im lặng được phát hiện gồm:

• HTTP 200 nhưng body trả về lỗi (ví dụ rate limit exceeded)
• Exception bị bắt trong try-catch nên bị “nuốt”
• Truy vấn SOQL không trả về dữ liệu (0 rows)
• Giới hạn governor limit đạt tới gần mức tối đa (95%)
• Luồng xử lý (Flow) bị bỏ qua hoàn toàn

Điểm thú vị là chưa có máy chủ MCP nào có thể tự động lấy hoặc phân tích những log này.

Khoảng trống của hệ sinh thái hiện tại

Tác giả khảo sát những máy chủ MCP hiện có:

• Certinia's @certinia/apex-log-mcp: parser tốt cho phân tích hiệu năng, nhưng vẫn yêu cầu đường dẫn file log cục bộ, không tự động tải log từ Salesforce.

• Salesforce's @salesforce/mcp: Bộ công cụ MCP chính thức với nhiều công cụ về metadata, dữ liệu, testing nhưng lại hoàn toàn không hỗ trợ debug log.

Hiện tại, quy trình debug vẫn là thủ công:

Bạn: “Tích hợp Vendor X có vấn đề”

AI: “Bạn tải log debug và đưa đường dẫn cho tôi nhé!”

Bạn: thao tác thủ công rồi trả file

AI: “Đây là phân tích...”

Như vậy AI vẫn thiếu khả năng tự động lấy logs – điều rất cần thiết cho việc debug hiệu quả.

sf-log-mcp – Giải pháp được xây dựng

sf-log-mcp ra đời nhằm lấp đầy khoảng trống giữa Salesforce và trợ lý AI. Đây là máy chủ MCP độc lập giúp:

• Tự động liệt kê, tải về và phân tích log debug
• Tự động phát hiện các lỗi im lặng khó thấy
• Kết hợp nhiều bộ parser để “đọc hiểu” sâu sắc nội dung log
• Cung cấp các công cụ quản lý lifecycle log như tạo, cập nhật trace flags

Triết lý phát triển

“Đừng chỉ lọc log theo trạng thái. Hãy tải về, đọc và suy luận.”

Thay vì tin vào trường Status chỉ bắt được dưới 10% lỗi, sf-log-mcp tải nguyên log thô và cho AI đánh giá thực tế các sự kiện gọi callout, exception, governor limits, luồng xử lý...

Quy trình làm việc mới

Người dùng chỉ cần yêu cầu AI:

“Kiểm tra các log debug gần đây của tích hợp Vendor X”

AI sẽ tự động:

1. Quản lý trace flags để bật logging nếu chưa có
2. Tải 5 log mới nhất từ Salesforce
3. Phân tích từng log, đánh giá điểm sức khỏe (health score)
4. Đào sâu vào những phần có lỗi như callouts hay exceptions
5. Báo cáo chi tiết kết quả phát hiện lỗi, cảnh báo

Toàn bộ quy trình không cần can thiệp thủ công, AI tự động fetch – read – reason và trả lời.

Kiến trúc và thiết kế

• Trực tiếp gọi Salesforce Tooling API qua REST, không phụ thuộc CLI con, giảm rào cản phiên bản và tăng quyền kiểm soát truy vấn.
• Sử dụng lại cơ chế xác thực của Salesforce CLI (sf), không lưu trữ cred, bảo mật cao.
• Chạy riêng biệt, không thay thế parser mạnh của Certinia mà bổ trợ nhau.
• Tương thích với nhiều nền tảng AI như Claude Desktop, VS Code, Cursor...

Các công cụ và bộ parser chính

sf-log-mcp có 9 công cụ đa tầng:

• List, fetch, tải log
• Trích xuất nội dung chi tiết (callouts, exceptions, SOQL, DML, governor limits, flow, debug messages)
• Phân tích, tính điểm sức khỏe log (0-100)
• Tìm kiếm regex xuyên log
• Quản lý trace flags
• Xóa log
• So sánh log đối chiếu tìm lỗi mới

7 bộ parser đặc biệt tập trung phát hiện lỗi im lặng:

1. Callout parser – phát hiện HTTP 200 có body chứa lỗi
2. Exception parser – phân biệt lỗi được catch và unhandled
3. SOQL parser – cảnh báo truy vấn trả về 0 rows
4. Governor limits parser – cảnh báo khi sát ngưỡng giới hạn
5. DML parser – cảnh báo thao tác khối lượng lớn gây lỗi
6. Flow parser – phát hiện flow bị lỗi
7. Debug message parser – lấy thông tin debug từ System.debug()

Điểm sức khỏe log (Health Score)

Công cụ analyze_log trả về điểm từ 0 đến 100 như thang đo tổng quan chất lượng log với mức độ:

• 90-100: Healthy – ổn định
• 70-89: Warning – có vấn đề nhỏ
• 50-69: Degraded – cần chú ý
• 0-49: Critical – lỗi nghiêm trọng

Điểm này giúp AI xác định phần nào của log cần phân tích sâu trước để tiết kiệm thời gian và tài nguyên.

Tính năng bảo mật

• Không lưu trữ credential, tận dụng hệ thống xác thực Salesforce CLI
• Hạn chế truy cập theo danh sách org được phép
• Giao tiếp qua stdin/stdout, không mở cổng mạng
• Bảo vệ khỏi tấn công SOQL Injection
• Chỉ cho phép thay đổi các thiết lập nhạy cảm, không thao tác dữ liệu nghiệp vụ

Kích thước và số liệu dự án

• 9 tools, 7 parsers
• 2.488 dòng code nguồn, 1.069 dòng code test
• 101 test case đã pass
• 15 test suite
• Kích thước package: 44,8 KB
• Hỗ trợ Node.js 18, 20, 22

Cách dùng nhanh trong 2 phút

Chuẩn bị:

• Node.js phiên bản >= 18
• Salesforce CLI đã xác thực với org

Cài đặt và chạy:

npx sf-log-mcp --allowed-orgs ALLOW_ALL_ORGS

Cấu hình AI client (Claude, VS Code) dùng lệnh npx trên với các tham số phù hợp.

Sau đó hỏi AI:

“List my recent Salesforce debug logs”

Tương lai và kế hoạch phát triển

• Hỗ trợ Windsurf AI IDE
• Tích hợp streaming log realtime (Server-Sent Events)
• Cho phép tuỳ biến quy tắc phân tích lỗi
• Hướng dẫn kết hợp với Certinia apex-log-mcp để phân tích hiệu năng sâu

Tổng kết

Nếu bạn đang mắc kẹt khi debug các tích hợp Salesforce, đặc biệt những lỗi “vô hình” dù log báo “Success”, sf-log-mcp là công cụ đáng để thử. Giải pháp giúp AI tự động lấy và hiểu log, nâng cao hiệu quả gỡ lỗi, giảm công sức thủ công.

Dự án mã nguồn mở, sẵn sàng đóng góp trên GitHub: https://github.com/Likhit-Kumar/SF-Logs

Gói npm: https://www.npmjs.com/package/sf-log-mcp

---

Việc ứng dụng AI trong hỗ trợ gỡ lỗi Salesforce giờ đây trở nên khả thi và hiệu quả hơn rất nhiều nhờ việc tạo ra một tầng kết nối chuyên biệt như sf-log-mcp.