Hướng Dẫn Viết Prompt Khi Sử Dụng MCP Với MariaDB

Tài liệu này hướng dẫn cách viết prompt khi dùng AI agent kết nối tới MariaDB thông qua MCP server mariadb-mcp-server.py trong dự án này.

Mục tiêu của tài liệu:

• giúp bạn viết prompt rõ ràng, dễ kiểm soát
• giúp agent chọn đúng tool cho từng tác vụ
• bao quát đầy đủ các quyền và khả năng tương tác database mà MCP server hiện đang expose
• giảm rủi ro khi cho agent thao tác với dữ liệu thật

1. MCP server này có thể làm gì

MCP server trong dự án hiện hỗ trợ các nhóm thao tác sau:

• xem thông tin cấu hình kết nối hiện tại
• cấu hình lại kết nối MariaDB trong runtime
• kiểm tra kết nối tới MariaDB
• liệt kê database
• liệt kê table trong database
• xem cấu trúc cột của table
• xem index của table
• chạy câu lệnh đọc dữ liệu như SELECT, SHOW, DESCRIBE, EXPLAIN
• chạy câu lệnh ghi dữ liệu hoặc thay đổi schema như INSERT, UPDATE, DELETE, CREATE, ALTER, DROP
• tạo database mới
• tạo user database
• cấp quyền cho user trên một database hoặc toàn server
• xem trạng thái MariaDB
• xem process list
• backup dữ liệu của một table dưới dạng các câu lệnh INSERT

Nói ngắn gọn: nếu tài khoản MariaDB bạn cung cấp có quyền cao, agent có thể thực hiện gần như toàn bộ vòng đời thao tác với database, từ đọc dữ liệu đến quản trị quyền.

2. Danh sách tool hiện có

Các tool MCP đang được expose:

Tool	Mục đích
get_connection_info	Xem cấu hình kết nối hiện tại, không lộ mật khẩu
configure_connection	Thay đổi host, port, user, password, database, charset, timeout trong runtime
test_connection	Kiểm tra kết nối tới MariaDB
list_databases	Liệt kê các database có thể truy cập
list_tables	Liệt kê các table trong database
describe_table	Xem cấu trúc cột của table
get_table_indexes	Xem index của table
execute_query	Chạy query chỉ đọc
execute_command	Chạy lệnh ghi dữ liệu hoặc DDL
create_database	Tạo database
create_user	Tạo user MariaDB
grant_privileges	Cấp quyền cho user
get_server_status	Xem trạng thái MariaDB
get_process_list	Xem SHOW PROCESSLIST
backup_table	Backup dữ liệu table dưới dạng INSERT statements

3. Cách viết prompt tốt khi làm việc với database

Một prompt tốt nên có đủ 4 phần:

1. mục tiêu cần đạt
2. phạm vi được phép thao tác
3. mức độ an toàn mong muốn
4. định dạng kết quả mong muốn

Mẫu khung prompt khuyến nghị:

Bạn đang làm việc với MariaDB thông qua MCP.

Mục tiêu:
- <mô tả rõ việc cần làm>

Phạm vi:
- Database: <tên database hoặc *>
- Table liên quan: <nếu có>

Nguyên tắc:
- Nếu chưa rõ schema, phải kiểm tra schema trước khi viết SQL.
- Chỉ dùng các tool MCP được cung cấp.
- Không tự suy đoán tên cột, tên bảng, index hoặc quan hệ dữ liệu.
- Nếu là thao tác ghi dữ liệu, DDL, hoặc cấp quyền, phải nêu rõ rủi ro trước khi thực hiện.
- Sau khi chạy, phải trả về câu lệnh đã dùng và kết quả thực tế.

Kết quả mong muốn:
- Tóm tắt ngắn gọn
- SQL hoặc tool đã sử dụng
- Số dòng bị ảnh hưởng hoặc dữ liệu trả về

4. Hướng dẫn viết prompt theo từng nhóm tác vụ

4.1. Quản lý kết nối

Nhóm tool:

• get_connection_info
• configure_connection
• test_connection

Khi nào dùng:

• bạn muốn biết agent đang kết nối vào đâu
• bạn muốn đổi sang database khác
• bạn muốn xác minh kết nối trước khi thao tác dữ liệu

Prompt mẫu:

