verex

Phase 1: Core (Week 1~3) — 실행 계획

docs/principles/first-scope.md의 Phase 1을 실제 작업 단위로 풀어낸 문서. 원칙: 단순하게 시작 / 작게 만들기 / 빠르게 검증.

목표

로컬 anvil 위에서 다음 end-to-end 동선이 web UI로 완주되는 것:

market 생성 → YES/NO 베팅 → 수동 resolve → claim

이게 끝나야 Phase 2(API/인덱서/오라클)의 의미가 생긴다.

범위

포함 (in)

의도적으로 제외 (out)

작업 항목

packages/contracts

packages/sdk

packages/web

packages/openclaw-skill (superseded — see “MCP Server v0” section below)

The Week 2 OpenClaw-specific skill spike has been replaced by a single MCP server (@verex/mcp-server) that any harness — OpenClaw, Claude Dispatch, Claude Desktop, Cursor — connects to. OpenClaw skill / Dispatch connector become thin wrappers on top of MCP in a later phase. The Week 2 work item is now: scaffold the MCP server. Full spec: see “MCP Server v0 — Phase 1 Task Spec” at the bottom of this file.

마일스톤

M 시점 산출물
M1 Day 3 컨트랙트 + 테스트 통과, anvil 배포 스크립트 동작
M2 Day 7 SDK로 anvil 위에서 create/bet/claim CLI 시연
M2.5 Day 11 MCP server v0 scaffold + list_markets works from Claude Desktop on local anvil
M3 Day 14 Web에서 메타마스크로 동일 플로우 완주
M4 Day 21 Demo recording — 두 지갑 베팅, owner resolve, winner claim

Week 2 todo (Day 8~14)

Runs in parallel with Web MVP. MCP server work is time-boxed — if it slips, Web MVP takes priority and MCP rolls into Week 3.

검증 기준 (acceptance)

리스크 & 주의

후속 Phase (요약)

각 phase는 별도 02-*.md, 03-*.md로 확장 예정.

MCP Server v0 — Phase 1 Task Spec

Context

You are working in the Verex monorepo (/Users/jay/work/verex). Verex is a Web3 prediction market dApp. The full design is in docs/principles/ (see the v1.1 design doc).

Currently the design doc has §11.1 (TODO) which proposes integrating Verex with personal AI assistants (OpenClaw skill, Dispatch, etc.) in Phase 3.

We are changing this decision: instead of writing one integration per harness (OpenClaw skill, Dispatch connector, etc.), we will publish a single MCP (Model Context Protocol) server as the canonical machine interface to Verex. Any harness — OpenClaw, Claude Dispatch, Cursor, Claude Desktop, etc. — connects to this MCP server. The MCP server becomes the single source of truth for programmatic access; OpenClaw skills or Dispatch connectors (if we publish them later) become thin wrappers around it.

We are also moving this work into Phase 1 because:

Goal of This Task

Update planning documents and scaffold the new package so that Phase 1 includes a working read-only Verex MCP server.

Scope

In scope (this task)

  1. Update docs/principles/ design doc to reflect the new decision.
  2. Update docs/features/01-phase-1-core.md to add the MCP server work.
  3. Add a new ADR (or equivalent) under docs/history/ documenting the decision.
  4. Scaffold packages/mcp-server/ with package.json, tsconfig, README, and stub source files.
  5. Update root pnpm-workspace.yaml and turbo.json so the new package is part of the monorepo.

Out of scope (do NOT do in this task)

Design Constraints

Tools to Expose (read-only, v0)

These are the tools the MCP server should advertise. For this task only declare them in the README + as stubs that throw NotImplementedError. Implementation comes in a follow-up task.

Tool Input Output Notes
list_markets { status?: "open" \| "resolved" \| "all" } Market[] Calls sdk.markets.list()
get_market { id: string } Market Calls sdk.markets.get(id)
get_position { user: string, marketId: string } Position Calls sdk.positions.get(...)
get_market_stats { id: string } { yesPool, noPool, impliedYesProb } Derived in SDK

Write tools (buy_yes, buy_no, claim, subscribe_market) are deferred to Phase 3 — list them in the README under a “Future tools (post-AA)” section but do not stub them.

Concrete Deliverables

  1. docs/history/0001-mcp-server-as-canonical-agent-interface.md — short ADR (Context / Decision / Consequences) explaining why MCP is now the single agent interface and why it moved to Phase 1.

  2. docs/principles/ design doc edit — modify §11.1:
    • Change “1차 후보 하네스: OpenClaw” to “1차 인터페이스: MCP 서버 (@verex/mcp-server). 하네스(OpenClaw / Dispatch / Claude Desktop / Cursor 등)는 모두 이 MCP 서버를 경유한다.”
    • Move “사용자 측 = OpenClaw skill, 시스템 측 = Claude Agent SDK” framing to: “공통 인터페이스 = MCP. OpenClaw skill / Dispatch connector는 후속 단계에서 MCP 위의 thin wrapper로 발행.”
    • Mark questions 2 (skill 배포 경로) as “MCP가 정답이므로 해소”.
    • Question 1 (AA + session key)은 그대로 — write tools 시점에 다시 등장.
  3. docs/features/01-phase-1-core.md edit — add a new section (suggest: §4 or appended) titled “MCP Server v0 (read-only)” containing:
    • Subtask: scaffold packages/mcp-server/
    • Subtask: declare 4 read tools as stubs
    • Subtask: implement list_markets + get_market against @verex/sdk
    • Subtask: smoke test by connecting from Claude Desktop locally and listing markets on a local anvil/foundry node
    • Acceptance: from Claude Desktop, the user can ask “list current Verex markets” and see results that match cast queries against the deployed Market contract.
  4. packages/mcp-server/ — scaffold: 
    packages/mcp-server/
├── src/
│   ├── index.ts           # entry: starts MCP stdio server
│   ├── server.ts          # registers tools
│   ├── tools/
│   │   ├── list-markets.ts
│   │   ├── get-market.ts
│   │   ├── get-position.ts
│   │   └── get-market-stats.ts
│   └── config.ts          # env loading
├── test/
│   └── server.test.ts     # one trivial test that the server boots
├── package.json
├── tsconfig.json
└── README.md
    • package.json: name @verex/mcp-server, private: true, depends on @verex/sdk (workspace:*) and @modelcontextprotocol/sdk.
    • README.md: how to run locally (pnpm --filter @verex/mcp-server dev), how to add to Claude Desktop’s claude_desktop_config.json, list of v0 tools, list of future tools (write path), and the SDK-only rule.
    • Each tool stub returns throw new Error("NotImplemented: <tool> ships in a follow-up task") except list_markets and get_market, which call the SDK if it exposes those methods, otherwise also throw NotImplemented.
  5. Root config edits — ensure pnpm-workspace.yaml includes packages/mcp-server and turbo.json pipelines (build, dev, test, lint) cover it the same way as other packages.

Verification

After your changes, the following should all pass:

pnpm install
pnpm --filter @verex/mcp-server build
pnpm --filter @verex/mcp-server test
pnpm --filter @verex/mcp-server dev   # should start and wait on stdio

And manually:

What to Do If You Hit Ambiguity

Final Output

When done, summarize in chat:

  1. Files created (paths).
  2. Files modified (paths).
  3. Any decisions you had to make that weren’t specified.
  4. The exact commands the user should run to verify.