Plugin scout

Điều khiển Astra Scout từ Claude Code, Codex CLI hoặc Gemini CLI qua MCP để chạy, viết và sửa flow.

Plugin scout cho phép Claude Code, OpenAI Codex CLI và Gemini CLI điều khiển Astra Scout đang chạy trên máy Mac của bạn, thông qua MCP. Từ terminal, bạn có thể chạy flow Maestro, viết flow từ mô tả, sửa flow fail, khám phá app như người dùng, kiểm tra tracking và chẩn đoán thiết lập.

Plugin chỉ chứa skill, command và cấu hình MCP. Nó không có binary, không có hook lúc bắt đầu session và không có script nào chạy trên máy bạn. Mọi việc với device do Astra Scout thực hiện.

Skill

Skill	Dùng để
run-flow	Chạy flow từ file hoặc YAML dán vào và xem kết quả từng lệnh, video và crash
write-flow	Viết flow mới từ mô tả, đọc text và id thật từ màn hình, kiểm tra, lưu (hỏi trước khi ghi đè) và chạy thử
fix-flow	Chạy vòng tự sửa của Astra Scout cho flow fail, xem diff và chỉ lưu nếu bạn đồng ý
explore-app	Khám phá app theo một persona và nhận báo cáo Markdown kèm các flow đề xuất
check-tracking	Chạy flow, rồi kiểm tra event Amplitude với catalog nêu trong header của flow (tracking-specs/<app>.yaml) và các step assertEvents, rồi giải thích các rule fail hoặc N/A
device-setup	Dùng Kiểm tra thiết lập để tìm và sửa error Xcode, Team ID, Developer Mode, Android SDK và AI CLI

Command: /scout:setup kiểm tra Astra Scout có đang chạy không, URL MCP đúng chưa, MCP đã bật chưa và token đã đặt chưa, và hiện các step cài cho từng CLI. /scout:doctor chạy kiểm tra thiết lập. Codex không có command /scout:…, nên hãy bảo nó "run scout setup" hoặc gõ $ để chọn skill.

Cài bằng nút bấm (khuyến nghị)

App native đã đóng gói sẵn plugin.

1. Mở Settings → CLI AI. Mỗi CLI hiện một trạng thái: Chưa cài, Đã cài (phiên bản), Cần cập nhật, CLI chưa đăng nhập hoặc Chưa có CLI, kèm một dòng Độ phủ agent: N/M CLI đã có plugin.
2. Bấm Cài đặt (hoặc Cập nhật) trên dòng của một CLI. App sao chép plugin đóng gói sẵn vào ~/.astra-scout/plugin và hiện lệnh ở mục Lệnh. Đọc lệnh rồi bấm Chạy (hoặc Sao chép để tự chạy trong terminal của bạn). Kết quả hiện trong một khung log bên dưới lệnh, và trạng thái được kiểm tra lại khi xong. Không có gì chạy cho tới khi bạn bấm Chạy.
3. Bấm Thêm SCOUT_MCP_TOKEN vào shell. Lệnh hiện ra sẽ thêm một dòng vào shell profile của bạn, đọc token từ file mcp-token của Astra Scout. Token không hiển thị, và chạy hai lần không thêm trùng.
4. Nếu Astra Scout không ở cổng 5050, bấm thêm Đặt SCOUT_MCP_URL.
5. Khởi động lại CLI và chạy /scout:setup.

App không nhúng terminal. Mọi lệnh đều có thể sao chép và chạy trong terminal của bạn.

Cài thủ công

Nếu bạn đã cài plugin vào ~/.astra-scout/plugin bằng các nút, hãy dùng đường dẫn đó. Nếu không, dùng thư mục plugin/ của repository.

CLI	Cài đặt	Cập nhật
Claude Code	claude plugin marketplace add ~/.astra-scout/plugin && claude plugin install scout@astra-scout	claude plugin marketplace update astra-scout && claude plugin update scout@astra-scout
Codex	codex plugin marketplace add ~/.astra-scout/plugin && codex plugin add scout@astra-scout	Giống lệnh cài
Gemini CLI	gemini extensions install ~/.astra-scout/plugin	gemini extensions update scout

