AI agent và MCP

KDIGI CMS là CMS AI-native: máy chủ Model Context Protocol có sẵn tại POST /api/mcp, nên AI agent (Claude Code, Codex, Cursor, VS Code, OMP…) đọc, viết, hẹn giờ, đăng bài và kiểm tra SEO trực tiếp trên CMS. Agent làm việc với tư cách người dùng sở hữu API key: đúng vai trò, đúng các site được gán, như khi người đó đăng nhập trang quản trị.

Máy chủ MCP và CLI kcms có từ KDIGI CMS 1.2.0. Tài khoản demo công khai không tạo được API key, nên hãy thử trên bản tự host.

Agent làm được gì

Nhóm	Công cụ
Định danh, site	whoami, list_sites, get_site
Tìm và đọc	search_content, get_content (thân bài Markdown, SEO, updatedAt)
Viết	create_post, create_page (mặc định là bản nháp), update_post, update_page
Xuất bản	set_status: đăng, gỡ, hẹn giờ bằng publishedAt trong tương lai
Hoàn tác	trash_content, restore_from_trash, list_versions, restore_version
Chuyên mục, thẻ	list_taxonomies, create_taxonomy
Media	search_media, import_media_from_url, update_media_alt
SEO	seo_audit, get_seo_report (cùng bộ chấm điểm với trang quản trị)
Khác	list_shortcodes, get_content_urls

Kèm theo: tài nguyên kcms://guide/content (quy tắc Markdown, shortcode, SEO) và hai prompt write-post, refresh-seo.

1. Tạo API key cho agent

Mỗi agent hoặc mỗi người nên có một tài khoản riêng với vai trò thấp nhất đủ dùng: author chỉ tạo bản nháp, editor được đăng và hẹn giờ. Tránh dùng key của super-admin.

1. Super admin vào Người dùng, tạo tài khoản (ví dụ ai-writer@example.com), chọn vai trò và site.
2. Mở tài khoản đó, bật Kích hoạt API Key (giao diện tiếng Anh: Enable API Key), sao chép key rồi Lưu.
3. Đặt key vào biến môi trường ở máy chạy agent: export KCMS_API_KEY=change-me.

Phiên đăng nhập bằng API key bị giới hạn trên mọi route REST, GraphQL và MCP: không đổi được email, mật khẩu, API key, vai trò hay site của tài khoản, không tạo người dùng, không xoá vĩnh viễn (chỉ chuyển vào thùng rác). Key bị lộ thì tắt Kích hoạt API Key.

2. Kết nối công cụ AI

Cách nhanh nhất là CLI kcms: nó ghi đúng tệp cấu hình cho từng công cụ và không chép key vào tệp.

npm install -g @kdigi/kcms-cli
export KCMS_API_KEY=change-me
kcms setup claude-code --url https://cms.example.com --write --with-skill

Thay claude-code bằng codex, cursor, vscode, omp hoặc json. Bỏ --write để chỉ in cấu hình ra màn hình. --with-skill cài thêm agent skill dạy quy trình biên tập an toàn: đọc trước khi sửa, viết bản nháp trước, chỉ đăng khi được yêu cầu.

Muốn tự cấu hình, ví dụ .mcp.json của Claude Code:

{
  "mcpServers": {
    "kdigi": {
      "type": "http",
      "url": "https://cms.example.com/api/mcp",
      "headers": { "Authorization": "Bearer ${KCMS_API_KEY}" }
    }
  }
}

Cấu hình cho Codex, Cursor, VS Code, OMP và cầu nối stdio (kcms mcp) cho công cụ chỉ hỗ trợ stdio nằm ở AI integration reference (tiếng Anh).

3. Agent làm việc an toàn thế nào

• Bản nháp trước. Bài tạo mới là bản nháp; bản nháp không có URL công khai, agent gửi lại link trang quản trị để bạn duyệt.
• Không ghi đè bài người khác vừa sửa. Mọi lần sửa phải kèm expectedUpdatedAt lấy từ lần đọc gần nhất; có người lưu xen giữa thì lệnh báo conflict và không thay đổi gì.
• Tôn trọng khoá biên tập. Biên tập viên đang mở bài trong trang quản trị thì agent nhận lỗi locked, không chiếm khoá.
• Đúng quyền, đúng site. Author không đăng được bài; site không được gán thì agent không thấy.
• Hoàn tác được. Thùng rác và lịch sử phiên bản dùng như trong trang quản trị.
• Có nhật ký. Mỗi lần gọi công cụ ghi một dòng log agent-op (công cụ, người dùng, site, tài liệu, kết quả), không ghi nội dung hay key.

4. Dùng CLI không cần agent

kcms cũng là công cụ dòng lệnh: lấy bài về thành tệp Markdown có frontmatter, sửa bằng trình soạn thảo quen tay rồi gửi lên.

kcms login --url https://cms.example.com
kcms posts get my-post -o my-post.md
kcms posts update my-post.md
kcms media upload ./cover.webp --alt "Ảnh bìa"
kcms seo audit

Vận hành

• Máy chủ MCP bật sẵn; đặt MCP_ENABLED=false để tắt (route trả 404). Xem cấu hình.
• Đặt reverse proxy cho /api/mcp thời gian chờ tối thiểu 30 giây và giới hạn tần suất (CMS không tự giới hạn).
• Chỉ dùng HTTPS vì key đi trong header.
• ChatGPT và Claude.ai bản web cần OAuth, hiện chưa hỗ trợ; dùng công cụ desktop/CLI ở trên hoặc cầu nối stdio.

Danh sách công cụ đầy đủ, xử lý lỗi và kiểm tra kết nối: AI integration reference. Quyền của từng vai trò: Vai trò và phân quyền.