Yakrover 8004 MCP

雅克罗夫-8004-mcp

用于多机器人车队控制的模块化MCP框架，通过 ERC-8004，以及一个机器人端竞价市场——机器人接收任务请求、生成出价、执行有偿工作，并通过美元或Stripe接收付款。

一种基于插件的架构，整合了共享基础设施，因此可以用最少的粘合代码添加任何机器人。每个机器人都有自己的隔离MCP服务器，所有服务器都在一个端口和ngrok隧道后面提供服务。

建筑

┌────────────────────────────────┐     ┌──────────────────────────────────────┐
│     External Marketplace       │     │           LLM / AI Agent             │
│   (yakrover-marketplace)       │     │     (Claude, GPT, etc. via MCP)      │
└──────────────┬─────────────────┘     └─────────────────────┬────────────────┘
               │                                             │
               │  /tumbller/mcp                              │  /fleet/mcp
               │  /tello/mcp                                 │  /tumbller/mcp
               │  /fakerover/mcp                             │  /tello/mcp
               │  → robot_submit_bid                         │  /fakerover/mcp
               │  → robot_execute_task                       │  → fleet_request_bids
               │  → robot_get_pricing                        │  → fleet_accept_bid
               │                                             │  → fleet_execute_task
               │                                             │  → fleet_get_auction_status
               │                                             │  → discover_robot_agents
               │                                             │
               └─────────────────────┬───────────────────────┘
                                     │
                             ┌───────▼─────────┐
                             │  ngrok tunnel   │
                             │  single URL     │
                             │  single port    │
                             └───────┬─────────┘
                                     │
┌────────────────────────────────────▼─────────────────────────────────────────┐
│                          FastAPI Gateway  :8000                              │
│                                                                              │
│ ┌──────────────────────────┐  ┌────────────────────┐  ┌──────────────────┐   │
│ │       /fleet/mcp         │  │   /tumbller/mcp    │  │   /tello/mcp     │   │
│ │   Fleet MCP Server       │  │   Tumbller MCP     │  │   Tello MCP      │   │
│ │                          │  │                    │  │                  │   │
│ │  discover_robot_agents   │  │  tumbller_move     │  │  tello_takeoff   │   │
│ │  fleet_request_bids      │  │  tumbller_is       │  │  tello_land      │   │
│ │  fleet_list_auctions     │  │    _online         │  │  tello_move      │   │
│ │  fleet_accept_bid        │  │  tumbller_get      │  │  tello_rotate    │   │
│ │  fleet_execute_task      │  │    _temperature    │  │  tello_flip      │   │
│ │  fleet_get_auction_status│  │    _humidity       │  │  tello_get_*     │   │
│ │                          │  │                    │  │                  │   │
│ │  ┌───────────────────┐   │  │  robot_submit_bid  │  │  robot_submit    │   │
│ │  │  AuctionEngine    │   │  │  robot_execute     │  │    _bid          │   │
│ │  │  bid fan-out      │   │  │    _task           │  │  robot_execute   │   │
│ │  │  accept / execute │   │  │  robot_get_pricing │  │    _task         │   │
│ │  │  requires_approval│   │  │                    │  │  robot_get       │   │
│ │  └───────────────────┘   │  └────────┬───────────┘  │    _pricing      │   │
│ └──────────────────────────┘           │              └─────────┬────────┘   │
│                                        │                        │            │
│  POST /stripe/webhook                  │                        │            │
│  → verify sig → on_payment_confirmed() │                        │            │
│    Mode A: status="paid", wait         │                        │            │
│    Mode B: auto-execute via task       │                        │            │
│                                        │                        │            │
└────────────────────────────────────────┼────────────────────────┼────────────┘
                                         │                        │
                             ┌───────────▼──────┐    ┌───────────▼────────┐
                             │ TumbllerClient   │    │   TelloClient      │
                             │ (HTTP/httpx)     │    │   (UDP/djitellopy) │
                             └───────┬──────────┘    └─────────┬──────────┘
                                     │                          │
                            HTTP :80 │                UDP :8889 │
                                     ▼                          ▼
                             ┌───────────────┐       ┌──────────────────┐
                             │  ESP32-S3     │       │  DJI Tello       │
                             │  Tumbller     │       │  Drone           │
                             └───────────────┘       └──────────────────┘

Payment paths
  USDC  ──► buyer pays robot on-chain wallet (getAgentWallet) — 88% to robot
  Card  ──► Stripe Checkout ──► POST /stripe/webhook ──► on_payment_confirmed()
            88% routed to operator Stripe Connect Express, 12% platform fee

On-chain
  ERC-8004 registry (Ethereum Sepolia / Base / …)
  └── robot agent card on IPFS: endpoint, tools, bidding_terms

竞价市场

外部 雅科孚市场 策划拍卖。此repo实现了 机器人侧：评标、任务执行、付款收据和链上投标条款。

全生命周期

1. DISCOVER   Robot registered on ERC-8004. Marketplace finds it, reads
              bidding_terms (min_price, accepted_task_types) from IPFS agent card.

