Tumbller 8004 MCP

翻滚剂

使用以下方式将物理机器人注册为链上AI代理 ERC-8004 并通过MCP展示其功能。

该项目将Tumbller ESP32-S3自平衡机器人的HTTP API包装为MCP服务器，并将其注册在Ethereum Sepolia上，以便其他代理可以发现并与之交互。

建筑

Claude / AI Client
        |
        | MCP (streamable-http)
        v
  FastMCP Server (port 8000)
        |
        | ngrok tunnel
        v
  Public URL (*.ngrok-free.dev/mcp)
        |
        | registered on-chain
        v
  ERC-8004 Identity Registry (Sepolia)
        |
        | tokenURI -> IPFS
        v
  Agent Card JSON (Pinata/IPFS)

先决条件

• Python 3.13+
• 紫外线 包管理器
• 带有HTTP API的ESP32机器人（或任何含HTTP-控制设备）
• Sepolia ETH用于天然气（免费 水龙头)
• 增加 IPFS上传帐户（免费层）
• 吸烟 公共隧道账户（免费等级）

快速开始

1.克隆并安装

git clone 
cd tumbller-agent
uv sync --prerelease=allow

--prerelease=allow 是必需的，因为 agent0_sdk 取决于 ipfshttpclient>=0.8.0a2.

2.配置环境

cp .env.example .env

编辑 .env 与你的价值观：

3.生成钱包

uv run python src/generate_wallet.py --new

这将创建一个以太坊密钥对并将其保存到 .env。从水龙头上用Sepolia ETH为其提供资金。

4.启动MCP服务器

# Local only (for testing with Claude Code)
uv run python src/server.py

# With ngrok tunnel (for public access and registration)
uv run python src/server.py --ngrok

服务器运行在 http://localhost:8000/mcp 使用MCP流式http传输。

5.使用克劳德代码进行测试

将MCP服务器添加到Claude代码中：

claude mcp add --transport http tumbller http://localhost:8000/mcp

然后在Claude Code会话中，让Claude移动机器人或检查其温度。

6.在ERC-8004上注册

MCP服务器正在运行（ --ngrok):

uv run python src/register_agent.py

这将：

1. 创建一个具有名称、描述和MCP端点的代理
2. 声明MCP工具： move, is_robot_online, get_temperature_humidity
3. 设置链上元数据： category=robot, robot_type, fleet_provider, fleet_domain
4. 通过Pinata将代理卡JSON上传到IPFS
5. 在身份注册表上创建ERC-721 NFT，并将tokenURI设置为IPFS哈希

输出：

Agent registered on Ethereum Sepolia!
Agent ID: 11155111:989
Agent URI: ipfs://bafkrei...

7.发现已注册的机器人

uv run python src/discover_robot_agent.py

搜索所有代理 category=robot Sepolia上的元数据，并显示他们的工具和车队信息。

注册自己的机器人

要注册其他机器人，请修改以下文件：

server.py-定义您的MCP工具

用机器人的功能替换工具功能：

@mcp.tool
async def move(direction: Literal["forward", "back", "left", "right", "stop"]) -> dict:
    """Move the robot."""
    return await robot.get(f"/motor/{direction}")

@mcp.tool
async def my_custom_sensor() -> dict:
    """Read a custom sensor."""
    return await robot.get("/sensor/custom")

register_agent.py-更新元数据

更改代理名称、描述和元数据以匹配您的机器人：

agent = sdk.createAgent(
    name="My Robot Name",
    description="Description of your robot's capabilities (50-500 chars).",
)

# Update the tool list to match your server.py
mcp_ep.meta["mcpTools"] = ["move", "my_custom_sensor"]

# Set your classification metadata
agent.setMetadata({
    "category": "robot",                    # ERC-8004 reserved key
    "robot_type": "differential_drive",     # your robot type
    "fleet_provider": "your-org",           # your organization
    "fleet_domain": "your-domain.com",      # fleet management domain
})

链上元数据密钥

看 ERC-8004最佳实践 对于完整的元数据标准。

更新现有注册

注册后更新IPFS元数据或MCP工具：

uv run python src/update_agent.py

要单独修复链上元数据键（避免随机数问题）：

uv run python src/fix_metadata.py

项目结构

src/
  server.py                 # FastMCP server with robot tools
  tumbller_client.py        # Async HTTP client for robot API
  tunnel.py                 # ngrok tunnel helper
  register_agent.py         # ERC-8004 registration (first time)
  update_agent.py           # Update existing registration
  fix_metadata.py           # Fix on-chain metadata keys
  discover_robot_agent.py   # Find registered robot agents
  generate_wallet.py        # Ethereum wallet generator
docs/
  PLAN.md                   # Architecture and implementation plan
  CHANGELOG.md              # Release notes

已知限制

• SDK自动发现功能已损坏：The agent0_sdk EndpointCrawler不支持MCP流式http传输。工具必须通过以下方式手动申报 mcp_ep.meta["mcpTools"] 随着 auto_fetch=False.
• 子图索引延迟：链上更新后，Graph可能需要时间重新索引。发现脚本回退到MCP工具的直接IPFS获取。
• 非竞争条件：SDK的 registerIPFS() 在主事务之后立即提交元数据事务时，可能会遇到nonce错误。使用 fix_metadata.py 用于单独的元数据更新。

链接

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