Hãy kiểm tra cấu hình kết nối MCP hiện tại, sau đó test kết nối MariaDB.
Trả về host, port, database, user, version và hostname của server.
Không hiển thị password.

Prompt mẫu khi cần đổi kết nối:

Hãy cấu hình lại kết nối MCP để dùng database `analytics_db`, sau đó test lại kết nối.
Chỉ trả về thông tin cấu hình an toàn, không hiển thị mật khẩu.

4.2. Khám phá database và schema

Nhóm tool:

• list_databases
• list_tables
• describe_table
• get_table_indexes

Khi nào dùng:

• bạn mới tiếp cận một database chưa rõ cấu trúc
• bạn cần xác nhận tên bảng, tên cột trước khi query
• bạn muốn phân tích quan hệ nghiệp vụ từ schema

Prompt mẫu:

Hãy khảo sát database `app_db`.

Yêu cầu:
- liệt kê tất cả table
- mô tả cấu trúc bảng `users`
- liệt kê index của bảng `users`
- tóm tắt nhanh bảng này đang phục vụ mục đích gì dựa trên schema

Prompt mẫu cho bước khám phá ban đầu:

Tôi vừa kết nối tới một MariaDB mới qua MCP.
Hãy:
- kiểm tra kết nối
- liệt kê các database có thể truy cập
- chọn database `app_db`
- liệt kê các table
- mô tả 3 bảng quan trọng nhất
- tóm tắt kiến trúc dữ liệu ở mức cơ bản

Không được sửa dữ liệu.

4.3. Đọc dữ liệu

Nhóm tool:

• execute_query

Tool này phù hợp cho:

• SELECT
• SHOW
• DESCRIBE
• EXPLAIN

Prompt mẫu:

Trong database `app_db`, hãy:
- kiểm tra schema của bảng `orders` trước
- viết query để lấy 20 đơn hàng mới nhất
- chỉ hiển thị các cột quan trọng
- nếu chưa chắc tên cột, phải kiểm tra schema trước khi query

Prompt mẫu cho tác vụ phân tích:

Hãy dùng MCP để phân tích bảng `orders`.

Mục tiêu:
- đếm tổng số bản ghi
- đếm số đơn theo từng trạng thái
- lấy 10 đơn gần nhất

Yêu cầu:
- chỉ dùng query đọc
- trả về cả SQL đã dùng
- tóm tắt kết quả bằng ngôn ngữ dễ hiểu

Prompt mẫu khi cần kiểm tra hiệu năng query:

Hãy phân tích truy vấn đọc dữ liệu từ bảng `orders`.

Yêu cầu:
- kiểm tra schema và index trước
- viết query phù hợp
- dùng `EXPLAIN` cho query chính
- nêu nếu có dấu hiệu thiếu index hoặc query chưa tối ưu

4.4. Ghi dữ liệu

Nhóm tool:

• execute_command

Tool này dùng cho:

• INSERT
• UPDATE
• DELETE

Đây là nhóm thao tác có rủi ro trực tiếp lên dữ liệu thật. Khi viết prompt cho nhóm này, nên bắt buộc agent làm theo quy trình an toàn.

Prompt mẫu:

Hãy cập nhật bảng `users` trong database `app_db`.

Yêu cầu:
- kiểm tra schema trước
- tìm trước các bản ghi có `status = 'pending'`
- sau đó đổi thành `status = 'active'` cho tối đa 50 dòng
- trả về câu lệnh đã chạy và số dòng bị ảnh hưởng
- nếu số bản ghi dự kiến lớn hơn mong đợi, dừng lại và báo tôi

Prompt mẫu cho thao tác xóa:

Hãy xóa các session hết hạn trong bảng `user_sessions`.

Quy tắc bắt buộc:
- kiểm tra schema trước
- chạy query đếm số dòng sẽ bị xóa
- chỉ thực hiện DELETE sau khi đã nêu số lượng dự kiến
- trả về số dòng đã xóa

Prompt mẫu cho thao tác thêm dữ liệu:

Hãy thêm một bản ghi mới vào bảng `notifications`.

Yêu cầu:
- đọc schema trước để xác định các cột cần thiết
- viết câu lệnh INSERT phù hợp
- sau khi thực hiện, trả về `last_insert_id` và số dòng bị ảnh hưởng