2. BID        Buyer posts task → marketplace calls robot_submit_bid on each
              robot's /mcp endpoint → robot evaluates capability + liveness
              → returns price or declines.

3. AWARD      Buyer picks winner. Robot is notified via task acceptance.

4. EXECUTE    Marketplace (or fleet operator) calls robot_execute_task → robot
              does the work → returns delivery_data JSON.

5. DELIVER    Marketplace wraps delivery_data in the yakrover/delivery/v1
              envelope and uploads to IPFS.

6. VERIFY     Buyer reviews sensor data / images via the IPFS link.

7. PAY        Buyer releases payment:
              USDC → robot on-chain wallet (88%)
              Card → Stripe Checkout → /stripe/webhook (88% to Connect Express)

机器人侧MCP工具（在每个机器人/MCP端点上）

Fleet MCP工具（在线/flete/MCP，适用于LLM客户）

审批流程

模式A——循环中的人 (requires_approval=True，默认）：

1. 任务已发布→ 机器人竞标→ 中标
2. 条纹结账已创建→ 买方付款
3. Webhook火灾→ 拍卖预付款 "paid"
4. 车队运营商电话 fleet_execute_task 批准
5. 机器人执行→ 交货日期返回

模式B——自主 (requires_approval=False 在 BiddingTerms): 1–3与模式A相同 4.Webhook火灾→ on_payment_confirmed() 自动安排执行 5.机器人执行→ 结果已存储；查询方式 fleet_get_auction_status

集 requires_approval 每台机器人 BiddingTerms 在插件的内部 metadata().

交付格式

robot_execute_task 总是返回：

{
  "success": true,
  "delivery_data": {
    "readings": [{"type": "temperature", "value": 21.3, "unit": "celsius"}],
    "summary": "Temperature: 21.3°C, Humidity: 58%",
    "robot_id": "989",
    "robot_name": "Tumbller Self-Balancing Robot",
    "duration_seconds": 1.2
  }
}

失败时：

{"success": false, "error": "Reason.", "partial_data": {}}

市场包装 delivery_data 在一个 yakrover/delivery/v1 信封和上传到IPFS——机器人从不自己上传IPFS。

链上竞价条款

每个插件的 BiddingTerms 在注册时作为扁平字符串字段序列化到IPFS代理卡中：

{
  "metadata": {
    "min_bid_price": "50",
    "accepted_currencies": "usd,usdc",
    "task_categories": "env_sensing"
  }
}

通过更改来更新它们 BiddingTerms 在插件中并运行：

uv run python scripts/update_agent.py tumbller 11155111:989

先决条件

• Python 3.13+
• 紫外线 包管理器
• 吸烟 公共隧道账户（免费等级）
• Sepolia ETH用于链上注册（免费 水龙头)
• 增加 IPFS上传帐户（免费层）

快速开始

1.克隆并安装

git clone git@github.com:YakRoboticsGarage/yakrover-8004-mcp.git
cd yakrover-8004-mcp
uv sync --extra fakerover

2.配置环境

cp .env.example .env
# Fill in NGROK_AUTHTOKEN, NGROK_DOMAIN, SIGNER_PVT_KEY, PINATA_JWT

3.运行假漫游车（不需要硬件）

# Terminal 1 — Start the simulator
PYTHONPATH=src uv run python -m robots.fakerover.simulator

# Terminal 2 — Start the MCP gateway
PYTHONPATH=src uv run python scripts/serve.py --robots fakerover

4.连接MCP客户端

# Claude Code
claude mcp add --transport http fakerover http://localhost:8000/fakerover/mcp

然后让克劳德移动假漫游车，读取其温度，或出价。

安装选项

uv sync                          # Core only (discovery + registration)
uv sync --extra fakerover        # With fake rover (no hardware needed)
uv sync --extra tumbller         # With Tumbller robot support
uv sync --extra tello            # With Tello drone support
uv sync --extra marketplace      # Stripe payment integration
uv sync --extra all              # Everything

环境变量

STRIPE_SECRET_KEY 和 STRIPE_WEBHOOK_SECRET 必须同时设置这两个选项才能激活Stripe。 NGROK_DOMAIN 还必须设置（Stripe要求绝对重定向URL）。没有Stripe，USDC链上路径无需额外设置即可工作。

多链支持

所有CLI脚本和 discover_robot_agents MCP工具接受 --chain 标志：

uv run python scripts/register.py tumbller --chain base-mainnet
uv run python scripts/discover.py --provider yakrover --chain base-sepolia

集 CHAIN=base-mainnet 在 .env 更改所有命令的默认值。

发现流程

机器人通过以下方式在EVM区块链上注册 ERC-8004 --任何人都可以在任何地方发现，没有中央目录。

注册（车队运营商，一次性）

# Start the gateway
uv run python scripts/serve.py --robots tumbller --ngrok

# Register on Ethereum Sepolia
uv run python scripts/register.py tumbller

写入区块链：

