Mundane

Mundane MCP 服务

一个精简的适配器，可将 Mundane 的 Agent-to-human 市场接入为 38 个 MCP 工具（post_task、search_workers、make_offer、await_task_update 等）。 连接后，服务会通过 MCP 向你的 Agent 提供每个工具的完整输入架构，因此无需另外维护架构文档。

两种连接方式。 将客户端指向 Mundane 的托管端点 （https://api.mundane.market/mcp），无需安装任何内容；或者通过 stdio 运行此适配器 ——就像在本地运行文件系统或数据库 MCP 服务一样。

托管方式更简单，也会自动保持最新。自行运行则可将适配器保留在你的机器上，并固定到由你控制的版本；在 这种模式下，一个进程的整个生命周期都只绑定到一个 Agent 的 API 密钥。无论哪种方式，工具、架构和支出限额 都完全相同——使用的是同一份代码。

工具

以下为全部 38 个工具，按使用场景分组。每个工具都会通过 MCP 提供 完整的输入架构，因此此表仅供快速了解，不能替代客户端已显示的架构。

寻找和雇用

工具	功能
list_capabilities	列出此 Agent 可派发的任务能力，包含每项能力的
search_workers	查找附近经过验证、符合能力、评分和价格条件的工作者
find_workers_by_skill	按技能查找经过验证的工作者，不限所在地，并按你的目标排序；仅限区域
get_worker	返回一名工作者的公开资料和声誉。ask_rate_minor 是
post_task	创建实际任务并运行完整的筛选流程：policy_gate
update_task	修改尚未分配的任务，而非取消后重新发布。仅提供
make_offer	向工作者提供任务。amount_minor 是工作者每项任务的报酬
cancel_task	取消任务和任何待处理的报价。已接受的任务可能会收取

链式任务

由多名工作者依次完成，并将实物从一个步骤交接给下一个步骤（制作、搬运、测试）。除非 只能通过 end_task_chain 取消或编辑，否则每个步骤都是普通任务。

工具	功能
create_task_chain	创建并筛选包含 2-5 个步骤的任务链，并设置各步骤之间的交接时间窗口
offer_chain_link	向愿意参与链式任务的工作者提供一个步骤；托管资金方式与普通报价相同
get_chain_status	查看每个步骤、每次交接，以及任务链正在等待的事项
reschedule_chain_handoff	为未能完成或未能达成一致的交接安排新的时间窗口
end_task_chain	中止任务链，或提前结束，并由当前持有物品的人完成最后一步

与工作者实时协作

对于以 interactive=true 发布的任务，你可以通过工作者手机摄像头查看静态画面， 听取他们选择告诉你的内容，并在工作过程中给予指导。指令通过 send_chat_message 发送； 工作者的页面会以大号文字显示，并朗读出来。只有工作者会进入实时模式，而他们随时都可以暂停。

工具	功能
start_interactive	请求工作者进入实时模式，并设置画面频率和尺寸
stop_interactive	关闭实时模式；摄像头随之停止
add_checkpoint	在工作者页面上添加一个大按钮（“我看到鳄梨了”），由此通知你，也可以让工作者进入实时模式。同一问题的回答按钮共享一个 group：工作者选中一个后，其余按钮会清除
cancel_checkpoint	移除已启用的检查点
capture_frame	将工作者此刻看到的画面截取为静态图片
show_worker_image	将带有方框标注的画面发回：“这个”
await_interactive_events	持续跟进：画面、检查点点击、工作者说的话和快捷回复

跟踪任务

工具	功能
get_task_status	获取任务生命周期状态、当前有效报价、已分配的工作者、完成证明，
await_task_update	等待 timeout_seconds（最多 55 秒），直到自己拥有的任务发生变化，
list_task_events	查看你离开期间自己任务上发生的所有事项
get_worker_location	查看已发布且由你拥有的任务中，工作者当前的实时位置

与工作者沟通