4.5. Thay đổi schema và DDL

Nhóm tool:

• execute_command
• create_database

Dùng cho:

• CREATE DATABASE
• CREATE TABLE
• ALTER TABLE
• DROP TABLE
• DROP DATABASE

Prompt mẫu khi tạo database:

Hãy tạo database `analytics_db` với charset `utf8mb4` và collation mặc định phù hợp.
Sau khi tạo, liệt kê lại database để xác nhận kết quả.

Prompt mẫu khi thay đổi cấu trúc bảng:

Hãy cập nhật schema bảng `orders` trong database `app_db`.

Mục tiêu:
- thêm cột `processed_at` kiểu DATETIME NULL

Quy tắc:
- kiểm tra schema hiện tại trước
- nếu cột đã tồn tại thì không được tạo lại
- nếu cần ALTER TABLE, trả về câu lệnh đã thực hiện

Prompt mẫu cho thao tác nguy hiểm:

Tôi muốn xóa bảng `temp_import_logs`.

Yêu cầu:
- xác nhận bảng có tồn tại
- nêu rõ rủi ro mất dữ liệu
- chỉ thực hiện lệnh DROP sau khi đã giải thích bảng nào sẽ bị tác động

5. Hướng dẫn prompt cho quản trị user và phân quyền

Đây là phần quan trọng nhất nếu bạn muốn “đầy đủ các quyền” trong tương tác database.

Nhóm tool:

• create_user
• grant_privileges

MCP server này cho phép:

• tạo user mới
• cấp quyền chi tiết như SELECT, INSERT, UPDATE, DELETE
• cấp ALL PRIVILEGES
• cấp quyền trên một database cụ thể
• cấp quyền trên toàn server bằng cách dùng database = "*"

Điểm cần lưu ý:

• khả năng thành công phụ thuộc vào chính quyền của tài khoản MariaDB đang dùng để kết nối
• nếu tài khoản hiện tại có quyền admin, agent có thể tạo user mới và cấp quyền rất rộng
• grant_privileges nhận chuỗi quyền do bạn chỉ định, ví dụ SELECT, SELECT, INSERT, hoặc ALL PRIVILEGES

5.1. Tạo user chỉ đọc

Prompt mẫu:

Hãy tạo user `report_user` và cấp quyền chỉ đọc trên database `app_db`.

Yêu cầu:
- tạo user với host `%`
- cấp quyền `SELECT`
- không cấp quyền ghi hoặc thay đổi schema
- tóm tắt user, host, database và quyền đã cấp

5.2. Tạo user vận hành

Prompt mẫu:

Hãy tạo user `app_operator` cho database `app_db`.

Yêu cầu:
- tạo user với host `%`
- cấp các quyền `SELECT, INSERT, UPDATE, DELETE`
- không cấp quyền tạo user hoặc cấp quyền tiếp cho user khác
- trả về thông tin tóm tắt sau khi hoàn tất

5.3. Cấp quyền quản trị trên một database

Prompt mẫu:

Hãy tạo user `ops_admin` và cấp `ALL PRIVILEGES` trên database `app_db`.

Sau khi thực hiện:
- tóm tắt user
- host
- database
- tập quyền đã cấp

5.4. Cấp quyền trên toàn server

Prompt mẫu:

Hãy grant `ALL PRIVILEGES` cho user `root_clone` trên tất cả database.

Yêu cầu:
- dùng phạm vi database `*`
- nêu rõ đây là quyền toàn server
- trả về kết quả ngắn gọn sau khi cấp quyền

5.5. Mẫu prompt an toàn hơn cho cấp quyền

Hãy chuẩn bị thao tác cấp quyền cho user `bi_reader`.

Yêu cầu:
- trước tiên mô tả quyền dự kiến sẽ cấp
- giải thích phạm vi database bị ảnh hưởng
- chỉ thực hiện grant sau khi đã nêu rõ quyền là `SELECT`
- sau khi hoàn tất, trả về thông tin quyền đã cấp

6. Theo dõi tình trạng server

Nhóm tool:

• get_server_status
• get_process_list

Phù hợp khi:

• bạn muốn kiểm tra server có đang hoạt động bình thường không
• bạn cần xem số lượng kết nối đang mở
• bạn muốn phát hiện query chậm hoặc tiến trình bất thường