• MCP端点→ https://your-domain.ngrok.app/tumbller/mcp
• 车队终点→ https://your-domain.ngrok.app/fleet/mcp
• 工具→ ["tumbller_move", ..., "robot_submit_bid", "robot_execute_task", "robot_get_pricing"]
• 投标条款→ min_bid_price=50, accepted_currencies=usd,usdc, task_categories=env_sensing

发现（任何人）

uv run python scripts/discover.py --provider yakrover

# Write discovered endpoints into Claude MCP config
uv run python scripts/discover.py --add-mcp            # → .mcp.json (project)
uv run python scripts/discover.py --add-mcp --scope global  # → ~/.claude.json

或者在运行时通过LLM：

User: "Find robots that can read temperature"
LLM:  calls discover_robot_agents(fleet_provider="yakrover") on /fleet/mcp
  →   returns: Tumbller in Finland, min_bid_price=$0.50, task_categories=[env_sensing]

添加机器人

每个机器人都是一个插件—— src/robots/ 有三个文件：

src/robots/myrobot/
├── __init__.py    # RobotPlugin subclass: metadata(), tool_names(), register_tools(),
│                  #   bid(), execute()
├── client.py      # Communication with the physical robot
└── tools.py       # MCP tool definitions

实施 bid() 和 execute() 选择进入竞价市场：

async def bid(self, task_spec: dict) -> dict | None:
    # Return None to decline; return bid dict to participate
    ...

async def execute(self, task_id: str, task_description: str, parameters: dict) -> dict:
    # Return {"success": True, "delivery_data": {...}}
    ...

集 bidding_terms 上 RobotMetadata 在链上发布定价：

def metadata(self) -> RobotMetadata:
    return RobotMetadata(
        ...,
        bidding_terms=BiddingTerms(
            min_price_cents=50,           # $0.50 minimum
            rate_per_minute_cents=10,     # $0.10/min
            accepted_task_types=["sensor_reading"],
            requires_approval=True,       # False = auto-execute after payment
        ),
    )

看 src/robots/_template/ 为了一个可复制的起点和 docs/MODULAR_FRAMEWORK_PLAN.md 第7节为分步指南。

常用命令

# Serve robots
uv run python scripts/serve.py --ngrok                          # All robots
uv run python scripts/serve.py --robots tumbller --ngrok        # Single robot
uv run python scripts/serve.py --robots tumbller tello --ngrok  # Multi-select

# Fake rover (hardware-free development + bidding tests)
PYTHONPATH=src uv run python -m robots.fakerover.simulator       # Start simulator
uv run python scripts/serve.py --robots fakerover                # MCP gateway

# On-chain registration and management
uv run python scripts/register.py tumbller
uv run python scripts/register.py tumbller --chain base-mainnet
uv run python scripts/update_agent.py tumbller 11155111:989      # Update metadata
uv run python scripts/fix_metadata.py tumbller 989               # Fix on-chain KV keys

# Discovery
uv run python scripts/discover.py --provider yakrover
uv run python scripts/discover.py --add-mcp --provider yakrover

# Wallet
uv run python scripts/generate_wallet.py

项目结构

src/
  core/
    plugin.py              # RobotPlugin base class, RobotMetadata, BiddingTerms
    server.py              # FastAPI gateway, ASGI sub-mounts, Stripe webhook mount
    tunnel.py              # ngrok tunnel helper
    discovery.py           # discover_robot_agents MCP tool + CLI helper
    registration.py        # Generic ERC-8004 register/update/fix
    marketplace_tools.py   # Shared robot_submit_bid/execute_task/get_pricing registrar
    chains.py              # Multi-chain config (eth-sepolia, base-mainnet, etc.)
    wallet.py              # Ethereum wallet generation
  auction/
    models.py              # TaskSpec, Bid, AuctionResult dataclasses
    engine.py              # AuctionEngine — bid fan-out, accept, execute, approval flow
    mcp_tools.py           # Fleet MCP tools (fleet_request_bids, fleet_accept_bid, …)
    payments.py            # StripePaymentHandler — Checkout sessions + webhook verify
    webhooks.py            # FastAPI POST /stripe/webhook route
  robots/
    fakerover/             # Software-only simulator (no hardware needed)
    tumbller/              # ESP32-S3 self-balancing robot (HTTP/httpx)
    tello/                 # DJI Tello drone (UDP/djitellopy)
    _template/             # Copyable scaffolding for new robots
scripts/
  serve.py                 # Start MCP gateway for one or more robots
  register.py              # Register a robot on ERC-8004
  discover.py              # CLI discovery + MCP config writer (--add-mcp)
  update_agent.py          # Update on-chain agent metadata / bidding terms
  fix_metadata.py          # Fix flat on-chain KV keys
  generate_wallet.py       # Ethereum wallet generator
docs/
  BIDDING_MARKETPLACE_PLAN.md  # Full marketplace design
  MODULAR_FRAMEWORK_PLAN.md    # Framework design
  DEVELOPMENT.md               # Implementation progress tracker
  CHANGELOG.md                 # Version history

链接

• ERC-8004规范
• 8004scan最佳实践
• 代理0 sdk
• FastMCP
• MCP规范

许可证

Apache 2.0——请参阅 许可证.