AI agent (MCP)

devkit mcp là một MCP server chạy trên stdin và stdout. Agent khởi động nó khi bắt đầu phiên làm việc và nó thoát khi phiên kết thúc. Mỗi tool gọi đúng code của lệnh CLI tương ứng và trả về đúng JSON của lệnh đó khi chạy với --json, nên agent có thể chạy site, tạo lane, chạy test và đọc log y như bạn, không phải đoán port hay đường dẫn.

Thiết lập agent

devkit mcp config <agent> in ra đúng lệnh hoặc mục cấu hình, kèm đường dẫn tuyệt đối của devkit bạn vừa chạy (app mở từ Dock hay launcher không nhận PATH của shell, nên chỉ ghi devkit sẽ không tìm thấy). Không chỉ định agent thì nó in tất cả. Trong các ví dụ dưới đây, <devkit> là đường dẫn đó, ví dụ /Applications/devkit.app/Contents/Helpers/devkit hoặc ~/.local/bin/devkit.

Với --write, devkit gộp mục đó vào file cấu hình của agent: các server và key khác giữ nguyên, mục devkit cũ được thay, file trước đó được giữ lại thành <file>.devkit-backup-<time>, và file JSON có comment sẽ bị từ chối thay vì bị ghi đè. Với các agent cấu hình theo dự án, --dir <project> chọn thư mục dự án (mặc định: thư mục hiện tại).

Claude Code

claude mcp add --scope project devkit -- <devkit> mcp

hoặc devkit mcp config claude-code --write, lệnh này gộp đoạn sau vào .mcp.json trong dự án:

{
  "mcpServers": {
    "devkit": { "type": "stdio", "command": "<devkit>", "args": ["mcp"] }
  }
}

Codex CLI

codex mcp add devkit -- <devkit> mcp

hoặc devkit mcp config codex --write, lệnh này gộp đoạn sau vào ~/.codex/config.toml ($CODEX_HOME/config.toml nếu biến này được đặt):

[mcp_servers.devkit]
command = "<devkit>"
args = ["mcp"]

Gemini CLI

gemini mcp add devkit <devkit> mcp

hoặc devkit mcp config gemini --write, ghi vào .gemini/settings.json trong dự án:

{ "mcpServers": { "devkit": { "command": "<devkit>", "args": ["mcp"] } } }

Cursor

devkit mcp config cursor --write, ghi vào .cursor/mcp.json trong dự án:

{ "mcpServers": { "devkit": { "command": "<devkit>", "args": ["mcp"] } } }

VS Code (Copilot)

devkit mcp config vscode --write, ghi vào .vscode/mcp.json trong dự án. Lưu ý key ở đây là servers:

{ "servers": { "devkit": { "type": "stdio", "command": "<devkit>", "args": ["mcp"] } } }

Claude Desktop

devkit mcp config claude-desktop --write, ghi vào ~/Library/Application Support/Claude/claude_desktop_config.json (Linux: ~/.config/Claude/). Sau đó khởi động lại Claude Desktop.

{ "mcpServers": { "devkit": { "command": "<devkit>", "args": ["mcp"] } } }

MCP client khác

Một MCP server chạy qua stdio, không cần biến môi trường nào:

{ "command": "<devkit>", "args": ["mcp"], "transport": "stdio" }

Trong app

Mục MCP có một ô cho mỗi agent, kèm lệnh hoặc cấu hình của agent đó và nút Sao chép. Với Claude Code, Gemini CLI, Cursor và VS Code, Ghi vào dự án… hỏi thư mục dự án rồi chạy devkit mcp config <agent> --write --dir <folder>. Khi một agent kết nối, nó hiện dưới Đang kết nối, trên menu bar và trên thanh trạng thái.

Các tool

devkit mcp tools liệt kê các tool cùng nhóm và mô tả (--json kèm thêm input schema). Tham số viết kiểu snake_case; tham số sai trả về kết quả INVALID_ARGUMENT, không phải lỗi giao thức.

Một vài tool nên biết kỹ:

exec

Chạy một lệnh trong thư mục của site hoặc lane, bằng PHP của nó. command là một mảng argv như ["php","artisan","migrate","--force"]; shortcut (artisan, composer hoặc phpunit) thêm php artisan, composer hoặc php vendor/bin/phpunit vào trước. timeout_seconds mặc định là 600, xdebug: true chạy riêng lệnh này với Xdebug. Output là 64 KiB cuối; lệnh chạy lỗi vẫn trả về ok: true, kèm exitCode của nó.

url

Site hoặc lane đang được phục vụ ở đâu, có phản hồi không (một request GET; status dưới 500 là ổn), các port Vite và URL hộp thư mail. Dùng được cả với site đang dừng.

logs

source là laravel (mặc định), engine (web server), proc:<name> hoặc container:<service>; lines mặc định là 200.

db_query

Một câu SELECT, SHOW, DESCRIBE hoặc EXPLAIN chỉ đọc, chạy trong transaction chỉ đọc, tối đa 500 dòng (truncated cho biết khi còn nhiều hơn).

lane_new, site_clone, site_setup

Báo từng bước bằng progress notification khi agent yêu cầu. Mọi tool được truyền progress token cũng báo "vẫn đang chạy" mỗi 10 giây, và huỷ một lần gọi sẽ huỷ luôn công việc đó (exec bị dừng, kể cả trong container PHP).

Có hai thứ cố ý không làm thành tool: devkit trust và devkit hosts sync, vì chúng hỏi mật khẩu của bạn.