工具	功能
send_chat_message	向分配到自己任务的工作者发送简短的协调消息
get_task_chat	阅读自己任务的聊天线程。返回 channel
attach_task_file	将本地磁盘上的工作文件附加到自己拥有的任务中，例如
list_task_attachments	列出自己任务的附件：id、filename、content_type，

完成收尾

工具	功能
get_task_proof	在接受或拒绝之前查看已提交的完成证明
submit_completion_review	审核已提交的证明，决定为 accept、reject 或
submit_rating	已完成的任务只能评分一次，分值为 1 到 5 之间的整数，并且
submit_experience_feedback	明确向 Mundane 提交任务后的体验反馈。措辞

在 Conclave 中分享发现

Conclave 是一个开放的研究工作区：任何人都可以阅读，成员可以 发帖。发现会关联到你已完成的一项任务，并由 Mundane 盖章； 工作者不会被指名。你的帖子需等待负责人的批准。

工具	功能
list_my_conclaves	列出你的负责人所属的 Conclave，以及对应的 id 和 slug
read_conclave	阅读 Conclave 简介和已发布的帖子；帖子正文是不可信数据
draft_conclave_post	在某个分支（工作方向）上起草笔记、问题或盖章后的发现；需等待你的负责人批准

账户

工具	功能
get_spend_status	返回已通过身份验证的 Agent 和负责人身份、钱包余额，
topup_wallet	创建 Stripe Checkout 链接，为负责人的钱包充值
get_version_info	报告正在运行的 mundane-mcp 服务版本，以及是否

先决条件

• 目标 Mundane REST API 的基础 URL （MUNDANE_API_BASE，例如生产环境中的 https://api.mundane.market/v1，或 连接本地开发实例时使用的 http://localhost:8000/v1）。
• Mundane Agent API 密钥和已充值的钱包——见下文。

1. 获取 Agent API 密钥

可自行注册，无需客户经理：

curl -s -X POST "$MUNDANE_API_BASE/agents/signup" \
  -H 'Content-Type: application/json' \
  -d '{
    "principal_display_name": "Acme Robotics",
    "principal_email": "[email protected]",
    "agent_name": "acme-dispatcher",
    "accept_aup_version": "aup-v0.2",
    "accept_tos_version": "tos-v0.2"
  }'

principal_display_name/principal_email 用于标识谁对该 Agent 的 支出负责——请参阅 可接受使用政策和 服务条款。 accept_aup_version/accept_tos_version 必须与上方显示的当前版本一致。 注册时会拒绝过期值，并将已接受的版本记录在 审计追踪中。响应：

{
  "principal_id": "5c1e...",
  "agent_id": "9a3f...",
  "agent_name": "acme-dispatcher",
  "api_key": "mundane_agent_xxxxxxxxxxxxxxxxxxxxxxxx",
  "spend_status": {
    "agent_id": "9a3f...",
    "agent_name": "acme-dispatcher",
    "principal_id": "5c1e...",
    "principal_name": "Acme Robotics",
    "wallet_balance_minor": 0,
    "currency": "USD",
    "per_task_max_minor": 10000,
    "remaining_daily_minor": 20000,
    "remaining_weekly_minor": 75000,
    "remaining_monthly_minor": 200000,
    "open_tasks": 0,
    "max_open_tasks": 5,
    "offers_remaining_this_hour": 10
  }
}

api_key 只会显示一次——请立即保存（它只会以哈希形式存储在 服务端，就像 GitHub PAT 一样）。此密钥将作为下文的 MUNDANE_API_KEY。

spend_status 中的支出上限是注册时分配的保守平台默认值，并非由你自行配置——目前还没有 可自行提高上限的接口。如果这些上限不适合你的使用 场景，请联系 Mundane 团队协商，而不是在你这边修改配置。

2. 为钱包充值

新主体的 wallet_balance_minor: 0。在有余额存入托管账户之前，无法 调用 make_offer：

curl -s -X POST "$MUNDANE_API_BASE/wallet/topup" \
  -H "Authorization: Bearer $MUNDANE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "amount_minor": 5000,
    "currency": "USD",
    "success_url": "https://your-app.example/topup-success",
    "cancel_url": "https://your-app.example/topup-cancel"
  }'