Kiểm tra kết nối: trong Claude Code, /mcp phải hiện plugin:scout:astra-scout đã kết nối. Trong Codex, codex mcp list. Trong Gemini CLI, gemini mcp list.

Chỉ dùng một cách kết nối. Nếu bạn đã thêm thủ công một MCP server astra-scout, hãy xoá nó để các tool không bị liệt kê hai lần.

MCP token

1. Mở Settings → MCP. MCP được bật mặc định ở http://localhost:5050/mcp.

2. Bấm Copy token. Token được tạo ở run đầu và lưu trong mcp-token ở thư mục dữ liệu (~/Library/Application Support/Astra Scout/data/mcp-token với app native).

3. Đặt nó vào một biến môi trường. Plugin chỉ đọc token từ đó:

   echo "export SCOUT_MCP_TOKEN='<token>'" >> ~/.zshrc
   exec zsh

Tạo token mới (mũi tên tròn cạnh token) tạo một token mới. Các CLI dùng token cũ bị từ chối cho đến khi bạn cập nhật biến.

Nếu Astra Scout không ở cổng 5050

App chuyển sang cổng khác khi 5050 bận và ghi URL thật vào ~/.astra-scout/mcp.json. Cách đơn giản nhất là giải phóng cổng 5050 và mở lại app. Nếu không, hãy trỏ CLI tới URL mới:

CLI	Cách làm
Claude Code, Gemini CLI	export SCOUT_MCP_URL='http://localhost:<PORT>/mcp', rồi khởi động lại CLI
Codex	codex mcp add astra-scout --url http://localhost:<PORT>/mcp --bearer-token-env-var SCOUT_MCP_TOKEN

Mọi CLI khác hỗ trợ MCP qua streamable HTTP đều có thể dùng một server tên astra-scout tại URL đó với header Authorization: Bearer ${SCOUT_MCP_TOKEN}.

Bạn có thể nhờ gì

• "Liệt kê các device, rồi chạy flows/samples/settings_smoke.yaml trên một iPhone simulator"
• "Viết một flow: mở Settings, vào General, kiểm tra About hiển thị. Lưu vào samples/"
• "mydmv/smoke_launch.yaml fail. Tự sửa tối đa 3 vòng và cho tôi xem diff trước khi lưu"
• "Khám phá phần onboarding như một người mới, 25 step, và viết báo cáo"
• "Chạy mydmv/onboarding_paywall_skip.yaml, rồi kiểm tra tracking" (header của flow nêu mydmv/tracking-specs/mydmv.yaml)
• "iPhone không kết nối được và báo cần một development team. Hãy kiểm tra giúp."

An toàn

• run_flow, run_command, autofix_flow và explore_app chạy ngay trên device test, không cần xác nhận. Tool duy nhất cần bạn duyệt là report_bug: mở Astra Scout và duyệt trong Chờ xác nhận, nơi ghi rõ CLI nào đã yêu cầu. Không có tool nào cho CLI tự xác nhận.
• Không có tool để xoá file hay chạy lệnh shell. save_flow không ghi đè nếu bạn chưa đồng ý, và mọi đường dẫn đều nằm trong workspace. Mỗi device chỉ chạy một lần tại một thời điểm.
• Các tool chỉ đọc được cho phép sẵn. Các tool ghi hoặc thao tác trên device (save_flow, run_flow, run_command, autofix_flow, kết nối device) theo các hộp xin quyền thông thường của CLI.
• Mọi lời gọi MCP đều được ghi log và liệt kê trong Hoạt động từ CLI ở Settings → MCP.
• Token là bí mật cục bộ. Đừng dán nó vào chat hay commit.
• Báo bug lên Jira là gửi ra ngoài, nên report_bug luôn cần bạn xác nhận trong app. Xem Jira.

Liên quan

• Trợ lý AI cho khung chat trong app
• Khám phá app và Tracking