Tool phá huỷ và confirm

Sáu tool có tính phá huỷ: stack_down, site_delete, lane_rm, db_reset, db_restore và db_snapshot_rm. Gọi mà không có "confirm": true thì chúng không thay đổi gì và trả về CONFIRM_REQUIRED, mô tả chính xác điều sẽ xảy ra:

{"ok":false,"error":{"code":"CONFIRM_REQUIRED",
  "message":"this would remove lane core-development--crm-fix: stop it, drop its database core_development_l1 and its snapshots, remove its worktree …",
  "hint":"show this to the user; call lane_rm again with \"confirm\": true to go ahead"}}

Một agent đúng mực sẽ cho bạn xem nội dung đó và hỏi bạn trước khi gọi lại với confirm. Ngoài ra, các kiểm tra an toàn thông thường vẫn áp dụng khi có confirm: site_delete và lane_rm từ chối với DIRTY_WORKTREE khi còn thay đổi chưa commit hoặc chưa push, trừ khi có thêm force là true, và db_restore tạo một snapshot an toàn trừ khi safety là false. Các tool này cũng được đánh dấu destructiveHint của MCP, nên client nào hỏi trước các lần gọi phá huỷ sẽ hỏi bạn.

Audit log

Mỗi lần gọi tool được ghi thêm vào ~/.config/devkit/audit.log thành một dòng JSON: thời điểm, pid của server, client (tên agent tự báo), tool, tham số, tool đó có chỉ đọc không, ok hoặc mã lỗi, và thời gian chạy. Thông tin bí mật được thay bằng [redacted] (nội dung template, các tên giống mật khẩu, thông tin đăng nhập trong URL). Log được xoay vòng sang audit.log.1 khi đạt 10 MB.

devkit mcp audit --limit 20
2026-10-26 14:31:07  claude-code  exec        ok                {"command":["php","vendor/bin/phpunit"],"site":"core-development--agent-a"}
2026-10-26 14:29:40  claude-code  lane_rm     CONFIRM_REQUIRED  {"lane":"core-development--old-spike"}
2026-10-26 14:22:13  claude-code  lane_new    ok                {"name":"agent-a","site":"core-development","start":true}

Trong app, MCP → Audit log hiển thị nội dung tương tự và tải lại mỗi khi agent gọi tool. Khi server đang chạy, ~/.config/devkit/mcp/<pid>.json ghi lại agent nào đang kết nối, từ lúc nào và tool gần nhất của nó; devkit status liệt kê các phiên này và dọn file của những server đã bị kill.

Cách làm việc nên dùng

Mỗi agent một lane

Đừng bao giờ để hai agent (hoặc một agent và bạn) làm chung một thư mục. Hãy cho mỗi agent một lane riêng: branch, database và port của riêng nó.

Create a lane "agent-a" of core-development with lane_new (start: true),
work only in its folder, and run tests with exec on core-development--agent-a.

Khi công việc đã được push, xoá lane bằng lane_rm; agent sẽ nhận CONFIRM_REQUIRED trước và nên cho bạn xem những gì sẽ mất.

Chạy test và lệnh qua exec

• Bảo agent chạy test bằng exec trên lane của nó (shortcut: "phpunit", hoặc ["php","artisan","test"]) thay vì shell riêng, để dùng đúng phiên bản PHP và .env của lane.
• Khi chỉ cần debug một lần, dùng exec với xdebug: true thay vì bật Xdebug cho cả site: Xdebug làm chậm mọi request, và với caddy nó được dùng chung cho mọi site trên container.
• Để agent đọc lỗi bằng logs (laravel, rồi proc:queue) và kiểm tra dữ liệu bằng db_query thay vì mở shell database.

Snapshot trước các bước rủi ro

Trước một migration hay một lần sửa dữ liệu, hãy để agent gọi db_snapshot với tên rõ ràng (before_orders_migration). Nếu có sự cố, db_restore cần bạn xác nhận và cũng giữ một snapshot an toàn của trạng thái bị hỏng.

Bắt đầu với status và doctor

Một chỉ dẫn mở đầu tốt: "gọi status, rồi doctor cho site, và cho tôi biết cái gì đang chạy, cái gì đang hỏng trước khi bạn thay đổi bất cứ thứ gì". Cả hai đều chỉ đọc.

Những gì devkit đảm bảo

• Không phá huỷ gì nếu chưa confirm. Sáu tool phá huỷ chỉ mô tả việc chúng sẽ làm cho tới khi được gọi với "confirm": true.
• Mặc định không mất công việc. Xoá site hay xoá lane đều từ chối khi còn thay đổi chưa commit hoặc chưa push, trừ khi agent truyền thêm force. Khôi phục sẽ giữ một snapshot an toàn.
• Không hỏi mật khẩu. Tin cậy chứng chỉ và sửa /etc/hosts không phải là tool. Git chạy bằng thông tin đăng nhập bạn đang có và không bao giờ hỏi.
• Truy vấn chỉ đọc thì chỉ đọc. db_query từ chối mọi thứ ngoài một câu lệnh đọc và chạy nó trong transaction chỉ đọc.
• Mọi thứ đều được ghi lại trong audit log trên máy bạn, đã lược bỏ thông tin bí mật.
• Không gì rời khỏi máy bạn. devkit không có tài khoản, không telemetry; MCP server chỉ nói chuyện với agent đã khởi động nó.