Prompt mẫu:

Hãy kiểm tra tình trạng MariaDB qua MCP.

Yêu cầu:
- lấy status tổng quan của server
- lấy process list
- tóm tắt nhanh các dấu hiệu bất thường nếu có

7. Backup dữ liệu của một table

Nhóm tool:

• backup_table

Tool này xuất dữ liệu của table dưới dạng các câu lệnh INSERT.

Phù hợp khi:

• bạn muốn backup nhanh một phần dữ liệu
• bạn muốn trích xuất dữ liệu mẫu để lưu lại hoặc chuyển môi trường

Prompt mẫu:

Hãy backup 100 dòng đầu tiên của bảng `users` trong database `app_db`.

Yêu cầu:
- kiểm tra schema bảng trước
- dùng tool backup_table
- nêu rõ đây là backup logic dưới dạng INSERT statements

Prompt mẫu khi cần giới hạn dữ liệu:

Hãy backup bảng `audit_logs` trong database `app_db`.

Yêu cầu:
- chỉ xuất tối đa 500 dòng
- không đọc quá phạm vi đó
- trả về kết quả dưới dạng các câu lệnh INSERT

8. Mẫu prompt theo mức quyền sử dụng

Nếu bạn muốn agent hành xử nhất quán, nên chỉ định vai trò rõ ràng trong prompt.

8.1. Vai trò đọc dữ liệu

Bạn chỉ được phép dùng các tool đọc:
- get_connection_info
- test_connection
- list_databases
- list_tables
- describe_table
- get_table_indexes
- execute_query
- get_server_status
- get_process_list

Không được phép dùng:
- execute_command
- create_database
- create_user
- grant_privileges

Nếu cần thay đổi dữ liệu hoặc schema, phải dừng lại và đề xuất thao tác cần xin phép.

8.2. Vai trò vận hành dữ liệu

Bạn được phép đọc và ghi dữ liệu, nhưng không được quản trị user hoặc phân quyền.

Được phép:
- đọc schema
- chạy query đọc
- execute_command cho INSERT, UPDATE, DELETE

Không được phép:
- create_database
- create_user
- grant_privileges
- DROP TABLE hoặc DROP DATABASE nếu tôi chưa ghi rõ

Mọi thao tác ghi phải:
- kiểm tra schema trước
- ước lượng phạm vi tác động nếu có thể
- báo lại số dòng bị ảnh hưởng sau khi chạy

8.3. Vai trò DBA

Bạn đang đóng vai trò DBA qua MCP.

Được phép:
- dùng toàn bộ tool hiện có

Quy tắc:
- trước thao tác nguy hiểm, phải nêu rõ rủi ro
- trước thao tác grant quyền, phải nêu rõ phạm vi database
- trước thao tác ALTER hoặc DROP, phải kiểm tra object có tồn tại hay không
- sau mỗi thao tác, phải trả về câu lệnh và kết quả thực tế

9. Các mẫu prompt hoàn chỉnh cho tình huống thực tế

9.1. Khảo sát một database mới

Tôi vừa kết nối tới một MariaDB mới qua MCP. Hãy:
- kiểm tra kết nối
- liệt kê database
- chọn database `app_db`
- liệt kê table
- mô tả 3 bảng quan trọng nhất
- tóm tắt nhanh cấu trúc hệ thống

Không được sửa dữ liệu.

9.2. Điều tra lỗi dữ liệu

Hãy điều tra vì sao đơn hàng bị trễ trong database `app_db`.

Yêu cầu:
- đọc schema các bảng `orders`, `payments`, `shipments`
- tìm 20 đơn gần nhất đang ở trạng thái trễ
- nếu cần, dùng EXPLAIN cho query chính
- không được ghi dữ liệu
- trả về nhận định ngắn gọn dựa trên dữ liệu thực tế

9.3. Sửa dữ liệu có kiểm soát

Hãy sửa dữ liệu trong database `app_db`.

Mục tiêu:
- đổi `status` từ `draft` sang `published` cho các bản ghi trong bảng `posts`
- chỉ áp dụng với các bản ghi có `published_at` khác NULL

Quy trình bắt buộc:
- đọc schema trước
- chạy SELECT để đếm số dòng phù hợp
- sau đó mới thực hiện UPDATE
- trả về số dòng bị cập nhật