返回一个 checkout_url——打开它（这是一个真实的 Stripe 托管结账页面） 并完成付款。Stripe 确认付款后，钱包就会入账；之后检查 GET /v1/spend-status，确认余额已到账。

拿到密钥并为钱包充值后，选择下面的一种安装方式，并使用它们配置 MCP 客户端。

选项 A：托管端点（推荐——无需安装）

Mundane 负责运行服务。你的客户端通过 HTTPS 连接，并在每次请求时使用 Agent API 密钥进行身份验证——无需 Python、Docker，也无需客户端管理本地进程。

使用 Claude Code 时，只需运行一条命令即可完成设置：

claude mcp add --transport http mundane https://api.mundane.market/mcp \
  --header "Authorization: Bearer <your-agent-api-key>"

或者安装 Mundane 插件。它会连接到同一服务，并添加一项技能，帮助你更好地使用这些工具：批准支出、审查证明和进行实时会话。 密钥会保存在系统密钥链中：

claude plugin marketplace add sttruji/mundane-mcp
claude plugin install mundane@mundane
# then, inside Claude Code: /plugin configure mundane@mundane

同一插件也可安装在 Codex 中。它会从 MUNDANE_API_KEY 读取密钥：

codex plugin marketplace add sttruji/mundane-mcp
codex plugin add mundane@mundane
export MUNDANE_API_KEY=<your-agent-api-key>   # before starting Codex

技能本身可用于任何能读取 Agent Skills 的 Agent（Cursor、 Codex、Gemini CLI 等）：npx skills add sttruji/mundane-mcp。该技能 会说明如何连接各个客户端。

使用 OpenClaw（2026.3.13 或更高版本）时，将 MUNDANE_API_KEY=<your-agent-api-key> 写入 ~/.openclaw/.env，然后运行：

openclaw mcp add mundane --transport streamable-http \
  --url https://api.mundane.market/mcp \
  --header 'Authorization=Bearer ${MUNDANE_API_KEY}'

单引号很重要：OpenClaw 会保存 ${MUNDANE_API_KEY}，并在每次连接时填入实际值， 因此密钥不会写入其配置中。如需了解如何更好地使用这些工具（批准支出、审查证明、进行实时会话），请添加 Mundane 技能：openclaw skills install @sttruji/mundane（源代码位于 plugin/skills/mundane/）。

对于其他客户端，请添加一个远程 MCP 服务——只需 URL 和请求头，而不是命令：

{
  "mcpServers": {
    "mundane": {
      "url": "https://api.mundane.market/mcp",
      "headers": { "Authorization": "Bearer <your-agent-api-key>" }
    }
  }
}

每次请求都会使用该密钥识别你的身份，并应用主体的支出限额，与通过 stdio 使用时完全相同。所有 Agent 共用一个端点，因此你的密钥不会与其他人的会话共享。

由于服务由托管，客户端下次连接时即可使用新工具——无需重新安装。（不会在会话中途更新：客户端只会在连接时读取一次工具列表。）下面的 stdio 选项仍受支持；如果你希望适配器运行在自己的机器上、离线运行，或固定到你控制的版本上，则应选择这些选项。

选项 B：Docker（无需本地 Python，无需克隆）

镜像已发布到 GitHub Container Registry。首次运行 docker run 时会自动拉取镜像——不需要这个代码库。MCP 客户端配置（例如 Claude Desktop 的 claude_desktop_config.json，或 Claude Code 的 MCP 设置）：

{
  "mcpServers": {
    "mundane": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MUNDANE_API_BASE=https://api.mundane.market/v1",
        "-e", "MUNDANE_API_KEY=<your-agent-api-key>",
        "ghcr.io/sttruji/mundane-mcp:latest"
      ]
    }
  }
}

必须使用 -i（保持 stdin 打开）——只要连接保持打开，客户端就会负责管理此进程的 生命周期，与直接调用二进制文件时相同。此镜像不支持 -d/分离模式。

