mcp-alexagent

AlexAgent MCP — Hướng dẫn sử dụng

AI-driven DevOps workflow cho dự án ASP.NET (.NET) Microservices, Next.js (FE), và Expo + React Native (Mobile). Một MCP server, ba cụm tools: BE / FE / Mobile.

---

Mục lục

1. AlexAgent là gì?
2. Kiến trúc & cách hoạt động
3. Cài đặt — lần đầu
4. Cấu hình cho 1 project
5. 24 MCP tools
6. 15 slash commands
7. Workflow chuẩn — đi từ ý tưởng đến PR
8. Ví dụ thực tế
9. File generated trong .alexagent/
10. Customization — thêm target mới hoặc sửa logic
11. Troubleshooting
12. FAQ

---

1. AlexAgent là gì?

AlexAgent là MCP server (Model Context Protocol) tự build, giúp Claude Code:

• Hiểu project — scan toàn bộ codebase, biết services/pages/screens hiện có
• Lập kế hoạch — sinh plan có structured tasks + test cases dựa trên feature description
• Code tự động — implement từng task, auto-commit, chạy tests
• Tạo PR — verify, rebase, build, test, push, mở PR qua gh CLI

Khác với scaffold-* skills (chỉ tạo 1 component), AlexAgent xử lý toàn bộ feature lifecycle end-to-end.

Hỗ trợ 3 loại project

Cụm	Stack	Storage plans	Build cmd	Test cmd
BE	ASP.NET 8 + Clean Arch + CQRS + EF Core	.alexagent/be/plans/	dotnet build	dotnet test
FE	Next.js + React + TanStack Query + Tailwind	.alexagent/fe/plans/	npm run build	npm test
Mobile	Expo + RN + Expo Router + TanStack Query	.alexagent/mobile/plans/	tsc --noEmit + npm lint	npm test

---

2. Kiến trúc & cách hoạt động

Sơ đồ

┌──────────────────────┐         ┌────────────────────────┐
│  Claude Code (CLI)   │  stdio  │  alexagent MCP server  │
│                      │◄───────►│  (Node.js)             │
│  - Slash commands    │         │  - 24 tools            │
│  - .claude/skills/   │         │  - dist/server.js      │
└──────────────────────┘         └────────────┬───────────┘
                                              │
                                  PROJECT_DIR (env)
                                              │
                                              ▼
                                  ┌──────────────────────┐
                                  │  Your project repo   │
                                  │  - source code       │
                                  │  - .alexagent/       │
                                  │  - .git              │
                                  └──────────────────────┘

Lifecycle

User gõ /alexagent-fe-plan F001 "Voucher"
   │
   ▼
Claude đọc .claude/skills/alexagent-fe-plan/SKILL.md
   │
   ▼
Claude phân tích → gọi MCP tool alexagent_fe_plan(...)
   │
   ▼
MCP server (running từ dist/server.js):
  - target = feSpec
  - scan PROJECT_DIR
  - generate tasks + tests
  - write .alexagent/fe/plans/F001/{plan.json, PLAN.md, TASKS.md, TESTCASES.md}
   │
   ▼
Claude trình bày plan cho user review

Tách target theo prefix tool

Cụm	Tool prefix	Slash prefix
BE	alexagent_* (no prefix — backward compat)	/alexagent-*
FE	alexagent_fe_*	/alexagent-fe-*
Mobile	alexagent_mobile_*	/alexagent-mobile-*

---

3. Cài đặt — lần đầu

Yêu cầu

• Node.js ≥ 18 (cho MCP server)
• git (cho branch/commit/push)
• gh CLI (cho tạo PR) — brew install gh && gh auth login
• dotnet SDK 8.0 (chỉ cần cho BE projects)
• POSIX shell (macOS / Linux / Git Bash trên Windows)

Cách 1 — Cài qua npm (khuyến nghị)

Không cần clone repo, không cần build. Chỉ config .mcp.json và Claude Code tự download:

{
  "mcpServers": {
    "alexagent": {
      "command": "npx",
      "args": ["-y", "mcp-alexagent"],
      "env": {
        "PROJECT_DIR": "/abs/path/to/your-project"
      }
    }
  }
}