9.4. Tạo user BI chỉ đọc

Hãy tạo user `bi_reader` cho database `analytics_db`.

Yêu cầu:
- tạo user với password tôi cung cấp
- host là `%`
- chỉ cấp quyền `SELECT`
- không cấp quyền ghi, xóa hoặc thay đổi schema
- tóm tắt thao tác sau khi hoàn tất

9.5. Backup nhanh một bảng

Hãy backup bảng `audit_logs` trong database `app_db`.

Yêu cầu:
- xuất tối đa 500 dòng
- trả về kết quả dưới dạng INSERT statements
- nếu bảng quá lớn, chỉ lấy trong giới hạn đã nêu

10. Các câu ràng buộc an toàn nên thêm vào prompt

Bạn có thể chèn trực tiếp các câu dưới đây vào prompt để agent an toàn hơn:

• “Không được chạy lệnh ghi nếu chưa mô tả tác động.”
• “Nếu query có thể ảnh hưởng hơn 100 dòng, dừng lại và báo tôi.”
• “Luôn đọc schema trước khi viết SQL.”
• “Không được dùng SELECT * trừ khi tôi yêu cầu.”
• “Mọi lệnh DDL phải kiểm tra object tồn tại trước khi chạy.”
• “Nếu tạo user hoặc cấp quyền, phải nêu rõ phạm vi và mục đích.”
• “Không được cấp ALL PRIVILEGES nếu tôi chưa ghi rõ.”
• “Ưu tiên nguyên tắc quyền tối thiểu cần thiết.”

11. Mẫu system prompt khuyến nghị

Bạn có thể dùng đoạn này làm system prompt hoặc instruction nền cho agent:

Bạn là AI agent đang thao tác với MariaDB qua MCP.

Nguyên tắc làm việc:
- chỉ sử dụng các tool MCP được cung cấp
- không giả định schema nếu chưa kiểm tra
- ưu tiên an toàn, minh bạch, khả năng giải trình
- với thao tác đọc: trả về SQL đã dùng và kết quả tóm tắt
- với thao tác ghi, DDL, hoặc quản trị quyền: nêu rõ rủi ro, phạm vi tác động và kết quả sau khi chạy
- không hiển thị password hoặc secret trong câu trả lời
- nếu yêu cầu còn mơ hồ, hãy khảo sát schema trước rồi mới hành động

12. Lưu ý quan trọng về an toàn và quyền hạn

• MCP server này chạy bằng đúng credential MariaDB mà bạn cấu hình
• nếu bạn dùng tài khoản có quyền admin, agent cũng sẽ có khả năng thao tác tương ứng
• execute_command có thể chạy các lệnh nguy hiểm như DELETE, ALTER, DROP
• grant_privileges có thể cấp quyền rất rộng, bao gồm quyền trên toàn server
• create_user và grant_privileges là nhóm thao tác cần được kiểm soát chặt nhất

Khuyến nghị thực tế:

• môi trường production: nên dùng user read-only hoặc user có quyền tối thiểu
• môi trường staging/dev: có thể cấp quyền rộng hơn nếu cần agent hỗ trợ sửa dữ liệu hoặc schema
• tác vụ quản trị user/quyền: chỉ nên cho phép khi đã xác định rất rõ phạm vi và mục đích

13. Kết luận

Khi làm việc với MCP cho MariaDB, điều quan trọng nhất không phải là viết prompt dài, mà là viết prompt rõ phạm vi, rõ quyền, rõ quy trình và rõ mức độ an toàn mong muốn.

Nếu bạn viết prompt tốt, agent có thể hỗ trợ rất hiệu quả trong các việc như:

• khảo sát schema
• phân tích dữ liệu
• sửa dữ liệu có kiểm soát
• thay đổi cấu trúc database
• backup dữ liệu
• tạo user và cấp quyền

Ngược lại, nếu prompt quá mơ hồ và tài khoản kết nối có quyền cao, rủi ro thao tác nhầm trên dữ liệu thật là rất lớn.

Vì vậy, với các tác vụ ghi dữ liệu, DDL, hoặc phân quyền, nên luôn yêu cầu agent:

• kiểm tra hiện trạng trước
• mô tả tác động trước
• thực hiện trong phạm vi rõ ràng
• báo cáo kết quả sau khi chạy