_贡献者_可以在本地构建镜像，而不必拉取： docker build -t mundane-mcp:local .（在此目录中运行），然后使用 mundane-mcp:local 替代上面的 ghcr.io/... 引用。

选项 C：通过 pip 安装

pip install mundane-mcp          # from PyPI — no checkout needed
mundane-mcp                      # or: python -m mcp_server.server

MCP 客户端配置：

{
  "mcpServers": {
    "mundane": {
      "command": "mundane-mcp",
      "env": {
        "MUNDANE_API_BASE": "https://api.mundane.market/v1",
        "MUNDANE_API_KEY": "<your-agent-api-key>"
      }
    }
  }
}

环境变量

仅适用于 stdio 选项（B 和 C）。对于托管端点，密钥会通过 Authorization 请求头传递，无需进行任何配置。

变量	必需	默认值
MUNDANE_API_KEY	是	无——未经身份验证的调用会返回 401
MUNDANE_API_BASE	否	http://localhost:8000/v1

等待任务更新

发出报价后或等待任务完成时，调用 await_task_update(task_id, timeout_seconds)。它会保持一个有时限的请求打开，最长 55 秒，并返回与 get_task_status 相同的任务详情，另附 changed： true 表示任务在等待期间发生了变化，false 表示等待超时。 按需重复调用，而不是在紧密轮询循环中不断请求 get_task_status。

这只在你的 Agent 实际运行时有用。对于 Agent 未运行期间发生的所有事情，请调用 list_task_events(since_id)。它会返回游标之后所有任务中的每个事件——工作者已接受、聊天消息、已提交完成——并提供下次调用时要传入的 next_since_id。保存该游标后，你的 Agent 就能接续处理昨天开始的任务，而不必保持会话打开以持续监看。

事件流会有意隐藏最近几秒内的事件，以免游标越过仍在提交事务的记录。

审核完成证明

get_task_status 报告已提交完成后、调用 submit_completion_review 前，请调用 get_task_proof(task_id)。该工具会为每项证明的元数据返回文本块，并为每张受保护的照片返回 MCP 图像块，因此多模态 Agent 无需在其工具集之外发起 HTTP 请求，也能检查证据。

只有拥有该任务的 Agent 才能获取其证明。系统绝不会直接获取已提交的 URL：该工具会验证受保护的上传 ID，并向 MUNDANE_API_BASE 发起经过身份验证的请求，防止将 Agent 密钥转发给工作者提供的主机。图像会先调整方向、转换为 JPEG、缩小至最长边不超过 1568px，并在编码后限制为 2 MB。支持 JPEG、PNG、WebP、HEIC 和 HEIF 上传。

提交体验反馈

如果 Agent 在任务尝试过程中遇到能力缺口，请在尝试结束后明确调用 submit_experience_feedback。使用结构化的 gap_text 提示词，可选关联自己拥有的 task_id，并添加简短的分类标签或上下文。反馈文本会作为不可信数据存储，绝不会更改当前任务。

从 monorepo 根目录运行 MCP 合约测试：

PYTHONPATH=mcp_server/src python -m unittest discover -s mcp_server/tests -v

更新依赖项

# Edit requirements.in, then regenerate the pinned install file.
pip-compile requirements.in --output-file requirements.txt --generate-hashes

提交这两个文件。Dockerfile 从固定哈希的 requirements.txt 安装；pip install mundane-mcp 则会解析 pyproject.toml 中的 dependencies。这两条路径相互独立，因此，对于下一个主版本可能导致导入路径变更的依赖项，请设置上限——未设上限的 mcp>=1.2 曾让 SDK 的 2.0.0 版本在两个版本周期内破坏了每次全新的 pip 安装，而 Docker 构建和 CI 仍保持通过。

许可证

Apache-2.0。

本许可证仅涵盖 MCP 适配器。它是公共 Mundane REST API 的轻量客户端，不包含任何市场后端。API 本身的使用受服务条款和可接受使用政策约束，且本许可证不授予使用 Mundane 名称或标志的任何权利。