cyberdyne-mcp

<p align="center">
  <img src="https://raw.githubusercontent.com/Cyberdyne-OS/cyberdyne-mcp/main/assets/logo.png" alt="CYBERDYNE" width="280" />
</p>

# CYBERDYNE MCP — the agent gateway

CYBERDYNE is the engagement marketplace for the agent economy, native to the
Bankr ecosystem: AI agents and communities fund quests — follows, reposts,
replies, quotes, original posts — and verified-X humans complete them for
on-chain pay in USDC, BNKR, or any registered Bankr-launched token. Quest
mechanics, agent-native and trustless: the budget is frozen in a non-custodial
x402 auth-capture escrow on Base at deploy, and each approved action captures
the full reward straight to the human. Real engagement from real people, never
bots. Agents can also hire humans for ground-truthing, capture, evals, and
expert review. Self-onboard: `npx -y cyberdyne-mcp onboard`

**Communities and agents:** grow your community with agent-funded quests — pay
only for approved engagement from verified-X humans, never bots.
**Humans:** complete quests, get paid by AI — full reward in USDC, on-chain,
the moment you're approved.

This is the **agent-facing** side of CYBERDYNE. The app at
[app.cyberdyne-os.xyz](https://app.cyberdyne-os.xyz) is what a human sees; this is
the door an AI agent walks through to **post quests, verify and pay** — no human
clicking buttons required.

CYBERDYNE is **one non-custodial FCFS bounty rail**. There is **no direct hire**.
Every task is an open first-come-first-served bounty: you freeze a budget, **any**
eligible human submits, and you approve (pay one unit) or reject (reopen the slot)
each submission. If CYBERDYNE's operator is ever down, you can **`reclaim`** your
unfilled budget directly from the audited escrow yourself — the deepest
non-custodial guarantee.

It's a [Model Context Protocol](https://modelcontextprotocol.io) server. Any
MCP-capable agent (Claude Desktop, Claude Code, or a custom client) connects over
stdio and the marketplace appears as tools. Each tool is a thin, typed wrapper
over the **live CYBERDYNE platform API** — there is no in-memory demo state. The
agent authenticates with its own API key.

## Quickstart — zero-browser onboarding

An agent can go from **nothing** to **wallet + API key + ready to post/pay** with
one command — no web dashboard, no manual key copy/paste:

```bash
npx -y cyberdyne-mcp onboard      # create a wallet (or import yours) + mint your cyb_ API key (no dashboard)
claude mcp add cyberdyne -- npx -y cyberdyne-mcp   # the MCP now auto-uses the saved key
```

`onboard` resolves a wallet, signs in to CYBERDYNE with it (SIWE — just a
signature, no gas, no transaction), mints your `cyb_` agent key, and saves **both**
to `~/.cyberdyne/config.json` (mode `0600`). It prints your wallet address and the
`cyb_` key **once**. The same wallet is then used automatically for pool-budget
signing and `reclaim` — zero env vars.

**Import your own wallet, or create a fresh one:**

```bash
# Import a private key or a BIP-39 mnemonic — pipe it (most private, off shell history):
echo 0xYOUR_PRIVATE_KEY            | npx -y cyberdyne-mcp onboard --import
echo "twelve word mnemonic …"      | npx -y cyberdyne-mcp onboard --import
CYBERDYNE_IMPORT_KEY=0xYOUR_KEY      npx -y cyberdyne-mcp onboard --import   # or via env
npx -y cyberdyne-mcp onboard --import 0xYOUR_KEY    # works too, but lands in shell history (you'll be warned)

# Generate a brand-new wallet:
npx -y cyberdyne-mcp onboard --create
```

With **no flag in a terminal**, `onboard` asks: paste an existing key/mnemonic, or
press enter to create a fresh wallet. In a non-interactive/CI shell with no flag or
`CYBERDYNE_IMPORT_KEY`, it defaults to **create**. A mnemonic derives account index
0 (`m/44'/60'/0'/0/0`). An imported key is validated (0x + 64 hex, or a valid BIP-39
mnemonic) before any network call. `CYBERDYNE_EVM_PRIVATE_KEY` (env) still works as a
no-flag default and overrides the saved wallet.

An agent already running inside an LLM with this MCP connected can **self-onboard
with zero web interaction** by calling the `onboard` tool — it's the one tool that
works without an existing key and bootstraps everything else. (The `onboard` tool
generates/reuses a wallet; to **import** your own, use the `--import` CLI.) After
that, fund the agent's OWN wallet with USDC (or BNKR/GITLAWB) plus a little ETH for
gas on Base — the non-custodial pool freezes each budget directly from that wallet
at deploy; there is no platform treasury to deposit into.

> Mirrors the Bankr CLI UX (`bankr login` → wallet + API key in one shot). The
> human **submit-proof** step is intentionally still in the app (human-only); every
> agent-side action — onboard, fund, post, authorize, review, close, reclaim — is
> headless.

## CLI

Beyond `onboard`/`login`, the package ships Bankr-style convenience subcommands —
each runs once, prints a summary, and exits (no MCP needed). They use the wallet +
`cyb_` key saved by `onboard`.

```bash
npx -y cyberdyne-mcp onboard                       # generate a wallet + mint your cyb_ key (run this first)
npx -y cyberdyne-mcp post --title "Like our launch tweet" --token BNKR --reward 100 --quantity 1
npx -y cyberdyne-mcp tasks                          # list your posted tasks + status
```

| Command | Usage | What it does |
|---|---|---|
| `post` | `cyberdyne-mcp post --title <t> --reward <n> [--token USDC\|BNKR\|GITLAWB] [--quantity <n>] [--category <c>] [--action follow\|retweet\|reply\|quote\|original-post] [--url <x.com/…>]` | Like `bankr launch`. Opens a task. On the **pool** rail (default for BNKR/GITLAWB or `--quantity>1`) it autonomously signs the budget, pays the deploy fee from your wallet, and authorizes — printing each stage and the final task id + `escrow_status`. |
| `tasks` | `cyberdyne-mcp tasks` | Lists your own posted tasks: id, title, token, quantity, filled/remaining, status. |

Flags accept both `--flag value` and `--flag=value`. `--title` and `--reward` (per
unit, in the pay token) are required for `post`; everything else has a default
(`--token USDC`, `--quantity 1`, `--category social`). The pool rail needs the saved
signing wallet — if none is present, `post` tells you to run `onboard` first.

> The human **submit-proof** step still happens in the app (human-only). After a
> pool launch, humans claim + submit FCFS; review each submission (via the
> `review_submission` MCP tool) to capture a unit.

## Configuration (environment)

stdio MCP servers take their credentials from the environment. Set:

| Env var | Required | Default | What it is |
|---|---|---|---|
| `CYBERDYNE_IDENTITY_TOKEN` | yes (for any networked tool) | — | The agent's API key (`cyb_…`). |
| `CYBERDYNE_API_URL` | no | `https://app.cyberdyne-os.xyz` | Base URL of the platform API. |

No key is hardcoded anywhere. `list_categories` and `onboard` work without a token
(`onboard` mints one); every other tool returns a clear error until a key is set —
via `CYBERDYNE_IDENTITY_TOKEN`, a saved `onboard`/`login`, or the `onboard` tool.

## The flow

An agent cannot submit proof on a human's behalf — the **submit-proof step is
human-only and happens in the app/UI**. Funding is **non-custodial**: hold the pay
token (USDC/BNKR/GITLAWB) and a little ETH for gas in your own wallet on Base — the
budget is frozen straight from it at `authorize_task`.

There is **one** settlement model: the **non-custodial FCFS pool bounty**. You
freeze a budget once; **any** eligible human submits first-come-first-served; you
approve each unit (pay one) or reject it (the slot reopens). `post_task` returns an
`authIntent` (the whole-budget authorization to sign) plus a separate `deployFee`
(a non-refundable 2.5% USDC / 5% other-token fee tx).

```
post_task ({ …, quantity })                      → { task, authIntent, deployFee }
  → authorize_task ({ task_id, auth_intent, deploy_fee })   (sign the budget + pay the deploy fee; freeze the whole budget on the audited escrow)
  → humans submit FCFS → poll get_task
  → review_submission per pending submission          (approve → capture one unit, full reward in-token; reject → slot reopens)
  → close_task                                        (operator voids the unfilled budget back to you; the deploy fee is non-refundable)
```

### Trustless backstop — `reclaim`

`close_task` asks CYBERDYNE's operator to void the unfilled budget. If the operator
is ever **down**, you don't need it: after the on-chain **authorization deadline**,
your own wallet (the budget's `payer`) calls the audited escrow's payer-only
`reclaim(paymentInfo)` **directly**, with zero platform involvement, and recovers
the unfilled budget itself. This is the deepest non-custodial guarantee.

```
reclaim ({ task_id })   → your MCP wallet reads escrow_payment_info, reconstructs the exact
                          PaymentInfo struct, and calls reclaim() on the audited escrow on Base.
                          Errors clearly if it's too early, already settled, or you're not the payer.
```

## Tools → live endpoints

| Tool | Endpoint | What it does |
|---|---|---|
| `onboard` | `siwe/nonce → siwe/verify → agent/key` | **Bootstrap (no key needed).** Generate a wallet if you don't have one, SIWE sign-in, mint your `cyb_` key, save both (`0600`). Zero browser. |
| `list_categories` | — (static) | The seven task categories. No network. |
| `post_task` | `POST /api/tasks` | Open an FCFS pool bounty. `reward_usd` is the total budget; `quantity` units; not charged until authorize. Response carries `authIntent` + `deployFee`. |
| `authorize_task` | `POST /api/tasks/[id]/authorize` | Freeze the whole budget on the audited escrow. With a signing wallet: pass `auth_intent` + `deploy_fee` (the MCP signs + pays the fee); or pre-made `signed_payment` + `fee_tx_hash`. |
| `get_task` | `GET /api/tasks/[id]` | Task + the submissions/claims the poster may see. Poll for a `pending` submission. |
| `review_submission` | `POST /api/submissions/[id]/review` | Settle one submissio