npx sẽ tự download package từ npm registry lần đầu (cache lại cho lần sau).

Pre-release version: ["-y", "mcp-alexagent@rc"] để dùng release candidate.

Cách 2 — Build từ source (cho dev hoặc contribute)

git clone https://github.com/Alexdev257/mcp-alexagent.git
cd mcp-alexagent
npm install
npm run build
npm test          # 42 unit tests pass

Output: dist/server.js (đã chmod +x). Sau đó config .mcp.json trỏ trực tiếp:

{
  "mcpServers": {
    "alexagent": {
      "command": "node",
      "args": ["/abs/path/to/mcp-alexagent/dist/server.js"],
      "env": { "PROJECT_DIR": "/abs/path/to/your-project" }
    }
  }
}

Verify install

npx -y mcp-alexagent --version    # → mcp-alexagent v2.0.0-rc.1
npx -y mcp-alexagent --help       # → usage info

---

4. Cấu hình cho 1 project

Bước 1: Tạo .mcp.json ở root project

Xem Cách 1 hoặc Cách 2 ở trên.

Quan trọng: PROJECT_DIR phải là absolute path. Không dùng ~ hay $HOME. Nếu bỏ qua, MCP sẽ fall back về process.cwd() (thường là project dir Claude Code launch từ).

Bước 2: Restart Claude Code

Trong Claude Code CLI: thoát rồi mở lại trong project. Test:

/         ← gõ slash, xem các /alexagent:* có hiện không

→ 15 lệnh tự xuất hiện (không cần copy file gì!):

• /alexagent:be-init, /alexagent:be-plan, /alexagent:be-status, /alexagent:be-execute, /alexagent:be-complete
• /alexagent:fe-* (5 lệnh)
• /alexagent:mobile-* (5 lệnh)

Bước 3 (optional, recommended): Thêm .claude/CLAUDE.md

Tạo file mô tả project (services, conventions, business rules). MCP init tool sẽ tự đọc và inject vào context của Claude khi planning/executing.

# .claude/CLAUDE.md

## Stack
- ASP.NET 8 Microservices
- ...

## Conventions
- ...

MCP cũng tự đọc:

• .claude/rules/*.md — coding rules áp dụng theo file path
• .claude/skills/*/SKILL.md — scaffold skills hiện có
• .claude/hooks/*.sh — hooks (chỉ liệt kê, không chạy)
• .claude/settings.json — settings

---

5. 24 MCP tools

Mỗi cụm có 8 tools (3 × 8 = 24). Tên tool theo dạng alexagent_{prefix}{action}.

#	Tool	Tác dụng
1	*_init	Scan project — services/pages/screens, tech stack, git, plans hiện có
2	*_plan	Tạo plan mới — sinh tasks + tests theo phase
3	*_plan_status	Xem status plan(s)
4	*_plan_update	Manual update task/test status
5	*_execute	Lấy task tiếp theo + auto-create branch lần đầu
6	*_execute_done	Mark task done + auto-commit
7	*_execute_tests	Chạy tests cho feature
8	*_complete	Pipeline cuối: rebase → build → test → push → PR

Bạn không cần gọi MCP tool trực tiếp — Claude sẽ tự gọi qua slash commands.

---

6. 15 slash commands

Auto-registered từ MCP Prompts (không cần copy SKILL.md). Format: /<server>:<prompt> = /alexagent:<target>-<action>.

Action	BE	FE	Mobile
Scan project	/alexagent:be-init	/alexagent:fe-init	/alexagent:mobile-init
Tạo plan	/alexagent:be-plan	/alexagent:fe-plan	/alexagent:mobile-plan
Execute tasks	/alexagent:be-execute	/alexagent:fe-execute	/alexagent:mobile-execute
Xem status	/alexagent:be-status	/alexagent:fe-status	/alexagent:mobile-status
Push + PR	/alexagent:be-complete	/alexagent:fe-complete	/alexagent:mobile-complete

Argument hints

Prompt	Args
*-init	(none)
*-plan	featureId (required), featureName (required)
*-status	featureId (optional — empty = list all)
*-execute	featureId (required)
*-complete	featureId (required)

Khi user gọi prompt thiếu required args, MCP trả về warning " Missing required arguments" ở đầu content → Claude sẽ hỏi user trước khi proceed.

---

7. Workflow chuẩn — đi từ ý tưởng đến PR

1. /alexagent-{fe|mobile}-init
   └─ Scan project (lần đầu, hoặc sau git pull lớn)

2. /alexagent-{fe|mobile}-plan F001 "Tên feature"
   └─ Mô tả ý tưởng → AI sinh PLAN.md, TASKS.md, TESTCASES.md
   └─ Bạn review → điều chỉnh nếu cần

3. /alexagent-{fe|mobile}-execute F001
   └─ AI tự lấy từng task, code, auto-commit
   └─ Lặp đến khi hết tasks

4. /alexagent-{fe|mobile}-status F001 (optional)
   └─ Xem tiến độ giữa chừng

5. /alexagent-{fe|mobile}-complete F001
   └─ Pipeline cuối: rebase → build → test → push → tạo PR
   └─ Trả về URL PR

---

8. Ví dụ thực tế

Ví dụ 1: Tạo feature "Voucher" cho FE

/alexagent-fe-plan F001 "Voucher Management"

Bạn mô tả:

"Trang admin quản lý voucher. CRUD voucher với fields: code, type (percent/fixed), value, start_date, end_date, max_uses. List có filter theo type và trạng thái active. Form validate Zod. Auth: admin only."

Claude sẽ:

1. Phân tích requirements → thinking
2. Thiết kế approach → routes, hooks, components
3. Gọi alexagent_fe_plan → sinh ra:
   • 5-7 tasks cho domain (types, schemas)
   • 7-10 tasks cho application (API + hooks)
   • 5-8 tasks cho UI (page, list, form, detail, guard)
   • 3-5 tasks cho integration (env, navigation)
   • 6-10 tasks cho testing
   • Tổng: ~25-35 tasks
4. Hiển thị tóm tắt cho bạn review

/alexagent-fe-execute F001

Claude tự code từng task. Mỗi task = 1 commit. Khi hết tasks → chạy npm test.

/alexagent-fe-complete F001

Pipeline:

• Verify all tasks done
• Commit phần thừa
• Rebase onto main
• npm run build (Next.js production build)
• npm test (vitest)
• Push branch
• gh pr create với body auto-generated

→ Trả về PR URL.

Ví dụ 2: Feature Mobile "Wishlist"

/alexagent-mobile-plan M001 "Wishlist for Events"

Mô tả:

"User save event yêu thích. Tab mới trong (tabs)/_layout.tsx. List dùng FlatList có pull-to-refresh. Lưu wishlist trên BE qua API. SignalR notify khi event sale."

Claude tạo tasks bao gồm:

• types/Wishlist + Zod schema
• apiRequest/wishlist.ts (axios)
• hooks: useWishlistList, useWishlistAdd, useWishlistRemove
• screen app/(tabs)/wishlist/index.tsx
• WishlistList component (FlatList + RefreshControl)
• WishlistItem component (card với image)
• Navigation: thêm tab vào _layout
• SignalR connection cho notification
• Tests: jest-expo

Ví dụ 3: BE feature "Refund flow"

/alexagent-plan F042 "Refund Flow with Approval"

Claude tạo:

• Entity: Refund (AuditableEntity) + RefundStatusEnum
• DTOs, CQRS commands (Create/Approve/Reject), Queries (List/Detail)
• Controller với policy OrganizerOnly
• Integration event RefundApprovedEvent + Consumer
• gRPC call sang BookingService để verify booking
• Unit tests + Integration tests

---

9. File generated trong .alexagent/

your-project/
└── .alexagent/
    └── {target}/                       ← be | fe | mobile
        ├── context.json                ← Cache scan output (10 phút TTL)
        └── plans/
            └── F001/
                ├── plan.json           ← Source of truth (đừng sửa tay)
                ├── plan.json.backup    ← Backup auto
                ├── PLAN.md             ← Human-readable: PRD + thinking + approach
                ├── TASKS.md            ← Checklist progress
                ├── TESTCASES.md        ← Test cases
                ├── PROJECT_CONTEXT.md  ← Snapshot CLAUDE.md tại thời điểm tạo plan
                └── CONVENTIONS.md      ← Snapshot các rules/* từ .claude/rules/

Nên commit .alexagent/ vào git — để team biết history và state plans.

---

10. Customization

Thay đổi build/test command

Sửa target spec tương ứng:

Project loại	File	Method
BE	src/targets/be.ts	runBuild(), runTests()
FE	src/targets/fe.ts	runBuild(), runTests()
Mobile	src/targets/mobile.ts	runBuild(), runTests()

VD đổi FE từ npm sang pnpm:

// src/targets/fe.ts
runBuild() {
  const r = run(`pnpm build`, undefined, 600_000);  // ← thay npm → pnpm
  // ...
}

Sau đó: npm run build (rebuild MCP) + restart Claude Code.

Thay đổi default base branch

Trong target spec:

defaultBaseBranch: "develop",   // thay vì "main" / "master"

Hoặc khi gọi tool, override qua args:

alexagent_fe_complete({ featureId: "F001", baseBranch: "develop" })

Thay đổi danh sách tasks/tests sinh ra

Sửa method generateTasks() và generateTests() trong target spec.

VD muốn FE thêm task "Setup Storybook" cho mỗi entity:

// src/targets/fe.ts → generateTasks()
for (const p of spec.entities) {
  // ...existing tasks...
  tasks.push({ id: tid(), title: `Add Storybook stories for ${p}`, phase: "ui", status: "pending" });
}

Thêm target mới (vd: Backend Python/FastAPI)

1. Tạo src/targets/python.ts implement TargetSpec interface (xem targets/types.ts)
2. Tạo src/tools/python.ts:

   import { pythonSpec } from "../targets/python.js";
   import { init as coreInit } from "../core/init.js";
   // ... bind các core functions với pythonSpec

3. Trong src/server.ts, đăng ký 8 tools mới với prefix python_
4. Tạo 5 slash commands trong templates/skills/alexagent-python-*
5. npm run build

Thay đổi conflict resolution strategy trong rebase

src/core/complete.ts → step REBASE → đoạn git checkout --ours/--theirs. Hiện logic:

• BE migration files: --theirs (giữ remote)
• File khác: --ours (giữ local)

Tùy project có thể đổi lại.

---

11. Troubleshooting

Slash commands /alexagent:* không hiện khi gõ /

1. Restart Claude Code (thoát terminal rồi mở lại trong project dir)
2. Verify MCP đang chạy: trong Claude Code gõ /mcp (built-in) → check status alexagent
3. Test MCP manual:

   npx -y mcp-alexagent --version
   # → mcp-alexagent v2.0.0-rc.1

4. Nếu cài qua Cách 2 (build source): kiểm tra dist/server.js có exist + executable

   ls -la /path/to/mcp-alexagent/dist/server.js

Lỗi "PROJECT_DIR is not a git repository"

MCP yêu cầu git repo cho branch/commit operations. Fix:

cd /your/project && git init
# hoặc set PROJECT_DIR trỏ đến đúng git repo trong .mcp.json

Lỗi "PROJECT_DIR does not exist"

Path trong .mcp.json env sai. Phải là absolute path:

"env": { "PROJECT_DIR": "/Users/alex/projects/my-app" }   // ✅
"env": { "PROJECT_DIR": "~/projects/my-app" }             // ❌ tilde không expand
"env": { "PROJECT_DIR": "./my-app" }                      // ❌ relative

Hoặc bỏ env PROJECT_DIR → MCP tự dùng process.cwd() (thường là project dir Claude Code launch từ).

Windows: "single quote" hoặc "command not found" errors

MCP shell-quote tự detect platform (POSIX '...' vs Windows "..."). Tuy nhiên git/gh CLI vẫn cần POSIX shell ở mức nào đó. Khuyến nghị Windows users:

• Dùng Git Bash (cài cùng Git for Windows) làm default shell cho terminal
• Hoặc dùng WSL2 (Linux subsystem)

Nếu vẫn gặp issue trên cmd.exe / PowerShell native: open issue tại GitHub.

npx cache stale, không lấy version mới

# Force refresh
npx -y mcp-alexagent@latest --version

# Hoặc clear toàn bộ npx cache
npx clear-npx-cache
# Rồi reinstall
npx -y mcp-alexagent

Pre-release version

# Mới nhất rc
npx -y mcp-alexagent@rc

# Specific version
npx -y mcp-alexagent@2.0.0-rc.1

Tool gọi xong báo "scan trống"

Nguyên nhân thường gặp:

• PROJECT_DIR sai trong .mcp.json → trỏ vào folder khác, không có code
• Cấu trúc project không match với scanner expected:
  • BE: cần services/{Name}/src/{Name}.{Api,Domain,...}
  • FE: cần src/app/, src/components/, src/hooks/ (Next.js App Router)
  • Mobile: cần app/ (Expo Router) ở root
• Cache cũ → gọi với forceRefresh: true

Build fail trong complete

• BE: check .csproj reference, missing usings, EF migration conflict
• FE: TypeScript strict errors thường gặp — fix trước, không suppress
• Mobile: TypeScript hoặc ESLint errors — npm run lint --fix

Push fail "non-fast-forward"

MCP dùng --force-with-lease (an toàn). Lỗi này thường do:

• Có người khác đã push lên cùng branch → pull về trước, hoặc rebase tay
• Branch protection rules trên GitHub

gh pr create fail

gh auth status
# Nếu chưa login: gh auth login
# Nếu sai org: gh auth login --hostname github.com --web

Plan bị stuck "in_progress"

Mở .alexagent/{target}/plans/{F001}/plan.json xem có task nào ở status in_progress lâu. Có thể manual reset:

alexagent_{target}_plan_update({
  featureId: "F001",
  taskId: "T-007",
  status: "pending"   // hoặc "done" nếu thực ra đã xong
})

dotnet test / npm test báo no tests found nhưng vẫn fail

MCP coi không tìm thấy test = OK. Nếu fail khác → check stderr trong output execute_tests.

---

12. FAQ

Q: MCP có gọi LLM không? Có tốn tokens API không?

Không. MCP chỉ là logic shell + filesystem + git. Tất cả "AI" diễn ra ở Claude Code phía client. MCP chỉ trả JSON cho Claude đọc.

Q: Có chạy được trên Windows không?

Logic shell (bash, git, gh) chạy được qua Git Bash hoặc WSL. Chưa test thuần Windows cmd.

Q: Có chạy được offline không?

Có cho init, plan, execute_done (commit local). Không được cho complete vì cần git fetch + git push + gh pr create.

Q: Plans có được sync giữa máy không?

Có, nếu commit .alexagent/ vào git. Khi pull về máy khác, MCP đọc lại plan.json — state nguyên vẹn.

Q: Nhiều người cùng làm 1 plan được không?

Được, miễn coordinate qua git. MCP không có locking — nếu 2 người cùng execute 1 plan, có thể conflict commits. Khuyến cáo: 1 người 1 feature plan.

Q: Chuyển plan từ in_progress sang abandoned thế nào?

Hiện không có status "abandoned". Dùng plan_update với notes ghi rõ, hoặc xóa folder .alexagent/{target}/plans/{F001}/.

Q: Có giới hạn số tasks/tests sinh ra không?

Không hard limit. Tasks scale theo số entities × số phase. 10 entities có thể tạo 100+ tasks. Plan to lớn → khó review → khuyến nghị chia nhỏ feature.

Q: Slash commands trùng tên với plugin/global skills thì sao?

Project skills override. Nếu trùng tên global, project version ưu tiên.

Q: MCP có log lại lệnh đã chạy không?

Có. console.error() mỗi tool call (timestamp + name + args truncated 200 chars). Xem trong stderr của Claude Code logs.

Q: Sửa source MCP rồi mà chạy không thấy thay đổi?

Quên build:

cd mcp-alexagent && npm run build

Restart Claude Code để MCP server reload.

---

Liên kết

• Source MCP: mcp-alexagent/src/
• Target specs: mcp-alexagent/src/targets/{be,fe,mobile}.ts
• Core logic: mcp-alexagent/src/core/{init,plan,execute,complete}.ts
• Slash command templates: mcp-alexagent/templates/skills/
• Quick install: mcp-alexagent/INSTALL.md

---

AlexAgent MCP v2.0.0 — Ba cụm tools (BE / FE / Mobile), một workflow.