agent-bounty-protocol/CONTEXT.md

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