Core MCP AI Agent (apt-mcp-agent-setup)

Bộ cổng kết nối AI Agent bảo mật, tích hợp hệ thống quản lý License Key và Skill bundle mã hóa động dành cho doanh nghiệp.

📋 Tổng Quan Hệ Thống

Core MCP AI Agent được phân phối dưới dạng một bộ cài đặt tự động (npm package). Hệ thống cho phép phân phối các kỹ năng (Skills) và tác nhân (Agents) độc quyền của công ty một cách bảo mật tới máy của lập trình viên (Client) mà không lo lộ mã nguồn hay bị sử dụng trái phép ngoài phạm vi thiết bị được cấp quyền.

+-----------------------------------------------+
|             Admin (Offline Machine)           |
|  - master.key (Signature)                     |
|  - bundle.key (AES-256 Encryption Key)        |
+----------------------+------------------------+
                       |
                       | 1. Build & Encrypt (.enc)
                       | 2. Publish Package (GitLab Package Registry)
                       v
+----------------------+------------------------+
|          GitLab Private NPM Registry          |
|  - Package: apt-mcp-agent-setup        |
|  - Contains: Obfuscated installer & Encrypted |
|    skills (*.enc)                             |
+----------------------+------------------------+
                       |
                       | 3. npx apt-mcp-agent-setup install
                       |    --key <LICENSE_KEY>
                       v
+----------------------+------------------------+
|            Developer's Local Machine          |
|  - Verifies License with Hardware Device ID    |
|  - Decrypts skills to local workspace         |
|  - Registers MCP Server to IDE (Antigravity)   |
+-----------------------------------------------+

📚 Tài Liệu Hướng Dẫn Nhanh

Hệ thống được chia làm hai vai trò vận hành chính. Vui lòng tham khảo tài liệu hướng dẫn chi tiết tương ứng:

1. Dành Cho Quản Trị Viên (Admin)

👉 Xem tại: Hướng Dẫn Triển Khai & Cấp Khóa (Admin)

• Nội dung bao gồm:
  • Các nguyên tắc bảo mật và lưu trữ khóa ngoại tuyến (master.key, bundle.key).
  • Quy trình build, đóng gói mã hóa AES-256 các Skill thành tệp .enc và xáo trộn mã JS bằng javascript-obfuscator.
  • Cách publish package lên GitLab Package Registry cá nhân/doanh nghiệp.
  • Hướng dẫn chạy CLI gen-key.js để cấp License Key giới hạn theo thời gian và Device ID cho lập trình viên.

2. Dành Cho Lập Trình Viên (Developer)

👉 Xem tại: Hướng Dẫn Cài Đặt & Sử Dụng (Developer)

• Nội dung bao gồm:
  • Cách thiết lập xác thực .npmrc để truy cập GitLab Package Registry riêng tư của công ty.
  • Cách lấy Device ID phần cứng thông qua lệnh npx apt-mcp-agent-setup init.
  • Lệnh cài đặt tự động AI Agent vào workspace dự án và đăng ký cổng kết nối vào IDE.
  • Kiểm tra trạng thái hoạt động và thời hạn License Key.
  • Cơ chế tự động dọn dẹp (xóa sạch tài nguyên độc quyền) khi License hết hạn.
  • Hướng dẫn sử dụng các Slash Commands nâng cao: /plan, /tdd, /debug, /verify, /to-issues.

⚡ Tóm Tắt Quy Trình Phân Phối Trọn Gói (Deploy/Publish)

Bước 1: Build đóng gói mã hóa (Admin)

Đảm bảo bạn đã có các file khóa bảo mật trong thư mục admin/. Tăng version trong package.json và chạy:

npm run build

Lệnh này sẽ mã hóa thư mục .agents/ và src/templates thành các file .enc trong thư mục bundle/, sau đó build mã nguồn JS đã được xáo trộn ra thư mục dist/.

Bước 2: Publish lên npmjs.org (Admin)

1. Đăng nhập vào tài khoản npm của bạn (nếu chưa đăng nhập):

   npm login

2. Di chuyển vào thư mục dist/ và thực hiện publish gói lên NPMJS Registry công khai:

   cd dist
   npm publish --access public

   (Nếu tài khoản NPM của bạn yêu cầu mã xác thực 2-Factor Authentication (2FA) khi publish, hãy thêm tham số --otp: npm publish --access public --otp <MÃ_OTP_6_SỐ>)

Bước 3: Sinh License Key cho Dev/QC/BA/PM (Admin)

Khi nhận được Device ID từ nhân viên, hãy chạy CLI sinh khóa. Bạn có thể chỉ định một hoặc nhiều Preset ghép nối (Stackable Presets) ngăn cách bằng dấu phẩy:

# Cấp khóa cho Dev di động Flutter
node admin/gen-key.js --device <DEVICE_ID> --user "nguyen-van-a" --expires 2026-12-31 --preset mobile-flutter

# Cấp khóa tích hợp: Dev React + Quyền quản lý dự án (PM) + Tích hợp thiết kế Figma
node admin/gen-key.js --device <DEVICE_ID> --user "tran-van-b" --expires 2026-12-31 --preset fe-react,pm,figma

Copy chuỗi License Key xuất ra và gửi cho người dùng.

Bước 4: Cài đặt & Sử dụng (Developer / QC / BA / PM)

Người dùng không cần cấu hình bất kỳ tệp tin xác thực .npmrc nào. Hãy mở terminal tại thư mục gốc dự án và chạy trực tiếp lệnh cài đặt:

npx apt-mcp-agent-setup install --key <LICENSE_KEY_ĐÃ_NHẬN>

[!IMPORTANT] Lưu ý quan trọng: Luôn mở terminal và chạy lệnh trên tại thư mục gốc của dự án bạn muốn cấu hình AI Agent. Không chạy ở thư mục người dùng chung (~ hoặc C:\Users\Username). Mỗi dự án sẽ được cấp một vùng làm việc độc lập chứa các Skill (.agents/) và bộ nhớ (.memory/) riêng biệt để đảm bảo hiệu quả làm việc và bảo mật.

Hệ thống sẽ tự động cấu hình môi trường, giải mã các Kỹ năng phù hợp với Preset được cấp trong License Key và tích hợp thẳng vào IDE (Antigravity IDE, Claude Code, Cursor, hoặc VS Code).