# SUI BROKERS participant agent kit

This package exposes public, read-only SUI BROKERS data through MCP. It has six tools:

- `suibrokers_get_status` — public health and runtime configuration;
- `suibrokers_get_season` — one published season stage and optional viewer row;
- `suibrokers_get_swap_history` — wallet-scoped trainee history;
- `suibrokers_get_desk` — public Desk snapshot and history range;
- `suibrokers_get_partner` — partner stats and history;
- `suibrokers_prepare_action` — a review-only checklist for a future swap, Desk action, partner, or points workflow, with the exact app route (`#pit`, `#desk`, `#partners`, or `#leaderboard`) and no prefilled query parameters.

The first five tools perform bounded `GET` requests only. Their list limits default to 10 and cap at 100. The action tool creates a plan; it does not quote, build, sign, send, activate referrals, boot a wallet, or mint an NFT. Signing requirements are true only for swap and Desk action plans; partner and points plans are read-only. Every result includes a source origin and `asOf` timestamp. API states such as `pending`, `confirmed`, `failed`, `partial`, `unavailable`, and empty `zero` results remain distinct when the service reports them. Thresholds, qualification, allocation, revenue, and returns are never inferred by the kit.

## Remote MCP

The remote MCP route is `/api/agents/mcp`. For an app deployment at the production origin, its URL is `https://suibrokers.com/api/agents/mcp`; use the remote commands only after that deployment exposes this route. The route accepts the production origin, the staging origin, and exact loopback hosts for local testing. No API key is needed for these public tools. Codex CLI can add it with:

```sh
codex mcp add suibrokers --url https://suibrokers.com/api/agents/mcp
```

Claude Code can add the same HTTP server with:

```sh
claude mcp add --transport http suibrokers https://suibrokers.com/api/agents/mcp
```

Hosted ChatGPT conversations cannot read a local MCP config. They need an approved remote connector/plugin; this kit is not a marketplace publication.

## Local stdio

From the extracted kit directory, install the pinned package dependencies and run:

```sh
npm ci
node server.mjs
```

For example, extract the archive into a directory you choose, then use that real directory in a shell variable; do not paste a permanent machine-specific path into a shared config:

```sh
PARTICIPANT_DIR="$PWD"
KIT_DIR="$PARTICIPANT_DIR/suibrokers-agent-kit"
test ! -e "$KIT_DIR" || { echo "Refusing to replace existing kit directory: $KIT_DIR" >&2; exit 1; }
mkdir "$KIT_DIR"
unzip ./agent-kit.zip -d "$KIT_DIR"
cd "$PARTICIPANT_DIR"
npm ci --prefix "$KIT_DIR"
```

Codex CLI's documented local stdio command form is:

```sh
codex mcp add suibrokers-local --env API_SUIBROKERS_URL=https://suibrokers.com -- node "$KIT_DIR/server.mjs"
```

The `codex mcp add … -- <stdio command>` form follows the [official Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp).

Claude Code's documented local stdio command form is:

```sh
claude mcp add --transport stdio --env API_SUIBROKERS_URL=https://suibrokers.com suibrokers-local -- node "$KIT_DIR/server.mjs"
```

The `--transport stdio … -- <command>` form follows [Claude Code's MCP documentation](https://code.claude.com/docs/en/mcp).

Both commands launch the exact `public/agent-kit/server.mjs` entry after extraction. `API_SUIBROKERS_URL` may be set to the exact production origin, the exact staging origin, or an explicit loopback origin for fixture/local tests. It must not contain a path, query, credentials, or redirect target. Review-only action plans use this validated origin for their corresponding `app.html` hash route, so a staging or local run does not emit a production action link; the default remains production.

The package's spawned stdio and MCP protocol paths are covered by its local tests; registration with a particular installed Codex or Claude CLI remains host-specific.

## Install the four skills

The archive contains four independent `SKILL.md` folders. These commands install them into project-local roots and fail before copying if any destination already exists. Review the folders first; the MCP server does not auto-install them:

```sh
SKILL_ROOT="$PWD/.agents/skills" # Codex project-local skills
mkdir -p "$SKILL_ROOT"
for name in suibrokers-swap suibrokers-desk suibrokers-partners suibrokers-progress; do
  test ! -e "$SKILL_ROOT/$name" || { echo "Refusing to replace existing skill: $SKILL_ROOT/$name" >&2; exit 1; }
done
for name in suibrokers-swap suibrokers-desk suibrokers-partners suibrokers-progress; do
  cp -R "$KIT_DIR/skills/$name" "$SKILL_ROOT/$name"
done
```

For a Claude Code project, use the same guarded block with this root instead:

```sh
SKILL_ROOT="$PWD/.claude/skills" # Claude Code project-local skills
mkdir -p "$SKILL_ROOT"
for name in suibrokers-swap suibrokers-desk suibrokers-partners suibrokers-progress; do
  test ! -e "$SKILL_ROOT/$name" || { echo "Refusing to replace existing skill: $SKILL_ROOT/$name" >&2; exit 1; }
done
for name in suibrokers-swap suibrokers-desk suibrokers-partners suibrokers-progress; do
  cp -R "$KIT_DIR/skills/$name" "$SKILL_ROOT/$name"
done
```

Keep existing user or repository guidance. `templates/AGENTS.md` is a participant template: merge its relevant rules into the participant project's instructions after review; do not overwrite a repository `AGENTS.md`, Codex global guidance, or an existing Claude configuration. The four skills are ordinary Markdown folders and may be loaded by a host that supports this skill format.

## Local HTTP

For a local MCP HTTP endpoint:

```sh
npm ci --prefix "$KIT_DIR"
PORT=8788 API_SUIBROKERS_URL=https://suibrokers.com node "$KIT_DIR/http.mjs"
```

The local server binds to `127.0.0.1` by default and serves `/api/agents/mcp`. The Node server rejects arbitrary Host and Origin values, limits request bodies to 64 KiB, limits JSON responses to 1 MiB, and applies a 15 second upstream GET timeout.

## Supported client boundary

Codex CLI and Claude Code support either the remote HTTP URL or the local stdio command documented above. Gemini and DeepSeek are model/provider names; use an actual MCP-compatible host or tool runner and do not assume a native model integration. The package does not perform wallet boot, automatic signing, referral activation, token claims, NFT minting, or live transaction submission.

## Safe participant workflow

Read the relevant skill, call the read tool, review the returned source and `asOf`, then use the application UI for any action. A user reviews the final transaction in their wallet and signs it explicitly. Only a confirmed ledger readback can support credited Points or season progress. Text prompts, installation, simulations, and unconfirmed plans earn no Points. Partner Trust and the verified-activity allocation are separate; accrued revenue is not a paid balance.

The four skills under `skills/` are progressively disclosed: start at each `SKILL.md`, then read its linked reference only when that workflow is selected. `templates/AGENTS.md` is participant guidance and does not replace repository instructions.