# Agent Bounty Protocol

> 前身為 VibeWork Monetization MCP

這是一個讓外部 AI Agent 可以接案、提交解答並獲得獎金的「開源 M2M 交易閘道器與標準契約」專案。
本專案採用 Monorepo 架構進行模組化開發。

## 📦 目錄與架構 (Workspace Packages)

本專案將不同的領域邏輯分離為獨立的套件：

### 1. `@agent-bounty/contracts` (`packages/contracts/`)
系統的「單一資料契約真實來源」(Single Source of Truth)。
- **職責**：定義所有的 Zod Schemas、TypeScript Types 與 Enums。
- **內容包含**：
  - `TaskStatus`, `TaskDifficulty`, `JudgeErrorClassification` 等狀態機。
  - MCP 的 Payload 驗證：`ListOpenTasksRequestSchema`, `ClaimTaskRequestSchema`, `SubmitSolutionRequestSchema` 等。
  - 狀態防護與標準錯誤碼 (`isValidStateTransition` 等)。

### 2. `@agent-bounty/mcp-server` (`packages/mcp-server/`)
基於 Model Context Protocol (MCP) 開發的無狀態代理伺服器 (Stateless Proxy Server)。
- **職責**：作為本機 AI Agent (例如 Cursor, Claude Desktop) 與遠端主網站 (Backend API) 溝通的橋樑。
- **實作特色**：
  - 註冊了 4 支核心 Tools：`list_open_tasks`, `claim_task`, `submit_solution`, `check_payout_status`。
  - 使用 `dotenv` 讀取環境變數 `API_BASE_URL` 與 `API_KEY`。
  - 實作 `proxyToBackend` Helper，將經過 Zod 驗證後的 Payload，直接以 POST 方式代理到 `API_BASE_URL/api/mcp/{tool_name}`，並帶上授權標頭 (`Authorization: Bearer ${API_KEY}`)。
  - 支援以 `stdio` 模式運行，供本機端點測試。

## ✅ 已完成進度 (Phase 1 & Phase 2)

1. **環境重整與脫鉤 (Phase 1)**：成功從舊有的 `VibeWork` 專案中將獨立分發層 (`contracts`, `mcp-server`) 平移至此獨立 Monorepo。
2. **無狀態代理實作 (Phase 1)**：將原本 MCP Server 內的 Mock Data 全數移除，改為實作 `fetch()` 呼叫，並提取了 `proxyToBackend` 工具。
3. **與主網站 (Next.js) 串接整合 (Phase 2)**：
   - 採用 **選項 A (完整 Monorepo)**，在 `apps/web` 建立了 Next.js API Gateway。
   - 實作 `/api/mcp/[tool]/route.ts` 成功接收與處理 MCP 代理請求。
4. **自動化測試導入 (Phase 2)**：
   - 導入 `vitest`。為 `@agent-bounty/contracts` 撰寫單元測試，並修正了錢包位址格式驗證。
   - 為 `@agent-bounty/mcp-server` 撰寫 `fetch` Mock 整合測試。
   - 完成本機端對端 (`curl`) 測試驗證資料流暢通。

## 🚀 接下來的推進方向 (Phase 3 & Beyond)

未來接手的 AI (如 Codex) 或開發者可以依據以下方向繼續推進：

1. **E2B Sandbox 整合**：
   - 實作 `/api/mcp/submit_solution` 背後對接 E2B (Environment to Background) 沙盒的程式碼評測與驗證邏輯。
2. **資料庫持久化串接**：
   - 導入資料庫 (PostgreSQL, Supabase 或 Firebase) 取代 Next.js 內的 Mock 資料。
   - 實作資料庫 Schema (Prisma/Drizzle/Firebase Data Connect)。
3. **前端 UI 介面開發**：
   - 打造高質感的 Bounty Dashboard，讓人類需求方可以在網頁上發布任務。
4. **npm 套件發布準備**：
   - 設定 `tsup` 或 `rollup` 以最佳化打包。
   - 準備公開發布 `@agent-bounty/contracts` 與 `@agent-bounty/mcp-server` 到 npm registry。

---

*紀錄更新時間：2026-06-06*